DarkMatter

DarkMatter MCP 服务

通用 MCP 服务，可为 AI Agent 的决策和操作生成 Context Passport 记录。将其添加到任何兼容 MCP 的客户端（Claude Code、Cursor、Cline、Continue、ChatGPT Desktop、Zed、Goose 等），即可为你的 Agent 提供 commit / verify / replay / export 工具集，生成可验证、防篡改的记录。

由 DarkMatter 构建。实现了 Context Passport v2.0，这是一项开放的 CC0 标准。此服务生成的记录采用 RFC 8785（JCS）规范化，在 Python 和 TypeScript 参考 SDK 中逐字节等效。

安装

在 MCP 客户端的配置中（claude_desktop_config.json、Cursor 的 mcp.json 等）：

{
  "mcpServers": {
    "darkmatter": {
      "command": "npx",
      "args": ["-y", "@darkmatterhub/mcp-server"]
    }
  }
}

重启客户端。你的 Agent 将获得以下五个工具：

• darkmatter_commit — 记录 Agent 的决策或操作
• darkmatter_verify — 检查链是否遭到篡改
• darkmatter_replay — 按顺序遍历完整链
• darkmatter_export — 生成可移植的证明包
• darkmatter_list_sessions — 查看本地有哪些会话

证明包会自我说明

darkmatter_export 会生成一份任何人都能据此采取行动的证明包。除了记录外，它还包含格式名称、规范链接、导出时链是否完整、在 Python 或 TypeScript 中验证所需的准确命令，以及验证失败时的表现。

这很重要，因为证明包是离开你设备的产物。它会交给审计员、监管机构或交易对手，而他们可能从未听说过这种格式；整个承诺就是，他们无需信任发送者也能自行检查。如果证明包没有说明如何验证，就等于要求别人相信它。

默认存储在本地，按需发布

未进行任何配置时，服务会将所有记录保存在你自己的磁盘上。你可以通过 darkmatter_verify 离线验证记录链，无需账户即可评估整个方案。

设置 API 密钥即可发布记录，并获得他人可检查的链接：

变量	作用
DARKMATTER_API_KEY	将每条记录发布到 DarkMatter，并返回 verify_url。请前往 darkmatterhub.ai 获取。
DARKMATTER_SHARE	设为 true，即可让任何拥有链接的人读取已发布的记录。默认关闭，因为未经请求就发布你的记录并不妥当。
DARKMATTER_API_URL	覆盖 API 主机。默认为 https://darkmatterhub.ai。
DARKMATTER_MCP_STORE_DIR	本地记录的写入位置。

commit 会在 storage 字段中报告两种操作中实际发生的一种。如果发布失败，记录仍会在本地提交，同时返回错误，因此网络问题不会导致记录丢失。

在 0.3.0 中更改。 早期版本的每次提交都会返回 https://darkmatterhub.ai/r/{id} 链接，但实际上完全没有进行网络请求， 因此链接总是返回 404。现在只有在记录已发布的情况下才会 返回验证 URL。

会捕获哪些内容

通过 darkmatter_commit 由 Agent（或用户）明确调用的任何内容。未经明确调用而自动捕获每次工具调用，属于独立组件（见下文的 自动捕获）。

Agent 工作流示例：

User:    Approve the refund for order #1247 and record the decision.
Agent:   Calls refund_order(1247).
Agent:   Calls darkmatter_commit({
           input: "Approve refund for order #1247",
           output: "Approved. $84.00 refunded to original payment method.",
           role: "compliance",
           event_type: "commit"
         })
Result:  { ok: true, passport: {...}, storage: "local", verify_url: null,
           note: "Saved locally and verifiable offline..." }

护照会进行签名（如果已配置密钥），与会话中的上一次提交进行哈希链式关联，并在本地保存到 ~/.darkmatter/mcp/<session_id>/chain.jsonl。

存储

默认：仅存储在本地。护照不会离开设备。

~/.darkmatter/mcp/
├── default/
│   ├── chain.jsonl        # append-only stream of all commits
│   └── latest.json        # most recent passport (used as parent for the next)
└── <other-session-id>/
    └── ...

若要在本地存储之外，将每份护照转发到 DarkMatter 接收服务，请设置：

export DARKMATTER_API_KEY="dm_sk_..."

转发采用尽力而为的方式，绝不会阻塞 Agent 的工具调用。本地存储仍是事实来源。

自动捕获

MCP 服务仅捕获 Agent 明确调用的内容。若要在特定开发工具中自动捕获每次工具调用和轮次边界（无需 Agent 记得调用 darkmatter_commit），请安装专用的开发工具适配器之一：

• darkmatter-hub/claude-code — 为 Claude Code（Anthropic）提供自动捕获
• Cursor 适配器 — 计划中
• OpenAI Codex 适配器 — 计划中
• 欢迎社区构建 Aider 适配器

每个适配器都会接入对应开发工具的事件生命周期，并通过此 MCP 服务的 darkmatter_commit 工具转发事件。一个规范端点，多种捕获方式。

验证

记录是有效的 Context Passport v2.0 工件。可使用任何符合规范的实现进行验证：

pip install context-passport context-passport-conformance
context-passport-conformance --level signed     # 9/9 vectors, no --vectors-dir needed

符合性套件将测试向量打包在 wheel 中，因此只需一行命令即可对照公开参考套件进行检查。

或者直接使用离线参考验证器验证 JSONL 文件：

import json
from context_passport import verify_chain

with open("~/.darkmatter/mcp/default/chain.jsonl") as f:
    chain = [json.loads(line) for line in f]

print(verify_chain(chain))  # True if intact, False if tampered

为什么选择 MCP

MCP（Model Context Protocol）正成为 AI 工具的通用互操作层。只需编写一次此服务，即可在每个兼容 MCP 的客户端中使用，无需为每个客户端编写集成代码。有关更广泛的架构依据，请参阅 Context Passport for MCP 提案。

许可证

Apache-2.0。请参阅 LICENSE。

此服务实现的 Context Passport 架构另行以 CC0 1.0 许可发布，地址为 github.com/contextpassport/spec。

相关仓库

• github.com/contextpassport/spec — 开放标准
• github.com/contextpassport/python — Python 参考 SDK
• github.com/contextpassport/typescript — TypeScript 参考 SDK
• github.com/darkmatter-hub/claude-code — 为 Claude Code 提供自动捕获
• github.com/darkmatter-hub/darkmatter — DarkMatter 接收服务