MCP Spine

Minificador de contexto y guardián de estado — Proxy de middleware MCP local que reduce el desperdicio de tokens en un 61%, previene la degradación del contexto y añade refuerzo de seguridad.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP Spine

La capa de middleware que MCP necesita. Seguridad, enrutamiento, control de tokens y cumplimiento normativo — entre tu LLM y tus herramientas.

MCP Spine es un proxy local-first que se sitúa entre Claude Desktop (o cualquier cliente MCP) y tus servidores MCP. Una configuración, un punto de entrada, control total sobre lo que entra, lo que sale y lo que se registra.

57 herramientas en 5 servidores. Un proxy. Cero tokens desperdiciados.

El Problema

Has conectado Claude a GitHub, Slack, tu base de datos, tu sistema de archivos. Ahora tienes más de 40 herramientas cargadas, miles de tokens quemados en esquemas en cada turno, sin registro de auditoría, sin límites de tasa y sin forma de evitar que el LLM lea los DMs de tu jefe. MCP les da poder a los agentes. Spine te da control a ti.

Qué Hace

Capa	Qué resuelve
Proxy de Seguridad	Límites de tasa, limpieza de secretos, jails de rutas, registro de auditoría HMAC
Enrutador Semántico	Solo las herramientas relevantes llegan al LLM — embeddings locales, sin llamadas a API
Minificador de Esquemas	61% de ahorro de tokens al eliminar campos innecesarios de esquemas
Guardián de Estado	Pines de archivo SHA-256 evitan que el LLM edite versiones obsoletas
Presupuesto de Tokens	Límites diarios con aplicación de advertencia/bloqueo y seguimiento persistente
Sistema de Plugins	Hooks de middleware personalizados — filtrar, transformar, bloquear por herramienta
Confirmación HITL	Las herramientas destructivas se pausan para aprobación humana antes de ejecutarse
Detección de Inyección	Escanea las respuestas de herramientas en busca de inyección de prompt antes de que lleguen al LLM
Auditoría Multi-Usuario	Registro de auditoría etiquetado por sesión para despliegues compartidos
Caché de Herramientas	Caché LRU para herramientas de solo lectura — omite llamadas posteriores redundantes
Alertas Webhook	Notificaciones Slack/Discord/JSON sobre eventos de seguridad y advertencias de presupuesto
Panel Web	Monitoreo basado en navegador con estadísticas en vivo, seguimiento de latencia, registro de solicitudes

Demo

MCP Spine Doctor

Se ejecuta en Windows, macOS y Linux. Probado con CI en los tres.

Panel Web

MCP Spine Web Dashboard

mcp-spine web --db spine_audit.db

Instalación

pip install mcp-spine

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

Inicio 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

Integración con Claude Desktop

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

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

Características

Proxy de Seguridad (Etapa 1)

Validación y saneamiento de mensajes JSON-RPC
Limpieza de secretos (claves AWS, tokens de GitHub, tokens bearer, claves privadas, cadenas de conexión)
Límites de tasa por herramienta y globales con ventanas deslizantes
Prevención de traversal de rutas con jail consciente de symlinks
Protecciones contra inyección de comandos al iniciar servidores
Registro de auditoría SQLite con huella HMAC
Interruptores de circuito en servidores con fallos
Políticas de seguridad declarativas desde la configuración

Enrutador Semántico (Etapa 2)

Embeddings vectoriales locales usando all-MiniLM-L6-v2 (sin llamadas a API, los datos no salen 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 explícito de contexto
Reordenamiento por solapamiento de palabras clave + refuerzo de actualidad
Carga del modelo en segundo plano — las herramientas funcionan de inmediato, el enrutamiento se activa cuando está listo

Minificación de Esquemas (Etapa 3)

4 niveles de agresividad (0=desactivado, 1=ligero, 2=estándar, 3=agresivo)
El nivel 2 logra 61% de ahorro de tokens en esquemas de herramientas
Elimina $schema, títulos, additionalProperties, descripciones de parámetros, valores por defecto
Conserva todos los campos obligatorios e información de tipos
El ahorro de tokens se registra en el registro de auditoría y es visible en el panel web

Guardián de Estado (Etapa 4)

Vigila archivos del proyecto mediante watchfiles
Mantiene un manifiesto SHA-256 con versionado monótono
Inyecta pines de estado compactos en las respuestas de herramientas
Evita que los LLM editen versiones obsoletas de archivos

Human-in-the-Loop

Indicador 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 Resultados de Herramientas

Buffer circular que almacena en caché 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 cambia de herramientas entre turnos

Presupuesto de Tokens

Seguimiento del consumo diario de tokens en todas las llamadas a herramientas
Límite diario configurable con acciones de advertencia/bloqueo
Límites de tokens por servidor para control de costos
Almacenamiento SQLite persistente (sobrevive reinicios dentro del mismo día)
Reinicio automático a medianoche
Meta-herramienta spine_budget para verificar el uso a mitad de conversación

Sistema de Plugins

Plugins Python de inserción directa que se enganchan al pipeline de llamadas a herramientas
Cuatro puntos de enganche: on_tool_call, on_tool_response, on_tool_list, on_startup/on_shutdown
Los plugins pueden transformar argumentos, filtrar respuestas, bloquear llamadas u ocultar herramientas
Encadenamiento de plugins — múltiples plugins se ejecutan en secuencia
Listas de permitidos/denegados para control de acceso de plugins
Auto-descubrimiento desde un directorio de plugins configurable
Ejemplo incluido: filtro de cumplimiento para canales de Slack

Detección de Inyección de Prompt

Escanea todas las respuestas de herramientas antes de que lleguen al LLM
Detecta sobrescrituras del prompt del sistema, inyección de roles, secuestro de instrucciones, intentos de jailbreak
Detecta URLs de exfiltración de datos y payloads codificados
Acción configurable: registrar, eliminar o bloquear
Todas las detecciones se registran como eventos de seguridad y se envían mediante webhooks

Alias de Herramientas

Renombra herramientas para que el LLM vea nombres más limpios
create_or_update_file → edit_github_file
Los alias se resuelven de forma transparente — los servidores posteriores ven los nombres originales

Caché de Respuestas de Herramientas

Caché LRU para herramientas de solo lectura (patrones configurables)
Los aciertos de caché omiten por completo la llamada posterior
Expiración basada en TTL (5 minutos por defecto)
Invalidación automática al desbordarse la caché

Recarga en Caliente de Configuración

Edita spine.toml mientras Spine está en ejecución — los cambios se aplican en segundos
Recargables en caliente: nivel de minificador, límites de tasa, políticas de seguridad, presupuesto de tokens, patrones de state guard
No recargables (requieren reinicio): lista de servidores, comandos, ruta de la base de datos de auditoría
Todas las recargas se registran en el registro de auditoría

Auditoría Multi-Usuario

ID de sesión único generado por conexión de cliente
Nombre y versión del cliente extraídos del handshake de MCP
Todas las entradas de auditoría etiquetadas con ID de sesión
mcp-spine audit --sessions lista todas las sesiones de clientes
mcp-spine audit --session <id> filtra entradas por sesión

Notificaciones Webhook

Envía alertas POST a Slack, Discord o cualquier endpoint JSON
Disparadores: eventos de seguridad, advertencias de presupuesto, presupuesto excedido, herramienta bloqueada, límite de tasa alcanzado
Payloads preformateados para bloques de Slack y embeds de Discord
No bloqueante (hilos en segundo plano)

Monitoreo de Latencia

Rastrea tiempos de respuesta por servidor (ventana deslizante)
Advierte cuando la latencia promedio supera el umbral (5s por defecto)
Panel de latencia de servidores en el panel web con estado OK/LENTO

Exportación de Analíticas

mcp-spine export --format csv o --format json
Filtrar por horas, tipo de evento
Salida a archivo o stdout para canalización

Soporte de Transportes

stdio — servidores locales de subprocesos (filesystem, GitHub, SQLite, etc.)
SSE — servidores remotos heredados sobre HTTP/Server-Sent Events
Streamable HTTP — especificación MCP 2025-03-26, transporte bidireccional de un solo endpoint con gestión de sesiones
Todos los transportes comparten el mismo pipeline de seguridad, enrutamiento y auditoría

Panel Web

Monitoreo basado en navegador en localhost:8777
Tarjetas de estadísticas en vivo: llamadas a herramientas, eventos de seguridad, sesiones, presupuesto de tokens, ahorro de tokens
Llamadas recientes a herramientas con servidor, sesión y estado
Gráfico de barras de uso de herramientas
Tabla de latencia de servidores con promedio/máximo y estado OK/LENTO
Registro completo de solicitudes/respuestas con duración y conteo de tokens
Tablas de eventos de seguridad y sesiones de clientes
Auto-refresco cada 3 segundos
Cero dependencias (stdlib de Python http.server)

Diagnósticos

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

Ejemplo de Configuración

[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 Seguridad

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

Amenaza	Mitigación
Inyección de prompt mediante respuestas de herramientas	Detección automatizada de patrones (8 categorías), registrar/eliminar/bloquear
Inyección de prompt mediante argumentos de herramientas	Validación de entrada, listas de permitidos de nombres de herramientas
Traversal de rutas	Jail consciente de symlinks a `allowed_roots`
Fuga de secretos	Limpieza automática de claves AWS, tokens, claves privadas
Bucles de agente descontrolados	Límites de tasa por herramienta + globales
Inyección de comandos	Lista de permitidos de comandos, bloqueo de metacaracteres de shell
Denegación de servicio	Límites de tamaño de mensajes, interruptores de circuito
Acceso a archivos sensibles	Patrones de lista de denegados para `.env`, `.key`, `.pem`, `.ssh/`
Abuso de herramientas	Bloqueo basado en políticas, registro de auditoría, confirmación HITL
Manipulación de registros	Huellas HMAC en cada entrada de auditoría
Operaciones destructivas	`require_confirmation` pausa para aprobación del usuario
Gasto descontrolado de tokens	Límites diarios de presupuesto con advertencia/bloqueo + límites por servidor
Plugins no verificados	Listas de permitidos/denegados, aislamiento de directorios, registro de auditoría
Exposición de datos sensibles	Filtrado de respuestas basado en plugins (p. ej., cumplimiento de Slack)
Degradación de servidores	Monitoreo de latencia con alertas automáticas

Arquitectura

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
                   └───────┘

Secuencia de Inicio

Handshake instantáneo (~2ms) — Responde a initialize de inmediato
Inicio concurrente de servidores — Todos los servidores se conectan en paralelo mediante asyncio.gather
Disponibilidad progresiva — Las herramientas están disponibles en cuanto cualquier servidor se conecta
Notificación de servidores lentos — tools/listChanged se envía cuando los servidores lentos terminan
Carga de ML en segundo plano — El enrutador semántico se activa silenciosamente cuando el modelo carga

Soporte para Windows

Probado a fondo en Windows con endurecimiento 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 multiplataforma del nombre base
Fusión de variables de entorno (el env de configuración extiende, no reemplaza, el env del sistema)
Codificación UTF-8 sin BOM
stdout sin buffer (indicador -u) para evitar bloqueos de pipe

Estructura del Proyecto

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

Pruebas

pytest tests/ -v

Más de 190 pruebas. CI en Windows + Linux, Python 3.11/3.12/3.13.

Licencia

MIT