pranaxis-mcp-gateway

Pranaxis MCP Gateway

为 MCP 工具调用提供一致性判定。 一个透明的 stdio 代理，位于任意 MCP 客户端（Claude Code、Cursor、Codex、自定义 Agent）与任意 MCP 服务之间。读取操作原样通过。会消耗共享资源的调用（启动运行、支付订单、以给定 sha 写入文件、更新行）会先经过仲裁：如果另一个 Agent 已持有该资源版本，调用就不会到达工具，Agent 会收到一条易读的错误消息和证书。

它解决了多 Agent 系统中的更新丢失问题：两个 Agent 各自遵循自己的策略，却两次消耗同一项资源。

agent ──stdio──▶ pranaxis-mcp ──stdio──▶ your MCP server ──▶ tool
                     │
                     └── verdict (software, or the Pranaxis chip)

安装

pip install pranaxis-mcp-gateway      # or: uvx pranaxis-mcp-gateway

使用

在 MCP 客户端中注册 Gateway，而不是注册服务，并将服务设为子命令。每个 Agent 使用一个 Gateway，并设置各自的 --agent-id；同一台机器上的所有 Gateway 共享版本状态。以下是 Claude Code 配置 AMD Ross Vivado 服务的示例：

claude mcp add vivado-mcp --scope project --transport stdio --env VIVADO_PATH=/path/to/vivado -- \
  pranaxis-mcp --agent-id agent-a --rules vivado-ross -- vivado-mcp-server --stdio-bridge

GitHub MCP 服务：

pranaxis-mcp --agent-id agent-a --rules github-official -- npx -y @modelcontextprotocol/server-github

被拒绝的调用会返回 isError: true，并附带类似以下消息：

DENIED by the Pranaxis consistency verifier.
Resource 'owner/repo/main/README.md' version abc123 is being consumed by another agent
(holder: agent-a; their request: agent-a-3f2c...). Certificate: ...
Your call did NOT reach the tool. Do not retry the same write; read the current state and work from it.

工具描述会添加标注，让 Agent 知道写入操作会经过仲裁。在我们的测试中，Agent（两个不同的模型）被拒绝后不会盲目重试：它们会读取状态并选择其他操作。

规则：哪些操作算作消耗

规则是数据，每个 MCP 服务对应一个 JSON 文件（src/pranaxis_gateway/rules/）。每条规则都会指定工具，使用正则表达式匹配参数（命名分组会成为字段），通过模板构建资源名称，并可选地从某个参数获取版本（例如 GitHub 的上一个 blob sha）。release 规则用于说明哪些响应表明资源已完成。已完成的资源会继续归其持有者所有，直到持有者发起下一次调用（即已收取结果）或宽限期到期（--grace，默认 600 s）：在持有者读取结果之前，任何人都不会清除他人的结果。

内置规则：vivado-ross（AMD Ross Vivado MCP 服务）、github-official、postgres-generic。与规则不匹配的调用会直接通过，并记录为 passthrough。欢迎贡献其他服务的规则。

验证器

• --verifier stub（默认）：软件参考实现。持有者通过状态文件共享；判定不包含物理测量。
• --verifier fam --fam-endpoint host:port：Pranaxis 物理验证器，是 AMD Zynq UltraScale+ / Kria 设备上的环形振荡器模块，用于测量仲裁并返回包含 sieve、频率、容差和时序信息的证书。该硬件是独立产品（https://pranaxis.eu）；本仓库仅包含 Gateway 及其使用的 HTTP 接口约定。

证书

每项判定都会追加到 ross_demo_YYYYMMDD.jsonl（可通过 --log-file 配置文件名）：Agent、资源、版本、判定、原因、冲突请求、证书 ID、物理测量数据（如有）以及代理延迟。只读调用会记录为 passthrough。

测试

python tests/test_two_agents.py --verifier stub        # two agents, Vivado-like server: P1..P4
python tests/test_rules_generic.py                      # GitHub and SQL rule files

状态和路线图

0.3：本地模式（每个 Agent 一个代理，stdio）、声明式规则、持有者释放 / 宽限期、jsonl 日志。已在 ZUBoard 1CG 上使用物理验证器进行测量（10/10 次预注册运行），并由两个真实 Agent 在 AMD Ross 上进行测试。 下一步：集中式模式（所有 Agent 共用一个网络 Gateway，提供审计 API）、在 Kria K26 上运行的嵌入式模式。

知识产权和许可

代码：Apache-2.0。仲裁流程和物理设备受西班牙专利申请 P202631184 和 P202631345 保护（被许可方为 Arignatxa S.L.）；使用本 Gateway 和软件验证器免费；物理验证器 bitstream 不属于本仓库。“Pranaxis”是商标申请（M4406608）。