pramana-mcp

Pramana MCP 服务

mcp-name: io.github.loopg/pramana-mcp

通过在你自己的生产运行中测试，判断提示词或模型变更是否可以安全发布。

Pramana 是 AI Agent 的飞行记录器。它会记录 Agent 在生产环境中做出的每一个非确定性决策，使用变更后的代码精确重放任意历史运行，并报告哪些决策发生了变化，而不是哪些句子换了说法。

此 MCP 服务允许助手读取 Pramana 记录的内容，并离线检查经过签名的证据包。它是只读的。 我们特意没有提供启动重放或比较的工具：沙箱中的批处理会针对每条轨迹实际调用模型，因此会产生费用；而 MCP 工具就像一个按钮，任何助手无需经过人类决定都可以按下。生成比较结果仍然是 CLI 命令，并设有独立的确认门槛。

安装

无需安装——uvx 会按需获取。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "pramana": {
      "command": "uvx",
      "args": ["pramana-mcp"],
      "env": {
        "PRAMANA_API_KEY": "<your-engineer-or-admin-api-key>"
      }
    }
  }
}

Claude Code

$ claude mcp add pramana --env PRAMANA_API_KEY=<your-engineer-or-admin-api-key> -- uvx pramana-mcp

在 reliai.in 的 Settings → API keys 中创建密钥。请使用 engineer 或 admin 密钥——审计员密钥有意不提供已记录的提示词或响应，因此 get_trace 返回的内容会是空的。要自托管？请将 PRAMANA_API_URL 设置为你自己的 API。

工具

list_traces

列出 Pramana 捕获的已记录 AI Agent 运行（轨迹），可按 Agent、状态或时间范围筛选。

“上周二我们记录了哪些 Agent 运行？”

{ "agent": "refund-agent", "since": "2026-09-22T00:00:00Z", "limit": 20 }

get_trace

获取一条已记录的 Agent 运行：其步骤、模型调用、带参数的工具调用以及结果。

“带我了解 loan-07 这次运行中 Agent 做了什么——它调用了哪些工具，分别传入了什么参数？”

{ "trace_id": "loan-07-5a6eef" }

较长的载荷会被截断，响应会说明这一点，不会让人误以为内容完整。

list_model_diffs

列出将提示词或模型变更与已记录的生产运行进行比较的结果。

“模型升级后，我们有对照生产环境进行过比较吗？”

{ "since": "2026-09-20T00:00:00Z", "limit": 20 }

get_model_diff

获取一次比较运行的发现结果：哪些决策在行为上发生了变化，哪些只是表面变化，以及哪些运行中止了。

“上周二切换到新模型后发生了什么变化？”

{ "diff_id": "mdr_9f2c1a", "trace_id": "loan-07-5a6eef" }

先返回各类别的数量，然后是根源发现，接着是后续发现——绝不会合并。一项导致四十项下游差异的根本原因，只是一件需要调查的事情，而不是四十件。trace_id 是可选参数，但传入后会快得多（见下文的API 无法做到的事）。

verify_bundle

离线验证 Pramana 的签名证据包，无需账户，也无需网络连接。

“这是供应商发来的证据包。它完整无损吗？”

{ "bundle_path": "./bundle.json", "public_key_path": "./pramana-public-key.txt" }

public_key_path 是必填项。绝不会使用证据包中附带的公钥来验证同一个证据包——那样就失去了验证的意义。

验证通过只能证明证据包自签名后未被篡改，不能证明记录的内容涵盖了实际发生的一切。这是对记录真实性的证明，而非对行为的评判。

API 无法做到的事情

有两个工具的表现不如预期，这不是设计选择，而是 API 的限制：

• 没有可供全账户查询对比运行的端点。 只能按追踪访问（/v1/traces/{id}/model-diffs），因此 list_model_diffs 和不带 trace_id 的 get_model_diff 会遍历最近的 20 条追踪。较早追踪中的对比将无法找到。每个响应都会在 notes 字段中说明这一点，而不会悄悄返回较短的列表。上限设为 20 而不是更大，是因为遍历需要依次进行这么多次往返：在生产 API 上实测，遍历 50 条耗时 6.0s，遍历 20 条耗时 2.4s。
• /v1/traces 返回的是 agent_count，而非 Agent ID，因此按 agent 筛选意味着必须打开每条追踪。此筛选仅应用于最近的 20 条追踪，并会对此作出说明。

限制

这些限制与 SDK 相同。我们不会为了在目录中展示而淡化它们。

• 无法导入现有的对话日志。 重放需要执行追踪，而对话记录不包含追踪。你的语料库从开始埋点那天起算。
• 它会报告决策发生了变化，但不会判断变化是好是坏。 对变化后的决策作出判断由你决定。
• 沙箱仅覆盖你封装过的工具调用。 在沙箱批处理中，你封装过的工具调用会从录制记录中提供，绝不会执行；模型则会实际调用，因为新模型正是你要测试的对象。在普通重放中，完全没有任何内容离开进程：出站网络访问会在进程级别被阻止，层级低于你使用的任何 HTTP 客户端。未封装的工具调用对 Pramana 不可见，并会照常执行，每条追踪执行一次——CLI 会在批次运行前打印找到的已封装工具调用位置数量，以及该数量乘以批次规模后的含义。
• 仅支持 Python。没有 JavaScript 或 TypeScript SDK。
• 支持 OpenAI 和 Anthropic 客户端。Azure OpenAI 和 AnthropicBedrock 会路由到相应适配器，并且已通过测试；但两者都未使用真实云凭证进行验证。不支持原始 boto3。
• 已测试 LangChain。未测试 LangGraph、CrewAI 和 LlamaIndex，也不支持它们。
• 没有 SOC 2 认证、没有渗透测试、没有正常运行时间 SLA，也不支持本地部署。
• 证据公钥尚未发布在稳定 URL 上。 verify_bundle 可离线运行且无需账户，但目前你仍需向我们获取密钥——这不等同于独立验证，我们也没有声称它是独立验证。

证据包示例

evidence-samples/ 中包含两个已签名证据包、各自一份被篡改的副本，以及用于验证它们的密钥。无需账户，也无需联网。该目录中的密钥是 sample-public-key.txt——这是单独用于示例的密钥，并非生产部署发布在 /.well-known/pramana-evidence-public-key 的密钥：

$ pip install 'pramana-verify>=0.0.6'
$ pramana-verify evidence-samples/production-run.json \
    --pubkey evidence-samples/sample-public-key.txt
OK — 2 event(s), merkle_root=6ec957f1ec1443e56c01bab5440df06cfbdd6bbd67c9e8c35398d02d1a840a3a

$ pramana-verify evidence-samples/production-run.TAMPERED.json \
    --pubkey evidence-samples/sample-public-key.txt
TAMPERED / INVALID:
  - payload 535f17dac0ea...: content does not hash to its reference — this recorded prompt or response was tampered with

evidence-samples/FORMAT.md 是逐字段的规范。这些文件使用示例密钥签名，而非用于签署真实证据包的密钥。

---

文档 · reliai.in · pramana-sdk · pramana-verify