mcpField
A
atlassian-readonly-skills

atlassian-readonly-skills

github.com/langpingxue生産性41128 回インストール29 週間前に更新
リポジトリ

atlassian-readonly-skills について

Atlassian Readonly Skillsは、CloudとData Center環境のJira、Confluence、Bitbucketから情報を取得するPythonユーティリティ群です。作成・更新・削除操作を含まず、エージェント環境などにフラット化したJSONを返します。

主な機能

  1. 01Jira・Confluence・Bitbucketへの読み取り専用アクセス
  2. 02CloudとData Centerのデプロイに対応
  3. 03環境変数または引数による認証情報の設定
  4. 04JQLでJira、CQLでConfluenceを検索
  5. 05フラット化JSONと統一されたエラー処理

活用シーン

  1. 01Jiraの課題やプロジェクト情報の取得
  2. 02Confluenceのページやコメントの検索
  3. 03Bitbucketのリポジトリ・ファイル・プルリクエストの確認
  4. 04書き込み操作なしでエージェントにAtlassianデータを提供

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/langpingxue/atlassian-skills --skill atlassian-readonly-skills

インストール後、Claude Code で/atlassian-readonly-skillsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

.env.example
REFERENCE.md
requirements.txt
scripts/
__init__.py
_common.py
bitbucket_commits.py
bitbucket_files.py
bitbucket_projects.py
bitbucket_pull_requests.py
confluence_comments.py
confluence_labels.py
confluence_pages.py
confluence_search.py
jira_agile.py
jira_issues.py
jira_links.py
jira_projects.py
jira_search.py
jira_users.py
jira_workflow.py
jira_worklog.py

詳細

Atlassian 読み取り専用スキル

Jira、Confluence、Bitbucket を統合する、Cloud と Data Center の両方のデプロイメントに対応した読み取り専用の Python ユーティリティです。

注：これは、すべての書き込み操作（作成、更新、削除）を除外した読み取り専用版です。書き込み操作を含むすべての機能を利用するには、atlassian-skills を使用してください。

設定

2 つの設定モードを利用できます。

モード 1：環境変数（従来方式）

デプロイメントの種類に応じて環境変数を設定します。このモードは、スキル関数に credentials パラメーターが指定されていない場合に使用されます。

Cloud（API トークン）
# Jira Cloud
JIRA_URL=https://your-company.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token

# Confluence Cloud
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
[email protected]
CONFLUENCE_API_TOKEN=your_api_token

API トークンは次の場所で生成できます：https://id.atlassian.com/manage-profile/security/api-tokens

Data Center／Server（PAT トークン）
# Jira Data Center
JIRA_URL=https://jira.your-company.com
JIRA_PAT_TOKEN=your_pat_token

# Confluence Data Center
CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PAT_TOKEN=your_pat_token

# Bitbucket Server/Data Center
BITBUCKET_URL=https://bitbucket.your-company.com
BITBUCKET_PAT_TOKEN=your_pat_token

注：両方が指定されている場合は、PAT トークンが優先されます。

モード 2：パラメーターベース（エージェント環境）

環境変数を利用できないエージェント環境にスキルをデプロイする場合は、AtlassianCredentials オブジェクトを使って、スキル関数に認証情報を直接渡します。

from scripts._common import AtlassianCredentials, check_available_skills
from scripts.jira_issues import jira_get_issue

# Create credentials object
credentials = AtlassianCredentials(
    # Jira configuration
    jira_url="https://your-company.atlassian.net",
    jira_username="[email protected]",
    jira_api_token="your_api_token",
    
    # Confluence configuration (optional)
    confluence_url="https://your-company.atlassian.net/wiki",
    confluence_username="[email protected]",
    confluence_api_token="your_api_token",
    
    # Bitbucket configuration (optional)
    # bitbucket_url="https://bitbucket.your-company.com",
    # bitbucket_pat_token="your_pat_token"
)

# Check which services are available
availability = check_available_skills(credentials)
print(availability["available_services"])  # ["jira", "confluence"]
print(availability["unavailable_services"])  # {"bitbucket": "Missing bitbucket_url"}

# Use skills with credentials parameter
result = jira_get_issue(
    issue_key="PROJ-123",
    credentials=credentials  # Pass credentials here
)
サービスごとの設定

必要なサービスのみを設定できます。認証情報がすべて揃っていないサービスは利用できません。

# Only configure Jira
credentials = AtlassianCredentials(
    jira_url="https://your-company.atlassian.net",
    jira_username="[email protected]",
    jira_api_token="your_api_token"
)

# Jira skills will work
jira_get_issue("PROJ-123", credentials=credentials)  # ✓ Works

# Confluence/Bitbucket skills will fail with ConfigurationError
confluence_get_page("Page Title", "SPACE", credentials=credentials)  # ✗ Fails

認証情報オブジェクトのフィールドと認証オプションについては、atlassian-skills の全ドキュメントを参照してください。

基本的なワークフロー

環境変数を使用する
from scripts.jira_issues import jira_get_issue
from scripts.jira_search import jira_search
from scripts.confluence_pages import confluence_get_page
import json

# 1. Get a Jira issue
result = jira_get_issue(issue_key="PROJ-123")
issue = json.loads(result)
print(f"Issue: {issue['key']} - {issue['summary']}")

# 2. Search for issues
result = jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50
)
issues = json.loads(result)

# 3. Get a Confluence page
result = confluence_get_page(title="Feature Documentation", space_key="DEV")
page = json.loads(result)
print(f"Page: {page['title']}")
認証情報パラメーターを使用する（エージェントモード）
from scripts._common import AtlassianCredentials
from scripts.jira_issues import jira_get_issue
from scripts.jira_search import jira_search
from scripts.confluence_pages import confluence_get_page
import json

# Create credentials
credentials = AtlassianCredentials(
    jira_url="https://company.atlassian.net",
    jira_username="[email protected]",
    jira_api_token="token123",
    confluence_url="https://company.atlassian.net/wiki",
    confluence_username="[email protected]",
    confluence_api_token="token123"
)

# 1. Get a Jira issue with credentials
result = jira_get_issue(
    issue_key="PROJ-123",
    credentials=credentials
)
issue = json.loads(result)

# 2. Search for issues with credentials
result = jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50,
    credentials=credentials
)

# 3. Get a Confluence page with credentials
result = confluence_get_page(
    title="Feature Documentation",
    space_key="DEV",
    credentials=credentials
)

利用可能なユーティリティ

Jira 課題管理（scripts.jira_issues）
from scripts.jira_issues import jira_get_issue

# Get issue by key
jira_get_issue(
    issue_key="PROJ-123",
    credentials=credentials  # Optional
)
Jira 検索（scripts.jira_search）
from scripts.jira_search import jira_search, jira_search_fields

# Search with JQL
jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50
)

# Find field definitions
jira_search_fields(keyword="custom")
Jira ワークフロー（scripts.jira_workflow）
from scripts.jira_workflow import jira_get_transitions

# Get available transitions for an issue
jira_get_transitions(issue_key="PROJ-123")
Jira アジャイル（scripts.jira_agile）
from scripts.jira_agile import (
    jira_get_agile_boards,
    jira_get_board_issues,
    jira_get_sprints_from_board,
    jira_get_sprint_issues
)

# Get boards
jira_get_agile_boards(project_key="PROJ")

# Get issues on a board
jira_get_board_issues(board_id=1, jql="status = 'In Progress'")

# Get sprints from a board
jira_get_sprints_from_board(board_id=1, state="active")

# Get issues in a sprint
jira_get_sprint_issues(sprint_id=42)
Jira リンク（scripts.jira_links）
from scripts.jira_links import jira_get_link_types

# Get available link types
jira_get_link_types()
Jira 作業ログ（scripts.jira_worklog）
from scripts.jira_worklog import jira_get_worklog

# Get worklog entries for an issue
jira_get_worklog(issue_key="PROJ-123")
Jira プロジェクト（scripts.jira_projects）
from scripts.jira_projects import (
    jira_get_all_projects,
    jira_get_project_issues,
    jira_get_project_versions
)

# Get all projects
jira_get_all_projects()

# Get issues in a project
jira_get_project_issues(project_key="PROJ", limit=100)

# Get project versions
jira_get_project_versions(project_key="PROJ")
Jira ユーザー（scripts.jira_users）
from scripts.jira_users import jira_get_user_profile

# Get user profile
jira_get_user_profile(user_identifier="[email protected]")
Confluence ページ（scripts.confluence_pages）
from scripts.confluence_pages import confluence_get_page

# Get page by title
confluence_get_page(title="Meeting Notes", space_key="TEAM")

# Get page by ID
confluence_get_page(page_id="12345")
Confluence 検索（scripts.confluence_search）
from scripts.confluence_search import confluence_search

# Search with CQL
confluence_search(
    query="space = DEV AND type = page AND text ~ 'API'",
    limit=25
)
Confluence コメント（scripts.confluence_comments）
from scripts.confluence_comments import confluence_get_comments

# Get comments on a page
confluence_get_comments(page_id="12345")
Confluence ラベル（scripts.confluence_labels）
from scripts.confluence_labels import confluence_get_labels

# Get labels on a page
confluence_get_labels(page_id="12345")
Bitbucket プロジェクト（scripts.bitbucket_projects）
from scripts.bitbucket_projects import (
    bitbucket_list_projects,
    bitbucket_list_repositories
)

# List all projects
bitbucket_list_projects(limit=25)

# List repositories in a project
bitbucket_list_repositories(project_key="PROJ", limit=50)
Bitbucket プルリクエスト（scripts.bitbucket_pull_requests）
from scripts.bitbucket_pull_requests import (
    bitbucket_get_pull_request,
    bitbucket_get_pr_diff
)

# Get PR details
bitbucket_get_pull_request(
    project_key="PROJ",
    repository_slug="my-repo",
    pr_id=123
)

# Get PR diff
bitbucket_get_pr_diff(
    project_key="PROJ",
    repository_slug="my-repo",
    pr_id=123
)
Bitbucket ファイルと検索（scripts.bitbucket_files）
from scripts.bitbucket_files import (
    bitbucket_get_file_content,
    bitbucket_search
)

# Get file content
bitbucket_get_file_content(
    project_key="PROJ",
    repository_slug="my-repo",
    file_path="src/main.py",
    branch="develop"
)

# Search code
bitbucket_search(
    query="def authenticate",
    project_key="PROJ",
    search_type="code",
    limit=25
)
Bitbucket コミット（scripts.bitbucket_commits）
from scripts.bitbucket_commits import (
    bitbucket_get_commits,
    bitbucket_get_commit
)

# Get recent commits from a branch
bitbucket_get_commits(
    project_key="PROJ",
    repository_slug="my-repo",
    branch="master",
    limit=10
)

# Get details of a specific commit
bitbucket_get_commit(
    project_key="PROJ",
    repository_slug="my-repo",
    commit_id="1da11eaec25aed8b251de24841885c91493b3173"
)

応答データ構造

すべての関数は、フラット化されたデータ構造（ネストされた API 応答ではありません）を含む JSON 文字列を返します。

Jira 課題の構造
{
  "key": "PROJ-123",
  "id": "10001",
  "summary": "Issue title",
  "description": "Issue description",
  "status": "In Progress",
  "issue_type": "Task",
  "priority": "High",
  "assignee": "[email protected]",
  "reporter": "[email protected]",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-16T14:20:00.000+0000",
  "labels": ["backend", "urgent"],
  "components": ["API", "Auth"],
  "custom_fields": {}
}
Confluence ページの構造
{
  "id": "12345",
  "title": "Page Title",
  "space_key": "DEV",
  "status": "current",
  "created": "2024-01-15T10:30:00.000Z",
  "updated": "2024-01-16T14:20:00.000Z",
  "author": "[email protected]",
  "version": 3,
  "url": "https://company.atlassian.net/wiki/spaces/DEV/pages/12345"
}

注：これらは簡略化された構造です。元の Jira API は {"key": "...", "fields": {"summary": "...", "status": {"name": "..."}}} のようなネストされたデータを返しますが、このスキルでは使いやすいようにフラット化しています。

エラー処理

すべての関数は JSON 文字列を返します。エラーがないか確認してください。

import json

result = jira_get_issue(issue_key="PROJ-999")
data = json.loads(result)

if not data.get("success", True):
    print(f"Error: {data['error']}")
    print(f"Type: {data['error_type']}")
else:
    print(f"Issue: {data['key']}")
エラーの種類
  • ConfigurationError - 環境変数がありません
  • AuthenticationError - 認証情報が無効です
  • ValidationError - 入力パラメーターが無効です
  • NotFoundError - リソースが見つかりません
  • APIError - Atlassian API エラーです
  • NetworkError - 接続に問題があります

方針

このスキルは、以下を提供します。

  • 読み取り専用アクセス：データを変更せずに照会・取得できます
  • トークン効率：書き込み操作を除外し、コンテキストサイズを削減します
  • 安全性：意図しないデータ変更を防ぎます
  • 柔軟性：Cloud と Data Center の両方のデプロイメントに対応します
  • 一貫性：統一されたエラー処理と応答形式を提供します

以下は提供しません。

  • 書き込み操作（作成、更新、削除）
  • API への直接アクセス（代わりに提供されている関数を使用してください）
  • Webhook の処理やイベント処理
  • 一括インポート／エクスポート操作

ベストプラクティス：

  • 戻り値にエラーがないか、必ず確認してください
  • 効率的に検索するには JQL／CQL を使用してください
  • 書き込み操作には、完全版の atlassian-skills パッケージを使用してください

依存関係

pip install requests python-dotenv

または、requirements ファイルを使用してください。

pip install -r requirements.txt

コメント

Markdown 対応