jira-read

Jira Read — 実行ルール

ローカルキャッシュからダウンロード済みの Jira データをすばやく読み取ります。ネットワーク接続は不要です。

設定

使用する前にキャッシュディレクトリの環境変数を設定してください（.zshrc／.bashrc に追加することを推奨します）。

export JIRA_CACHE_DIR="$HOME/.cache/jira"

設定されていない場合は、~/.cache/jira/ がデフォルトで使用されます。

トリガーとパラメーター

主なトリガー：jira-read [JIRA-ID] — 大文字・小文字を区別しません（自動的に大文字に変換されます）

使用方法	動作	出力モード
jira-read {ID}	ローカルキャッシュを読み取ります。見つからない場合は API から自動取得します	要約
jira-read {ID} --live	キャッシュを使わず、API から取得してキャッシュを更新します	要約
jira-read {ID} --force	API から強制取得し、ローカルキャッシュを上書きします	要約
jira-read {ID} --no-download	ローカルのみを使用します。見つからない場合は確認を求めます	要約
jira-read {ID} --full	デフォルトと同じですが、すべてのコメントを含む全内容を出力します	全文
jira-read {ID} --meta	デフォルトと同じですが、YAML フロントマターのみを出力します	メタデータ
jira-read ID1 ID2 ID3	ローカルキャッシュから一括で読み取ります	要約
jira-read --live ID1 ID2 ID3	API から一括取得してキャッシュします	要約
jira-read --force ID1 ID2 ID3	一括で強制再取得し、ローカルキャッシュを上書きします	要約
jira-read --list / -l	ローカルキャッシュのエントリをすべて一覧表示します	一覧

---

保存パス

• メインファイル：$JIRA_CACHE_DIR/{JIRA-ID}.md
• フィールドマッピングキャッシュ：$JIRA_CACHE_DIR/.field-mapping.json

初回使用時は、フィールド ID マッピングを作成するために jira_search_fields を自動的に呼び出します。以降の読み取りではキャッシュを直接使用します。--force はマッピングを更新します。

---

実行フロー

ステップ 1：Jira ID を解析する

ID を抽出し（正規表現：([A-Za-z]+-\d+)）、大文字に変換してローカルファイルのパスを作成します。

ステップ 2：ファイルの存在を確認する

ファイルが存在する場合：ステップ 3 に進みます

ファイルが存在しない場合：

• API を呼び出す前に、以下の認証情報チェーンを使って PAT を解決します
• デフォルト：jira_get_issue(issue_key="{JIRA-ID}", fields="*all", comment_limit=50) を呼び出します → 成功した場合は、整形して保存してから続行します。失敗した場合は、エラー処理に従って分類します
• --no-download：確認のみを求め、自動ダウンロードは行いません
• --live：ローカルの確認をスキップし、API から取得してキャッシュを更新します
• --force：API から取得し、ローカルキャッシュを上書きします

ステップ 3：読み取り、解析、出力

Markdown を読み込み → YAML フロントマターと本文を解析 → 構造化された Markdown として出力します。

解析されるフィールド：jira_id、title、priority、status、reporter、assignee、created_at、updated_at、downloaded_at、source_url。本文には課題の説明、再現手順、期待される結果／実際の結果、コメント履歴が含まれます。

添付ファイルの処理：添付ファイルの内容をエージェントのコンテキストに読み込むことはありません。課題に添付ファイル（ログ、スクリーンショット）がある場合は、出力の末尾に記載します。実際の添付ファイル（ログ）が必要な場合は、以下の「添付ファイルのダウンロード」セクションに従ってください。

各シナリオの出力形式の例については、reference.md を参照してください。

---

資格情報の解決（ライブ取得の前）

MCP／jira_get_issue、--live／--force、添付ファイルのダウンロードを行う前に、この順序で確認してください。mcp-atlassian は手順 1 の値を設定する任意の方法であり、必須ではありません。

1. 環境変数 JIRA_PERSONAL_TOKEN（標準）
2. ない場合は環境変数 JIRA_PAT（別名。セッションの残りの間は JIRA_PERSONAL_TOKEN にコピーしてください）
3. ない場合はファイル ~/.config/jira-certs/jira-pat.txt（Windows の場合：%USERPROFILE%\.config\jira-certs\jira-pat.txt）— 1 行目を読み取り、前後の空白を削除した 1 行のシークレット
4. いずれもない場合は、ユーザーに PAT を一度だけ尋ね、そのファイルに書き込むかどうかも尋ねてください。トークンが存在するまでライブ取得を行わないでください。

環境変数またはファイルからトークンを取得した後は、PAT をチャット、argv、コマンドのプレビューに貼り付けないでください。返信やログにも出力しないでください。また、ファイルの内容を会話に cat しないでください。スクリプトに環境変数またはファイルを直接読み取らせてください。

PAT を埋め込む手動の curl は案内しないでください（「Authentication テーブルに相当する curl」も不可）。この代替手段は禁止されています（以前の添付ファイルダウンロードに関する差分が未解決の場合も、こちらが優先されます）。

添付ファイルのダウンロード

添付ファイルは必ずスキルスクリプトを使ってローカルディスクにダウンロードしてください。添付ファイルの内容を Agent のコンテキストに読み込んではいけません。ログの内容を確認するには、grep／head／tail を使って関連する行だけを抽出してください。

認証（社内 Jira）

要素	ソース	備考
PAT（Bearer）	上記の資格情報の解決手順	標準環境変数 JIRA_PERSONAL_TOKEN、別名 JIRA_PAT、ファイル jira-pat.txt
mTLS クライアント証明書	JIRA_CLIENT_CERT／JIRA_CLIENT_KEY	デフォルトは ~/.config/jira-certs/client.crt ＋ client.key
SSL	JIRA_SSL_VERIFY=false	社内の自己署名証明書 → curl の -k／node の rejectUnauthorized: false

資格情報（レシピのフィールド）： PAT は 1 行で ~/.config/jira-certs/jira-pat.txt に保存してください（mTLS の証明書ペアと同じディレクトリで、Git リポジトリ内には置かないでください）。形式：引用符なしの 1 行のシークレット。ローテーションする場合は、ファイルの内容とエクスポート済みの環境変数を更新してから、再試行してください。mcp-atlassian によって、ファイルの代わりに JIRA_PERSONAL_TOKEN が設定される場合があります。

添付ファイルの URL

jira_get_issue が返す attachment[].url から直接取得してください。例： https://jira.example.com/secure/attachment/{attachmentId}/{filename}

ダウンロードスクリプト

まず curl -V を実行してください。出力に Schannel（一般的な Windows 環境）が含まれる場合、または PEM の --cert／--key が利用できない場合は、必ず node サイドカーを使用してください。それ以外の場合は bash スクリプトを使用できます。

# Node (Windows / Schannel curl)
node scripts/download_jira_attachments.mjs 100001 app-log-1700000000000.zip /tmp/logs/PROJ-1234.zip

# Bash + OpenSSL curl (PEM --cert/--key)
scripts/download_jira_attachments.sh 100001 app-log-1700000000000.zip /tmp/logs/PROJ-1234.zip

どちらも資格情報の解決手順に従って PAT を取得します（Bearer、Basic のフォールバック）。証明書のパスは JIRA_CLIENT_CERT／JIRA_CLIENT_KEY で上書きできます。JIRA_URL を設定してください（例：https://jira.example.com）。PAT をコマンドラインに指定しないでください。

ダウンロードとアーカイブのフロー

1. 資格情報を解決し（上記の手順）、jira_get_issue(issue_key=..., fields="summary,description,attachment,status,priority") を呼び出して、attachment[].id／filename／url を取得します
2. 選択したスクリプトを使って一時ディレクトリにダウンロードします。まず 1 件をダウンロードして認証を確認し、その後まとめてダウンロードします
3. unzip -l で zip の構成をプレビューし、展開前にフラットな構成であることを確認します
4. プロジェクト内の issues/{type}/jira-bug/{JIRA-ID}-app-log/ にアーカイブし、チケット情報と添付ファイル一覧を記録する {JIRA-ID}.md を書き込みます

ダウンロード結果の報告形式については、reference.md § 7 を参照してください

---

キャッシュの鮮度に関するプロンプト

キャッシュの経過時間	プロンプト
< 1 時間	なし
1～24 時間	「X 時間前にキャッシュ済み」
1～7 日	「X 日前にキャッシュ済みです。更新を推奨します」
> 7 日	「キャッシュの有効期限が切れています（X 日前）。更新を強く推奨します」

---

エラー処理

エラーのシナリオ	処理
Jira ID の形式が無効	正しい形式を入力するよう促します
ファイルが見つからない	API から自動取得します（--no-download を指定した場合のみ取得しないよう促します）
認証情報チェーンが空（環境変数＋エイリアス＋ファイル）	確認して保存します（401 として扱いません）
mcp-atlassian が利用できない	オプションのインジェクターがありません。認証情報チェーンは引き続き使用します。issue の JSON が必要な場合は、PAT の解決後にキャッシュを試すか、jira-read --live を実行します。MCP がないことだけを理由に中断しません
解決済みトークンで HTTP 401／403 が発生	トークンが無効または取り消されています。トークンをローテーションし、jira-pat.txt（環境変数が設定されている場合は環境変数も）を更新します
TLS ハンドシェイク／クライアント証明書	client.crt／client.key と TLS 1.3 を確認します。Windows では PEM mTLS に Schannel curl を使用せず、node sidecar を使用します
issue が見つからない	Jira ID が間違っている可能性があることを伝えます
ファイルの解析に失敗	ファイルの内容をそのまま出力します