murphy-mcp

murphy-mcp

一个为编码 Agent 提供其未曾撰写的记录的 MCP 服务。

编码 Agent 完成任务后会告诉你它做了什么。报告条理清晰、结构良好，而且通常是正确的。但这也是你唯一掌握的说法，而且是由被评估的一方写下的。

这个服务会生成另一份记录。它会在工作开始前记录工作区，之后再次读取，并报告实际发生的变化：每个新增、修改或删除的文件，以及 git 中发生的变动。然后，它会将 Agent 自己的说法与这份记录进行核对，并报告两者之间的分歧。

它不会询问 Agent 发生了什么。这正是关键所在。

基于 2026-07-28 MCP specification 和 v2 TypeScript SDK 构建。采用 MIT 许可证。

---

它能发现什么

问题不在于 Agent 会撒谎。Agent 的报告是基于自身上下文窗口撰写的摘要，而这个上下文只是一个状态远比 Agent 所能掌握的系统的局部视图。报告通常能准确描述意图，但对实际效果的描述就不那么可靠了。

以下三种情况反复出现：

• 叙述之外的副作用。 Agent 说自己编辑了三个文件。实际上写入了四个。第四个可能是缓存、锁文件、生成的产物，或被工具改写的配置。
• 在认知边界上宣称完成。 Agent 完成了自己能看到的部分，并报告任务已完成，因为从它的上下文内部来看，任务确实完成了。
• 磁盘上没有依据的说法。“测试通过了。”“Bug 修好了。”这些说法可能属实，但无论如何，光看文件列表无法判断。

这个服务会分别指出这三种情况。

安装

已发布的构建：

npx -y murphy-mcp

Claude Code：

claude mcp add murphy -- npx -y murphy-mcp

任何 MCP 客户端，都可以通过配置使用：

{
  "mcpServers": {
    "murphy": {
      "command": "npx",
      "args": ["-y", "murphy-mcp"]
    }
  }
}

从克隆的仓库安装：

npm install && npm run build

然后将客户端指向 node /absolute/path/to/murphy-mcp/dist/index.js。

使用

开始工作前创建检查点，然后在工作完成后核对说法。

checkpoint        { root: "/path/to/project", label: "refactor auth" }
                  -> checkpointId

... the agent works ...

check_claims      { root, checkpointId,
                    claimedPaths: ["src/auth.ts", "src/session.ts"],
                    claimedStatements: ["All tests pass."] }

返回内容：

# Evidence report

**2 unreported · 1 contradicted · 1 confirmed · 1 unverifiable**

## Unreported: observed on disk, never mentioned
- `b.txt` (deleted)
- `generated/out.bin` (added)

## Contradicted: claimed, but nothing changed
- `never_touched.ts` — no such file at checkpoint time and none now

## Unverifiable: outside what this record can settle
- The test suite passes. — a filesystem and git record cannot settle this; it needs its own evidence

## Confirmed: claimed and observed
- `a.txt` (modified)

分歧会优先列出，因为这正是需要人来判断的部分。没人会审阅一份包含 50,000 条事件的平铺日志；任何人都能在一分钟内浏览完四条分歧。

四种类别

这些类别刻意分开。将它们混为一谈，正是让说法看起来像证据的原因。

类别	含义
confirmed	已声称，且在磁盘上观察到
contradicted	已声称，但没有任何变化
unreported	磁盘上发生了变化，却从未提及
unverifiable	文件系统或 git 记录中没有任何信息可以确定

unverifiable 会明确标出，而不是悄悄靠猜测得出。以与事实相同的置信度呈现猜测，正是这个工具要防止的问题。

工具

checkpoint

记录当前工作区：每个文件的路径、大小、修改时间和 SHA-256，以及 git HEAD、分支和 status --porcelain。返回检查点 ID。

root（必填）· label · ignore · noDefaultIgnores · maxFiles · maxFileBytes

evidence_since

重新扫描并报告自检查点以来发生的变化。只返回观察到的记录，不涉及任何说法。

root（必填）· checkpointId（必填）· 相同的扫描选项

check_claims

将 Agent 的说法与记录进行核对，并返回四种类别。

root（必填）· checkpointId（必填）· claimedPaths · claimedStatements · 相同的扫描选项

list_checkpoints

列出工作区下保存的检查点，按时间从近到远排列。

root（必填）

值得了解的设计决策

不会忽略构建输出。 默认只跳过 .git、node_modules 和服务自身的 .murphy 存储目录。忽略 dist、.next、target 或 coverage 会恰好隐藏那些往往不在 Agent 说明范围内的写入。若要跳过这些目录，请将其传入 ignore。

检查点会写入磁盘，存放在工作区的 .murphy/checkpoints 下，并附带一个 .gitignore，以免将该存储目录纳入代码仓库。2026-07-28 协议核心是无状态的，因此进程不会保留任何必须超出单次调用生命周期的数据。这也意味着，描述该会话的证据会一直留存，而人们通常正是在会话结束后才需要查阅这些证据。

会记录符号链接，但绝不跟随。 如果快照可能遍历到根目录之外，就无法说明它检查过哪些位置。

哈希有局限，而且会明确说明。 大于 8 MiB 的文件不会计算哈希；对于这些文件，变更是根据大小和修改时间推断的，证据较弱，报告会注明这一点。每个被截断的内容、跳过的目录和未计算哈希的文件，都会列在“此报告未涵盖的内容”下。

此工具不会做什么

明确说明范围，避免任何人感到意外：

• 不追踪进程来源，也不捕获网络流量。 它会查看文件系统和 git 代码仓库，但无法告诉你哪个命令产生了某次写入，也无法说明获取了什么内容。
• 不会读取 .gitignore。 默认忽略列表就是上面提到的三个目录，以及你传入的内容。
• 不是沙箱或防护措施。 它只会事后观察，不会阻止任何操作。
• 无法验证行为。 根据设计，“测试通过”每次都会被判定为无法验证。请运行测试。

与 MURPHY 的关系

MURPHY 是一款独立的商用、本地优先的 Windows 工具，可根据进程来源、文件系统活动、工作区边界和网络行为重建 Agent 活动。此服务是一个独立的跨平台开源实现，涵盖了相同理念中的文件系统和 git 部分，可供任何 MCP 客户端使用。

两者背后的理念详见 Agent 的报告并非证据。

开发

npm install
npm run build
node test/smoke.mjs

冒烟测试会构建一个临时 git 工作区，通过真实的 stdio MCP 连接驱动服务，进行三处更改，报告其中一处，并断言另外两处会作为未报告的更改返回。

许可证

MIT。请参阅 LICENSE。