mcp-slim-guard

MCP Slim Guard

O MCP Slim Guard oferece ao host uma forma deliberada de acessar ferramentas upstream autorizadas. Ele mantém os schemas de entrada intactos, valida chamadas antes de o upstream ser invocado e pode recuperar um resultado superdimensionado exatamente sem repetir essa invocação.

Escolha um modo

Modo	O que o host vê	Melhor adequação
Nativo	Nomes de ferramentas originais autorizados e schemas completos, além de read_result	Hosts que funcionam bem com um catálogo MCP normal, incluindo Codex
Compacto	find_tool, call_tool e read_result; a descoberta retorna o schema original completo de cada correspondência	Uma superfície de host pequena e previsível
Extremo	A superfície e os schemas de ferramentas do Compacto; apenas resultados suficientemente grandes recebem uma primeira entrega recuperável mais curta	Hosts sensíveis ao contexto em que um primeiro resultado menor é valioso

Compacto é o padrão para start. Nativo é o plano de instalação padrão para Codex. Compacto é o padrão para Claude Code; o Claude Code suporta planos de instalação Compacto e Extremo, não o Nativo.

Todos os modos aplicam a mesma autorização de permitir/negar. Compacto e Extremo retornam no máximo três correspondências de descoberta, cada uma com os campos obrigatórios originais, enums e schema aninhado. Uma chamada é validada contra esse schema original antes de o servidor upstream ser contatado.

find_tool rejeita campos desconhecidos e consultas com mais de 256 pontos de código Unicode localmente. Ele pesquisa apenas o catálogo autorizado atual e nunca recorre a uma entrada não autorizada.

Início rápido

0.1.1-alpha.2 é um candidato a fonte e ainda não foi publicado no npm. A partir de um checkout revisado deste candidato:

npm ci
npm run build
npm link
cd /path/to/project-with-mcp-config
mcp-slim-guard init
mcp-slim-guard validate

# Run the default Compact mode.
mcp-slim-guard start

init grava mcp-slim-guard.yml com a versão 2. O arquivo contém apenas configurações de upstream e segurança. Selecione um modo no comando do host, não no YAML.

# Inspect a host-specific plan without changing host files.
mcp-slim-guard plan --host codex
mcp-slim-guard plan --host claude-code --mode extreme

# Verify the configured runtime without changing Host configuration or calling a business Tool.
mcp-slim-guard verify --host codex

# Apply a reviewed plan.
mcp-slim-guard install --host codex --mode native

Entradas do host

Para Codex, use Nativo quando quiser o catálogo MCP autorizado normal:

[mcp_servers.slim_guard]
command = "mcp-slim-guard"
args = ["start", "--mode", "native"]
cwd = "/absolute/path/to/project"

Para Claude Code, use Compacto por padrão:

{
  "mcpServers": {
    "slim-guard": {
      "command": "mcp-slim-guard",
      "args": ["start", "--mode", "compact"],
      "cwd": "/absolute/path/to/project"
    }
  }
}

Consulte configuração do host para as etapas completas de configuração e verificação.

Configuração

version: 2
tools:
  allow:
    - "upstream_*"
  deny:
    - "*_delete_*"
ssrf:
  mode: block
  block_private_ips: true
  allow_domains: []
  block_domains: []
rate_limit:
  default: "60/min"
injection_detection:
  enabled: true
  sensitivity: medium
  mode: block
audit:
  output: file
  filePath: mcp-slim-guard-audit.log
servers:
  upstream:
    command: npx
    args: ["-y", "@your/mcp-server"]

A configuração da versão 1 não é suportada intencionalmente. A seção removida compressor é rejeitada em vez de migrada automaticamente.

Corrigir uma chamada inválida

Se os argumentos não corresponderem ao schema original de uma ferramenta autorizada, o Slim Guard retorna um erro normal de ferramenta MCP com structuredContent que identifica a falha do schema e confirma que a ferramenta upstream não foi invocada. Corrija os argumentos e tente novamente; os valores de argumentos enviados não são ecoados nesse erro.

Recuperação de resultados

Quando uma resposta precisa de entrega recuperável, a primeira resposta inclui um result_ref. Use read_result com query para localizar até três fragmentos locais limitados, ou omita query e siga next_cursor para recuperar o snapshot exato. Ambos os caminhos usam a mesma captura imutável e nunca invocam a ferramenta upstream novamente. Não combine query com cursor. Nativo e Compacto usam o limite de entrega padrão. Extremo usa um limite menor apenas quando a resposta entregue inicialmente tem pelo menos metade do tamanho da resposta exata; caso contrário, ele passa a resposta exata sem alterações.

Evidências e verificações

O repositório inclui uma comparação de modos com 24 tarefas, fixtures de recuperação de resultados e um fixture de estresse com 100 ferramentas / 8.000 linhas. Execute os artefatos atuais com:

npm run build
npm run bench:task
npm run bench:compression
npm run bench:stress
npm run bench:compression:verify

Seus relatórios são específicos de cada modo e são gerados localmente; não trate figuras de benchmark alfa antigas como alegações para esta linha de produtos.

Desenvolvimento

npm run build
npm run typecheck
npm run lint
npm test
npm run verify:package-boundary
npm run smoke:package

Este projeto é um alfa. Revise os padrões de autorização e as configurações de upstream antes de usá-lo com ferramentas privilegiadas.