🏛️ ArchMCP: Servidor MCP Remoto Central para Microservicios

Dale a tu asistente de codificación con IA un cerebro organizativo.
ArchMCP es un servidor ligero y remoto del Protocolo de Contexto de Modelo (MCP) que conecta tus asistentes de IA (Google Antigravity, Claude Desktop, Cursor, VS Code) a toda tu arquitectura de microservicios en tiempo real.

📚 Lee el Manual de Usuario y Guía de Configuración Paso a Paso

📖 La Historia Detrás de ArchMCP

El Problema Cotidiano

Imagina que estás escribiendo una funcionalidad en order-service con tu asistente de codificación con IA. Le preguntas a la IA:

"Implementa el checkout y cobra al cliente."

Inmediatamente, la IA se topa con un muro:

• No tiene ni idea de qué cabeceras requiere payment-service para la idempotencia.

• No sabe qué columnas de base de datos existen en inventory-service para reservar stock.

• No tiene ni idea de qué servicios upstream se romperán si modificas un endpoint.

Para solucionar esto hoy en día, los desarrolladores suelen probar una de dos malas opciones:

1. Verter repositorios enteros en el prompt: Esto desperdicia fácilmente más de 100.000 tokens por pregunta, cuesta mucho dinero, hace que la IA sea lenta y provoca alucinaciones debido al desorden del prompt.

2. Clonar más de 20 repos localmente: Cada desarrollador del equipo tiene que mantener 20 repos actualizados en su portátil solo para que su IA local tenga contexto.

La Solución: Un Cerebro Remoto Compartido

ArchMCP resuelve esto actuando como un cerebro de arquitectura centralizado y de submilisegundos.

En lugar de ejecutarse como un comando local privado en un portátil, ArchMCP se ejecuta como un servicio remoto compartido. Cualquier ingeniero de tu equipo conecta su asistente de IA a la URL del servidor ArchMCP con un token de autenticación.

Cuando tu asistente de IA necesita saber:

• "¿Qué servicio gestiona los reembolsos?" $\rightarrow$ Llama a search_microservices.

• "¿Qué tablas posee payment-service?" $\rightarrow$ Llama a get_database_schema.

• "Si cambio /api/v1/orders, ¿quién se rompe?" $\rightarrow$ Llama a analyze_blast_radius.

┌────────────────────────────────────────────────────────┐
│                   AI Assistant Client                  │
│       (Google Antigravity, Claude Desktop, Cursor)     │
└──────────────────────────┬─────────────────────────────┘
                           │
                           │  HTTP / Server-Sent Events (SSE)
                           │  Authorization: Bearer <token>
                           │
┌──────────────────────────▼────────────────────────────────────────────────────────┐
│                                   ArchMCP Server                                   │
│                                                                                    │
│   ┌─────────────────────┐  ┌─────────────────────┐  ┌──────────────────────────┐   │
│   │      MCP Tools      │  │    MCP Resources    │  │       MCP Prompts        │   │
│   │ • search_services   │  │ • arch/overview     │  │ • cross_service_planner  │   │
│   │ • blast_radius      │  │ • services/catalog  │  │ • incident_triage        │   │
│   │ • sequence_diagram  │  │ • guidelines/docs   │  │ • contract_refactor      │   │
│   │ • get_db_schema     │  │ • service docs      │  │                          │   │
│   └──────────┬──────────┘  └──────────┬──────────┘  └────────────┬─────────────┘   │
│              │                        │                          │                 │
│   ┌──────────▼────────────────────────▼──────────────────────────▼─────────────┐   │
│   │                       Microservice Intelligence Engine                     │   │
│   │ • Transitive Graph Traversal & Blast Radius Analyzer (BFS)                 │   │
│   │ • In-Memory Index & Token Search (< 2ms response time)                     │   │
│   │ • Dynamic OpenAPI / Swagger 3.0 Importer                                   │   │
│   └───────────────────────────────────┬────────────────────────────────────────┘   │
│                                       │                                            │
│   ┌───────────────────────────────────▼────────────────────────────────────────┐   │
│   │              Embedded Web Visualizer & Live Sandbox (/dashboard)           │   │
│   │ • Interactive Service Topology Explorer & Token Economics Calculator       │   │
│   └────────────────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────────────┘

💡 Cómo Lo Diseñé y Por Qué

Al diseñar ArchMCP, el objetivo era mantenerlo rápido, limpio y práctico sin complejidad innecesaria:

1. ¿Por qué HTTP/SSE remoto en lugar de un proceso CLI local?

Los servidores MCP estándar se ejecutan como un subproceso local stdio. Aunque eso funciona para scripts de escritorio de un solo usuario, una empresa con 50 ingenieros trabajando en 30 microservicios necesita una única fuente de verdad. Al alojar ArchMCP sobre HTTP/SSE, las actualizaciones de arquitectura y los nuevos esquemas de API están disponibles al instante para todos sin clonar repositorios localmente.

2. ¿Por qué indexación de grafos en memoria en lugar de una base de datos vectorial pesada?

Muchas herramientas de IA saltan inmediatamente a bases de datos vectoriales pesadas (como Pinecone o Milvus). Para metadatos de arquitectura estructurados (rutas de API, tablas de base de datos y dependencias de servicios), el recorrido de grafos y la coincidencia rápida de tokens léxicos son:

• Deterministas: Coincidencias exactas para rutas como /api/v1/auth/login o la tabla users.

• Cero sobrecarga: Se ejecuta con ~38 MB de RAM y cero claves API externas o requisitos de GPU.

• Rapidísimo: Tiempo de respuesta inferior a 2 ms.

3. Compensaciones Consideradas

📊 Métricas de Rendimiento y Economía de Tokens

Medimos la diferencia entre pedirle a un asistente de IA que analice una tarea de microservicio vertiendo el contexto del repositorio frente a consultar ArchMCP:

💡 Verificación en Tiempo Real: Puedes probar y observar estas métricas de rendimiento en vivo en cualquier momento usando el Sandbox del Panel Interactivo integrado, que calcula la latencia de consulta y el ahorro de tokens en cada solicitud.

🔍 Sorpresas y Descubrimientos en el Camino

Construir un servidor MCP remoto en Python reveló algunos detalles técnicos fascinantes:

1. Las anotaciones de tipo se convierten en esquemas de IA: El SDK oficial de MCP para Python lee automáticamente las anotaciones de tipo y los docstrings de Python para generar definiciones JSON-Schema que el LLM usa para elegir herramientas. Los buenos docstrings literalmente hacen que la IA sea más inteligente.

2. Protección contra DNS Rebinding: El protocolo MCP 2.0 valida automáticamente las cabeceras Host entrantes para proteger las redes internas de desarrolladores de ataques DNS basados en navegador.

3. El protocolo de enlace SSE en 2 fases: Cuando un cliente de IA se conecta a GET /sse, el servidor abre el flujo de eventos y devuelve una URL de postback de sesión única (/messages/?session_id=...). Todas las llamadas posteriores a herramientas JSON-RPC se publican en esta sesión.

🖥️ Visualizador de Navegador en Vivo y Sandbox

ArchMCP incluye un panel web integrado y adaptable en http://localhost:8000/dashboard (o /):

• Topología Interactiva: Haz clic en cualquier tarjeta de servicio (auth-service, order-service, payment-service) para inspeccionar sus APIs, tablas de base de datos propias y el mapeo de dependencias.

• Sandbox de Herramientas en Vivo: Prueba cualquier herramienta MCP en tiempo real y ve la solicitud/respuesta JSON-RPC con ahorro de tokens en vivo y métricas de latencia.

⌨️ CLI para Desarrolladores

ArchMCP incluye una práctica herramienta de línea de comandos:

# 1. Start the Remote Server
archmcp run

# 2. Explore the Catalog in your Terminal
archmcp explore

# 3. Calculate Change Blast Radius
archmcp blast-radius auth-service

# 4. Import a live OpenAPI / Swagger Specification
archmcp import-openapi https://petstore.swagger.io/v2/swagger.json --owner "Commerce Team"

🔌 Conectando Tu Asistente de IA

Una vez que ArchMCP esté en ejecución (p. ej. en http://127.0.0.1:8000/sse), configura tu herramienta de IA en segundos:

Google Antigravity IDE

Añade a .agents/mcp_config.json:

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer dev-token-secret-123"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer dev-token-secret-123"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse?token=dev-token-secret-123"
    }
  }
}

🚀 Inicio Rápido en 3 Pasos

# 1. Clone & Install
git clone https://github.com/ShubhamScript/archmcp.git
cd archmcp
pip install -e .[dev]

# 2. Run Tests
pytest -v

# 3. Start Server
archmcp run

Abre http://localhost:8000/dashboard en tu navegador para explorar tu arquitectura de forma interactiva.

🔮 Lo Que Sigue en la Hoja de Ruta

Si se expande ArchMCP para más de 500 microservicios en una gran empresa:

1. Búsqueda Semántica de Conceptos: Añadir pgvector o sqlite-vec con embeddings locales para que los desarrolladores puedan hacer preguntas conceptuales ("¿Dónde vive la facturación recurrente?").

2. Integración con Backstage: Sincronización automática desde catalog-info.yaml de Backstage de Spotify.

3. Bus de Eventos Redis: Sincronizar sesiones SSE activas entre réplicas de contenedores escaladas horizontalmente.

4. Webhooks de Git: Actualizar automáticamente los esquemas cada vez que se fusiona un PR.

📂 Estructura del Proyecto

archmcp/
├── README.md                      # Project guide & architecture story
├── pyproject.toml                 # Dependencies, CLI scripts, and build config
├── Dockerfile                     # Container build instructions
├── docker-compose.yml             # Container orchestration
├── data/
│   └── repositories.yaml          # Sample microservices catalog
├── src/
│   └── archmcp/
│       ├── main.py                # Server bootstrap
│       ├── cli.py                 # Developer CLI (run, explore, blast-radius, import-openapi)
│       ├── config/settings.py     # Environment settings
│       ├── auth/                  # Bearer token verification & ASGI middleware
│       ├── mcp/                   # Tools, Resources, Prompts, and SSE route handlers
│       ├── services/              # Blast radius, graph traversal, and search logic
│       ├── ingestion/             # OpenAPI importer, markdown parser, dependency scanner
│       ├── storage/               # In-memory database & token search index
│       ├── web/                   # Embedded visualizer and live testing playground
│       └── models/                # Pydantic schemas (Architecture, BlastRadius, Services)
└── tests/                         # 18 unit & integration tests

📄 Licencia

Licencia MIT. Gratuita para uso comercial y de código abierto.