MCP Atlassian

MCP Atlassian

Atlassian 製品（Confluence および Jira）と連携するための包括的なツールを提供する、Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーを使用すると、AI エージェントは標準化されたインターフェースを通じて Atlassian 製品と連携できます。次のような幅広いツールを提供します。

• Confluence：v2 REST API を使用した、作成・読み取り・更新・削除操作、コンテンツ検索、スペース管理、ページ管理、コメント、ラベルなど
• Jira：課題管理、プロジェクト操作、トランジション、コメント、包括的なワークフローサポート

主な機能

• 最新の API サポート：Confluence v2 REST API を使用し、検索機能では v1 にフォールバックします
• 包括的なツールセット：主要な操作を網羅する 18 種類以上の Confluence ツールと 8 種類以上の Jira ツール
• セキュリティとプライバシー：PII フィルタリングと SSL 検証制御を内蔵しています
• 柔軟な設定：サービス URL の個別設定、認証方法、ツールのフィルタリングをサポートします
• ページネーションのサポート：v2 API ではカーソルベース、v1 API ではオフセット／上限によるページネーションをサポートします
• エラー処理：詳細なエラーメッセージを含む、包括的なエラー処理
• 型安全性：適切な型定義を備えた、TypeScript による完全な実装

前提条件

• Node.js（v16 以降）
• npm または yarn
• API トークンを持つ Atlassian アカウント
• Docker（任意。コンテナ化されたデプロイに使用）

インストール

標準インストール

1. リポジトリをクローンします。

   git clone https://github.com/yourusername/mcp-atlassian.git
   cd mcp-atlassian
   

2. 依存関係をインストールします。

   npm install
   # or using make
   make install
   

3. ルートディレクトリに Atlassian の認証情報を記載した .env ファイルを作成します。

   ATLASSIAN_HOST=https://your-domain.atlassian.net
   [email protected]
   ATLASSIAN_API_TOKEN=your-api-token
   

Docker インストール

1. リポジトリをクローンします。

   git clone https://github.com/yourusername/mcp-atlassian.git
   cd mcp-atlassian
   

2. 上記の説明に従って .env ファイルを作成します。

3. Docker コンテナをビルドして実行します。

   # Build the Docker image
   make docker-build
   
   # Run the Docker container
   make docker-run
   
   # Or use Docker Compose
   make docker-compose
   

使用方法

サーバーの起動

# Using npm
npm start

# Using make
make start

# Using Docker
make docker-run

これにより MCP サーバーが起動し、ストリーミング可能な HTTP でリッスンして応答します。

MCP の設定

    "mcp-searchapi": {
      "name": "mcp-searchapi",
      "type": "streamable-http",
      "streamable": true,
      "url": "http://localhost:3007/mcp"
    }

利用可能なツール

Confluence ツール

検索と探索：

• search_confluence: CQL を使用し、v1 API で Confluence のコンテンツを検索します

  • パラメーター：searchText（文字列）、spaceKey（文字列、省略可）、limit（数値）、start（数値）

• search_confluence_pages_by_title: v2 API を使用し、タイトルでページを検索します

  • パラメーター：title（文字列、省略可）、spaceId（文字列、省略可）、limit（数値）、cursor（文字列、省略可）

スペース管理：

• get_confluence_space_by_id_or_key: 特定の Confluence スペースの情報を取得します

  • パラメーター：spaceIdOrKey（文字列）

• get_confluence_spaces: 利用可能なすべてのスペースを取得します

  • パラメーター：limit（数値、省略可）、cursor（文字列、省略可）

ページ管理：

• get_confluence_content: ID で指定したページのコンテンツを取得します

  • パラメーター：pageId（文字列）、bodyFormat（列挙型：storage/atlas_doc_format/wiki、省略可）

• get_confluence_pages: スペース内のすべてのページを取得します

  • パラメーター：spaceId（文字列）、limit（数値、省略可）、cursor（文字列、省略可）

• get_confluence_child_pages: 特定のページの子ページを取得します

  • パラメーター：pageId（文字列）、limit（数値、省略可）、cursor（文字列、省略可）

• confluence_create_page: Confluence の新しいページを作成します

  • パラメーター：spaceId（文字列）、title（文字列）、content（文字列）、status（列挙型、省略可）、representation（列挙型、省略可）、parentId（文字列、省略可）

• confluence_update_page: 既存のページを更新します

  • パラメーター：pageId（文字列）、title（文字列）、content（文字列）、version（数値）、status（列挙型、省略可）、representation（列挙型、省略可）、versionMessage（文字列、省略可）

• update_confluence_page_title: ページのタイトルのみを更新します

  • パラメーター：pageId（文字列）、title（文字列）、status（列挙型、省略可）

• confluence_delete_page: Confluence のページを削除します

  • パラメーター：pageId（文字列）

ラベル管理：

• get_confluence_pages_by_label: 特定のラベルが付いたページを検索します

  • パラメーター：label（文字列）、spaceId（文字列、省略可）、limit（数値、省略可）、cursor（文字列、省略可）

• get_confluence_page_labels: 特定のページのラベルを取得します

  • パラメーター：pageId（文字列）、limit（数値、省略可）、cursor（文字列、省略可）

• add_confluence_page_labels: ページにラベルを追加します

  • パラメーター：pageId（文字列）、labels（文字列の配列）

コメント：

• get_confluence_page_comments: ページの通常のコメントを取得します

  • パラメーター：pageId（文字列）、limit（数値、省略可）、cursor（文字列、省略可）

• add_confluence_page_comment: ページにコメントを追加します

  • パラメーター：pageId（文字列）、content（文字列）、representation（列挙型、省略可）

• get_confluence_page_inline_comments: ページのインラインコメントを取得します

  • パラメーター：pageId（文字列）、limit（数値、省略可）、cursor（文字列、省略可）

• create_confluence_footer_comment: フッターコメントを作成します

  • パラメーター：pageId（文字列、省略可）、blogPostId（文字列、省略可）、parentCommentId（文字列、省略可）、attachmentId（文字列、省略可）、customContentId（文字列、省略可）、content（文字列）、representation（列挙型、省略可）

Jira ツール

• search_jira_issues：JQL（Jira クエリ言語）を使用して課題を検索します

  • パラメーター：jql（文字列）、maxResults（数値、任意）

• get_jira_issue：特定の課題の詳細情報を取得します

  • パラメーター：issueKey（文字列）

• jira_get_all_projects：アクセス可能なすべてのプロジェクトを取得します

  • パラメーター：なし

• jira_create_issue：新しい Jira 課題を作成します

  • パラメーター：projectKey（文字列）、issueType（文字列）、summary（文字列）、description（文字列、任意）、追加フィールド

• jira_update_issue：既存の課題を更新します

  • パラメーター：issueKey（文字列）、fields（更新データを含むオブジェクト）

• jira_add_comment：課題にコメントを追加します

  • パラメーター：issueKey（文字列）、comment（文字列）

• jira_get_transitions：課題で利用可能なトランジションを取得します

  • パラメーター：issueKey（文字列）

• jira_transition_issue：課題のステータスを変更します

  • パラメーター：issueKey（文字列）、transitionId（文字列）、comment（文字列、任意）

アーキテクチャに関する注意事項

Confluence API の移行

このサーバーはほとんどの操作で主に Confluence v2 REST API を使用し、必要に応じて v1 API に戦略的にフォールバックします。

• v2 API：スペース、ページ、コメント、ラベルに使用します。パフォーマンスが向上し、最新のカーソルベースのページネーションを利用できます
• v1 API：CQL によるコンテンツ検索に使用します。より強力な検索機能を提供します
• SSL サポート：セルフホスト型インスタンス向けに、SSL 検証のバイパスを設定できます
• 認証：基本認証、OAuth 2.0（予定）、PAT トークンをサポートします

ツールのフィルタリングとセキュリティ

• 読み取り専用モード：安全に探索できるよう、すべての書き込み操作を無効にします
• ツールの許可リスト：ENABLED_TOOLS 環境変数を使用して、特定のツールのみを有効にします
• PII フィルタリング：応答内の機密情報を自動的に検出してマスキングします
• エラーコンテキスト：機密設定を公開せずに、詳細なエラーメッセージを提供します

開発

プロジェクト構成

src/
├── config/         # Configuration files
│   └── env.ts      # Environment configuration with validation
├── services/       # Service classes for Atlassian APIs
│   ├── confluencev2.ts    # Confluence v2 REST API service (primary)
│   ├── confluence.ts      # Legacy Confluence service (deprecated)
│   └── jira.ts           # Jira REST API service
├── tools/          # MCP tool implementations
│   ├── search-confluence.ts                    # Content search (v1 API)
│   ├── search-confluence-pages-by-title.ts     # Title search (v2 API)
│   ├── get-confluence-space.ts                 # Single space info
│   ├── get-confluence-spaces.ts                # All spaces list
│   ├── get-confluence-content.ts               # Page content by ID
│   ├── get-confluence-pages.ts                 # Pages in space
│   ├── get-confluence-child-pages.ts           # Child pages
│   ├── get-confluence-pages-by-label.ts        # Pages by label
│   ├── get-confluence-page-labels.ts           # Page labels
│   ├── add-confluence-page-labels.ts           # Add labels
│   ├── get-confluence-page-comments.ts         # Page comments
│   ├── add-confluence-page-comment.ts          # Add comment
│   ├── get-confluence-page-inline-comments.ts  # Inline comments
│   ├── confluence-create-page.ts               # Create page
│   ├── confluence-update-page.ts               # Update page
│   ├── update-confluence-page-title.ts         # Update title only
│   ├── confluence-delete-page.ts               # Delete page
│   ├── create-confluence-footer-comment.ts     # Footer comments
│   ├── search-jira-issues.ts                   # Jira search
│   ├── get-jira-issue.ts                       # Single issue
│   ├── jira-create-issue.ts                    # Create issue
│   ├── jira-update-issue.ts                    # Update issue
│   ├── jira-add-comment.ts                     # Add comment
│   ├── jira-get-transitions.ts                 # Get transitions
│   ├── jira-transition-issue.ts                # Transition issue
│   ├── jira-get-all-projects.ts                # All projects
│   ├── utils.ts                                 # Utility functions & PII filtering
│   └── index.ts                                # Tool exports
├── utils/          # Utility modules
│   └── tool-filter.ts      # Tool filtering and access control
└── index.ts        # Main entry point and server setup

ビルド

# Using npm
npm run build

# Using make
make build

テスト

# Using npm
npm test

# Using make
make test

Makefile コマンド

このプロジェクトには、一般的な操作を簡単に実行できる Makefile が含まれています。

# Display available commands
make help

ライセンス

MIT

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します