Mcp Spine

MCP Spine

MCP 缺失的中间件层。 在你的大模型和工具之间提供安全防护、路由、令牌控制和合规支持。

MCP Spine 是一个本地优先的代理，位于 Claude Desktop（或任何 MCP 客户端）与 MCP 服务之间。只需一份配置、一个入口点，即可全面掌控输入、输出和日志内容。

5 个服务共提供 57 个工具。一个代理。零令牌浪费。

问题所在

你已将 Claude 连接到 GitHub、Slack、数据库和文件系统。现在，你加载了 40 多个工具，每轮都要为工具架构消耗数千个令牌，却没有审计跟踪、没有速率限制，也无法阻止大模型读取老板的私信。MCP 为 Agent 赋予能力，Spine 则让你掌控一切。

功能

层	解决的问题
安全代理	速率限制、机密信息清理、路径隔离、HMAC 审计跟踪
语义路由器	只有相关工具才会发送给大模型 — 本地嵌入，不调用 API
架构精简器	移除不必要的架构字段，节省 61% 的令牌
状态保护器	SHA-256 文件锁定，防止大模型编辑过时版本
令牌预算	每日限额，支持警告/阻止强制执行和持久化跟踪
插件系统	自定义中间件钩子 — 按工具筛选、转换或拦截
人工确认	执行破坏性工具前暂停，等待人工批准
注入检测	扫描工具响应中的提示词注入，再将其发送给大模型
多用户审计	为共享部署提供带会话标签的审计跟踪
工具缓存	为只读工具提供 LRU 缓存 — 跳过重复的下游调用
Webhook 警报	安全事件和预算警告触发 Slack/Discord/JSON 通知
Web 控制面板	基于浏览器的监控，提供实时统计、延迟跟踪和请求日志

演示

支持 Windows、macOS 和 Linux。CI 已在这三个平台上完成测试。

Web 控制面板

mcp-spine web --db spine_audit.db

安装

pip install mcp-spine

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

快速开始

# 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

Claude Desktop 集成

用单个 Spine 条目替换所有独立的 MCP 服务条目：

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

功能

安全代理（阶段 1）

• JSON-RPC 消息验证与清理
• 机密信息清理（AWS 密钥、GitHub 令牌、Bearer 令牌、私钥、连接字符串）
• 支持滑动窗口的单工具及全局速率限制
• 具备符号链接感知隔离的路径遍历防护
• 服务启动的命令注入防护
• 基于 HMAC 指纹的 SQLite 审计跟踪
• 为故障服务启用熔断器
• 通过配置声明式定义安全策略

语义路由器（阶段 2）

• 使用 all-MiniLM-L6-v2 进行本地向量嵌入（不调用 API，数据不会离开你的设备）
• 由 ChromaDB 提供支持的工具索引
• 查询时进行路由：只向大模型发送最相关的工具
• 用于显式切换上下文的 spine_set_context 元工具
• 通过关键词重叠度和近期性加权进行重新排序
• 在后台加载模型 — 工具立即可用，模型就绪后启用路由

架构精简（阶段 3）

• 4 个精简级别（0=关闭，1=轻度，2=标准，3=激进）
• 级别 2 可使工具架构节省 61% 的令牌
• 移除 $schema、标题、additionalProperties、参数描述和默认值
• 保留所有必填字段和类型信息
• 在审计跟踪中跟踪令牌节省量，并显示在 Web 控制面板中

状态保护器（阶段 4）

• 通过 watchfiles 监视项目文件
• 维护带单调递增版本号的 SHA-256 清单
• 将精简的状态锁定信息注入工具响应
• 防止大模型编辑过时的文件版本

Human-in-the-Loop

• 用于破坏性工具的 require_confirmation 策略标志
• Spine 会拦截调用、显示参数，并等待用户批准
• 提供 spine_confirm / spine_deny 元工具，让大模型传达决定
• 可通过 glob 模式按工具粒度配置

Tool Output Memory

• 环形缓冲区，用于缓存最近 50 条工具结果
• 按工具名称和参数哈希去重
• TTL 过期机制（默认 1 小时）
• 提供 spine_recall 元工具，用于查询缓存结果
• 防止语义路由器在不同轮次间切换工具时丢失上下文

Token Budget

• 跟踪所有工具调用的每日 Token 消耗
• 可配置每日上限，并设置警告或阻止操作
• 为每个服务设置 Token 上限，以控制成本
• 使用持久化 SQLite 存储（同一天内重启后数据仍会保留）
• 每天午夜自动重置
• 提供 spine_budget 元工具，用于在对话中途检查用量

Plugin System

• 即插即用的 Python 插件，可在工具调用流水线中执行钩子
• 四个钩子点：on_tool_call、on_tool_response、on_tool_list、on_startup/on_shutdown
• 插件可以转换参数、筛选响应、阻止调用或隐藏工具
• 插件链式调用——多个插件按顺序运行
• 插件访问的允许列表和拒绝列表
• 从可配置的插件目录自动发现插件
• 包含示例：Slack 频道合规筛选器

Prompt Injection Detection

• 在工具响应到达大模型之前扫描所有响应
• 检测系统提示词覆盖、角色注入、指令劫持和越狱尝试
• 检测数据窃取 URL 和编码载荷
• 可配置操作：记录、移除或阻止
• 所有检测结果都会记录为安全事件，并通过 Webhook 发送

Tool Aliasing

• 重命名工具，让大模型看到更简洁的名称
• create_or_update_file → edit_github_file
• 别名会透明解析——下游服务仍会看到原始名称

Tool Response Caching

• 为只读工具提供 LRU 缓存（可配置模式）
• 命中缓存时会完全跳过下游调用
• 基于 TTL 的过期机制（默认 5 分钟）
• 缓存溢出时自动失效

Config Hot-Reload

• Spine 运行期间编辑 spine.toml——更改会在数秒内生效
• 支持热重载：压缩器级别、速率限制、安全策略、Token 预算、状态防护模式
• 不支持热重载（需要重启）：服务列表、命令、审计数据库路径
• 所有重载都会记录到审计跟踪中

Multi-User Audit

• 为每个客户端连接生成唯一会话 ID
• 从 MCP 握手中提取客户端名称和版本
• 所有审计条目都会标记会话 ID
• mcp-spine audit --sessions 列出所有客户端会话
• mcp-spine audit --session <id> 按会话筛选条目

Webhook Notifications

• 向 Slack、Discord 或任何 JSON 端点发送 POST 告警
• 触发条件：安全事件、预算警告、预算超限、工具被阻止、触发速率限制
• 为 Slack 区块和 Discord 嵌入内容预格式化载荷
• 非阻塞（后台线程）

Latency Monitoring

• 跟踪每个服务的响应时间（滚动窗口）
• 平均延迟超过阈值时发出警告（默认 5 秒）
• Web 控制面板中的服务延迟面板会显示 OK/SLOW 状态

Analytics Export

• mcp-spine export --format csv 或 --format json
• 按小时数、事件类型筛选
• 输出到文件或 stdout，以便通过管道传递

Transport Support

• stdio — 本地子进程服务（filesystem、GitHub、SQLite 等）
• SSE — 通过 HTTP/Server-Sent Events 连接的旧版远程服务
• Streamable HTTP — 符合 MCP 2025-03-26 规范的单端点双向传输，并支持会话管理
• 所有传输方式共用同一套安全、路由和审计流水线

Web 仪表板

• 基于浏览器的监控，地址为 localhost:8777
• 实时统计卡片：工具调用、安全事件、会话、令牌预算、令牌节省量
• 显示最近的工具调用及其服务、会话和状态
• 工具使用量柱状图
• 服务延迟表，显示平均值/最大值和 OK/SLOW 状态
• 完整的请求/响应日志，包含耗时和令牌数量
• 安全事件和客户端会话表
• 每 3 秒自动刷新
• 零依赖（Python 标准库 http.server）

诊断

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

配置示例

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

安全模型

纵深防御——每一层都假设其他层可能失效。

威胁	缓解措施
通过工具响应进行提示词注入	自动模式检测（8 个类别），记录/剥离/拦截
通过工具参数进行提示词注入	输入验证、工具名称允许列表
路径遍历	对 allowed_roots 实施感知符号链接的隔离
机密泄露	自动清理 AWS 密钥、令牌、私钥
Agent 循环失控	按工具及全局进行速率限制
命令注入	命令允许列表，阻止 Shell 元字符
拒绝服务	消息大小限制、熔断器
访问敏感文件	针对 .env、.key、.pem、.ssh/ 的拒绝列表模式
工具滥用	基于策略的拦截、审计日志、HITL 确认
日志篡改	为每条审计记录添加 HMAC 指纹
破坏性操作	require_confirmation 会暂停操作，等待用户批准
令牌支出失控	每日预算限制，支持警告/拦截，并设置每个服务的限制
未审核的插件	允许/拒绝列表、目录隔离、审计日志
敏感数据暴露	基于插件的响应过滤（例如 Slack 合规性）
服务性能下降	延迟监控并自动发出警报

架构

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

启动顺序

1. 即时握手（约 2ms）——立即响应 initialize
2. 并发启动服务——通过 asyncio.gather 并行连接所有服务
3. 渐进式就绪——任一服务连接后即可使用其工具
4. 通知延迟连接的服务——慢速服务完成连接后发送 tools/listChanged
5. 后台加载 ML——模型加载完成后，语义路由器会静默激活

Windows 支持

已在 Windows 上经过充分测试，并针对以下情况进行了加固：

• Claude Desktop 配置和日志的 MSIX 沙盒路径
• 通过 shutil.which() 解析 npx.cmd
• 包含空格（C:\Users\John Doe\）和圆括号（C:\Program Files (x86)\）的路径
• 使用 PureWindowsPath 跨平台提取基本名称
• 合并环境变量（配置环境变量会扩展系统环境变量，而非替换它们）
• UTF-8 编码，不带 BOM
• 无缓冲的 stdout（-u 标志），防止管道挂起

项目结构

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

测试

pytest tests/ -v

190 多项测试。CI 在 Windows 和 Linux 上运行，使用 Python 3.11/3.12/3.13。

许可证

MIT