failshare

failshare

failshare は、FailEcho がホストする MCP サーバーへの小規模なローカルブリッジです。エージェント向けの、 共有型の障害ナレッジベースです。 ツール、API、MCP の呼び出しが失敗すると、エージェントは むやみに再試行する前に、 その特定の障害についてネットワークがすでに把握していることを確認し、 自身の障害、成功、復旧結果を報告して、 次のエージェントがより適切な回答を得られるようにします。

このブリッジは障害データを保持せず、独自の計算も行いません。 ライブエンドポイントから取得した状態そのままの上流サーバーのツール一覧を ローカルで提供し、各ツール呼び出しを上流に転送して、 結果を変更せずに返します。

ツール

• check_tool_failure - 再試行する前に、障害についてネットワークが把握していることを 確認します。ステータス （HEALTHY / DEGRADED / MAJOR / INSUFFICIENT_DATA）、 件数、成功した復旧アクションとその成功率、 推奨事項を1つ返します。必須： 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 - 障害への対処（再試行、待機、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 リクエストを送信します。上流が Mcp-Session-Id ヘッダーを付けて initialize に応答すると、その値はセッションの後続リクエストすべてに付与され、 プロセスの終了まで同じセッションが再利用されます。応答は プレーンな JSON またはサーバー送信イベントで届く場合があり、 どちらも読み取られます。

上流からの成功結果は、上流が設定した isError フラグも含め、 そのまま渡されます。 失敗（JSON-RPC エラー、2xx 以外のステータス、読み取り不能な応答、 または完了できないリクエスト）は、 テキストが failshare error: で始まる isError 結果として返されます （この形式も、この再構築独自の、再構築であることを明示したものです）。

CLI

各ツールは、JSON 引数文字列を1つ受け取るサブコマンドとしても実行できます。

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 を参照してください。