mpc-bridge

flujo http a stdin/stdout y viceversa

Documentación

Documentación Maestra del Puente HTTP MCP de Go

Resumen

Una aplicación en Go que envuelve servidores MCP (Protocolo de Contexto de Modelo) con transmisión HTTP (SSE), totalmente compatible con el transporte StreamableHTTP de llama.cpp. Este puente permite que clientes MCP basados en web se comuniquen con servidores MCP basados en subprocesos.

Arquitectura

┌─────────────────┐
│   Client        │
│   (LLM/App)     │
└────────┬────────┘
         │
         │ HTTP POST + SSE Stream
         ▼
┌──────────────────────────────┐
│  Go MCP HTTP Bridge          │
│  ┌────────────────────────┐  │
│  │ HTTP Server            │  │
│  │ - POST /mcp/{ns}/msg   │  │
│  │ - GET  /mcp/{ns} (SSE) │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ Protocol Handler       │  │
│  │ - initialize           │  │
│  │ - tools/list           │  │
│  │ - tools/call           │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ Subprocess Manager     │  │
│  │ - test-server          │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

Características

✅ Implementado (Todas las Fases 1-6 Completas)

Servidor de Transmisión HTTP
- Transmisión SSE (GET /mcp/{namespace})
- Endpoint HTTP POST (POST /mcp/{namespace}/message)
- Soporte CORS adecuado
- Gestión del ciclo de vida de conexiones
Gestión de Subprocesos
- Generación bajo demanda
- Reutilización de conexiones
- Reinicios con retroceso exponencial (1s, 2s, 4s... hasta 60s)
- Apagado elegante (manejo de SIGTERM/SIGINT)
- Seguimiento del estado del proceso
JSON-RPC 2.0
- Análisis de solicitudes/respuestas
- Validación de mensajes
- Manejo de errores
- Soporte de notificaciones
Soporte del Protocolo MCP
- initialize - Protocolo de enlace con información del servidor
- tools/list - Listar herramientas disponibles
- tools/call - Ejecutar herramientas
- ping - Verificación de salud
Seguridad
- Validación de entrada (JSON-RPC, argumentos)
- Prevención de inyección de comandos
- Validación de CORS y origen
- Límites de tamaño de mensaje (solicitud de 1MB, respuesta de 10MB)
- Límites de conexión (configurables, predeterminado: 5)
Registro
- Registro JSON estructurado con slog
- Registros conscientes del contexto (espacio de nombres, sesión, ID de solicitud)
- Seguimiento de eventos de conexión
- Registro de eventos de subprocesos
Herramientas de Depuración
- /debug - Panel de control
- /debug/stream - Registro de mensajes en tiempo real
Verificaciones de Salud
- /health - Estado del puente
- /health/{namespace} - Estado por servidor
Métricas de Prometheus
- Endpoint /metrics
- Métricas de solicitudes HTTP (mcp_http_requests_total, mcp_http_request_duration_seconds)
- Métricas de llamadas a herramientas (mcp_tool_calls_total, mcp_tool_calls_duration_seconds, mcp_tool_errors_total)
- Medidor de sesiones activas (mcp_active_sessions)
- Métricas de estado de subprocesos (mcp_subprocess_state)
Transmisión de Depuración Mejorada
- /debug/stream - Registros DEBUG e INFO en tiempo real
- Formato SSE compatible con JSON-RPC 2.0
- No se necesita indicador verbose

🔧 Configuración

Ejemplo de configuración completa:

bridge:
  port: 8080
  allowed_origins:
    - http://localhost:3000
    - http://127.0.0.1:3000
  request_timeout: 30s
  idle_timeout: 5m
  connection_limit: 5
  request_size_limit: 1048576
  response_size_limit: 10485760

servers:
  filesystem:
    name: "filesystem"
    binary: "/usr/bin/node"
    args:
      - "/path/to/mcp-filesystem-server/index.js"
    env:
      HOME: "/home/user"
    timeout: 30s
    max_restarts: 3
    auto_start: true

  git:
    name: "git"
    binary: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-git"
    timeout: 60s
    max_restarts: 5
    auto_start: false

Para opciones de configuración completas, consulte docs/CONFIG.md.

🚀 Inicio Rápido

Compilar
```
cd go-mcp-bridge
make build
```

Configurar Cree config.yaml con la configuración de su servidor MCP:

bridge:
  port: 8080
  allowed_origins:
    - http://localhost:3000

servers:
  git:
    name: "git"
    binary: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-git"

Ejecutar
```
./bin/bridge --config config.yaml
```

Probar

# Health check
curl http://localhost:8080/health

# Send initialize request
curl -X POST http://localhost:8080/mcp/git \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

# Check metrics
curl http://localhost:8080/metrics

# View debug stream
curl http://localhost:8080/debug/stream

📡 Endpoints de API

Endpoint MCP Principal

GET  /mcp/{namespace}          → Start SSE stream
POST /mcp/{namespace}/message  → Send JSON-RPC request

Solicitud de Ejemplo:

curl -X POST http://localhost:8080/mcp/test/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

Verificación de Salud

GET /health              → Bridge health
GET /health/{namespace}  → Namespace health

Endpoint de Depuración

GET /debug               → Debug dashboard (HTML)
GET /debug/stream        → Debug message stream (SSE)

Estructura del Proyecto

go-mcp-bridge/
├── cmd/
│   ├── bridge/main.go       # Main entry point
│   ├── test-server/         # Go test MCP server
│   └── test-mcp-server/     # TypeScript test MCP server
├── internal/
│   ├── config/
│   │   └── loader.go        # YAML config parser
│   ├── mcp/
│   │   ├── handler.go       # Protocol handler
│   │   ├── jsonrpc.go       # JSON-RPC 2.0
│   │   └── types.go         # MCP types
│   ├── process/
│   │   └── manager.go       # Subprocess manager
│   ├── router/
│   │   └── namespace.go     # Namespace routing
│   └── server/
│       ├── http.go          # HTTP server
│       ├── sse.go           # SSE writer
│       └── metrics.go       # Prometheus metrics
├── docs/                    # Documentation
│   ├── CONFIG.md            # Configuration reference
│   ├── API.md               # API specification
│   ├── EXAMPLES.md          # Usage examples
│   ├── DEBUG.md             # Debug endpoint guide
│   └── TESTING.md           # Testing guide
├── testdata/                # Test configurations
├── bin/                     # Built binaries
├── config.yaml              # Configuration
├── Makefile                 # Build automation
├── test-tool-metrics.sh     # Tool metrics test script
└── README.md                # This file

Pruebas

Pruebas Unitarias

# Run all unit tests
go test ./... -v

# Specific package
go test ./internal/mcp/... -v

Prueba de Extremo a Extremo

# Start bridge in background
./bin/bridge --config config.yaml &
BRIDGE_PID=$!

# Run tests
./test.sh

# Stop bridge
kill $BRIDGE_PID

Pruebas de Integración (Completas)

# Test with real subprocess
./test-tool-metrics.sh

# Or run all tests
go test ./... -v

Ramas de Git

master - Estable actual (Todas las fases 1-6 completas)

Hoja de Ruta

✅ Fase 1-2: Arquitectura Principal (COMPLETA)

✅ Servidor de transmisión HTTP
✅ Gestión de subprocesos
✅ Manejo básico de JSON-RPC

✅ Fase 3: Soporte del Protocolo MCP (COMPLETA)

✅ Manejo de JSON-RPC 2.0
✅ Método de inicialización
✅ Herramientas/lista y herramientas/llamada
✅ Correlación solicitud-respuesta

✅ Fase 4: Seguridad y Manejo de Errores (COMPLETA)

✅ Validación de entrada (JSON-RPC, argumentos)
✅ Prevención de inyección de comandos
✅ Límites de recursos (tamaño, conexiones)
✅ Reinicios con retroceso exponencial
✅ Apagado elegante
✅ Registro JSON estructurado

✅ Fase 5: Pruebas y Documentación (COMPLETA)

✅ Pruebas unitarias (45 pruebas)
- Análisis JSON-RPC (20 pruebas)
- Carga de configuración (14 pruebas)
- Enrutamiento de espacios de nombres (11 pruebas)
✅ Pruebas de integración (45+ pruebas)
- Pruebas del servidor HTTP (20+ pruebas)
- Pruebas del gestor de procesos (15+ pruebas)
- Pruebas de aislamiento de espacios de nombres (10 pruebas)
✅ Documentación completa (docs/CONFIG.md, docs/API.md, docs/EXAMPLES.md, docs/DEBUG.md, docs/TESTING.md)

✅ Fase 6: Compilación y Monitoreo (COMPLETA)

✅ 6.1 Métricas de Prometheus (endpoint /metrics)
- ✅ Métricas de solicitudes HTTP (mcp_http_requests_total, mcp_http_request_duration_seconds)
- ✅ Medidor de sesiones activas (mcp_active_sessions)
- ✅ Métricas de estado de subprocesos (mcp_subprocess_state)
- ✅ Métricas de llamadas a herramientas (mcp_tool_calls_total, mcp_tool_calls_duration_seconds, mcp_tool_errors_total)
- ✅ Endpoint de métricas en /metrics
✅ 6.2 Registro estructurado con slog
- ✅ Reemplazar fmt.Printf con slog
- ✅ Registro JSON estructurado
- ✅ Registros conscientes del contexto (espacio de nombres, sesión, request_id)
✅ 6.3 Transmisión de depuración mejorada
- ✅ Transmitir registros DEBUG e INFO a /debug/stream
- ✅ Formato SSE compatible con JSON-RPC 2.0
- ✅ No se necesita indicador verbose
✅ 6.4 Limpieza de configuración
- ✅ Eliminar la configuración no utilizada debug_port
- ✅ Mantener los endpoints de depuración en el puerto principal 8080
✅ 6.5 Script de prueba para métricas de herramientas (test-tool-metrics.sh)
✅ 6.6 Verificación de extremo a extremo del registro de métricas de herramientas

Todas las fases completas a partir de la fusión de la Fase 6 en master.

Compatibilidad

✅ Interfaz web de llama.cpp

Compatible con el transporte StreamableHTTP
Funciona con la compilación más reciente de llama.cpp

✅ SDK MCP

Utiliza el formato estándar JSON-RPC 2.0
Soporta versiones del protocolo MCP:
- 2025-06-18 (más reciente)
- 2025-03-26 (predeterminada)
- 2024-11-05 (compatibilidad hacia atrás)

Servidores MCP Conocidos

Estos servidores se pueden utilizar con el puente:

Git MCP (NPM)

servers:
  git:
    name: "git"
    binary: "npx"
    args: ["-y", "@modelcontextprotocol/server-git"]

Filesystem MCP (uvx)

servers:
  filesystem:
    name: "filesystem"
    binary: "uvx"
    args: ["mcp-server-filesystem", "--allowed-directory", "/data"]

Memory MCP (Docker)

servers:
  memory:
    name: "memory"
    binary: "docker"
    args: ["run", "-i", "mcp/memory-server"]

Binario Personalizado

servers:
  custom:
    name: "custom"
    binary: "./my-mcp-server"
    args: ["--port", "8080"]

Consulte EXAMPLES.md para más ejemplos de configuración.

Solución de Problemas

El subproceso no se inicia

Verifique que la ruta del binario sea correcta: which npx
Verifique que el binario sea ejecutable: chmod +x ./bin/test-server
Verifique las variables de entorno en la configuración
Revise los registros estructurados para ver errores

La conexión falla

Verifique que el espacio de nombres exista en la configuración
Verifique que allowed_origins incluya el origen del cliente
Revise /debug/stream para errores en tiempo real
Verifique /health/{namespace} para el estado del subproceso

Los mensajes no se transmiten

Asegúrese de que el subproceso envíe JSON-RPC a la salida estándar
Verifique la terminación de nueva línea en los mensajes (\n)
Verifique que los encabezados SSE estén configurados correctamente
Use /debug/stream para ver los mensajes sin procesar

Recuento alto de reinicios

Revise los registros del subproceso para ver errores
Aumente el tiempo de espera si el subproceso es lento
Verifique que los argumentos sean correctos
Verifique los límites de recursos

Errores de seguridad

Verifique la sanitización de argumentos
Verifique los hosts/orígenes permitidos
Asegúrese de que la ruta del binario sea segura (sin inyección de shell)

Documentación

Documento	Descripción
docs/CONFIG.md	Referencia completa de configuración
docs/API.md	Especificación de la API HTTP
docs/EXAMPLES.md	Ejemplos de uso y configuraciones
docs/DEBUG.md	Guía del endpoint de depuración
docs/TESTING.md	Guía de pruebas e infraestructura de pruebas

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

Cree una rama de características
Agregue pruebas para la nueva funcionalidad
Actualice la documentación
Envíe una solicitud de extracción

Licencia

MIT