Mcp Spine

MCP Spine

MCP に欠けているミドルウェア層です。 LLM とツールの間で、セキュリティ、ルーティング、トークン制御、コンプライアンスを実現します。

MCP Spine は、Claude Desktop（または任意の MCP クライアント）と MCP サーバーの間に配置される、ローカルファーストのプロキシです。設定は 1 つ、エントリーポイントも 1 つ。入出力とログの内容を完全に制御できます。

5 つのサーバーにまたがる 57 個のツール。プロキシは 1 つ。無駄なトークンはゼロです。

問題点

Claude を GitHub、Slack、データベース、ファイルシステムに接続したとします。すると、40 個以上のツールが読み込まれ、毎回の処理でスキーマに何千ものトークンが消費され、監査証跡もレート制限もなく、LLM が上司の DM を読むのを止める方法もありません。MCP はエージェントに力を与えます。Spine は、あなたに制御をもたらします。

機能

レイヤー	解決する問題
セキュリティプロキシ	レート制限、シークレットの除去、パス制限、HMAC 監査証跡
セマンティックルーター	関連するツールだけを LLM に渡します — ローカル埋め込みを使用し、API 呼び出しはありません
スキーマの簡素化	不要なスキーマフィールドを削除し、トークンを 61％ 節約します
状態ガード	SHA-256 のファイルピンにより、LLM が古いバージョンを編集するのを防ぎます
トークン予算	警告／ブロックによる適用と永続的な追跡を備えた日次上限
プラグインシステム	ツールごとにフィルタリング、変換、ブロックできるカスタムミドルウェアフック
HITL 確認	破壊的なツールは実行前に一時停止し、人間の承認を求めます
インジェクション検出	ツールの応答をスキャンし、LLM に届く前にプロンプトインジェクションを検出します
マルチユーザー監査	共有デプロイメント向けのセッションタグ付き監査証跡
ツールのキャッシュ	読み取り専用ツール用の LRU キャッシュ — 重複する下流呼び出しを省略します
Webhook アラート	セキュリティイベントや予算警告を Slack／Discord／JSON で通知します
Web ダッシュボード	ライブ統計、レイテンシ追跡、リクエストログを備えたブラウザーベースの監視

デモ

Windows、macOS、Linux で動作します。CI では 3 つすべての環境でテスト済みです。

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 との連携

個別の MCP サーバーエントリーをすべて、Spine のエントリー 1 つに置き換えます。

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

機能

セキュリティプロキシ（ステージ 1）

• JSON-RPC メッセージの検証とサニタイズ
• シークレットの除去（AWS キー、GitHub トークン、ベアラートークン、秘密鍵、接続文字列）
• スライディングウィンドウによるツールごとおよび全体のレート制限
• シンボリックリンクを考慮した制限によるパストラバーサルの防止
• サーバー起動時のコマンドインジェクション対策
• HMAC フィンガープリント付きの SQLite 監査証跡
• 障害が発生しているサーバーのサーキットブレーカー
• 設定による宣言的なセキュリティポリシー

セマンティックルーター（ステージ 2）

• all-MiniLM-L6-v2 を使用したローカルベクトル埋め込み（API 呼び出しなし、データはマシン外に送信されません）
• ChromaDB を利用したツールのインデックス作成
• クエリ時のルーティング：最も関連性の高いツールだけを LLM に送信します
• 明示的なコンテキスト切り替えを行う spine_set_context メタツール
• キーワードの重複と新しさの優先度を組み合わせた再ランキング
• モデルはバックグラウンドで読み込み — ツールはすぐに利用でき、読み込み完了後にルーティングが有効になります

スキーマの簡素化（ステージ 3）

• 4 段階の強度レベル（0＝オフ、1＝軽度、2＝標準、3＝強力）
• レベル 2 では、ツールスキーマのトークンを 61％ 節約します
• $schema、タイトル、additionalProperties、パラメーターの説明、デフォルト値を削除
• すべての必須フィールドと型情報を保持
• トークンの節約量は監査証跡で追跡され、Web ダッシュボードに表示されます

状態ガード（ステージ 4）

• watchfiles を使ってプロジェクトファイルを監視
• 単調増加するバージョン管理を備えた SHA-256 マニフェストを維持
• コンパクトな状態ピンをツールの応答に挿入
• LLM が古いファイルバージョンを編集するのを防止

ヒューマン・イン・ザ・ループ

• 破壊的なツール向けの require_confirmation ポリシーフラグ
• Spine が呼び出しをインターセプトし、引数を表示して、ユーザーの承認を待ちます
• LLM が判断を伝えるための spine_confirm／spine_deny メタツール
• グロブパターンによるツールごとの細かな設定

ツール出力メモリ

• 直近 50 件のツール結果をキャッシュするリングバッファ
• ツール名と引数のハッシュによる重複排除
• TTL による有効期限（デフォルトは 1 時間）
• キャッシュ結果を検索する spine_recall メタツール
• セマンティックルーターがターン間でツールを切り替えたときのコンテキスト喪失を防止します

トークン予算

• すべてのツール呼び出しにおける 1 日のトークン消費量を追跡
• 警告／ブロック動作を設定できる 1 日の上限
• コスト管理のためのサーバーごとのトークン上限
• 永続的な SQLite ストレージ（同じ日の再起動後も維持）
• 深夜に自動でリセット
• 会話中に使用量を確認する spine_budget メタツール

プラグインシステム

• ツール呼び出しパイプラインにフックする、ドロップイン形式の Python プラグイン
• 4 つのフックポイント：on_tool_call、on_tool_response、on_tool_list、on_startup／on_shutdown
• プラグインは引数の変換、レスポンスのフィルタリング、呼び出しのブロック、ツールの非表示化が可能です
• プラグインの連結 — 複数のプラグインが順番に実行されます
• プラグインのアクセス制御用の許可リスト／拒否リスト
• 設定可能なプラグインディレクトリから自動検出
• 同梱の例：Slack チャンネルのコンプライアンスフィルター

プロンプトインジェクション検出

• LLM に届く前に、すべてのツールレスポンスをスキャン
• システムプロンプトの上書き、ロールインジェクション、指示の乗っ取り、ジェイルブレイクの試みを検出
• データ流出につながる URL やエンコードされたペイロードを検出
• 設定可能なアクション：ログ記録、除去、ブロック
• 検出結果はすべてセキュリティイベントとして記録され、Webhook 経由で送信されます

ツールのエイリアス設定

• ツール名を変更して、LLM に分かりやすい名前を表示
• create_or_update_file → edit_github_file
• エイリアスは透過的に解決され、下流のサーバーには元の名前が表示されます

ツールレスポンスのキャッシュ

• 読み取り専用ツール向けの LRU キャッシュ（パターンを設定可能）
• キャッシュにヒットすると、下流への呼び出しを完全にスキップ
• TTL による有効期限（デフォルトは 5 分）
• キャッシュがあふれた場合に自動で無効化

設定のホットリロード

• Spine の実行中に spine.toml を編集すると、変更が数秒以内に反映されます
• ホットリロード可能：最小化レベル、レート制限、セキュリティポリシー、トークン予算、状態ガードパターン
• ホットリロード不可（再起動が必要）：サーバーリスト、コマンド、監査 DB のパス
• すべてのリロードを監査証跡に記録

マルチユーザー監査

• クライアント接続ごとに一意のセッション ID を生成
• MCP ハンドシェイクからクライアント名とバージョンを取得
• すべての監査エントリにセッション ID を付与
• mcp-spine audit --sessions ですべてのクライアントセッションを一覧表示
• mcp-spine audit --session <id> でセッションごとにエントリを絞り込み

Webhook 通知

• Slack、Discord、または任意の JSON エンドポイントにアラートを POST
• トリガー：セキュリティイベント、予算警告、予算超過、ツールのブロック、レート制限
• Slack ブロックおよび Discord 埋め込み用の書式設定済みペイロード
• ノンブロッキング（バックグラウンドスレッド）

レイテンシ監視

• サーバーごとのレスポンス時間を追跡（ローリングウィンドウ）
• 平均レイテンシがしきい値（デフォルトは 5 秒）を超えると警告
• Web ダッシュボードにサーバーのレイテンシパネルを表示し、OK／SLOW のステータスを表示

分析データのエクスポート

• mcp-spine export --format csv または --format json
• 時間数、イベントタイプで絞り込み
• ファイルまたはパイプで渡すための stdout に出力

トランスポートのサポート

• 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 キー、トークン、秘密鍵を自動的にマスキング
エージェントの暴走ループ	ツールごとおよび全体のレート制限
コマンドインジェクション	コマンド許可リスト、シェルのメタ文字のブロック
サービス拒否	メッセージサイズ制限、サーキットブレーカー
機密ファイルへのアクセス	.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. 即時ハンドシェイク（約 2 ms） — 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 を使用
• 環境変数のマージ（設定の環境変数はシステム環境変数を置き換えず、拡張します）
• BOM なしの UTF-8 エンコーディング
• パイプのハングを防ぐバッファーなし 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 件以上のテストがあります。Windows と Linux で、Python 3.11／3.12／3.13 の CI を実施しています。

ライセンス

MIT