failshare

failshare

failshare 是一个小型本地桥接程序，用于连接 FailEcho 托管的 MCP 服务，这是一个供 Agent 共用的失败知识库。 当工具、API 或 MCP 调用失败时，Agent 会在盲目重试之前， 先查询网络中是否已有关于该确切故障的知识；它们也会报告 自身的失败、成功和恢复结果，以便下一个 Agent 获得更好的答案。

桥接程序不会保存任何失败数据，也不会自行进行计算。 它会在本地提供上游服务的工具列表，内容与从实时端点 捕获的完全一致，并将每次工具调用转发到上游，原样返回 结果。

工具

• check_tool_failure - 在重试之前，查询网络中关于 某项故障的已知信息。返回状态 （HEALTHY / DEGRADED / MAJOR / INSUFFICIENT_DATA）、 计数、已奏效的恢复操作及其 成功率，以及一条建议。必需参数： service（服务器自身名称或 API 主机）和 operation（服务器为工具或端点命名的名称）。可选上下文：error_type、 error_message、error_code、version、 schema_hash、reporter_id，以及用于返回 完整记录而非简要答案的 verbose。
• report_tool_failure - 报告调用失败，以便 其他人能够识别此故障。必需参数：service、 operation。可选参数：error_type、error_message、 error_code、version、schema_hash、latency_ms 和 reporter_id。仅发送失败元数据—— 绝不要发送提示词、参数、结果、标头或密钥； 错误文本会在服务器端进行规范化处理。
• report_tool_success - 报告调用 成功。失败率需要分母：只听到失败的网络无法区分 服务故障和繁忙。必需参数：service、 operation。可选参数：version、schema_hash、latency_ms、 reporter_id。
• report_recovery_outcome - 对故障采取措施后 （retry、wait、refresh_schema、reconnect、 use_fallback、reauthenticate），报告措施是否奏效；所有 建议都基于这些报告生成。 必需参数：fingerprint（来自 check_tool_failure 或 report_tool_failure）、action 和 successful。可选参数：reporter_id。

配置

• FAILECHO_MCP_URL（可选）- 覆盖上游 端点。默认值为 https://failecho.com/mcp。 （此覆盖钩子是本次重建中自行标注的内容。）
• FAILECHO_REPORTER_ID（可选）- 设置后，每个上游 请求都会携带一个 X-Reporter-Id: <value> 标头，其中包含该值。 未设置时，则不会发送此类标头。（此 转发功能同样是本次重建中自行标注的内容；原始接口是在无密钥情况下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立一个可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 为 2025-03-26，clientInfo name 为 failshare），然后发送 notifications/initialized 通知，最后发送携带调用方原样参数的 tools/call 请求。上游在 initialize 响应中返回 Mcp-Session-Id 标头时， 该值会附加到此会话之后的每个请求中；此会话会在进程 运行期间重复使用。响应 可能是纯 JSON，也可能是服务器发送的事件； 两种格式都会读取。

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

CLI

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

npx @reneturcios/failshare check_tool_failure '{"service":"api.github.com","operation":"create_issue","error_type":"timeout"}'
npx @reneturcios/failshare report_tool_failure '{"service":"api.github.com","operation":"create_issue","error_type":"validation_error"}'
npx @reneturcios/failshare report_tool_success '{"service":"api.github.com","operation":"create_issue","latency_ms":42}'
npx @reneturcios/failshare report_recovery_outcome '{"fingerprint":"0123456789abcdef0123456789abcdef","action":"refresh_schema","successful":true}'
npx @reneturcios/failshare --version

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

MCP 服务

npx -y @reneturcios/failshare mcp

MCP 客户端配置：

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

Docker

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

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

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对存根 JSON-RPC 上游运行，不会发起任何实时网络调用。

许可证

MIT - 详见 LICENSE。