MCP Spine

Минификатор контекста и защита состояния — локальный прокси-сервер промежуточного ПО для MCP, который сокращает расход токенов, предотвращает потерю инструментов и устраняет «гниение» контекста.

MCP Spine располагается между вашим LLM-клиентом (например, Claude Desktop) и вашими MCP-серверами, обеспечивая усиленную безопасность, интеллектуальную маршрутизацию инструментов, сжатие схем и отслеживание состояния файлов — и все это через единый прокси.

Зачем это нужно

Агенты LLM, использующие инструменты MCP, сталкиваются с тремя проблемами:

1. Расход токенов — схемы инструментов потребляют тысячи токенов на каждый запрос. При загрузке 40+ инструментов вы тратите контекст на JSON-схемы еще до начала диалога.

2. «Гниение» контекста — в длительных сессиях LLM возвращаются к редактированию старых версий файлов, которые они запомнили ранее, незаметно перезаписывая ваши последние изменения.

3. Отсутствие границ безопасности — MCP-серверы работают с полным доступом. Нет журнала аудита, ограничения частоты запросов (rate limiting) или очистки секретов между LLM и вашими инструментами.

MCP Spine решает все три проблемы.

Установка

pip install mcp-spine

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

Быстрый старт

# 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

Интеграция с Claude Desktop

Замените все ваши отдельные записи MCP-серверов на одну запись Spine:

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

Флаг -u обеспечивает небуферизованный вывод stdout, предотвращая зависание каналов (pipes) в Windows.

Функции

Этап 1: Прокси безопасности

• Валидация и санитарная обработка сообщений JSON-RPC

• Очистка секретов (ключи AWS, токены GitHub, bearer-токены, закрытые ключи, строки подключения)

• Ограничение частоты запросов для отдельных инструментов и глобально с использованием скользящих окон

• Предотвращение обхода путей (path traversal) с помощью изолированной среды (jail) с поддержкой символических ссылок

• Защита от инъекций команд при запуске серверов

• Журнал аудита SQLite с HMAC-отпечатками

• Автоматическое отключение (circuit breakers) неисправных серверов

• Декларативные политики безопасности из конфигурации

Этап 2: Семантический маршрутизатор

• Локальные векторные эмбеддинги с использованием all-MiniLM-L6-v2 (никаких API-вызовов, данные не покидают ваш компьютер)

• Индексация инструментов на базе ChromaDB

• Маршрутизация во время запроса: LLM получает только самые релевантные инструменты

• Мета-инструмент spine_set_context для явного переключения контекста

• Переранжирование на основе пересечения ключевых слов + учет недавности

• Фоновая загрузка модели — инструменты работают сразу, маршрутизация активируется по готовности

Этап 3: Минификация схем

• 4 уровня агрессивности (0=выкл, 1=легкий, 2=стандартный, 3=агрессивный)

• Уровень 2 обеспечивает 61% экономии токенов на схемах инструментов

• Удаляет $schema, заголовки, additionalProperties, описания параметров, значения по умолчанию

• Сохраняет все обязательные поля и информацию о типах

Этап 4: Защита состояния

• Отслеживает файлы проекта через watchfiles

• Поддерживает манифест SHA-256 с монотонным версионированием

• Внедряет компактные метки состояния в ответы инструментов

• Предотвращает редактирование LLM устаревших версий файлов

Человек в контуре (Human-in-the-Loop)

• Флаг политики require_confirmation для деструктивных инструментов

• Spine перехватывает вызов, показывает аргументы и ждет одобрения пользователя

• Мета-инструменты spine_confirm / spine_deny для передачи решения от LLM

• Гранулярность для каждого инструмента через glob-шаблоны

Память вывода инструментов

• Кольцевой буфер, кэширующий последние 50 результатов инструментов

• Дедупликация по имени инструмента + хешу аргументов

• Истечение срока действия (TTL) (по умолчанию 1 час)

• Мета-инструмент spine_recall для запроса кэшированных результатов

• Предотвращает потерю контекста, когда семантический маршрутизатор меняет инструменты между ходами

Транспорт SSE

• Подключение к удаленным MCP-серверам через HTTP/SSE наряду с локальными stdio-серверами

• Отсутствие внешних зависимостей (использует стандартную библиотеку urllib)

• Поддержка пользовательских заголовков для аутентификации

Диагностика

# 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

Пример конфигурации

[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"]

Модель безопасности

Глубокоэшелонированная защита — каждый уровень предполагает, что остальные могут отказать.

Архитектура

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

Последовательность запуска

1. Мгновенное рукопожатие (~2 мс) — немедленный ответ на initialize

2. Параллельный запуск серверов — все серверы подключаются параллельно через asyncio.gather

3. Прогрессивная готовность — инструменты доступны, как только подключается любой сервер

4. Уведомление о позднем подключении — tools/listChanged отправляется, когда медленные серверы завершают работу

5. Фоновая загрузка ML — семантический маршрутизатор активируется незаметно при загрузке модели

Поддержка Windows

Проверено в бою на Windows с особой защитой для:

• Путей песочницы MSIX для конфигурации и логов Claude Desktop

• Разрешения npx.cmd через shutil.which()

• Путей с пробелами (C:\Users\John Doe\) и скобками (C:\Program Files (x86)\)

• PureWindowsPath для кроссплатформенного извлечения базового имени

• Объединения переменных окружения (конфигурация расширяет, а не заменяет системные переменные)

• Кодировки UTF-8 без BOM

• Небуферизованного вывода stdout (флаг -u) для предотвращения зависания каналов

Структура проекта

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

Тесты

pytest tests/ -v

135+ тестов, охватывающих безопасность, валидацию конфигурации, минификацию схем, защиту состояния, политики HITL, запросы к панели управления, аналитику, память инструментов и граничные случаи путей Windows.

CI запускается при каждом пуше: Windows + Linux, Python 3.11/3.12/3.13.

Лицензия

MIT