MCP 服务器

RealWorker-Manager MCP Server

Enables centralized management and monitoring of multiple distributed worker MCP servers. Provides tools to list workers, get status of all workers, and query specific worker status.

README

MCP Admin Server Architecture

Overview

This is a Manager/Admin MCP (Model Context Protocol) Server that coordinates and monitors multiple worker MCP servers across a distributed network. It acts as a centralized control plane for managing worker nodes. This is a Manager/Admin MCP (Model Context Protocol) Server that coordinates and monitors multiple worker MCP servers across a distributed network. It acts as a centralized control plane for managing worker nodes.

Architecture Diagram


┌─────────────────────────────────────────────────────────────────┐
│                      MCP Client (Claude/AI)                     │
│                                                                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │ STDIO
                            │ (Standard Input/Output)
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│                    ADMIN/MANAGER SERVER                         │
│                   (admin_server/admin.py)                       │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              FastMCP Server Core                        │    │
│  │  - Server Name: "Manager"                               │    │
│  │  - Transport: STDIO                                     │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Management Tools                           │    │
│  │                                                         │    │
│  │  1. get_all_workers_status()                            │    │
│  │     - Polls all workers simultaneously                  │    │
│  │     - Returns aggregated status                         │    │
│  │                                                         │    │
│  │  2. get_worker_status(worker_name)                      │    │
│  │     - Gets status from specific worker                  │    │
│  │     - Returns detailed worker info                      │    │
│  │                                                         │    │
│  │  3. list_workers()                                      │    │
│  │     - Lists all configured workers                      │    │
│  │     - Returns worker URLs                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │           Worker Registry (WORKERS dict)                │    │
│  │                                                         │    │
│  │  Worker-One: http://10.149.14.61:8000                   │    │
│  │  [Additional workers can be added here]                 │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└───────────┬─────────────────────────────────┬───────────────────┘
            │ HTTP/HTTPX                      │ HTTP/HTTPX
            │ (Async Client)                  │ (Async Client)
            │                                 │
┌───────────▼─────────────┐       ┌──────────▼──────────────┐
│   WORKER-ONE SERVER     │       │   WORKER-N SERVER       │
│   (10.149.14.61:8000)   │       │   (Additional Workers)  │
│                         │       │                         │
│  ┌──────────────────┐   │       │  ┌──────────────────┐   │
│  │ MCP Worker Core  │   │       │  │ MCP Worker Core  │   │
│  │ - SSE Endpoints  │   │       │  │ - SSE Endpoints  │   │
│  │ - Tool Handler   │   │       │  │ - Tool Handler   │   │
│  └──────────────────┘   │       │  └──────────────────┘   │
│                         │       │                         │
│  ┌──────────────────┐   │       │  ┌──────────────────┐   │
│  │ Worker Tools     │   │       │  │ Worker Tools     │   │
│  │ - System Status  │   │       │  │ - System Status  │   │
│  │ - Battery Info   │   │       │  │ - Battery Info   │   │
│  │ - Custom Tasks   │   │       │  │ - Custom Tasks   │   │
│  └──────────────────┘   │       │  └──────────────────┘   │
│                         │       │                         │
└─────────────────────────┘       └─────────────────────────┘

Component Details

1. Admin/Manager Server (admin.py)

Purpose: Central coordination server that manages multiple worker MCP servers

Key Components:

FastMCP Core: Lightweight MCP server framework
Worker Registry: Dictionary mapping worker names to URLs
HTTP Client: Async HTTPX client for worker communication
Management Tools: Three exposed tools for worker management

Communication:

Upstream (to AI Client): STDIO transport
Downstream (to Workers): HTTP POST requests to worker SSE endpoints

2. Worker Servers

Purpose: Distributed worker nodes that perform actual tasks and report status

Key Components:

MCP Server Core: Handles incoming requests via SSE
Tool Endpoints: /sse/tools/call for tool execution
Status Tools: get_worker_status() and other worker-specific tools

Communication:

Upstream (to Admin): HTTP responses to manager requests
Local Resources: Access to system information (CPU, memory, battery, etc.)

Data Flow

Scenario 1: Get All Workers Status

1. AI Client → Admin: Call get_all_workers_status()
2. Admin → Worker-One: POST /sse/tools/call (get_worker_status)
3. Admin → Worker-N: POST /sse/tools/call (get_worker_status)
   [Parallel async requests]
4. Worker-One → Admin: Return status data
5. Worker-N → Admin: Return status data
6. Admin → AI Client: Aggregated results from all workers

Scenario 2: Get Specific Worker Status

1. AI Client → Admin: Call get_worker_status("Worker-One")
2. Admin: Lookup worker URL from WORKERS registry
3. Admin → Worker-One: POST /sse/tools/call (get_worker_status)
4. Worker-One → Admin: Return status data
5. Admin → AI Client: Worker status

Scenario 3: List Workers

1. AI Client → Admin: Call list_workers()
2. Admin: Return WORKERS dictionary
3. Admin → AI Client: List of workers with URLs

Technical Stack

Core Technologies

Python 3.11+: Runtime environment
FastMCP: MCP server framework
HTTPX: Async HTTP client for worker communication
STDIO: Transport protocol for AI client communication

Dependencies

httpx>=0.28.1       # Async HTTP client
mcp[cli]>=1.26.0    # MCP framework
psutil>=7.2.2       # System monitoring (likely used by workers)
uvicorn>=0.40.0     # ASGI server (for workers)

Deployment Architecture

Network Layer:
┌─────────────────────────────────────────────────────────┐
│                    Local Network / VPN                   │
│                                                          │
│  Admin Server         Worker-One         Worker-N       │
│  (localhost)          (10.149.14.61)     (10.x.x.x)     │
│                                                          │
└─────────────────────────────────────────────────────────┘

Deployment Characteristics:

Admin runs locally and communicates via STDIO with AI client
Workers are distributed across network (LAN/VPN)
HTTP-based communication between admin and workers
10-second timeout for worker requests
Async/parallel communication for efficiency

Security Considerations

Network Security:
- Workers expose HTTP endpoints (currently unencrypted)
- Should be deployed on trusted network or use VPN
- Consider adding HTTPS/TLS for production
Authentication:
- Currently no authentication between admin and workers
- Consider adding API keys or mutual TLS
Error Handling:
- Graceful degradation when workers are unavailable
- Timeout protection (10s) prevents hanging

Scalability

Current Design:

Synchronous registry (WORKERS dict)
Hardcoded worker URLs
Manual configuration

Future Improvements:

Service discovery mechanism
Dynamic worker registration
Health check automation
Load balancing across workers
Worker heartbeat monitoring

Extension Points

Add New Worker: Update WORKERS dictionary with new worker URL
Add New Tool: Define new @mcp.tool() function in admin.py
Custom Worker Communication: Extend HTTP client logic
Monitoring: Add logging, metrics collection, alerting

Usage Example

# From AI Client (Claude)
# The admin server exposes these tools:

# 1. List all configured workers
list_workers()
# Returns: {"workers": {"Worker-One": "http://10.149.14.61:8000"}}

# 2. Get status from all workers
get_all_workers_status()
# Returns: {"Worker-One": {...status data...}}

# 3. Get status from specific worker
get_worker_status("Worker-One")
# Returns: {...status data from Worker-One...}

Running the Server

# Development mode
uv run admin.py

# Production mode (via MCP configuration)
# Add to Claude Desktop config:
{
  "mcpServers": {
    "admin-server": {
      "command": "uv",
      "args": ["run", "admin.py"],
      "cwd": "d:\\SLT\\AI\\MCP_Servers\\admin_server"
    }
  }
}

Project Structure

admin_server/
├── admin.py           # Main admin/manager server
├── main.py           # Alternative entry point (unused)
├── pyproject.toml    # Project dependencies
└── README.md         # This architecture document