Agent: "What's the status of PROJ-42? Add a comment with the progress update."
  ↓
a2atlassian → get issue, add comment, transition to In Progress
  ↓
Agent: "Done — PROJ-42 updated and moved to In Progress."

なぜa2atlassianなのか？

既存のAtlassian MCPサーバー（Rovo、sooperset）は、Docker、.envファイル、mcp-remoteブリッジを必要とします。これらは72個ものツールをエージェントのコンテキストに詰め込み、既知の不具合によってサイレントに失敗することがあります。a2atlassianはこれらすべてを解決します：

Docker不要 — pip install a2atlassianを実行するだけです
事前設定済みの接続 — .mcp.jsonでプロジェクトを定義し、--registerを使用すれば、エージェントは即座に動作します
デフォルトで読み取り専用 — 書き込みアクセスは接続ごとにオプトイン方式です
接続のスコープ設定 — --scopeでエージェントが参照できるプロジェクトを制限します
コンパクトな出力 — リストにはTSV（トークンを30〜60%削減）、単一エンティティにはJSONを使用します
動的なツール読み込み — 遅延ツール読み込みをサポートするMCPクライアント（例：Claude Code）は、必要な時にツールを読み込むため、コンテキストを軽量に保てます
エラーの補完 — フィールド名の誤りには提案を、JQLのタイプミスには修正を、不具合には自動修正を提供します
シークレットは環境変数に保持 — 設定内の${ATLASSIAN_TOKEN}は、実行時にのみ展開されます

クイックスタート

# Recommended — installs globally as a CLI tool
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

MCPサーバーとして（推奨）

Claude Code（事前設定済みの接続を使用）：

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp \
  --register myproject https://mysite.atlassian.net user@company.com '${ATLASSIAN_TOKEN}'

Claude Code（最小構成 — エージェントが必要に応じてloginを呼び出します）：

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp

Claude Desktop / Cursor / その他のMCPクライアント (.mcp.json):

{
  "mcpServers": {
    "a2atlassian": {
      "command": "uvx",
      "args": [
        "--from", "a2atlassian", "a2atlassian-mcp",
        "--register", "myproject", "https://mysite.atlassian.net",
        "user@company.com", "${ATLASSIAN_TOKEN}"
      ],
      "env": {
        "ATLASSIAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

複数のプロジェクト：

{
  "args": [
    "--from", "a2atlassian", "a2atlassian-mcp",
    "--register", "myproject", "https://mysite.atlassian.net", "user@a.com", "${TOKEN_A}",
    "--register", "personal", "https://personal.atlassian.net", "user@b.com", "${TOKEN_B}"
  ]
}

スコープ付き接続（エージェントがアクセスできるプロジェクトを特定の保存済みプロジェクトに制限）：

{
  "args": ["--from", "a2atlassian", "a2atlassian-mcp", "--scope", "myproject"]
}

--registerはメモリ内の一時的な接続を作成します（プロセス生存期間中のみ有効で、ファイルは書き込まれません）。--scopeは表示可能な保存済み接続をフィルタリングします。どちらも影響範囲を最小限に抑えます。

CLIとして

# Save a connection (validates by calling /myself)
a2atlassian login -p myproject \
  --url https://mysite.atlassian.net \
  --email user@company.com \
  --token "$ATLASSIAN_TOKEN"

# Enable writes
a2atlassian login -p myproject \
  --url https://mysite.atlassian.net \
  --email user@company.com \
  --token "$ATLASSIAN_TOKEN" \
  --no-read-only

# List / remove connections
a2atlassian connections
a2atlassian logout -p myproject

MCPツール

接続管理

ツール	説明
`login`	接続を保存 — 最初に /myself を呼び出して検証します
`logout`	保存された接続を削除
`list_connections`	接続を一覧表示（シークレットは表示されません）

Jira — 読み取り

ツール	説明
`jira_get_issue`	キーで課題を取得 — 全フィールド、ステータス、担当者を含む
`jira_search`	JQLで検索（ページネーション対応） — デフォルトでコンパクトなTSV出力
`jira_get_comments`	課題の全コメントを取得
`jira_get_transitions`	利用可能なステータス遷移を確認

Jira — 書き込み（読み書き可能な接続が必要）

ツール	説明
`jira_add_comment`	コメントを追加（Wikiマークアップ、API v2）
`jira_edit_comment`	既存のコメントを更新
`jira_transition_issue`	課題を新しいステータスへ移動

出力フォーマット

すべてのツールは format パラメータを受け付けます：

フォーマット	デフォルト対象	説明
`toon`	リスト（検索、コメント）	ヘッダー付きTSV — 構造は一度だけ、データは複数。JSONよりトークンを30〜60%削減
`json`	単一エンティティ（get_issue）	メタデータエンベロープ付きの標準JSON

リストのレスポンスには、TOONに触発されたコンパクトなTSV形式（ヘッダー行 + タブ区切り値）を使用します。これはa2dbと同じアプローチで、列名は一度だけ表示され、後は値のみが続きます。50件の検索結果の場合、JSONと比較して通常40〜60%のトークンを節約できます。

TSVの例（検索結果）：

# search (23 results, 50ms, truncated: False)
key	summary	assignee	status
PROJ-142	Fix auth timeout	Alice Smith	In Progress
PROJ-141	Add search filters	Bob Jones	To Do

JSONの例（単一の課題）：

{
  "data": {"key": "PROJ-142", "fields": {"summary": "Fix auth timeout", ...}},
  "count": 1,
  "truncated": false,
  "time_ms": 85
}

エラーの補完

何らかの失敗が発生した場合、a2atlassianはエージェントに何をすべきかを伝えます：

Field 'asignee' does not exist
Did you mean: assignee?

Connection 'myproject' is read-only.
Run: a2atlassian login -p myproject --read-only false

自動的に処理される不具合：

担当者には表示名が必要（712020:のようなアカウントIDは不可） — ヒント付きで自動検出
親フィールドはプレーン文字列である必要がある — {"key": "PROJ-14"} を自動的に "PROJ-14" に正規化
課題タイプの変換はAPI経由ではサポートされていない — Jira UIでの明確な手順を提供

セキュリティ

デフォルトで読み取り専用

すべての接続は読み取り専用で開始されます。書き込みツールは実行前に接続フラグを確認します：

Connection 'myproject' is read-only.
Re-run 'a2atlassian login -p myproject --read-only false' to enable writes.

書き込みアクセスの制御はエージェントではなく、人間のオペレーターが行います。

認証情報の保存

login経由で保存された接続は、~/.config/a2atlassian/connections/にTOMLファイルとして保存されます：

ファイル権限: 0600（所有者のみ読み書き可能）
${ATLASSIAN_TOKEN}構文 — 環境変数の参照はそのまま保存され、実行時に展開されます
出力にシークレットを含まない — list_connectionsはプロジェクト名、URL、モードのみを表示し、トークンは決して表示しません
一時モード — --registerは認証情報をメモリ内のみに保持し、ディスクには書き込みません

接続のスコープ設定

--scopeを使用して、特定のMCPインスタンスがアクセスできる保存済み接続を制限します：

# Project config — only myproject visible, even if other connections are saved
uvx --from a2atlassian a2atlassian-mcp --scope myproject

プロジェクトレベルのMCP設定（.claude/mcp.json）はグローバル設定を上書きします。各リポジトリは自身の接続のみを参照できます。

レート制限

Atlassianのレート制限（429）および一時的なサーバーエラー（500）に対する指数バックオフ付きの再試行機能を内蔵しています。エラーを表面化させる前に、1秒および3秒の間隔で2回再試行します。

比較

機能	a2atlassian	Rovo (公式)	sooperset/mcp-atlassian
セットアップ	`pip install`	OAuth + Docker	Docker + .env + mcp-remote
コンテキスト内のツール数	10 (フェーズ1)	~72	~72
接続管理	TOML + `--register` + `--scope`	セッションごとのOAuth	.envファイル
マルチプロジェクト	対応 (スコープ設定)	非対応	セットアップごとに1つの.env
デフォルトで読み取り専用	対応 (接続ごと)	非対応	非対応
出力フォーマット	TSV + JSON	JSON	JSON
エラーの補完	フィールド提案、不具合修正	一般的なエラー	一般的なエラー
不具合の処理	自動修正 (担当者、親)	ドキュメント化された回避策	ドキュメント化された回避策
レート制限	内蔵の再試行	非対応	非対応
CLI	対応	非対応	非対応
ライセンス	Apache 2.0	プロプライエタリ	MIT

ロードマップ

フェーズ1（現在）： Jiraコア — 課題の取得/検索、コメント（CRUD）、遷移。二次的なクリティカルパス。

フェーズ2： Jiraの全機能 — スプリント、ボード、リンク、プロジェクト、フィールド、作業ログ、添付ファイル、ウォッチャー。

フェーズ3： Confluence — ページ、コメント、添付ファイル、ラベル、検索。

環境別のセットアップ

ローカル (macOS / Linux)

# Recommended
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

# CLI
a2atlassian login -p myproject --url https://mysite.atlassian.net --email me@co.com --token "$TOKEN"

# Or add as MCP server (see Quick Start)

CI / 自動化

uv tool install a2atlassian

# Pre-configured — no login needed
uvx --from a2atlassian a2atlassian-mcp --register ci https://mysite.atlassian.net ci-user@co.com "${CI_ATLASSIAN_TOKEN}"

開発

make bootstrap   # Install deps + hooks
make check       # Lint + test + security (full gate)
make test        # Tests with coverage
make lint        # Lint only (never modifies files)
make fix         # Auto-fix + lint

ライセンス

Apache 2.0

a2atlassian