bugsink-mcp

Bugsink(セルフホスト型、Sentry プロトコル互換のエラートラッカー)向けの、読み書き両対応のフル MCP サーバーです。Bugsink の /api/canonical/0/ OpenAPI スキーマに対して直接構築しています。

このサーバーが存在するのは、npm 上の既存の bugsink-mcp パッケージが API の読み取り側(list/get)しかラップしていないためです。こちらは canonical API のフルサーフェスをカバーします。イシューの解決、ミュート、再オープン、削除、コメント、チーム・プロジェクト・リリースの作成/更新に加え、オリジナルに対するいくつかの正確性の修正も含みます(オリジナルからの修正を参照してください)。

セットアップ

Node.js 18.17 以上が必要です。

1. Bugsink で Account Settings → Auth Tokens に移動し、トークンを作成します。

2. サーバーを MCP クライアントに追加します。

Claude Code

claude mcp CLI を使ったワンライナーは次のとおりです:

claude mcp add bugsink \
  -e BUGSINK_URL=https://bugs.example.com \
  -e BUGSINK_TOKEN=<your token> \
  -- npx -y github:fers4t/bugsink-mcp

これは、以下の内容と同等の設定を ~/.claude.json に書き込みます(ユーザーローカル設定の代わりに共有 .mcp.json に書き込みたい場合は --scope project を渡します):

{
  "mcpServers": {
    "bugsink": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:fers4t/bugsink-mcp"],
      "env": {
        "BUGSINK_URL": "https://bugs.example.com",
        "BUGSINK_TOKEN": "<your token>"
      }
    }
  }
}

その後、Claude Code を再起動します(または新しいセッションを開始します)。MCP ツールの一覧はセッション開始時に読み込まれるため、セッション途中の設定変更は反映されません。

その他の MCP クライアント

mcpServers マップを読み取るクライアント(Cursor、Windsurf など)は、上記と同じ JSON 構造を使用できます。command: npx、args: ["-y", "github:fers-refer/bugsink-mcp"] を指定し、2 つの必須環境変数を設定してください。

npx は GitHub から直接インストールし(npm への publish は行いません)、初回利用時に prepare スクリプトを実行して TypeScript をコンパイルし、以降の起動ではローカルキャッシュを再利用します。

環境変数

.env.example を参照してください。実際のトークンはコミットしないでください。サーバーは環境変数からのみトークンを読み取ります。

Related MCP server: Sierra Navigator Cloud

ツール

接続確認

| ツール | 説明 --- | --------------------------------------------------------------- | | test_connection | URL とトークンが機能するか検証し、可視のチーム数を報告する |

チーム

| ツール | 説明 -- | -------------------------------------- | | list_teams | すべてのチームを一覧取得 | | get_team | UUID でチームを取得 | | create_team | チームを作成 | | update_team | チーム名の変更または可視性の変更 |

プロジェクト

イシュー

イベント

リリース

オリジナルからの修正

• get_stacktrace が実際に動作します。 スタックトレースのエンドポイントは JSON ではなく text/markdown を返します。オリジナルのパッケージは無条件に res.json() を呼び出し、毎回 Unexpected token '#', "# TypeError"... is not valid JSON をスローしていました。このサーバーはそのエンドポイントをテキストとして読み取ります。

• 書き込みサポート: イシューの解決/ミュート/再オープン / 削除/コメント、およびチーム/プロジェクト / リリースの作成/更新をカバーします。読み取り専用のオリジナルでは一切公開されていませんでした。

• タイムアウトの制限: すべてのリクエストで AbortSignal.timeout(デフォルト 15 秒)を使用し、上流側がハングしても MCP プロセスが無期限にハングしないようにします。

• 安全なリトライ: 冪等リクエスト(GET)には、502/503/504 やネットワーク障害時、変動(jitter)付きの指数バックオフを制限付きで適用します。変更を伴うリクエスト(POST/PATCH/DELETE)は一切自動リトライしません。応答が失われただけの書き込みをリトライすると、副作用(例: 同じコメントの二重登録)が発生する可能性があるからです。

• 入力検証: すべてのツール引数を Zod で検証します(数値 ID、UUID、列挙値)。不正な入力は API 通信に入る前に、明確なメッセージでローカル拒否されます。

• 出力に秘密情報を出しません。 エラーでは HTTP ステータスと切り詰めたレスポンスボディを報告します。Authorization ヘッダーの値はログや例外に一切含まれません。

セキュリティに関する注意

• これはローカル stdio プロセスで、ネットワークリスナーを開きません。アクセス制御はお使いの MCP クライアントが提供するものに加え、BUGSINK_TOKEN の保持に依存します。

• 診断情報はすべて stderr に送ります。stdout は JSON-RPC プロトコルのストリーム用に予約しています。

• BUGSINK_URL は http: もしくは https: である必要があります。非ローカルホストへの平文 HTTP は警告を表示します(トークンが暗号化されず送信されます)が、内部ネットワークをサポートするためブロックはしません。

• BUGSINK_TOKEN は他の認証情報と同様に扱ってください。バージョン管理に組み込まず、万一漏えた場合は Bugsink でローテーションをかけてください。ワークフローで許可される最も低い権限のユーザーにスコープしてください。

開発

npm install     # installs deps and runs the TypeScript build (prepare script)
npm run typecheck
npm run build   # compile src/ -> dist/
npm run dev     # watch mode

ライセンス

MIT