MCP Spine

Minificador de Contexto e Guardião de Estado — Proxy de middleware MCP local que reduz o desperdício de tokens em 61%, previne a deterioração do contexto e adiciona reforço de segurança.

GitHub

Documentação

MCP Spine

A camada de middleware que falta ao MCP. Segurança, roteamento, controle de tokens e conformidade — entre seu LLM e suas ferramentas.

MCP Spine é um proxy local-first que fica entre o Claude Desktop (ou qualquer cliente MCP) e seus servidores MCP. Uma configuração, um ponto de entrada, controle total sobre o que entra, o que sai e o que é registrado.

57 ferramentas em 5 servidores. Um proxy. Zero tokens desperdiçados.

O Problema

Você conectou o Claude ao GitHub, Slack, seu banco de dados, seu sistema de arquivos. Agora você tem 40+ ferramentas carregadas, milhares de tokens queimados em schemas a cada turno, sem trilha de auditoria, sem limites de taxa e sem como impedir o LLM de ler as DMs do seu chefe. O MCP dá poder aos agentes. O Spine dá controle a você.

O Que Ele Faz

Camada	O que resolve
Security Proxy	Rate limiting, limpeza de segredos, jails de caminho, trilha de auditoria HMAC
Semantic Router	Apenas ferramentas relevantes chegam ao LLM — embeddings locais, sem chamadas de API
Schema Minifier	Economia de 61% de tokens ao remover campos desnecessários de schema
State Guard	Pins de arquivo SHA-256 impedem o LLM de editar versões desatualizadas
Token Budget	Limites diários com aplicação de aviso/bloqueio e rastreamento persistente
Plugin System	Hooks de middleware personalizados — filtrar, transformar, bloquear por ferramenta
HITL Confirmation	Ferramentas destrutivas pausam para aprovação humana antes de executar
Injection Detection	Verifica respostas de ferramentas em busca de injeção de prompt antes de chegarem ao LLM
Multi-User Audit	Trilha de auditoria com tags de sessão para implantações compartilhadas
Tool Caching	Cache LRU para ferramentas somente leitura — evita chamadas downstream redundantes
Webhook Alerts	Notificações Slack/Discord/JSON em eventos de segurança e avisos de orçamento
Web Dashboard	Monitoramento baseado em navegador com estatísticas ao vivo, rastreamento de latência, log de requisições

Demonstração

MCP Spine Doctor

Roda em Windows, macOS e Linux. Testado em CI nos três.

Painel Web

MCP Spine Web Dashboard

mcp-spine web --db spine_audit.db

Instalação

pip install mcp-spine

# With semantic routing (optional)
pip install mcp-spine[ml]

Início Rápido

# Interactive setup wizard — detects your servers, asks about features
mcp-spine init

# Or quick default config
mcp-spine init --quick

# Check everything works
mcp-spine doctor --config spine.toml

# Start the proxy
mcp-spine serve --config spine.toml

# Open the web dashboard
mcp-spine web --db spine_audit.db

# Export analytics
mcp-spine export --format csv --hours 24 --output report.csv

Integração com Claude Desktop

Substitua todas as entradas individuais de servidor MCP por uma única entrada do Spine:

{
  "mcpServers": {
    "spine": {
      "command": "python",
      "args": ["-m", "spine.cli", "serve", "--config", "/path/to/spine.toml"],
      "cwd": "/path/to/mcp-spine"
    }
  }
}

Recursos

Security Proxy (Estágio 1)

Validação e sanitização de mensagens JSON-RPC
Limpeza de segredos (chaves AWS, tokens GitHub, bearer tokens, chaves privadas, strings de conexão)
Rate limiting por ferramenta e global com janelas deslizantes
Prevenção de path traversal com jail ciente de symlinks
Proteções contra injeção de comandos na inicialização de servidores
Trilha de auditoria SQLite com fingerprint HMAC
Circuit breakers em servidores com falhas
Políticas de segurança declarativas a partir da configuração

Semantic Router (Estágio 2)

Embeddings vetoriais locais usando all-MiniLM-L6-v2 (sem chamadas de API, nenhum dado sai da sua máquina)
Indexação de ferramentas com ChromaDB
Roteamento no momento da consulta: apenas as ferramentas mais relevantes são enviadas ao LLM
Meta-ferramenta spine_set_context para troca explícita de contexto
Reordenação por sobreposição de palavras-chave + reforço de recência
Carregamento de modelo em segundo plano — ferramentas funcionam imediatamente, roteamento ativa quando pronto

Schema Minification (Estágio 3)

4 níveis de agressividade (0=desligado, 1=leve, 2=padrão, 3=agressivo)
Nível 2 alcança economia de 61% de tokens em schemas de ferramentas
Remove $schema, títulos, additionalProperties, descrições de parâmetros, valores padrão
Preserva todos os campos obrigatórios e informações de tipo
Economia de tokens rastreada na trilha de auditoria e visível no painel web

State Guard (Estágio 4)

Monitora arquivos do projeto via watchfiles
Mantém manifesto SHA-256 com versionamento monotônico
Injeta pins de estado compactos nas respostas das ferramentas
Impede que LLMs editem versões desatualizadas de arquivos

Human-in-the-Loop

Flag de política require_confirmation para ferramentas destrutivas
O Spine intercepta a chamada, mostra os argumentos e aguarda aprovação do usuário
Meta-ferramentas spine_confirm / spine_deny para o LLM transmitir a decisão
Granularidade por ferramenta via padrões glob

Memória de Saída de Ferramentas

Ring buffer armazenando em cache os últimos 50 resultados de ferramentas
Deduplicação por nome da ferramenta + hash de argumentos
Expiração por TTL (1 hora padrão)
Meta-ferramenta spine_recall para consultar resultados em cache
Evita perda de contexto quando o semantic router troca ferramentas entre turnos

Orçamento de Tokens

Rastreamento diário do consumo de tokens em todas as chamadas de ferramentas
Limite diário configurável com ações de aviso/bloqueio
Limites de tokens por servidor para controle de custos
Armazenamento persistente em SQLite (sobrevive a reinicializações no mesmo dia)
Reinício automático à meia-noite
Meta-ferramenta spine_budget para verificar o uso no meio da conversa

Sistema de Plugins

Plugins Python drop-in que se conectam ao pipeline de chamadas de ferramentas
Quatro pontos de hook: on_tool_call, on_tool_response, on_tool_list, on_startup/on_shutdown
Plugins podem transformar argumentos, filtrar respostas, bloquear chamadas ou ocultar ferramentas
Encadeamento de plugins — múltiplos plugins executam em sequência
Listas de permitir/negar para controle de acesso de plugins
Descoberta automática a partir de um diretório de plugins configurável
Exemplo incluído: filtro de conformidade de canal do Slack

Detecção de Injeção de Prompt

Verifica todas as respostas de ferramentas antes de chegarem ao LLM
Detecta sobrescritas de system prompt, injeção de papéis, sequestro de instruções, tentativas de jailbreak
Detecta URLs de exfiltração de dados e payloads codificados
Ação configurável: registrar, remover ou bloquear
Todas as detecções são registradas como eventos de segurança e enviadas via webhooks

Aliasing de Ferramentas

Renomeie ferramentas para que o LLM veja nomes mais limpos
create_or_update_file → edit_github_file
Aliases resolvidos de forma transparente — servidores downstream veem os nomes originais

Cache de Respostas de Ferramentas

Cache LRU para ferramentas somente leitura (padrões configuráveis)
Cache hits pulam completamente a chamada downstream
Expiração baseada em TTL (5 minutos padrão)
Invalidação automática em estouro de cache

Hot-Reload de Configuração

Edite spine.toml enquanto o Spine está em execução — as alterações são aplicadas em segundos
Hot-reloadable: nível do minifier, rate limits, políticas de segurança, orçamento de tokens, padrões do state guard
Não recarregável (requer reinicialização): lista de servidores, comandos, caminho do banco de auditoria
Todos os reloads são registrados na trilha de auditoria

Auditoria Multi-Usuário

ID de sessão único gerado por conexão de cliente
Nome e versão do cliente extraídos do handshake MCP
Todas as entradas de auditoria marcadas com ID de sessão
mcp-spine audit --sessions lista todas as sessões de clientes
mcp-spine audit --session <id> filtra entradas por sessão

Notificações Webhook

Envia alertas POST para Slack, Discord ou qualquer endpoint JSON
Gatilhos: eventos de segurança, avisos de orçamento, orçamento excedido, ferramenta bloqueada, rate limit
Payloads pré-formatados para blocos do Slack e embeds do Discord
Não bloqueante (threads em segundo plano)

Monitoramento de Latência

Rastreia tempos de resposta por servidor (janela deslizante)
Avisa quando a latência média excede o limite (padrão 5s)
Painel de latência de servidores no painel web com status OK/SLOW

Exportação de Analytics

mcp-spine export --format csv ou --format json
Filtrar por horas, tipo de evento
Saída para arquivo ou stdout para piping

Suporte a Transporte

stdio — servidores locais via subprocesso (filesystem, GitHub, SQLite, etc.)
SSE — servidores remotos legados via HTTP/Server-Sent Events
Streamable HTTP — especificação MCP 2025-03-26, transporte bidirecional de endpoint único com gerenciamento de sessão
Todos os transportes compartilham o mesmo pipeline de segurança, roteamento e auditoria

Painel Web

Monitoramento baseado em navegador em localhost:8777
Cartões de estatísticas ao vivo: chamadas de ferramentas, eventos de segurança, sessões, orçamento de tokens, economia de tokens
Chamadas de ferramentas recentes com servidor, sessão e status
Gráfico de barras de uso de ferramentas
Tabela de latência de servidores com média/máx e status OK/SLOW
Log completo de requisições/respostas com duração e contagem de tokens
Tabelas de eventos de segurança e sessões de clientes
Atualização automática a cada 3 segundos
Zero dependências (stdlib Python http.server)

Diagnóstico

# Check your setup
mcp-spine doctor --config spine.toml

# Live TUI monitoring
mcp-spine dashboard

# Web dashboard
mcp-spine web --db spine_audit.db

# Usage analytics (includes token budget)
mcp-spine analytics --hours 24

# Export data
mcp-spine export --format csv --hours 168 --output weekly.csv

# Query audit log
mcp-spine audit --last 50
mcp-spine audit --security-only
mcp-spine audit --tool write_file
mcp-spine audit --sessions
mcp-spine audit --session <session-id>

Exemplo de Configuração

[spine]
log_level = "info"
audit_db = "spine_audit.db"

# Downstream servers — start concurrently
[[servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
timeout_seconds = 120

[[servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_..." }
timeout_seconds = 180

[[servers]]
name = "sqlite"
command = "uvx"
args = ["mcp-server-sqlite", "--db-path", "/path/to/database.db"]
timeout_seconds = 60

[[servers]]
name = "memory"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]
timeout_seconds = 60

[[servers]]
name = "brave-search"
command = "node"
args = ["/path/to/server-brave-search/dist/index.js"]
env = { BRAVE_API_KEY = "your_key" }
token_limit = 100000  # per-server daily budget
timeout_seconds = 60

# Remote server via Streamable HTTP (MCP 2025-03-26)
# [[servers]]
# name = "remote-api"
# transport = "streamable-http"
# url = "https://your-server.com/mcp"
# headers = { Authorization = "Bearer token" }

# Semantic routing
[routing]
max_tools = 15
rerank = true

# Schema minification — 61% token savings at level 2
[minifier]
level = 2

# Token budget
[token_budget]
daily_limit = 500000
warn_at = 0.8
action = "warn"

# Tool aliasing
[tool_aliases]
enabled = true
aliases = { "create_or_update_file" = "edit_github_file" }

# Tool response caching
[tool_cache]
enabled = true
cacheable_tools = ["read_file", "read_query", "list_directory"]
ttl_seconds = 300

# State guard
[state_guard]
enabled = true
watch_paths = ["/path/to/project"]

# Plugins
[plugins]
enabled = true
directory = "plugins"

# Webhooks
[webhooks]
enabled = true

[[webhooks.hooks]]
url = "https://hooks.slack.com/services/T.../B.../xxx"
events = ["security", "budget_warn"]
format = "slack"

# Human-in-the-loop
[[security.tools]]
pattern = "write_file"
action = "allow"
require_confirmation = true

[[security.tools]]
pattern = "write_query"
action = "allow"
require_confirmation = true

# Security
[security]
scrub_secrets_in_logs = true
audit_all_tool_calls = true
global_rate_limit = 120
per_tool_rate_limit = 60

[security.path]
allowed_roots = ["/path/to/project"]
denied_patterns = ["**/.env", "**/*.key", "**/*.pem"]

Modelo de Segurança

Defesa em profundidade — cada camada assume que as outras podem falhar.

Ameaça	Mitigação
Injeção de prompt via respostas de ferramentas	Detecção automatizada de padrões (8 categorias), registrar/remover/bloquear
Injeção de prompt via argumentos de ferramentas	Validação de entrada, allowlists de nomes de ferramentas
Path traversal	Jail ciente de symlinks para `allowed_roots`
Vazamento de segredos	Limpeza automática de chaves AWS, tokens, chaves privadas
Loops de agente descontrolados	Rate limiting por ferramenta + global
Injeção de comandos	Allowlist de comandos, bloqueio de metacaracteres de shell
Negação de serviço	Limites de tamanho de mensagem, circuit breakers
Acesso a arquivos sensíveis	Padrões de deny-list para `.env`, `.key`, `.pem`, `.ssh/`
Abuso de ferramentas	Bloqueio baseado em políticas, registro de auditoria, confirmação HITL
Adulteração de logs	Fingerprints HMAC em cada entrada de auditoria
Operações destrutivas	`require_confirmation` pausa para aprovação do usuário
Gasto descontrolado de tokens	Limites diários de orçamento com aviso/bloqueio + limites por servidor
Plugins não verificados	Listas de permitir/negar, isolamento de diretório, registro de auditoria
Exposição de dados sensíveis	Filtragem de respostas baseada em plugins (ex.: conformidade do Slack)
Degradação de servidores	Monitoramento de latência com alertas automáticos

Arquitetura

Client ◄──stdio──► MCP Spine ◄──stdio────────► Filesystem Server
                       │      ◄──stdio────────► GitHub Server
                       │      ◄──stdio────────► SQLite Server
                       │      ◄──stdio────────► Memory Server
                       │      ◄──stdio────────► Brave Search
                       │      ◄──SSE──────────► Legacy Remote
                       │      ◄──Streamable HTTP──► Modern Remote
                   ┌───┴───┐
                   │SecPol │  ← Rate limits, path jail, secret scrub
                   │Inject │  ← Prompt injection detection
                   │Router │  ← Semantic routing (local embeddings)
                   │Minify │  ← Schema compression (61% savings)
                   │Cache  │  ← Tool response caching (LRU + TTL)
                   │Guard  │  ← File state pinning (SHA-256)
                   │HITL   │  ← Human-in-the-loop confirmation
                   │Memory │  ← Tool output cache
                   │Budget │  ← Daily token tracking + limits
                   │Plugin │  ← Custom middleware hooks
                   │Audit  │  ← Session-tagged multi-user trail
                   │Hooks  │  ← Webhook notifications
                   └───────┘

Sequência de Inicialização

Handshake instantâneo (~2ms) — Responde a initialize imediatamente
Inicialização concorrente de servidores — Todos os servidores conectam em paralelo via asyncio.gather
Prontidão progressiva — Ferramentas disponíveis assim que qualquer servidor conecta
Notificação de servidor tardio — tools/listChanged enviado quando servidores lentos terminam
Carregamento de ML em segundo plano — Semantic router ativa silenciosamente quando o modelo carrega

Suporte a Windows

Testado em batalha no Windows com endurecimento específico para:

Caminhos de sandbox MSIX para configuração e logs do Claude Desktop
Resolução de npx.cmd via shutil.which()
Caminhos com espaços (C:\Users\John Doe\) e parênteses (C:\Program Files (x86)\)
PureWindowsPath para extração de basename multiplataforma
Mesclagem de variáveis de ambiente (env da configuração estende, não substitui, o env do sistema)
Codificação UTF-8 sem BOM
stdout sem buffer (flag -u) para evitar travamentos de pipe

Estrutura do Projeto

mcp-spine/
├── pyproject.toml
├── spine/
│   ├── cli.py              # CLI: init, serve, verify, audit, dashboard, analytics, doctor, web, export
│   ├── config.py           # TOML config loader with validation
│   ├── proxy.py            # Core proxy event loop
│   ├── protocol.py         # JSON-RPC message handling
│   ├── transport.py        # Server pool, circuit breakers, concurrent startup
│   ├── audit.py            # Structured logging + SQLite audit trail + sessions
│   ├── router.py           # Semantic routing (ChromaDB + sentence-transformers)
│   ├── minifier.py         # Schema pruning (4 aggression levels)
│   ├── state_guard.py      # File watcher + SHA-256 manifest + pin injection
│   ├── memory.py           # Tool output cache (ring buffer + dedup + TTL)
│   ├── budget.py           # Token budget tracker (daily limits + persistence)
│   ├── plugins.py          # Plugin system (hooks, discovery, chaining)
│   ├── injection.py        # Prompt injection detection (8 pattern categories)
│   ├── tool_cache.py       # Tool response caching (LRU + TTL)
│   ├── webhooks.py         # Webhook notifications (Slack, Discord, JSON)
│   ├── dashboard.py        # Live TUI dashboard (Rich)
│   ├── web_dashboard.py    # Browser-based web dashboard
│   ├── sse_client.py       # SSE transport client (legacy)
│   ├── streamable_http.py  # Streamable HTTP transport (MCP 2025-03-26)
│   └── security/
│       ├── secrets.py      # Credential detection & scrubbing
│       ├── paths.py        # Path traversal jail
│       ├── validation.py   # JSON-RPC message validation
│       ├── commands.py     # Server spawn guards
│       ├── rate_limit.py   # Sliding window throttling
│       ├── integrity.py    # SHA-256 + HMAC fingerprints
│       ├── env.py          # Fail-closed env var resolution
│       └── policy.py       # Declarative security policies
├── tests/
│   ├── test_security.py
│   ├── test_config.py
│   ├── test_minifier.py
│   ├── test_state_guard.py
│   ├── test_proxy_features.py
│   ├── test_memory.py
│   ├── test_budget.py
│   └── test_plugins.py
├── examples/
│   └── slack_filter.py     # Example: Slack compliance filter plugin
├── configs/
│   └── example.spine.toml
└── .github/
    └── workflows/
        └── ci.yml

Testes

pytest tests/ -v

190+ testes. CI em Windows + Linux, Python 3.11/3.12/3.13.

Licença

MIT