Phocinae MCP

phocinae-mcp

把斑海豹的命令审批门与 P0 推理协议暴露为 MCP 工具（gate / classify / route / score），接入只读 MCP 的编码代理。双代协议并存：现代面（2026-07-28，含 server/discover、MRTR 交互、Streamable HTTP）与 2024-11-05 旧客户端兼容。

[PyPI] [Registry] [MCP] [deps]

_{▲ `tools/list` 的真实应答：四个工具的参数与返回形状}

斑海豹生态的 MCP server：把斑海豹的命令审批与推理能力以 4 个工具暴露给 MCP 客户端。纯标准库（Python ≥ 3.8，零第三方依赖），支持 stdio 与 Streamable HTTP 两种传输，MCP 2026-07-28 对齐并兼容 2024-11-05 旧客户端。

本仓库为本地增强版（基于 PyPI phocinae-mcp 0.1.1），仅用于本地开发与 协议对齐验证，不发布。

Install (local enhanced build)

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

This repository is a local enhanced build and is not the PyPI release; the registry entry and the package below refer to the same server contract.

工具

_{▲ **合成演示动画**（模型仓 docs/gallery [S07](https://huggingface.co/Phocinae/Phocinae-Largha-150M-v1/blob/main/docs/gallery)）：画面为逐帧渲染、场景数据虚构，但它演示的 **`route` 工具「一次前向在候选工具里选出该用的那个」的判定过程** 与真实实现一致（本页上方的终端截图即真实运行的同一流程）。}

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 帧。 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 一致）。

现代面补足项：

兼容性：旧客户端 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 HTTPpython3 -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.txtpython3 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__.pytests/├── 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）。