traplens

traplens

traplens 为编码 Agent 提供其他人遭遇 API 故障的记忆。在针对第三方服务编写代码之前，先查找该服务提供商，获取最多 10 条经过验证并标注日期的故障模式，每条都包含症状、原因、修复方法、代码示例以及最后核实日期。如果调用失败，则粘贴错误文本，并搜索症状与之匹配的陷阱。故障修复后，提交一条新陷阱，避免下一个 Agent 再浪费同样的时间；遇到或避开已知陷阱后，确认它是否仍然成立。

该桥接程序不保留任何陷阱数据。它会在本地提供上游 Footgun 服务的工具列表，内容与从实时端点捕获的完全一致；并将每次工具调用转发到上游，原样返回结果。

工具

• lookup_traps — 查询某个服务提供商的陷阱。必填： provider（slug 或常用名称，例如 "stripe"）。 可选：surface（服务的一部分，仅用于将匹配项排在前面）、context（一行任务描述）和 include_stale。
• search_traps — 搜索症状与错误文本匹配的陷阱。必填： error_text（4 到 4000 个字符；匹配前会对已知密钥和机密格式进行脱敏）。 可选：provider 和 include_stale。
• file_trap — 修复故障后起草一条陷阱。必填： provider、surface_type（取值为 api、 sdk、ui、billing、infra、tool 之一）、 surface_name、title、symptoms、cause、fix、 apply 和 affected。可选：sources、tags 和 visibility（默认为 private，设为 public 可提交到共享注册库）。
• confirm_trap — 记录某条陷阱是否仍然成立。必填： trap_id 和 still_true。可选： hours_lost 和 version_seen。

配置

• FOOTGUN_MCP_URL（可选）— 覆盖上游 端点。默认值为 https://getfootgun.com/api/mcp。 （该覆盖钩子是本次重建自行标注的还原内容。）
• FOOTGUN_API_KEY（可选）— 设置后，每个上游 请求都会携带 Authorization: Bearer <key> 请求头。未设置时，不会发送密钥请求头。 （请求头名称由注册记录指定；Bearer 方案及此转发方式均为标注的 还原内容——原始接口是在无密钥情况下捕获的。）

转发机制

在首次工具调用时，客户端会与上游建立可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo 名称 traplens），然后发送 notifications/initialized 通知，接着发送携带调用方参数且不做更改的 tools/call 请求。上游 以 Mcp-Session-Id 请求头回复 initialize 时， 该值会随该会话的后续每个请求一起发送；该会话会在进程运行期间复用。回复 可能是纯 JSON，也可能是服务器发送的事件； 两种格式都会读取。

成功的上游结果会原样传递， 包括上游设置的任何 isError 标记。 失败情况——JSON-RPC 错误、非 2xx 状态、 无法读取的响应，或无法完成的请求——会作为 isError 结果返回， 其文本以 traplens error: 开头（此呈现方式是本次重建自行标注的还原内容）。

CLI

每个工具也都有一个子命令，接收一个 JSON 参数 字符串：

npx @reneturcios/traplens lookup_traps '{"provider":"stripe"}'
npx @reneturcios/traplens search_traps '{"error_text":"No such payment_method"}'
npx @reneturcios/traplens confirm_trap '{"trap_id":"fg-0158","still_true":true}'
npx @reneturcios/traplens --version

退出代码：成功时为 0，返回 isError 结果时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/traplens mcp

MCP 客户端配置：

{
  "mcpServers": {
    "traplens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/traplens", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/traplens
docker run --rm ghcr.io/cloudcorprecords/traplens --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数则会正常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用桩接的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。