Phocinae MCP

phocinae-mcp

斑海豹のコマンド承認ゲートと P0 推論プロトコルを MCP ツール（gate / classify / route / score）として公開し、読み取り専用 MCP のコーディングエージェントに接続します。2 世代のプロトコルが共存：現行仕様（2026-07-28、server/discover、MRTR インタラクション、Streamable HTTP を含む）と、2024-11-05 の旧クライアントとの互換性を備えています。

_{▲ `tools/list` の実際の応答：4 つのツールのパラメーターと戻り値の形式}

斑海豹エコシステムの MCP サーバーです。斑海豹のコマンド承認と推論機能を 4 つのツールとして MCP クライアントに公開します。標準ライブラリのみ（Python ≥ 3.8、サードパーティー依存関係なし）で、stdio と Streamable HTTP の 2 種類のトランスポートに対応し、MCP 2026-07-28 に準拠し、2024-11-05 の旧クライアントとの互換性も備えています。

このリポジトリはローカル拡張版（PyPI phocinae-mcp 0.1.1 をベース）で、ローカル開発とプロトコル準拠の検証専用です。公開しません。

インストール（ローカル拡張ビルド）

git clone https://github.com/Phocinae/phocinae-mcp.git
cd phocinae-mcp
python3 -m pip install .
phocinae-mcp --help

このリポジトリはローカル拡張ビルドであり、PyPI リリースではありません。レジストリエントリーと以下のパッケージは、同じサーバーコントラクトを参照しています。

ツール

_{▲ **合成デモアニメーション**（モデルリポジトリ docs/gallery [S07](https://huggingface.co/Phocinae/Phocinae-Largha-150M-v1/blob/main/docs/gallery)）：映像はフレームごとにレンダリングされ、シーンデータは架空のものですが、ここで示されている **`route` ツールが「1 回のフォワードパスで候補ツールから使うべきものを選ぶ」判定プロセス**は、実際の実装と一致しています（このページ上部のターミナル画面は、同じ処理を実際に実行したものです）。}

ツール	役割	入力	出力
gate	shell コマンドを実行できるか判定	command、cwd?、server?	decision ∈ allow/deny/ask + layer/reason
classify	状態を候補ラベルのいずれかに分類	state、labels、server?	choice（インデックス）+ label
route	候補ツールから最適なものを選択	state、tools、server?	choice + tool
score	基準に基づいて状態に 2～10 点を付与	state、criteria、server?	score + range

fail-closed：斑海豹 P0 サービス（/v1/systemone）が利用できない、タイムアウトする、または異常な応答を返す場合、gate は常に deny（理由付き）を返し、classify/route/score は isError: true を返します。

トランスポート

stdio（デフォルト）

python3 -m phocinae_mcp --server http://127.0.0.1:8155

MCP クライアントは子プロセスとして起動し、stdin/stdout を使って JSON-RPC フレームを 1 行ずつ送受信します。 stdout のクリーン性を保証：stdout には JSON-RPC フレームのみを出力します。すべてのログ（起動、警告、ツール内部の例外）は stderr のみへ出力されます（phocinae-mcp[level]: プレフィックス）。guard.py のインポート時の出力も stderr にリダイレクトされるため、プロトコルチャネルを汚しません。

Streamable HTTP（新規、2026-07-28）

python3 -m phocinae_mcp --transport http --host 127.0.0.1 --port 8255
# --port 0 → 随机端口（测试用）；端口号打印在 stderr

• ループバックのみでバインド：--host が受け付けるのは 127.0.0.1 / localhost / ::1 のみです。それ以外のアドレスでは起動を拒否します（exit 2）。
• エンドポイントは POST /mcp です。通知 → 202 Accepted（空の body）、リクエスト → 200（単一オブジェクトの JSON）。
• リクエストヘッダーを必須化（Server Validation）：MCP-Protocol-Version は必須で、サポート対象である必要があります（そうでない場合は 400 + -32020/-32022）。Mcp-Method は必須で、body の method と一致する必要があります（tools/call、resources/read では Mcp-Name も必須で、name/uri と一致する必要があります）。条件に違反すると 400 -32020 になります。Accept に application/json / text/event-stream が含まれない場合は 406、未知のメソッドは 404 -32601、GET/DELETE は 405 になります（2026-07-28 に GET ストリームとセッション終了エンドポイントは削除されました）。
• セッションヘッダー（Mcp-Session-Id）も SSE 再開バッファーもありません。ステートレスサービスのため、いつでも再起動できます。

環境変数：PHOCINAE_MCP_TRANSPORT=stdio|http、PHOCINAE_MCP_HTTP_PORT をコマンドラインオプションの代わりに使用できます。

协议对齐（2026-07-28）

双代并存，按请求逐条分派：

• 带 params._meta（含 io.modelcontextprotocol/* 键）的请求、以及 server/discover、resources/* → 现代面；
• initialize 握手、无 _meta 的请求 → 旧年代（2024-11-05 行为， 与原版 0.1.x 一致）。

现代面补足项：

项	实现
server/discover	必实现：supportedVersions、capabilities、_meta.serverInfo、instructions，ttlMs=3600000、cacheScope=public
_meta 校验	逐请求必填 protocolVersion + clientCapabilities，缺失 → -32602；版本不支持 → -32022（data.supported/data.requested）
resultType	一切结果携带（complete / input_required）
ttlMs/cacheScope	discover、tools/list、resources/*（静态内容，public 共享缓存）
多轮交互（MRTR）	gate 返回 ask 且客户端声明 elicitation 能力时 → resultType=input_required + inputRequests.gate_confirmation（elicitation/create，form）+ requestState；回执 accept/decline/cancel → allow/deny/不授权；requestState 为 HMAC-SHA256 防篡改 + 10 分钟过期 + 请求指纹（tool+command）比对，篡改/过期自动重发交互
resources	resources/list + resources/read 暴露审批策略全文 phocinae://policy/gate-approval（text/markdown，含 L0/L1/fail-closed 判定链路、阈值、ask 处理义务）
已移除方法	现代面下 initialize/ping/shutdown/logging/setLevel/subscriptions/listen → -32601（data 附 supportedVersions）
工具 schema 收紧	maxLength（command/state 20000、cwd 4096、server 2048、列表单项 2000）、minItems/maxItems（1–100）、enum（decision/layer）、outputSchema 全量声明（classify/route/score additionalProperties:false）；服务端同步执行同口径校验（越限 → -32602）
description 重写	四工具均按「何时使用 / 何时不使用」结构重写
日志	全部走 stderr；_meta 里 io.modelcontextprotocol/logLevel 门控（info 起，MCP 级日志协议字段）

兼容性：旧客户端 initialize 握手返回 2024-11-05 能力；无 _meta 的 tools/list/tools/call 按旧年代应答（不报错）——对旧客户端零破坏。

运行

_{▲ `tools/call` 真实判定：L0 定夺安全/危险命令，灰区才调模型}

# stdio（默认）
python3 -m phocinae_mcp [--server http://127.0.0.1:8155] [--timeout 5]
    [--guard /path/to/guard.py] [--l1-enabled] [--model <name>]

# Streamable HTTP
python3 -m phocinae_mcp --transport http [--host 127.0.0.1] [--port 8255]

python3 -m phocinae_mcp --version

--guard：复用 phocinae-guard 的 guard.py（L0 确定性表 + L1 编排），自动 探测同级 ../phocinae-guard/guard.py；找不到则 gate 降级为纯 HTTP noul+score 两问（engine: "http:noul+score"）。导入 guard 时不写 __pycache__（只读复用）。

测试

python3 tests/test_mcp.py    # stdio 双代全流程冒烟 → tests/mcp_smoke.txt
python3 tests/test_http.py   # Streamable HTTP 冒烟 → tests/http_smoke.txt

• test_mcp.py：模拟 MCP 客户端，走 stdio 依次执行旧年代 initialize → notifications/initialized → ping → tools/list → tools/call 全工具矩阵（含失败分支）→ shutdown；现代年代 discover → tools/list → 全工具矩阵（gate allow/deny/ask、MRTR 接受/拒绝/取消/篡改、fail-closed、 schema 越限、-32602/-32022/-32601、resources）→ 通知。同时对 stdout 逐行审计（每行必须是 JSON-RPC 帧、日志零泄漏、无 traceback）。
• test_http.py：HTTP 头校验矩阵（-32020/-32022/406/405/404/ 202）+ MRTR 全链路 + resources。
• 两个测试共用 tests/mock_systemone.py（确定性 mock P0 服务，不跑模型）。

目录

phocinae_mcp/
├── server.py          主程序：双代分派、MRTR、CLI（stdio/http）
├── http_transport.py  Streamable HTTP（新增）
├── protocol.py        2026-07-28 共享件（新增）：版本/错误码/_meta 校验/
│                      resultType/ttlMs/cacheScope/HMAC requestState/策略文本/日志门控
├── tools.py           四工具 + 收紧后的 schema（description 重写）
├── backend.py         斑海豹 P0 客户端（原版不动）
├── guard_bridge.py    guard.py 复用桥（+stdout 纯净性防护）
└── __init__.py / __main__.py
tests/
├── test_mcp.py        stdio 全流程冒烟 → mcp_smoke.txt
├── test_http.py       HTTP 冒烟 → http_smoke.txt
└── mock_systemone.py  确定性 mock P0 服务

安全声明（与斑海豹生态同口径）

_{▲ `test_mcp.py` 42/42 + `test_http.py` 18/18：帧强制 UTF-8，与 locale 无关（这是 0.1.x 上真实存在的缺陷）}

• gate 的 ask 结果要求集成方把命令与理由呈现给人工，未获明确批准 不得执行（现代面走 elicitation 交互，旧年代走结果文本）；
• 判定结果不构成任何法律责任承诺；fail-closed 是唯一默认；
• 审批策略全文见资源 phocinae://policy/gate-approval（resources/read）。