MCP服务器编排平台

┌─────────────────────────────────────────────────────────────┐
│                     Agentes de IA                            │
│              (Claude Desktop, Cursor, etc.)                 │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                      MCP Hub                                │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  FastAPI + FastMCP (API REST + Protocolo MCP)        │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Core - Orchestration                               │  │
│  │  ├─ Registry (Configuración)                       │  │
│  │  ├─ Orchestrator (Ciclo de vida)                   │  │
│  │  ├─ Router (Enrutamiento)                          │  │
│  │  └─ MultitenantManager (Aislamiento)               │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Transport Layer                                   │  │
│  │  └─ StdioClientWrapper (Cliente MCP)               │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Gateway Layer                                     │  │
│  │  ├─ WebSocket Gateway (Apps)                       │  │
│  │  └─ UI Proxy (Recursos estáticos)                  │  │
│  └─────────────────────────────────────────────────────┘  │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│  Postgres│  │  GitHub  │  │  Custom  │
│   MCP    │  │   MCP    │  │   MCP    │
└──────────┘  └──────────┘  └──────────┘

# Clonar el repositorio
git clone https://github.com/ainsophic/mcp-hub.git
cd mcp-hub

# Crear entorno virtual (opcional pero recomendado)
python -m venv .venv
source .venv/bin/activate  # En Windows: .venv\Scripts\activate

# Instalar dependencias
pip install -r requirements.txt

# Instalar dependencias de desarrollo (opcional)
pip install -r requirements-dev.txt

# Instalar el paquete en modo desarrollo
pip install -e .

{
  "version": "1.0.0",
  "tenants": {
    "default": {
      "description": "Tenant por defecto",
      "servers": {
        "sqlite-demo": {
          "name": "sqlite-demo",
          "type": "database",
          "command": "python",
          "args": ["-m", "mcp.server.sqlite", "--db-path", "./data/demo.db"],
          "enabled": true,
          "capabilities": ["tools", "resources"],
          "transport": "stdio",
          "metadata": {
            "description": "Servidor SQLite de ejemplo"
          }
        }
      }
    }
  },
  "gateway": {
    "port": 8080,
    "mcp_port": 8000,
    "websocket_port": 8081,
    "host": "0.0.0.0"
  },
  "orchestrator": {
    "auto_start": false,
    "max_retries": 3,
    "startup_timeout": 30
  }
}

# Iniciar con configuración por defecto
python -m mcp_hub.main

# O especificar configuración personalizada
python -m mcp_hub.main --config config/servers.json

# Con recarga automática (desarrollo)
python -m mcp_hub.main --reload

# Salud del Hub
curl http://localhost:8080/health

# Listar tenants
curl http://localhost:8080/api/tenants

# Listar herramientas disponibles
curl http://localhost:8080/api/tools

# Iniciar todos los servidores del tenant "default"
curl -X POST http://localhost:8080/api/tenants/default/start

# Listar servidores activos
curl http://localhost:8080/api/servers

# Ejecutar una herramienta
curl -X POST http://localhost:8080/api/tools/sqlite-demo.query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users LIMIT 10"}'

mcp-hub/
├── config/
│   └── servers.json          # Configuración de servidores y tenants
├── plugins/
│   └── examples/             # Ejemplos de plugins y MCP Apps
├── src/
│   └── mcp_hub/
│       ├── core/             # Componentes core del Hub
│       ├── transport/        # Capa de transporte (stdio, etc.)
│       ├── gateway/          # Gateway para MCP Apps
│       └── main.py           # Aplicación principal
├── tests/                    # Tests unitarios y de integración
├── pyproject.toml           # Configuración del proyecto Python
├── requirements.txt          # Dependencias de producción
└── README.md                 # Este archivo

{
  "gateway": {
    "port": 8080,              // Puerto API REST
    "mcp_port": 8000,          // Puerto protocolo MCP
    "websocket_port": 8081,    // Puerto Gateway WebSocket
    "host": "0.0.0.0"          // Host donde escuchar
  }
}

# Clonar el repositorio
git clone https://github.com/ainsophic/mcp-hub.git
cd mcp-hub

# Construir imagen
docker build -t mcp-hub:0.1.0 .

# O construir con Docker Compose
docker-compose build

# Iniciar servicio de desarrollo con hot-reload
docker-compose -f docker-compose.dev.yml up

# Con PostgreSQL
docker-compose -f docker-compose.dev.yml --profile postgres up

# En modo detached
docker-compose -f docker-compose.dev.yml up -d

# Ver logs
docker-compose -f docker-compose.dev.yml logs -f

# Iniciar servicio de producción
docker-compose -f docker-compose.prod.yml up -d

# Con todos los servicios dependientes
docker-compose -f docker-compose.prod.yml --profile postgres --profile redis up -d

# Ver logs
docker-compose -f docker-compose.prod.yml logs -f

# Detener servicios
docker-compose -f docker-compose.prod.yml down

# Detener servicios
docker-compose down

# Detener con volúmenes
docker-compose down -v

# Reconstruir imagen
docker-compose build --no-cache

# Ejecutar tests en Docker
docker-compose run --rm mcp-hub pytest

# Acceder al contenedor
docker-compose exec mcp-hub bash

# Ver logs
docker-compose logs -f mcp-hub

# Verificar estado
docker-compose ps

docker inspect mcp-hub | jq '.[0].State.Health'

# Ver todos los comandos disponibles
make help

# Iniciar desarrollo
make up-dev

# Iniciar desarrollo con PostgreSQL
make up-dev-with-db

# Ver logs
make logs-dev

# Detener servicios
make down-dev

# Reconstruir todo
make rebuild-dev

{
  "mcpServers": {
    "mcp-hub": {
      "command": "python",
      "args": [
        "-m",
        "mcp_hub.main",
        "--config",
        "/ruta/a/config/servers.json"
      ]
    }
  }
}

# Ejecutar todos los tests
pytest

# Ejecutar tests con cobertura
pytest --cov=mcp_hub --cov-report=html

# Ejecutar tests específicos
pytest tests/test_registry.py
pytest tests/test_multitenant.py
pytest tests/test_integration.py

# Ejecutar tests con verbosidad
pytest -v

import asyncio
from mcp_hub.main import app, _multitenant_manager

async def main():
    # Iniciar servidores del tenant "default"
    servers = await _multitenant_manager.start_tenant_servers("default")
    print(f"Servidores iniciados: {len(servers)}")

asyncio.run(main())

import asyncio
from mcp_hub.main import _router

async def main():
    # Ejecutar una herramienta
    result = await _router.call_tool(
        "postgres.query",
        {"sql": "SELECT * FROM users LIMIT 10"}
    )
    print(f"Resultado: {result}")

asyncio.run(main())

// Ejemplo de conexión WebSocket desde una MCP App
const ws = new WebSocket('ws://localhost:8081/ws/app/myapp/default');

ws.onopen = () => {
    console.log('Conectado al MCP Hub');
    
    // Enviar mensaje de ready
    ws.send(JSON.stringify({
        type: 'app_ready',
        data: {}
    }));
};

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    
    switch (message.type) {
        case 'app_state':
            console.log('Estado de la App:', message.data);
            break;
        case 'tool_result':
            console.log('Resultado de herramienta:', message.data);
            break;
    }
};

// Llamar a una herramienta
function callTool(toolName, arguments) {
    ws.send(JSON.stringify({
        type: 'tool_call',
        data: {
            tool_name: toolName,
            arguments: arguments
        }
    }));
}

# Instalar dependencias de desarrollo
pip install -r requirements-dev.txt

# Instalar pre-commit hooks
pre-commit install

# Ejecutar linters
ruff check src/mcp_hub/
black src/mcp_hub/

# Ejecutar type checking
mypy src/mcp_hub/