MCPgraphy 发布：为 MCP 工具调用加一层学习型代理

你 agent 的工具，在它动手之前就已梳理清楚。 一个适用于任何 MCP 服务器的代理，它从 agent 自身的调用中学习哪些工具在哪种状态下有效，并在下一次错误调用发生前发出警告或加以阻止。 pip install mcpgraphy mcpgraphy wrap --adapter adapter.json --policy warn -- npx -y @modelcontextprotocol/server-filesystem ~/work 把你的 MCP host 指向这条命令，而不是直接指向服务器。同样的工具、同样的参数、无需密钥，任何数据都不离开你的机器。 explainer-voiced.mp4 1 分 48 秒讲清 MCPgraphy（带旁白）：工具调用错在哪里、代理如何从 agent 已有的调用中梳理出你的工具、以及一个真实的 GPT agent 跑在它后面时发生了什么变化。片中的每一个数字都来自下方的基准测试。 一个 MCP 服务器交给你的 agent 一份工具清单：名称、描述、参数 schema。它从不说某个工具在什么时候有效。于是 agent 去编辑一个并不存在的文件、发布一个从未测试过的 release、移动一张已经关闭的工单，然后从错误信息里才知道出了问题。接着它重试。有时候，正是这次重试造成了破坏。 每个 agent 框架都以同样的方式重新发现这一点：靠烧调用。服务器其实早就知道答案，只是不预先说出来，而协议里也没有任何东西要求它说。 MCPgraphy 位于 agent 和服务器之间。工具原样透传。在每次调用前后，它都会回读所触及的资源，并将其作为证据留存。根据这些证据，它构建一张行为图：节点是它实际观察到的状态，边是从每个状态出发发生过什么、发生过多少次、以及后续调用是否与之吻合。 它从不主动探测你的服务器，从不重置任何东西，也从不增加 agent 没有发起的调用。学习是被动的。这是经过实测的选择，而非局限；请看数据。 两个模拟服务器（一个 release 流水线和一个工单跟踪器，带有隐藏状态、漂移、过期快照和干扰 id）上的 200 个有状态任务，一个脚本化 agent，五种指导来源。oracle 在每次调用发起前对其作出判定。相同的种子、相同的字节，每一次运行都如此。 那张表里的三件事决定了这个设计： 完整的表格、消融实验和方法都在 docs/BENCHMARK.md 中。大约 20 秒即可自行重跑：mcpgraphy benchmark run --suite stateful-v1 --seed 42。 同样的 200 个任务、同样的 oracle，由 GPT-5.4-mini 自己发起工具调用。裸工具，对比同样的工具跑在按默认配置发布的代理之后：阻断门禁，加上每次读取、每个动作结果和每次拒绝时来自行为图的一行提示。 任务如何计数。agent 拿到一个目标（“把这个 release 变成 PUBLISHED”）和服务器的工具。每当它决定下一步做什么，就算一个模型轮次，而到目前为止的整段对话都会被重新发给模型，token 就花在这里。它调用的每个工具算一次工具调用；oracle 在每次变更性调用运行前对其进行判定，所以被拒的调用是服务器会拒绝的调用，而被拦下的调用是代理先行阻止的调用。当 agent 声称目标已达成（会对照服务器核查；虚假声明算作误报成功）、声称目标不可达，或者步数用尽时，任务结束。以下所有数据均为每任务平均值，在 200 个任务上取平均。 从任务开始到任务结束实测，在同类预算下代理完成了 129 个任务，而裸工具为 96 个，因此每个完成的任务少花 7% 的 token，工具调用更少，模型轮次也更少。裸工具唯一胜出的列是每个尝试任务的 token 数，而它胜出的部分原因是放弃：在那些不可达的任务上，它把一个被要求改为可编辑的 release 归档了，然后报告成功。 裸工具几乎四分之一的 token 花在了以服务器拒绝的调用收尾的轮次上。在 MCPgraphy 之后，agent 把 token 花在工作本身，每个轮次为那行图提示多花约 60 个 token。 我们尝试过的每种配置，都在同一坐标系上。越靠上完成的 任务越多，越靠左每个尝试任务越便宜： 只拒绝调用而不说明还有什么可能，是最便宜的一点，也是最差的一点；单独的 affordances 工具是最贵的；出厂配置位于这簇点的顶部。按类别拆分的明细（它准确显示了可见状态图在哪些地方帮不上忙：隐藏状态、过期快照、不确定的标志）在 docs/BENCHMARK.md 中。用 OPENAI_API_KEY=... mcpgraphy benchmark llm 重跑，大约一美元。 agent 看到的是下游工具，加上四个 mcpgraphy 自己的工具： 每次读取资源以及对其执行的每个动作的结果，都会带回来自行为图的一行提示，因此 agent 无需额外轮次就能了解该状态的可供性以及离开它的路径： mcpgraphy [status=DRAFT, tests_passed=False] ok: run_tests -> tests_passed becomes true | no: archive_release; publish_release | to tests_passed=True: run_tests 拒绝会带上同一行提示，每个被阻止或警告的调用都会带上其理由，例如 observed to fail from state [exists=False] (2 observations)。用 --no-hints 关闭提示。日志、行为图和每一个决策都持久化在一个 SQLite 文件中，因此重启后的代理会保留它学到的东西，你也可以审计它做过什么。

1. 描述如何观察一个资源 每个服务器一个 JSON 文件。它指定用于回读资源的只读工具，以及标识该资源的参数。其余都是可选项。 "server_id": "filesystem