mpc-bridge

fluxo http para stdin/stdout e de volta

Documentação

Documentação Mestre do Go MCP HTTP Bridge

Visão Geral

Um aplicativo Go que encapsula servidores MCP (Model Context Protocol) com streaming HTTP (SSE), totalmente compatível com o transporte StreamableHTTP do llama.cpp. Este bridge permite que clientes MCP baseados na web se comuniquem com servidores MCP baseados em subprocessos.

Arquitetura

┌─────────────────┐
│   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          │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

Recursos

✅ Implementado (Todas as Fases 1-6 Concluídas)

Servidor de Streaming HTTP
- Streaming SSE (GET /mcp/{namespace})
- Endpoint HTTP POST (POST /mcp/{namespace}/message)
- Suporte adequado a CORS
- Gerenciamento do ciclo de vida da conexão
Gerenciamento de Subprocessos
- Inicialização sob demanda
- Reutilização de conexões
- Reinicializações com backoff exponencial (1s, 2s, 4s... até 60s)
- Desligamento gracioso (tratamento de SIGTERM/SIGINT)
- Rastreamento de estado do processo
JSON-RPC 2.0
- Análise de requisição/resposta
- Validação de mensagens
- Tratamento de erros
- Suporte a notificações
Suporte ao Protocolo MCP
- initialize - Handshake com informações do servidor
- tools/list - Listar ferramentas disponíveis
- tools/call - Executar ferramentas
- ping - Verificação de integridade
Segurança
- Validação de entrada (JSON-RPC, argumentos)
- Prevenção de injeção de comandos
- Validação de CORS e origem
- Limites de tamanho de mensagem (1MB requisição, 10MB resposta)
- Limites de conexão (configuráveis, padrão: 5)
Registro de Logs
- Registro estruturado em JSON com slog
- Logs com contexto (namespace, sessão, ID de requisição)
- Rastreamento de eventos de conexão
- Registro de eventos de subprocesso
Ferramentas de Depuração
- /debug - Painel de controle
- /debug/stream - Log de mensagens em tempo real
Verificações de Integridade
- /health - Status do bridge
- /health/{namespace} - Status por servidor
Métricas Prometheus
- Endpoint /metrics
- Métricas de requisições HTTP (mcp_http_requests_total, mcp_http_request_duration_seconds)
- Métricas de chamadas de ferramentas (mcp_tool_calls_total, mcp_tool_calls_duration_seconds, mcp_tool_errors_total)
- Medidor de sessões ativas (mcp_active_sessions)
- Métricas de estado do subprocesso (mcp_subprocess_state)
Streaming de Depuração Aprimorado
- /debug/stream - Logs DEBUG e INFO em tempo real
- Formato SSE compatível com JSON-RPC 2.0
- Nenhum sinalizador verbose necessário

🔧 Configuração

Exemplo completo de configuração:

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 opções completas de configuração, consulte docs/CONFIG.md.

🚀 Início Rápido

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

Configurar Crie config.yaml com as configurações do seu servidor MCP:

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

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

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

Testar

# 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 da API

Endpoint MCP Principal

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

Exemplo de Requisição:

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

Verificação de Integridade

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

Endpoint de Depuração

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

Estrutura do Projeto

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

Testes

Testes Unitários

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

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

Teste de Ponta a Ponta

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

# Run tests
./test.sh

# Stop bridge
kill $BRIDGE_PID

Testes de Integração (Completos)

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

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

Ramificações Git

master - Estável atual (Todas as fases 1-6 concluídas)

Roteiro

✅ Fase 1-2: Arquitetura Principal (CONCLUÍDA)

✅ Servidor de streaming HTTP
✅ Gerenciamento de subprocessos
✅ Tratamento básico de JSON-RPC

✅ Fase 3: Suporte ao Protocolo MCP (CONCLUÍDA)

✅ Tratamento de JSON-RPC 2.0
✅ Método de inicialização
✅ Tools/list e tools/call
✅ Correlação requisição-resposta

✅ Fase 4: Segurança e Tratamento de Erros (CONCLUÍDA)

✅ Validação de entrada (JSON-RPC, argumentos)
✅ Prevenção de injeção de comandos
✅ Limites de recursos (tamanho, conexões)
✅ Reinicializações com backoff exponencial
✅ Desligamento gracioso
✅ Registro estruturado em JSON

✅ Fase 5: Testes e Documentação (CONCLUÍDA)

✅ Testes unitários (45 testes)
- Análise de JSON-RPC (20 testes)
- Carregamento de configuração (14 testes)
- Roteamento de namespace (11 testes)
✅ Testes de integração (45+ testes)
- Testes do servidor HTTP (20+ testes)
- Testes do gerenciador de processos (15+ testes)
- Testes de isolamento de namespace (10 testes)
✅ Documentação completa (docs/CONFIG.md, docs/API.md, docs/EXAMPLES.md, docs/DEBUG.md, docs/TESTING.md)

✅ Fase 6: Compilação e Monitoramento (CONCLUÍDA)

✅ 6.1 Métricas Prometheus (endpoint /metrics)
- ✅ Métricas de requisições HTTP (mcp_http_requests_total, mcp_http_request_duration_seconds)
- ✅ Medidor de sessões ativas (mcp_active_sessions)
- ✅ Métricas de estado do subprocesso (mcp_subprocess_state)
- ✅ Métricas de chamadas de ferramentas (mcp_tool_calls_total, mcp_tool_calls_duration_seconds, mcp_tool_errors_total)
- ✅ Endpoint de métricas em /metrics
✅ 6.2 Registro estruturado com slog
- ✅ Substituir fmt.Printf por slog
- ✅ Registro estruturado em JSON
- ✅ Logs com contexto (namespace, sessão, request_id)
✅ 6.3 Streaming de depuração aprimorado
- ✅ Transmitir logs DEBUG e INFO para /debug/stream
- ✅ Formato SSE compatível com JSON-RPC 2.0
- ✅ Nenhum sinalizador verbose necessário
✅ 6.4 Limpeza de configuração
- ✅ Remover configuração não utilizada de debug_port
- ✅ Manter endpoints de depuração na porta principal 8080
✅ 6.5 Script de teste para métricas de ferramentas (test-tool-metrics.sh)
✅ 6.6 Verificação de ponta a ponta do registro de métricas de ferramentas

Todas as fases concluídas a partir da Fase 6 mesclada no master.

Compatibilidade

✅ Interface web do llama.cpp

Compatível com transporte StreamableHTTP
Funciona com a versão mais recente do llama.cpp

✅ SDK MCP

Usa formato padrão JSON-RPC 2.0
Suporta versões do protocolo MCP:
- 2025-06-18 (mais recente)
- 2025-03-26 (padrão)
- 2024-11-05 (compatibilidade retroativa)

Servidores MCP Conhecidos

Estes servidores podem ser usados com o bridge:

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"]

Binário Personalizado

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

Consulte EXAMPLES.md para mais exemplos de configuração.

Solução de Problemas

Subprocesso não inicia

Verifique se o caminho do binário está correto: which npx
Verifique se o binário é executável: chmod +x ./bin/test-server
Verifique as variáveis de ambiente na configuração
Observe os logs estruturados para erros

Falha na conexão

Verifique se o namespace existe na configuração
Verifique se allowed_origins inclui a origem do cliente
Observe /debug/stream para erros em tempo real
Verifique /health/{namespace} para o status do subprocesso

Mensagens não estão sendo transmitidas

Garanta que o subprocesso emita JSON-RPC para stdout
Verifique a terminação de nova linha nas mensagens (\n)
Verifique se os cabeçalhos SSE estão configurados corretamente
Use /debug/stream para ver mensagens brutas

Contagem alta de reinicializações

Verifique os logs do subprocesso para erros
Aumente o timeout se o subprocesso estiver lento
Verifique se os argumentos estão corretos
Verifique os limites de recursos

Erros de segurança

Verifique a sanitização de argumentos
Verifique hosts/origens permitidos
Garanta que o caminho do binário seja seguro (sem injeção de shell)

Documentação

Documento	Descrição
docs/CONFIG.md	Referência completa de configuração
docs/API.md	Especificação da API HTTP
docs/EXAMPLES.md	Exemplos de uso e configurações
docs/DEBUG.md	Guia do endpoint de depuração
docs/TESTING.md	Guia de testes e infraestrutura de testes

Contribuição

Contribuições são bem-vindas! Por favor:

Crie uma ramificação de recurso
Adicione testes para novas funcionalidades
Atualize a documentação
Envie um pull request

Licença

MIT