MCP Spine

Minificador de contexto y protector de estado — Un proxy de middleware MCP local-first que reduce el desperdicio de tokens, evita la deserción de herramientas y elimina la degradación del contexto.

MCP Spine se sitúa entre tu cliente LLM (Claude Desktop, etc.) y tus servidores MCP, proporcionando refuerzo de seguridad, enrutamiento inteligente de herramientas, compresión de esquemas y seguimiento del estado de archivos, todo a través de un único proxy.

Por qué

Los agentes LLM que utilizan herramientas MCP se enfrentan a tres problemas:

1. Desperdicio de tokens — Los esquemas de herramientas consumen miles de tokens por solicitud. Con más de 40 herramientas cargadas, estás quemando contexto en esquemas JSON antes incluso de que comience la conversación.

2. Degradación del contexto — En sesiones largas, los LLM vuelven a editar versiones antiguas de archivos que memorizaron anteriormente, sobrescribiendo silenciosamente tus cambios más recientes.

3. Sin límite de seguridad — Los servidores MCP se ejecutan con acceso total. No hay registro de auditoría, ni limitación de tasa, ni limpieza de secretos entre el LLM y tus herramientas.

MCP Spine resuelve los tres.

Instalación

pip install mcp-spine

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

Inicio rápido

# Generate config
mcp-spine init

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

# Validate config
mcp-spine verify --config spine.toml

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

Integración con Claude Desktop

Reemplaza todas tus entradas individuales de servidores MCP con una única entrada de Spine:

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

La bandera -u asegura una salida estándar sin búfer, evitando bloqueos de tuberías en Windows.

Características

Etapa 1: Proxy de seguridad

• Validación y saneamiento de mensajes JSON-RPC

• Limpieza de secretos (claves AWS, tokens de GitHub, tokens de portador, claves privadas, cadenas de conexión)

• Limitación de tasa global y por herramienta con ventanas deslizantes

• Prevención de recorrido de rutas con cárcel consciente de enlaces simbólicos

• Protecciones contra inyección de comandos para el inicio de servidores

• Registro de auditoría SQLite con huella digital HMAC

• Disyuntores en servidores que fallan

• Políticas de seguridad declarativas desde la configuración

Etapa 2: Enrutador semántico

• Incrustaciones vectoriales locales usando all-MiniLM-L6-v2 (sin llamadas a API, ningún dato sale de tu máquina)

• Indexación de herramientas respaldada por ChromaDB

• Enrutamiento en tiempo de consulta: solo las herramientas más relevantes se envían al LLM

• Meta-herramienta spine_set_context para cambio de contexto explícito

• Reclasificación mediante superposición de palabras clave + impulso de recencia

• Carga de modelos en segundo plano: las herramientas funcionan inmediatamente, el enrutamiento se activa cuando está listo

Etapa 3: Minificación de esquemas

• 4 niveles de agresividad (0=desactivado, 1=ligero, 2=estándar, 3=agresivo)

• El nivel 2 logra un 61% de ahorro de tokens en esquemas de herramientas

• Elimina $schema, títulos, additionalProperties, descripciones de parámetros, valores predeterminados

• Conserva todos los campos obligatorios e información de tipo

Etapa 4: Protector de estado

• Supervisa archivos del proyecto mediante watchfiles

• Mantiene un manifiesto SHA-256 con versiones monótonas

• Inyecta pines de estado compactos en las respuestas de las herramientas

• Evita que los LLM editen versiones de archivos obsoletas

Humano en el bucle (HITL)

• Bandera de política require_confirmation para herramientas destructivas

• Spine intercepta la llamada, muestra los argumentos y espera la aprobación del usuario

• Meta-herramientas spine_confirm / spine_deny para que el LLM transmita la decisión

• Granularidad por herramienta mediante patrones glob

Memoria de salida de herramientas

• Caché de búfer circular de los últimos 50 resultados de herramientas

• Deduplicación por nombre de herramienta + hash de argumentos

• Expiración TTL (1 hora por defecto)

• Meta-herramienta spine_recall para consultar resultados en caché

• Evita la pérdida de contexto cuando el enrutador semántico intercambia herramientas entre turnos

Transporte SSE

• Conéctate a servidores MCP remotos a través de HTTP/SSE junto con servidores stdio locales

• Sin dependencias externas (usa urllib de la biblioteca estándar)

• Soporta encabezados personalizados para autenticación

Diagnóstico

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

# Live monitoring dashboard
mcp-spine dashboard

# Usage analytics
mcp-spine analytics --hours 24

# Query audit log
mcp-spine audit --last 50
mcp-spine audit --security-only
mcp-spine audit --tool write_file

Configuración de ejemplo

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

# Add as many servers as you need — they 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/node_modules/@modelcontextprotocol/server-brave-search/dist/index.js"]
env = { BRAVE_API_KEY = "your_key" }
timeout_seconds = 60

# Remote server via SSE
# [[servers]]
# name = "remote-tools"
# transport = "sse"
# url = "https://your-server.com/sse"
# headers = { Authorization = "Bearer token" }
# timeout_seconds = 30

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

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

# State guard — prevent context rot
[state_guard]
enabled = true
watch_paths = ["/path/to/project"]

# Human-in-the-loop for destructive tools
[[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 seguridad

Defensa en profundidad: cada capa asume que las demás podrían fallar.

Arquitectura

Client ◄──stdio──► MCP Spine ◄──stdio──► Filesystem Server
                       │      ◄──stdio──► GitHub Server
                       │      ◄──stdio──► SQLite Server
                       │      ◄──stdio──► Memory Server
                       │      ◄──stdio──► Brave Search
                       │      ◄──SSE────► Remote Server
                   ┌───┴───┐
                   │SecPol │  ← Rate limits, path jail, secret scrub
                   │Router │  ← Semantic routing (local embeddings)
                   │Minify │  ← Schema compression (61% savings)
                   │Guard  │  ← File state pinning (SHA-256)
                   │HITL   │  ← Human-in-the-loop confirmation
                   │Memory │  ← Tool output cache
                   └───────┘

Secuencia de inicio

1. Apretón de manos instantáneo (~2ms) — Responde a initialize inmediatamente

2. Inicio concurrente de servidores — Todos los servidores se conectan en paralelo mediante asyncio.gather

3. Preparación progresiva — Herramientas disponibles tan pronto como cualquier servidor se conecta

4. Notificación tardía de servidor — tools/listChanged enviado cuando los servidores lentos terminan

5. Carga de ML en segundo plano — El enrutador semántico se activa silenciosamente cuando el modelo se carga

Soporte para Windows

Probado en batalla en Windows con refuerzo específico para:

• Rutas de sandbox MSIX para configuración y registros de Claude Desktop

• Resolución de npx.cmd mediante shutil.which()

• Rutas con espacios (C:\Users\John Doe\) y paréntesis (C:\Program Files (x86)\)

• PureWindowsPath para extracción de nombres base multiplataforma

• Fusión de variables de entorno (la configuración de entorno extiende, no reemplaza, el entorno del sistema)

• Codificación UTF-8 sin BOM

• Salida estándar sin búfer (bandera -u) para evitar bloqueos de tuberías

Estructura del proyecto

mcp-spine/
├── pyproject.toml
├── spine/
│   ├── cli.py              # Click CLI (init, serve, verify, audit, dashboard, analytics, doctor)
│   ├── 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
│   ├── 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)
│   ├── dashboard.py        # Live TUI dashboard (Rich)
│   ├── sse_client.py       # SSE transport client for remote servers
│   └── 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    # Security tests
│   ├── test_config.py      # Config validation tests
│   ├── test_minifier.py    # Schema minification tests
│   ├── test_state_guard.py # State guard tests
│   ├── test_proxy_features.py  # HITL, dashboard, analytics tests
│   └── test_memory.py      # Tool output memory tests
├── configs/
│   └── example.spine.toml  # Complete reference config
└── .github/
    └── workflows/
        └── ci.yml          # GitHub Actions: test + lint + publish

Pruebas

pytest tests/ -v

Más de 135 pruebas que cubren seguridad, validación de configuración, minificación de esquemas, protector de estado, políticas HITL, consultas de panel, análisis, memoria de herramientas y casos extremos de rutas en Windows.

La CI se ejecuta en cada push: Windows + Linux, Python 3.11/3.12/3.13.

Licencia

MIT