把斑海豹的命令审批门与 P0 推理协议暴露为 MCP 工具（gate / classify / route / score），接入只读 MCP 的编码代理。双代协议并存：现代面（2026-07-28，含 server/discover、MRTR 交互、Streamable HTTP）与 2024-11-05 旧客户端兼容。
斑海豹生态的 MCP server：把斑海豹的命令审批与推理能力以 4 个工具暴露给 MCP 客户端。纯标准库（Python ≥ 3.8，零第三方依赖），支持 stdio 与 Streamable HTTP 两种传输，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 --helpThis 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.
Related MCP server: DeadBolt
工具 | 作用 | 输入 | 输出 |
| 判定 shell 命令能否执行 |
|
|
| 把状态归入候选标签之一 |
|
|
| 从候选工具中选最合适的一个 |
|
|
| 按标准给状态打 2–10 分 |
|
|
fail-closed：斑海豹 P0 服务（/v1/systemone）不可用、超时、应答异常时，
gate 一律返回 deny（带原因），classify/route/score 返回 isError: true。
python3 -m phocinae_mcp --server http://127.0.0.1:8155MCP 客户端以子进程方式拉起，走 stdin/stdout 逐行 JSON-RPC 帧。
stdout 纯净性保证：stdout 只输出 JSON-RPC 帧；一切日志（启动、告警、
工具内部异常）只走 stderr（phocinae-mcp[level]: 前缀）。guard.py 导入期
的打印也被重定向到 stderr，不会污染协议通道。
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
可替代命令行开关。
双代并存，按请求逐条分派：
带 params._meta（含 io.modelcontextprotocol/* 键）的请求、以及
server/discover、resources/* → 现代面；
initialize 握手、无 _meta 的请求 → 旧年代（2024-11-05 行为，
与原版 0.1.x 一致）。
现代面补足项：
项 | 实现 |
| 必实现： |
| 逐请求必填 |
| 一切结果携带（ |
|
|
多轮交互（MRTR） |
|
resources |
|
已移除方法 | 现代面下 |
工具 schema 收紧 |
|
description 重写 | 四工具均按「何时使用 / 何时不使用」结构重写 |
日志 | 全部走 stderr； |
兼容性：旧客户端 initialize 握手返回 2024-11-05 能力；无 _meta 的
tools/list/tools/call 按旧年代应答（不报错）——对旧客户端零破坏。
# 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.txttest_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 服务gate 的 ask 结果要求集成方把命令与理由呈现给人工，未获明确批准
不得执行（现代面走 elicitation 交互，旧年代走结果文本）；
判定结果不构成任何法律责任承诺；fail-closed 是唯一默认；
审批策略全文见资源 phocinae://policy/gate-approval（resources/read）。
何时使用：需要把一段状态/上下文归入若干已知标签之一（意图分类、类型识别）时。何时不使用：标签未知或不固定时（改走 route 或让模型自由作答）；需要对同一对象打多重分数时（用 score）。返回 choice=选项下标（0 起）、label、置信度；服务不可用返回明确错误。
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | 待分类的上下文/状态描述（必填；上限 20000 字符） | |
| labels | Yes | 候选标签列表（必填；1–100 个非空字符串，单项上限 2000 字符） | |
| server | No | 可选：覆盖服务地址（http://host:port，等价于 --server；上限 2048 字符） |
| Name | Required | Description |
|---|---|---|
| label | Yes | |
| model | No | |
| state | Yes | |
| usage | No | |
| choice | Yes | |
| labels | Yes | |
| server | No | |
| question | Yes | |
| confidence | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Because no annotations are provided, the description carries the full burden of describing behavior, and it does this well by describing the return shape (0-based choice index, label, confidence) and the failure mode (an explicit error when the service is unavailable). It omits operational details such as latency, determinism, and authentication, and it never explicitly says that the call is side-effect-free, so it is strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is three tight clauses covering when to use, when not to use, and what is returned, in a front-loaded order with zero filler. Every sentence carries decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool, an output schema exists, and the description even goes beyond it by covering the failure mode. The remaining gap is that without annotations, the description does not explicitly state the safety profile (side-effect-free) or whether the call is deterministic and how long it takes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description still adds real meaning by tying the returned 0-based index to the order of the supplied labels, which tells the agent that label ordering matters. It adds nothing about the optional server override beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: mapping a piece of state/context onto one of several known labels, with concrete examples (intent classification, type recognition). It also names the siblings it is not (route, score), so an agent can distinguish it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance on when to use the tool (classification into a fixed label set) and when not to use it, naming both the conditions and the alternatives: when labels are unknown or not fixed, use route; when you need to score the same object on multiple dimensions, use score. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
何时使用：需要判定一条 shell 命令能否执行时——代码代理要跑命令、批处理要校验、人工要复核灰区命令，都用 gate 逐条判定。何时不使用：不要用它判定非 shell 操作（文件读写、HTTP 调用）；不要把多条命令拼成一条字符串绕过判定；宿主已有内置审批机制时不要重复叠加。返回 decision ∈ allow|deny|ask 与 layer/reason；ask 时结果携带人工确认交互（MCP 2026-07-28 elicitation）或明示需人工复核；服务不可用 fail-closed 返回 deny。
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | 命令执行工作目录（可选；默认服务器进程当前目录） | |
| server | No | 可选：覆盖服务地址（http://host:port，等价于 --server；上限 2048 字符） | |
| command | Yes | 待判定的 shell 命令（必填；上限 20000 字符） |
| Name | Required | Description |
|---|---|---|
| cwd | No | |
| noul | No | |
| tool | No | |
| error | No | |
| layer | Yes | |
| model | No | |
| score | No | |
| engine | No | |
| reason | Yes | |
| server | No | |
| status | No | |
| command | Yes | |
| decision | Yes | |
| confidence | No | |
| noul_state | No | |
| fail_closed | No | |
| human_action | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it declares the return shape (decision ∈ allow|deny|ask plus layer/reason), states that ask triggers a human-confirmation interaction (MCP elicitation) or explicit manual review, and specifies fail-closed behaviour returning deny when the service is unavailable. Failure mode and human-in-the-loop semantics are exactly what an agent needs before wiring this into a pipeline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the decision-critical '何时使用 / 何时不使用' labels, then return values and failure mode. Every clause carries information (scenario, exclusion, output shape, fail-closed) and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Three parameters all documented, output schema present, no annotations needing compensation, and the description still adds decision semantics, human-review path, and fail-closed behaviour. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so command/cwd/server are already fully documented in the schema, which sets the baseline at 3. The description only implicitly touches parameters via the 'don't concatenate multiple commands into one string' constraint; it adds no cwd or server-override semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb + resource: judging whether a single shell command may execute, and explicitly scopes out non-shell operations (file I/O, HTTP calls). An agent can tell this apart from the generic sibling names classify/route/score because the description pins the domain to shell-command gating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with an explicit 'when to use' clause covering three concrete caller scenarios (coding agent about to run, batch validation, human grey-zone review) and follows with three explicit 'when not to use' exclusions, including the anti-pattern of concatenating commands to bypass judgement and stacking on an existing host approval mechanism.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
何时使用：有确定的候选工具/处理器清单、需要从中挑出最合适的一个来服务请求时。何时不使用：候选清单不固定或用户已直接指定工具时（尊重用户指定，不重复路由）；要评估每个候选的质量而非挑选时（用 score 逐个打分）。返回 choice=下标、tool=选中的工具名；服务不可用返回明确错误。
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | 请求/上下文描述（必填；上限 20000 字符） | |
| tools | Yes | 候选工具名列表（必填；1–100 个非空字符串，单项上限 2000 字符） | |
| server | No | 可选：覆盖服务地址（http://host:port，等价于 --server；上限 2048 字符） |
| Name | Required | Description |
|---|---|---|
| tool | Yes | |
| model | No | |
| state | Yes | |
| tools | Yes | |
| usage | No | |
| choice | Yes | |
| server | No | |
| question | Yes | |
| confidence | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose the outcome shape (choice = index, tool = selected name) and the failure mode (clear error when the service is unavailable), plus the non-destructive selection semantics implied by 'pick one'. It omits any statement about how selection is performed (model-based routing, latency/cost) and says nothing about the `server` override's effect on behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with 何时使用 before 何时不使用, then return values in a single short clause. No filler sentences; each clause carries a distinct decision rule or output fact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description needn't restate return structure, and it still adds the error case. For a 3-parameter router, the only real remaining gap is how the selection is made and how the optional `server` override changes routing scope; siblings `gate` and `classify` are also not differentiated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents `state`, `tools`, and `server` with lengths and counts. The description adds no further meaning about these parameters (e.g., what counts as a good `state` string, whether `tools` must be exact registered names), so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: pick the single best-suited tool/handler from a fixed candidate list to serve a request. It explicitly contrasts itself with the sibling `score` (per-candidate quality scoring vs. selection), so an agent can tell the two apart without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit 何时使用 / 何时不使用 pair: use when the candidate list is fixed and one must be chosen; do not use when the list is unstable or the user already named a tool (respect the user, don't re-route), and use `score` instead when you need per-candidate quality. Alternative and exclusion conditions are both spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
何时使用：需要按 criteria 给 state 打 2–10 分（风险、质量、适配度等）时。何时不使用：需要分类（用 classify）、多选一（用 route 或 gate）、或分数语义与 2–10 量纲不符时。返回 score ∈ [2, 10] 与 range；服务不可用或应答越界返回明确错误。
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | 待打分对象的状态描述（必填；上限 20000 字符） | |
| server | No | 可选：覆盖服务地址（http://host:port，等价于 --server；上限 2048 字符） | |
| criteria | Yes | 打分标准列表（必填；1–100 个非空字符串，单项上限 2000 字符） |
| Name | Required | Description |
|---|---|---|
| model | No | |
| range | Yes | |
| score | Yes | |
| state | Yes | |
| usage | No | |
| server | No | |
| criteria | Yes | |
| question | Yes | |
| confidence | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses the returned score range [2, 10] and range, plus explicit error behavior for service unavailability or out-of-range responses. It does not discuss side effects, idempotency, or authentication, though these are less critical for a scoring operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it leads with when to use, then when not to use, then return and error behavior. Every sentence adds actionable information, with no repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the input schema is fully documented, and an output schema exists, so the description need not enumerate return fields. It still completes the picture by covering the scale, alternatives, and error cases, leaving no major gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents state, criteria, and server fully. The description references criteria and state in the usage context but adds no format or constraint details beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: scoring a state against criteria on a 2–10 scale, with examples such as risk, quality, and fit. It explicitly distinguishes this tool from its siblings classify, route, and gate, so an agent can select it without opening the schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use and when-not-to-use guidance, including the exact condition for choosing classify for categorization and route or gate for single-choice routing. It also excludes cases where the score semantics do not match the 2–10 dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.6classifygateroutescoreScored across 4 tools
Each tool targets a fundamentally different decision shape: gate = command allow/deny/ask, classify = pick one known label, route = pick one tool from a fixed candidate list, score = numeric 2–10 rating. The descriptions explicitly state when NOT to use each tool and cross-reference the alternatives (e.g. 'use route instead of classify when labels are unknown'; 'use score to rate each candidate'), which eliminates the usual classify/route/score overlap.
All four names are single lowercase English words with no camelCase/snake_case mixing, which is highly predictable. The only minor deviation is that gate reads as a noun/resource while classify, route, and score are verbs, but the concise one-word convention is still uniform.
Four tools is well within the ideal 3–15 range and each corresponds to a distinct decision primitive (permit, categorize, select, rate). Nothing feels padded or missing at the count level; the surface is tightly scoped to a decision/judgment layer.
The server covers the core judgment operations—ternary gating, closed-set classification, single-choice routing, and bounded scoring—with explicit fail-closed/error behavior, so no major workflow dead-ends. Minor gaps exist around batch/multi-item evaluation and combined multi-step decisions, but agents can chain the four tools to work around these.
MCP server for CertScore.ai public website risk-signal workflows.
Guard wraps stdio MCP servers: risky calls wait for a person; no answer, no run. Remote: cooperative
MCP server (stdio): check if URLs are alive (status, redirects, latency) via the AgentForge API
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.