mcp-shield

mcp-shield

O nginx do MCP — middleware de resiliência plug-and-play para qualquer servidor MCP.

Timeout · Retry · Circuit Breaker · Logging Estruturado

---

Por quê

Servidores MCP têm zero resiliência embutida. Uma API do GitHub travada bloqueia seu agente por 600 segundos. Uma falha de rede transitória derruba toda a cadeia. Um servidor morto continua sendo bombardeado com requisições.

mcp-shield é um proxy stdio transparente que fica entre seu agente e o servidor MCP. Um comando, zero mudanças de código.

Agent ←stdio→ mcp-shield ←stdio→ MCP Server

Instalação

npm install -g @daino/mcp-shield

Ou execute diretamente com npx:

npx @daino/mcp-shield wrap -- npx @modelcontextprotocol/server-github

Início Rápido

# Wrap any MCP server with sensible defaults (30s timeout, 2 retries)
mcp-shield wrap -- npx @modelcontextprotocol/server-github

# Custom timeout and retries
mcp-shield wrap --timeout 60s --retries 5 -- npx server-github

# Using a config file
mcp-shield wrap --config mcp-shield.yaml --server github

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "@daino/mcp-shield", "wrap",
        "--timeout", "30s", "--retries", "3",
        "--",
        "npx", "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    }
  }
}

Pronto. Seu servidor MCP do GitHub agora tem proteção com timeout, retry e circuit breaker.

Recursos

Timeout

Elimine chamadas de ferramentas travadas. Chega de esperas de 600 segundos.

timeout: 30s  # per-tool override available

Retry

Backoff exponencial + jitter. Erros determinísticos (parâmetros inválidos, método não encontrado) nunca são repetidos.

retries:
  max: 3
  backoff: exponential  # 1s → 2s → 4s
  jitter: true

Circuit Breaker

Após falhas repetidas, falhe rapidamente em vez de queimar tokens em um servidor morto.

circuit_breaker:
  threshold: 5      # open after 5 consecutive failures
  reset_after: 60s  # try again after 60 seconds

Estados: Fechado (normal) → Aberto (rejeitando) → Meio-aberto (testando)

Logging Estruturado

Cada chamada de ferramenta registrada como JSON estruturado no stderr:

{
  "level": "info",
  "msg": "tool_call_end",
  "server": "github",
  "tool": "get_file_contents",
  "duration_ms": 245,
  "status": "success",
  "attempt": 1
}

Arquivo de Configuração

Para configurações com vários servidores:

# mcp-shield.yaml
defaults:
  timeout: 30s
  retries:
    max: 3
    backoff: exponential
    jitter: true
  circuit_breaker:
    threshold: 5
    reset_after: 60s

servers:
  github:
    command: "npx @modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    tools:
      get_file_contents:
        timeout: 60s          # slow tool gets more time
      search_repositories:
        retries:
          max: 5              # flaky tool gets more retries

  filesystem:
    command: "npx @modelcontextprotocol/server-filesystem /home/user"
    timeout: 10s
    retries:
      max: 1

Uso Programático

import { shield } from '@daino/mcp-shield';

const proxy = shield({
  command: 'npx',
  args: ['@modelcontextprotocol/server-github'],
  timeout: 30_000,
  retries: { max: 3, backoff: 'exponential', jitter: true },
  circuitBreaker: { threshold: 5, resetAfter: 60_000 },
});

proxy.start();

Comparação

	mcp-shield	Sem proteção	Bibliotecas de retry genéricas
Nativo MCP (ciente de JSON-RPC)	✅	—	❌
Configuração por ferramenta	✅	—	❌
Zero mudanças no código do agente	✅	—	❌
Circuit breaker	✅	❌	✅
Logging MCP estruturado	✅	❌	❌
Suporte plug-and-play para Claude Desktop	✅	—	❌

Roadmap

• Timeout + Retry + Circuit Breaker + Logging
• Validação de Resposta (verificação de esquema)
• Filtragem de Ferramentas (expor apenas ferramentas específicas)
• Limitação de Taxa (limites de chamadas por ferramenta)
• Exportação de Métricas (compatível com Prometheus)
• Composição Multi-servidor
• Configuração com recarga a quente
• Interface de Painel

Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue primeiro para discutir o que você gostaria de mudar.

git clone https://github.com/DainoJung/mcp-shield.git
cd mcp-shield
npm install
npm test

Licença

MIT