adminmcp by frankausberlin - MCP Server

AdminMCP (ACP)

A comprehensive MCP (Model Context Protocol) based agent environment for system administration and automation tasks. AdminMCP provides both a CLI tool for managing MCP servers and a server implementation with built-in tools and resources for administrative operations.

🎯 Project Description

AdminMCP is a dual-purpose tool that serves as both a command-line interface (CLI) for managing MCP servers and an MCP server itself. The project aims to create a robust environment for system administration tasks through MCP-compatible agents.

The CLI component (acp) provides easy management of MCP server processes, while the server component offers a collection of tools and resources for common administrative and computational tasks. Future versions will include client functionality for connecting to and interacting with MCP servers.

Architecture

CLI Tool: Command-line interface for server lifecycle management
MCP Server: FastMCP-based server providing tools and resources
Configuration System: User-configurable settings stored in ~/.config/adminmcp/
Client (Planned): MCP client for connecting to servers and executing tasks

✨ Features

Current Features

CLI Server Management

Server Control: Start and stop MCP servers as background processes
Process Management: Automatic PID tracking and safe process termination
Safety Checks: Prevents multiple server instances and handles edge cases

MCP Server Tools

Mathematical Operations: Add, subtract, multiply, divide numbers
Mathematical Constants: Access to π, e, τ via resource endpoints
Number Utilities: Check if numbers are even/odd
DateTime Resources: Current datetime with timezone information
Wikipedia Integration: Fetch article summaries from Wikipedia

Configuration Management

Initialization: Automated setup of configuration directories
User Settings: Customizable server port and logging levels
MCP Server Registry: Management of connected MCP servers

Planned Features

Client Functionality

Server Connection: Connect to MCP servers via WebSocket/SSE
Tool Execution: Remote execution of server-provided tools
Resource Access: Query server resources programmatically
Interactive Mode: REPL for interactive server interaction

Advanced Administration Tools

System Monitoring: CPU, memory, disk usage tools
File Operations: Safe file manipulation tools
Network Utilities: DNS lookup, port scanning, connectivity tests
Process Management: List, start, stop system processes

🚀 Installation

Prerequisites

Python 3.11 or higher
uv package manager (recommended) or pip

Install from Source

Clone the repository:

git clone https://github.com/yourusername/adminmcp.git
cd adminmcp

Create virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

# Using uv (recommended)
uv pip install -e .

# Or using pip
pip install -e .

Verify installation:
```
acp --help
```

Using uv (Recommended)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install AdminMCP
uv pip install -e .

📖 Usage Examples

Basic Server Management

Start the MCP server:

acp server start
# Output: Server started.

Stop the MCP server:

acp server stop
# Output: Server stopped.

Initialize configuration:

acp init
# Output:
# Copied config.adminmcp.json to /home/user/.config/adminmcp/config.adminmcp.json
# Created /home/user/.config/adminmcp/mcp_settings.json
# Configuration initialized.

Testing with MCP Inspector

The easiest way to test the server is using the MCP Inspector:

mcp dev ./src/adminmcp/server/acp_server.py

This starts the MCP Inspector UI where you can interact with all available tools and resources.

Programmatic Usage

The server can be used programmatically through MCP clients. Here are some example tool calls:

# Mathematical operations
result = add(5, 3)  # Returns 8
result = multiply(4, 7)  # Returns 28

# Resource access
pi_value = get_constant("pi")  # Returns 3.141592653589793
is_even = is_even(42)  # Returns True

# DateTime information
current = current_datetime()
# Returns: {"datetime": "2024-01-01T12:00:00+00:00", "timezone": "UTC", "unix_timestamp": 1704110400.0}

# Wikipedia lookup
article = wikipedia_article("Python (programming language)")
# Returns article summary JSON

⚙️ Configuration

AdminMCP uses a configuration system stored in ~/.config/adminmcp/. The configuration is initialized automatically with the acp init command.

Configuration Files

`config.adminmcp.json`

Template configuration file with default settings:

{
    "application": {
        "config_folder": "~/.config/adminmcp",
        "log_folder": "~/.local/share/adminmcp/logs",
        "data_folder": "~/.local/share/adminmcp/data",
        "logging_level": "info"
    },
    "server": {
        "port": 8000
    },
    "client": {}
}

`mcp_settings.json`

Runtime configuration for MCP server settings:

{
    "mcpServers": {},
    "acpServerPort": 8080,
    "acpLoggingLevel": "info"
}

Configuration Options

acpServerPort: Port number for the AdminMCP server (default: 8080)
acpLoggingLevel: Logging verbosity - "debug", "info", "warning", "error" (default: "info")
mcpServers: Registry of configured MCP servers (for future client functionality)

Customizing Configuration

Run initialization: acp init
Edit ~/.config/adminmcp/mcp_settings.json with your preferred settings
Restart the server for changes to take effect

🛠️ Development Setup

Development Environment

Clone and setup:

git clone https://github.com/yourusername/adminmcp.git
cd adminmcp
uv venv
source .venv/bin/activate
uv pip install -e .

Install development dependencies:
```
uv pip install pytest pytest-asyncio
```
Run tests:
```
pytest
```

Project Structure

adminmcp/
├── cli.py                 # Main CLI entry point
├── logging_config.py      # Logging configuration
├── server/
│   ├── acp_server.py     # MCP server implementation
│   └── server.py          # Additional server utilities
└── client/                # Future client implementation

Development Workflow

Make changes to source files in src/adminmcp/
Run tests to ensure functionality
Test with MCP Inspector for server changes
Update documentation as needed

Adding New Tools

To add new MCP tools to the server:

@mcp.tool()
def your_tool_name(param1: type, param2: type) -> return_type:
    """Tool description for MCP discovery."""
    # Implementation here
    return result

Adding New Resources

To add new MCP resources:

@mcp.resource("resource://your/resource/{param}")
def your_resource(param: str) -> dict:
    """Resource description."""
    # Implementation here
    return data

🧪 Testing

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=adminmcp

# Run specific test file
pytest tests/test_cli.py

Test Structure

Tests are organized in the tests/ directory. Currently, the test suite includes:

CLI command tests
Server functionality tests
Configuration management tests

Writing Tests

Example test structure:

import pytest
from adminmcp.cli import start_server, stop_server

def test_server_start_stop():
    # Test server lifecycle
    start_server()
    # Assertions here
    stop_server()
    # Assertions here

🤝 Contributing

We welcome contributions to AdminMCP! Here's how you can help:

Development Process

Fork the repository on GitHub
Create a feature branch: git checkout -b feature/your-feature-name
Make your changes following the coding standards
Add tests for new functionality
Run the test suite: pytest
Update documentation if needed
Submit a pull request

Coding Standards

Python Style: Follow PEP 8 guidelines
Type Hints: Use type annotations for function parameters and return values
Documentation: Add docstrings to all public functions and classes
Logging: Use the provided logging configuration
Error Handling: Implement proper exception handling

Areas for Contribution

New MCP Tools: Add administrative tools (file operations, system monitoring, etc.)
Client Implementation: Build the MCP client functionality
Documentation: Improve documentation and examples
Testing: Expand test coverage
Performance: Optimize server performance and resource usage

Reporting Issues

Bug Reports: Use GitHub Issues with detailed reproduction steps
Feature Requests: Describe the use case and expected behavior
Security Issues: Contact maintainers directly

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

Model Context Protocol for the underlying protocol
FastMCP for the Python MCP server implementation
The open-source community for inspiration and tools

AdminMCP is an ongoing project. Stay tuned for updates and new features!