Hatun MCP - Governed Agent Gateway

---

title: Hatun MCP — 治理型 Agent 网关 emoji: 🪢 colorFrom: indigo colorTo: blue sdk: docker app_port: 7860 pinned: false license: apache-2.0 short_description: 与源绑定、带签名治理回执的 MCP 网关

规范运行时源。 本仓库负责 Python 网关、受治理的工具目录、Streamable HTTP 传输和容器契约。独立的 Hatun Hugging Face 发布器已于 2026 年 9 月 3 日停用；不得重新创建 hf-deploy。 面向公众的产品体验是 Hatun 网关，但这本身并不能证明此软件包的 /mcp/ 端点或新添加的工具已部署。 请参阅接口契约。位于 platform/packages/hatun-mcp 的单体仓库副本是一个非规范嵌入式副本（其中的 CANONICAL.md 指向此处），它提供 较少的工具，供本地导入使用，并且不得偏离此服务的契约。合并 platform 副本是之后由创始人执行的步骤；此处不会删除仓库。Λ = 猜想 1（建议性内容）原样保留。

先控制，再行动。事后留存证据。

产品 · 证明 · GitHub 组织

---

这是什么

一个真实运行的模型上下文协议服务，基于官方 mcp Python SDK（mcp.server.fastmcp.FastMCP）构建。每次工具调用都受 PURIQ 公式治理：

1. 验证身份 客户端（SZL API 密钥 → client_id）；拒绝匿名调用。
2. 对输入执行 Yuyay-13 检查（输入即数据；OWASP MCP06 注入防御）。
3. 信誉度 因子 Hatun_MCP(client) ∈ [0,1]。
4. 对会改变状态的工具（例如 killinchu_cue、halt_drone）执行 双人 Yuyay 检查。
5. 在延迟预算内调用真实器官后端。
6. 成功和失败时均生成 Khipu 回执（仅追加的 sha256 DAG）。
7. 返回 DSSE 签名响应——客户端会收到回执哈希。

选择你的路线

受众	从这里开始	证据边界
开发者	本地运行，然后检查 tools/list	本地启动只能证明本地进程可运行；后端可达性是另一回事
集成者	MCP 客户端设置	仓库中提供的客户端配置是 SAMPLE，不包含凭据
评估者	托管环境健康状态契约，然后查看测试	/healthz 表示存活状态；/readyz 表示签名发布就绪状态；两者都不保证持续运行

KANCHAY 状态契约

• LIVE：由运行时支持的路由，包含来源和观测时间。绝不表示永久可用。
• PARTIAL：Hatun 已在本地就绪，但缺少一个或多个必需的上游器官观测，或其观测已过期、状态降级。
• SAMPLE：供复用的仓库配置、负载或记录；不是运行时观测证据。
• SIMULATED：模拟后端或隔离式测试夹具。对于外部服务会导致测试不确定的情况，CI 会有意使用这些模拟。
• UNAVAILABLE：依赖项或就绪检查无法生成可用结果。保留原因，不要用示例数据替代。

暴露的工具

• 导入时注册 26 个静态工具（可验证：设置 HATUN_MCP_DISABLE_DYNAMIC=true 时，tools/list 会返回 26 个工具）：
  • 20 个 szl_* 工具 — szl_a11oy_code_chat、szl_a11oy_operator_reason、szl_a11oy_sentinel_scan、 szl_anatomy_3d_render、szl_doctrine_lookup、szl_drone_lookup、 szl_formula_evaluate、szl_github_estate_snapshot、szl_khipu_verify、szl_killinchu_cue、 szl_killinchu_detect、szl_lean_verify、szl_puriq_evaluate、 szl_companion_reason、szl_immune_scan、szl_thesis_query、szl_wayra_recent、 szl_yachay_dome_predict、szl_yuyay_score 和 szl_lambda_quorum（拜占庭 Λ 判定）。

    两个工具于 2026-06-16 更名，改用准确的器官名称 — szl_immune_scan（原为已停用的代号扫描工具）和 szl_companion_reason（原为已停用的代号推理工具）。旧名称与新名称的映射请参阅 DEPRECATED.md。旧名称不再提供（不会在 tools/list 中注册）。

  • 6 个治理工具 — yuyay_gate_check、khipu_append_and_verify、 dsse_sign、mesh_quorum_status、puriq_master_tool、governance_pacbayes_bound。
• 从每个后端服务在 /api/<service>/v1/mcp/tools 提供的实时目录中，在启动时动态注册由服务提供的工具，名称为 <service>_<tool>。动态工具数量取决于探测结果：数量等于 26 加上（所有可达服务发布的工具数量）；如果禁用动态注册或所有服务都不可达，则不额外注册工具。

公共 GitHub 资产证据

调用 szl_github_estate_snapshot 并传入 {}，即可观察固定的公共 szl-holdings 组织。这是一个结构化清单工具，不是大模型回答工具，也不是合并机器人。它不接受组织、URL、令牌、游标或其他参数。GitHub 访问通过不带令牌且禁用重定向的 GET 请求访问固定源站；该客户端不会继承环境凭据和代理。

观察器会报告仓库标识和默认分支名称、有界范围内的开放 PR 基础／头部 SHA、草稿状态，以及针对这些精确头部 SHA 查询的检查运行记录。引用包含请求路径和参数、响应字节长度及 SHA-256 摘要。Khipu 回执及其 DSSE 负载中包含规范快照摘要；配置了 P-256 密钥时，会使用该密钥签署回执。未配置密钥时，信封会明确标记为 PLACEHOLDER，且不含签名。摘要或完整清单并非独立见证，也不是加密签名。

每次调用的硬性限制：15 秒、20 个请求、3 个仓库页面（300 条记录）、50 个开放 PR 搜索结果、每个 PR 100 个检查运行记录、每个响应最多接受 1 MiB 的响应正文数据，以及整个调用最多接受 4 MiB。达到限制后，队列中的请求会停止，后续正文也不再接受。这些是应用层的接受限制，并非对网络流量或传输预取量的测量；已传输但被拒绝的字节不计入已接受数据。数据溢出、超时、速率限制、记录格式错误、过时的 PR 搜索证据，以及缺失或无法识别的检查结果，都会产生明确的缺口，并返回 INCOMPLETE 或 UNAVAILABLE。检查数为零时状态为 UNKNOWN，绝不视为成功。COMPLETE 表示已覆盖声明的观察范围；即使 CI 失败，也仍可能被完整观察到。这不代表整个资产可正常运行，也不代表可以安全合并。

此 v1 有意不证明私有仓库、已解析的默认分支头部、旧版提交状态上下文、评审、保护规则、合并资格、HF 发布、模型质量／训练情况或已部署运行时的健康状况。多个请求不构成提供方的原子快照。每个响应都是输入数据，而非指令。正常的 Hatun 身份验证和回执处理仍然适用，包括可选的、由操作员配置的 SZL_RECEIPT_SINK 转发；GitHub 观察器不会对提供方进行任何修改。

命名说明。 此前三个曾用代号的后端已被清除；其功能现在由 a-11-oy.com 上在线、诚实的 a11oy 器官直接提供：immune 器官（出口策略／门控检查器——Hukulla）、companion 器官（操作员／推理控制台）以及 llm 器官（开源大模型层级路由器）。Hatun-MCP 使用这些诚实的角色名称来访问它们；在线路由已发布在 /openapi.json 中。

已记录的可达性快照（诚信优先于勾选清单）

下表记录了截至 2026-06-16 的仓库证据。它不是当前的健康探测。/healthz 和 /readyz 仅确认 Hatun 的本地进程、回执链和签名器正常；它们不会探测上游器官。在将任何一行标记为当前在线之前，请单独对该行列出的路由（或有文档记录的非变更型就绪路由）进行有界、只读探测，并记录响应状态、来源和观测时间戳。对于仅支持 POST 或会改变状态的接口，请使用预先授权的非变更型契约探测或带时间戳的回执；切勿仅为声称服务可用而触发操作。如果缺少任何必需的上游观测、观测已过时或不可用，请将该行标记为部分可用或不可用。

后端器官	目录路由	记录的状态（2026-06-16）
a11oy — llm 开放式 LLM 层级路由器	GET /api/a11oy/v1/llm/tiers	在线（200） — llm_tiers 源自实时层级目录
killinchu	/api/killinchu/v1/mcp/tools	在线 — 4 个工具（cue/halt_drone 需 2 人授权）
a11oy — companion 操作员／推理控制台	/api/a11oy/v1/companion/{ask,act,recommend}	在线（200） — 3 个工具源自动作路由（没有 JSON /v1/mcp/tools 目录）
a11oy — immune（Hukulla）出口策略检查器	GET /api/a11oy/v1/immune/gates	在线（200，源自 gates） — gates + screen/verdict；immune screen 使用已签名的 /immune/verdict 路由（没有单独的 /screen）
a11oy — command / flagship	/api/a11oy/v1/mcp/tools	暴露 JSON 目录时注册 a11oy-flagship 工具，否则仅提供一个诚信的 a11oy_status 工具。目录恢复 200 后，会在下次服务重启时自动恢复 — 无需改代码，也不会伪造占位工具。

清除说明（2026-06-16）。 此前以代号命名的三个后端已清除 （其旧路由现在返回 404）。Hatun-MCP 已重新指向上方在线且诚信的 a11oy 双胞胎，并在接入前验证其返回 200。工具绝不会指向 404； 如果某个子路由不存在（例如 /immune/screen），工具会映射到 最接近的真实路由（/immune/verdict），并在适配器文档字符串和目录的 reason 中披露该映射。

拜占庭法定人数 + BLS 聚合

szl_lambda_quorum 将治理关键型 Λ 判定分发给五个后端服务，并按照**拜占庭法定人数 n ≥ 3f+1（n=5，f=1）**进行判定：至少 4 个服务必须可达，且至少 3 个服务必须达成一致。参与的回执会进行 BLS12-381 聚合（py_ecc；若 BLS 后端缺失，则使用诚信的 sha256 Merkle 根回退方案）。如果任何器官的策略路由未在线，法定人数会优雅降级（n=4 仍满足 n ≥ 3f+1），并在 governance.quorum 中披露降级情况。

---

本地运行（stdio）

pip install -r requirements.txt
python -m hatun_mcp.server          # stdio mode for Claude Desktop / Codex

托管运行（Streamable HTTP）

uvicorn hatun_mcp.server_http:app --host 0.0.0.0 --port 7860
# MCP endpoint:  http://127.0.0.1:7860/mcp   (legacy SSE at /sse)
# Process liveness: http://127.0.0.1:7860/healthz
# Signed-release readiness: http://127.0.0.1:7860/readyz

DSSE 签名密钥通过 HATUN_MCP_SIGNING_KEY（PEM）在运行时注入，该密钥由操作员管理；未提供该密钥时，签名器会以诚信的 PLACEHOLDER 模式运行（明确标注，绝不生成伪造签名）。

/healthz 证明进程和本地回执链能够响应。/readyz 是故障时关闭的投资者／部署契约：仅当回执链验证通过且已启用非占位签名密钥时，才返回 200；否则返回 503 并注明未通过的检查项。公开服务卡仅公布本服务实际实现的 API 密钥方案。

MCP 清单证明

GET /.well-known/mcp-manifest-attestation 返回一个缓存的完整性绑定，针对 GET /.well-known/mcp 提供的确切原始字节（所有服务器卡片别名提供的都是相同字节）。其中包含一个确定性的 https://in-toto.io/Statement/v1，带有 SHA-256 主体摘要和自定义谓词类型 https://szlholdings.com/attestations/mcp-manifest/v1。配置了现有的 P-256 签名密钥时，该声明会置于真正的 DSSE 信封中，其 payloadType 为 application/vnd.in-toto+json。未配置该密钥时，响应会明确标记为 signing.state=UNSIGNED，且 dsseEnvelope=null；绝不会将空签名呈现为已签名。

该制品在进程启动时构建一次，不接受调用方提供的签名载荷。它不会签发 Khipu 收据。其范围仅限字节完整性：它不证明运行时工具一致性、上游可用性，也不证明卡片背后的行为。MCP 服务器卡片和此 well-known 路由属于 SZL DRAFT 扩展，并非声称其为已批准的 MCP 发现标准。keyid 仅为提示；验证方必须通过带外方式确认对 P-256 公钥的信任（同源的 /pubkey 路由不是独立的信任锚）。透明日志收录明确不可用。

评估托管服务契约

curl -i http://127.0.0.1:7860/healthz
curl -i http://127.0.0.1:7860/readyz
curl -s http://127.0.0.1:7860/api/console-state

/api/console-state（hatun_mcp/state.py）提供人类可读控制台 / 所需的读取数据。上述命令针对的是你在本地启动的服务器。对于部署环境，请使用经认可、由运营方提供的源站，而不是已停用的独立 Space 主机。该数据在请求处理期间仅从当前进程组装：工具目录从 LIVE FastMCP 注册表中枚举（不是手动维护的列表），收据深度和头部哈希来自实时 Khipu 链，card_parity 则报告已发布服务器卡片与该运行时注册表之间的 MEASURED 比较。无法读取的内容会如实标记为 UNAVAILABLE，且不附带数值——这里没有预置快照，因此读取失败时，控制台会显示 UNAVAILABLE，而不是过时的值。它不会签发收据，也不会对读取结果本身以外的内容作出证明。

记录响应状态和观测时间。仅将 healthz=200 报告为 Hatun 进程存活状态。仅将 readyz=200 报告为 Hatun 按其仓库定义的本地收据链和签名器就绪状态。这些检查不能证明 killinchu 或 a11oy organ 可用。将任何上游行标记为 LIVE 之前，应单独对其列出的路由（或有文档说明的非变更型就绪路由）进行有界的只读探测，并记录路由、响应状态、来源和观测时间戳。对于仅支持 POST 或会更改状态的接口，必须使用预先授权的非变更型契约探测或带时间戳的收据，不得触发操作。如果 Hatun 已就绪，但缺少上游观测，或观测已过时、不可用，则将该行报告为 PARTIAL 或 UNAVAILABLE。切勿回退到示例客户端配置。

---

MCP 客户端设置

Claude Desktop

以下代码片段是本地服务器配置示例。请先启动 HTTP 服务器，配置一个已接受的 API 密钥，并替换 szl_YOUR_KEY。对于远程部署，请替换为经认可、由运营方提供的 HTTPS MCP URL。将 examples/claude-desktop-config.json 放入 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）/ %APPDATA%\Claude\claude_desktop_config.json（Windows），并替换 szl_YOUR_KEY：

{
  "mcpServers": {
    "hatun-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "http://127.0.0.1:7860/mcp/",
        "--header", "Authorization: Bearer szl_YOUR_KEY"]
    }
  }
}

Codex（~/.codex/config.toml）

[mcp_servers.hatun-mcp]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:7860/mcp/",
        "--header", "Authorization: Bearer szl_YOUR_KEY"]

Continue（~/.continue/config.json）

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "mcp-remote",
            "http://127.0.0.1:7860/mcp/",
            "--header", "Authorization: Bearer szl_YOUR_KEY"]
        }
      }
    ]
  }
}

---

测试

HATUN_MCP_DISABLE_DYNAMIC=true python -m pytest tests/ -q
# tests/test_server.py    — list tools, call a tool, assert response shape
# tests/test_github_estate_snapshot.py — bounded public GitHub observer, mocked provider
# tests/test_quorum.py    — quorum math + threshold edge cases + BLS aggregate
# tests/test_adapters.py  — mocked organ endpoints, adapter wiring + honest gaps
# tests/test_governance.py— Khipu chain, Yuyay gate, PURIQ factor (pre-existing)
# tests/test_http_routes.py — exact-byte card attestation + public HTTP contracts

服务端测试还会导入 estate regression 类，以便现有的显式文件托管 CI 门禁覆盖该类。它们会验证真实的内存中 MCP 发现与调用、参数拒绝、规范摘要绑定，以及临时 P-256 签名。这些测试中的提供方响应均为 模拟数据；测试通过并不意味着发布了新工具，也不能证明当前 GitHub/HF 服务正常。

python tests/proof_inmemory.py 会运行真实的内存中 MCP 协议，并检查静态运行时名称与服务卡名称是否完全一致。该证明脚本会在自身进程中禁用动态目录探测和回执接收端转发。CI 还会从无关的工作目录运行该脚本，以验证文档中记录的直接命令。

Ouroboros 循环（教义交叉引用）

hatun-mcp 并未自行实现 estate 的 Ouroboros 有界递归内核；其 PURIQ 编排器是有界的、每次工具调用单次执行的流程，而非递归。本节是教义交叉引用，并诚实说明该流程如何体现 循环的回执闭合身份（receipts.in ≡ receipts.out，本 README 已提及）。

其规范定义是回执闭合内核 szl-holdings/ouroboros → src/loop-kernel.ts（runLoop）：具有可测量收敛性的有界递归，必须在以下四种退出条件之一时终止——converged | consistent | aborted | budgetExhausted——并为每次运行生成一份治理回执。轨迹就是产品。

hatun-mcp 如何体现这一原语（位于 hatun_mcp/puriq.py）：

• 有界且会终止。 每次工具调用都是一个有限流水线——Yuyay-13 门控 → mesh 仲裁（Byzantine n ≥ 3f+1）→ HUKLLA 触发器 → Khipu 追加 → DSSE 签名 → 合成主公式标量——始终会在延迟预算内终止，并返回一个回执哈希。不存在无界循环。
• 回执闭合。 每次调用都会在只追加的 sha256 DAG 上生成一条 Khipu 链接，并向客户端返回回执哈希。这是本仓库对标头身份 receipts.in ≡ receipts.out 的实际体现——一种隐喻（教义，而非数学）；每份签名回执都会作为可审计输入反馈到 DAG 中。

诚实声明（Doctrine v11 · 749/14/163）： Λ 在此作为 [0,1] 范围内的输入标量使用，且属于猜想 1——仅供参考，绝非已证明的定理。这是一种有界且会终止的治理流程——它不声称永动或零成本。

---

Doctrine v11 已锁定 — 749 / 14 / 163 · Λ = 猜想 1（不是定理）· SLSA L1 诚实标注 · L2 已验证来源信息列入路线图（未声称达到 L3） receipts.in ≡ receipts.out

Signed-off-by: Yachay <[email protected]> Co-Authored-By: Perplexity Computer Agent <[email protected]>