atlassian-proxy

Atlassian のホスト型 Rovo MCP サーバー (https://mcp.atlassian.com/v1/mcp) の前に配置し、Claude Code 向けに不要な部分を削ぎ落とすローカル stdio MCP プロキシです。

Claude Code (stdio) -> index.js -> mcp-remote (subprocess, OAuth) -> https://mcp.atlassian.com/v1/mcp

次のことを行います:

• index.js の ALLOWED_TOOLS にリストされたツールのみを公開します (jira-ops/jira-reviewer が実際に使うもの)。それ以外の上流ツールはすべて tools/list から隠されます。

• すべての呼び出しに cloudId、contentFormat、responseContentFormat を自動注入し、Claude が見るスキーマからはこれらのパラメータを取り除くため、Claude がそれらを知る必要はありません。

• すべてのツール結果を返す前に、ノイズとなるキー (avatarUrls、self、iconUrl、_links、expand、browseUrl など) を再帰的に取り除きます。

必要条件

• Node.js (ネイティブ ESM / type: "module" をサポートする任意のバージョン)。

• npx が PATH で利用できること (mcp-remote の起動に使用します)。

Related MCP server: JIRA MCP Server

インストール

まず、Node.js がすでにインストールされているか確認してください。インストール済みで、このフォルダに node_modules も存在する場合、npm install は不要です:

node -v

その確認で Node.js が見つからない場合は、先に Node.js をインストールしてから:

cd C:\Users\Dz\oktanetest\atlassian-proxy
npm install

これにより、package.json から @modelcontextprotocol/sdk と mcp-remote がインストールされます。

単独実行 (手動スモークテスト)

node index.js

stdio 経由で MCP をやり取りするため、直接実行すると stdin でクライアントを待ちながらブロックします。Jira/Confluence ツールへの最初の呼び出しで npx -y mcp-remote https://mcp.atlassian.com/v1/mcp を子プロセスとして起動し、Atlassian OAuth ログイン用のブラウザーウィンドウが開きます。認証されると mcp-remote がトークンをキャッシュするので、以降の実行で再認証する必要はありません。stderr に [atlassian-proxy] ready が表示されれば、上流に接続してフィルター済みのツールリストを提供中です。

Claude Code での登録

このプロキシは atlassian ではなく atlassian-proxy という名前で登録してください。そうすれば、実際のホスト型 Atlassian/Rovo MCP サーバーが atlassian という名前で登録されている場合でも衝突しません。

プロジェクトの stdio MCP サーバーとして追加します。例: そのプロジェクトの Claude Code 設定 (mcpServers ブロック) に:

{
  "atlassian-proxy": {
    "type": "stdio",
    "command": "node",
    "args": ["<path-to-atlassian-proxy>\\index.js"],
    "env": {}
  }
}

実際の atlassian MCP サーバーも登録されている場合は、このプロキシのフィルター済みツールだけが有効になるよう、それを削除せずに無効にしてください。Claude Code で /mcp を実行し、atlassian サーバーを選択して無効オプションを選びます。後でフィルタリングされていない完全な上流ツールセットが必要になったら、そこで再度有効にできます。

登録後、Claude Code (または MCP 接続) を再起動・再接続して、新しいサーバーを認識させてください。このプロキシのツールは atlassian-proxy プレフィックスの下に現れ (例: mcp__atlassian-proxy__getJiraIssue)、すでに ALLOWED_TOOLS に限定され、cloudId/contentFormat/responseContentFormat が取り除かれた状態です。

トークン削減量の統計

Claude Code はこのプロキシを隠して実行するため、stderr はチャットに表示されません。そのため削減量はファイルに書き出されます:

• logs/token-savings.log — JSONL。tools/list/tools/call の各イベントごとに 1 行 (tokensSavedIn、tokensSavedOut、累計)。

• logs/stats-summary.txt — イベントのたびに現在の累計で上書きされます。

追跡される値は 2 つです (どちらも概算です — 文字数 / 4 であり、実際のトークナイザーではありません。Claude のトークナイザーは組み込まれていないためです):

• Claude のコンテキストに入れずに済んだ分 (tokensSavedIn): ALLOWED_TOOLS によるツールリストの削減と、stripNoise によるツール結果からのノイズ除去の合計。

• Claude が生成しなくて済んだ分 (tokensSavedOut): プロキシが Claude の代わりに自動注入する定数パラメータ (cloudId、contentFormat、responseContentFormat) の分。

ライブで確認するには、別のターミナルを開いてサマリーファイルを tail してください:

Get-Content logs\stats-summary.txt -Wait

トラブルシューティング

• ready メッセージが出ずにハングする場合: npx -y mcp-remote ... が OAuth のブラウザーフローを待機している可能性が高いです。ブラウザーのウィ ンドウ/プロンプトを確認してください。

• Claude でツールを利用できない場合: ツール名が index.js の ALLOWED_TOOLS にあるか確認してください。リストにないものは tools/list から除外され、tools/call で拒否されます。

期限切れ・失効した認証 (401 Unauthorized、または could not resolve cloudId from getAccessibleAtlassianResources)

Claude Code の /mcp 再接続は node index.js の stdio プロセスを再起動するだけであり、再認証を強制するものではりません。実際の OAuth トークンは 1 層下にあり、mcp-remote 子プロセスが ~/.mcp-auth/mcp-remote-<version>/<server-hash>_tokens.json にディスクへキャッシュしていて、上流サーバー URL をキーにしています。そのトークンが古い (期限切れ、失効済み、または node プロセスが再起動する前からすでに古い) 場合、Claude Code で何度再接続しても、すべてのツール呼び出しは 401/could not resolve cloudId で失敗します再。接続はそのキャッシュに一切触れないからです。

完全な手順は、順番に次のとおりです:

1. キャッシュを削除します: rm -rf ~/.mcp-auth (Windows: C:\Users\<you>\.mcp-auth)。これにより、マシン上の mcp-remote を使うすべてのサーバーについて、キャッシュされたクライアント登録、PKCE verifier、トークンが消去されます。安全です。純粋な OAuth クライアント状態であり、他に依存するものはありません。

2. Claude Code の外で、単独で再認証します。専用のターミナルで:

   cd C:\Users\Dz\oktanetest\atlassian-proxy
   npx -y mcp-remote https://mcp.atlassian.com/v1/mcp --host 127.0.0.1

   このコマンドはフォアグラウンド (または確認できるバックグラウンドシェル) で実行し、ブラウザーのログインを自分のペースで完了してください。先に Claude Code 内で atlassian-proxy を再接続して再認証しようとすることは しないでください。index.js の main() は、上流の mcp-remote 接続 (ブラウザーでのクリック操作を含む) がすべて解決するまで自身の stdio 側を開かないため、Claude Code 独自の接続セットアップタイムアウトがインタラクティブな OAuth フローと競合しますか。Claude Code が先にタイムアウトすると、ハンドシェイクの途中で index.js とその mcp-remote 子プロセスが kill されれます。ブラウザーには "Authorization successful!" と表示されるかもしれませんが、tokens.json が書き込まれる前にトークン交換が遮断されます (その場合、~/.mcp-auth には client_info.json/code_verifier.txt しか残らず、トークンはありません — この症状が起きたら確認してください)。先に mcp-remote を単独で実行すればこの競合はまったく起こりません。Proxy established successfully が表示されて (終了コード 0)、トークンが安全にキャッシュされます。

3. その後 に、Claude Code (/mcp) で atlassian-proxy を再接続します。同じ mcp-remote が起動し、有効なキャッシュ済みトークンを見つけて、ブラウザー操作なしで即座に接続します。

--host 127.0.0.1 を index.js の spawn 引数に指定する (上流 mcp-remote のデフォルトとは異なる。)のは Windows では必須です。mcp-remote のローカル OAuth コールバックサーバーは 127.0.0.1 だけにバインドしますが、デフォルトの redirect_uri ホスト名は localhost です。localhost が先に ::1 に解決される Windows マシン (Resolve-DnsName localhost で確認できます) では、ログイン後のブラウザーリダイレクト先が誰も待機していないアドレスになり、コールバックページに「接続できません」と表示されて認証コードが使われないままになります。このフラグは削除しないでください。

コールバックポートで EADDRINUSE が発生した場合 (例: 前回の認証試行が中断された後の listen EADDRINUSE: 127.0.0.1:3736): Windows の npx は、親プロセスがキャンセルされたときに子プロセスツリー全体を常に kill するわけではないため、前回の mcp-remote が孤立プロセスとして残り、ポートを保持したままになる可能性があります。再試行する前にそれを探して kill してください:

Get-NetTCPConnection -LocalPort <port> | Select-Object OwningProcess
Stop-Process -Id <pid> -Force