atlassian-mcp-serverless

Atlassian Jira の MCP サーバーを AWS API Gateway + Lambda 上で動かす。 sooperset/mcp-atlassian の Jira read 系ツールを移植したもの。

設計は docs/superpowers/specs/2026-08-13-atlassian-mcp-serverless-design.md を参照。

現在の実装状況

フェーズ1（基盤）が完了。実装済みのツールは 2 つ。

• jira_search — JQL で課題を検索する
• jira_get_issue — 課題を 1 件取得する

残りの 36 ツールはフェーズ2〜5 で追加する。

必要なもの

• Node.js 22 以上
• AWS SAM CLI
• Atlassian Cloud の API トークン（https://id.atlassian.com/manage-profile/security/api-tokens で発行）

セットアップ

npm install
npm test

デプロイ

npm run sam:build
npm run sam:deploy

AtlassianSiteUrl パラメータに接続先サイトを指定する（例: https://example.atlassian.net）。 接続先はサーバー側に固定される。クライアントから接続先ホストを指定することはできない（SSRF 防止のため）。

デプロイが完了すると McpEndpoint が出力される。

Note: SAM CLI was not executed in this environment (not installed). Run the commands above with your SAM CLI installation to complete the deployment to AWS.

MCP クライアントの設定

エンドポイントに Atlassian の資格情報をヘッダで渡す。

{
  "mcpServers": {
    "atlassian": {
      "type": "http",
      "url": "https://<api-id>.execute-api.<region>.amazonaws.com/prod/mcp",
      "headers": {
        "Authorization": "Basic <base64 of email:api_token>"
      }
    }
  }
}

Authorization ヘッダの値は次のように作る。

printf 'you@example.com:YOUR_API_TOKEN' | base64

代わりに個別のヘッダを使ってもよい。

      "headers": {
        "X-Atlassian-Email": "you@example.com",
        "X-Atlassian-Api-Token": "YOUR_API_TOKEN"
      }

動作確認

ENDPOINT="https://<api-id>.execute-api.<region>.amazonaws.com/prod/mcp"
AUTH="Basic $(printf 'you@example.com:YOUR_API_TOKEN' | base64)"

curl -sS "$ENDPOINT" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "authorization: $AUTH" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

レスポンスは text/event-stream の SSE フレームで返る。これは 2025 年仕様の streamable HTTP における標準の応答形式で、MCP クライアントはそのまま解釈できる。curl で中身を読むときは data: 行を取り出す。

curl -sS "$ENDPOINT" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "authorization: $AUTH" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | sed -n 's/^data: //p' | jq .

資格情報を外すと 401 が返る。

バンドル実体の検証

npm test はソースツリー上で動くため、esbuild が実際にバンドルした Lambda アーティファクトの挙動は検証しない。特に adf-to-md のような型定義のない CJS 依存は、バンドラの扱い次第で本番でだけ解決に失敗し得る。

npm run verify:bundle

src/handler.ts を template.yaml と同じ esbuild 設定でバンドルし、リポジトリ外の一時ディレクトリ（adf-to-md が node_modules 経由で解決できない場所）にコピーして実行する。ADF の見出し・太字が実際に Markdown（## / **）へ変換されることと、handler が呼び出し可能な関数としてエクスポートされていることを確認する。プレーンテキストにフォールバックしている場合は非ゼロ終了する。

環境変数

変数	必須	既定値	用途
ATLASSIAN_SITE_URL	必須	—	接続先サイト
ENABLED_TOOLS	任意	全ツール	公開するツールのカンマ区切りリスト
MAX_ATTACHMENT_BYTES	任意	4194304	添付の base64 返却上限（template.yaml の MaxAttachmentBytes パラメータで変更可）
LOG_LEVEL	任意	info	debug / info / warn / error
JIRA_TIMEOUT_MS	任意	20000	Jira 呼び出しのタイムアウト（template.yaml の JiraTimeoutMs パラメータで変更可）

設計上の注意

• jira_search は total を返さない。Jira が 2025年8月に旧検索エンドポイントを廃止し、後継の /rest/api/3/search/jql が件数を返さなくなったため。代わりに nextPageToken を使ってページングする
• 資格情報はログに出力されない
• Lambda はステートレス。MCP のセッションは使わず、リクエストごとにサーバーインスタンスを構築する
• レスポンスは SSE フレーム。API Gateway がバッファリングして一括で返すが、ストリームは結果送出後に自ら閉じるため正しく完結する