traplens

traplens

traplens は、他の人が経験した API の破壊的変更に関する記憶をコーディングエージェントに提供します。サードパーティーのサービスを対象にコードを書く前に、そのプロバイダーを検索し、検証済みで日付の記載された失敗パターンを最大 10 件取得できます。それぞれに、症状、原因、修正方法、コード例、最終確認日が含まれます。呼び出しに失敗した場合は、エラーテキストを貼り付けて、症状が一致するトラップを検索します。失敗を修正したら、新しいトラップを登録して、次のエージェントが同じことで何時間も無駄にしないようにします。また、既知のトラップに遭遇した場合、または回避した場合は、それが今も有効かどうかを確認します。

このブリッジはトラップデータを一切保持しません。上流の Footgun サーバーのツール一覧を、ライブエンドポイントから取得した内容そのままにローカルで提供し、各ツール呼び出しを上流に転送して、結果を変更せずに返します。

ツール

• lookup_traps — プロバイダーのトラップを検索します。必須： provider（スラッグまたは一般的な名前。例："stripe"）。 任意：surface（サービスの一部分。該当結果を先頭に並べるためだけに使用）、context（タスクの説明を 1 行で指定）、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 リクエストを送ります。上流が initialize への応答で Mcp-Session-Id ヘッダーを返した場合、その値は以降のセッション内のすべてのリクエストに付与され、プロセスの終了まで同じセッションが再利用されます。応答は通常の JSON またはサーバー送信イベントで届く場合があり、どちらも読み取られます。

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

CLI

各ツールは、1 つの 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 を参照してください。