# mcp-confluence

Confluence の検索・ページ取得機能を提供する MCP サーバー。

## インストール

### バイナリをダウンロード

[Releases ページ](https://github.com/tjun1/mcp-confluence/releases) から環境に合ったバイナリをダウンロード：

| プラットフォーム | ファイル名 |
|------------------|------------|
| macOS (Apple Silicon) | `mcp-confluence-darwin-arm64` |
| Linux (x64) | `mcp-confluence-linux-x64` |
| Windows (x64) | `mcp-confluence-windows-x64.exe` |

ダウンロード後、PATH の通った場所に配置して実行権限を付与：

```bash
chmod +x mcp-confluence-*
mv mcp-confluence-* ~/.local/bin/mcp-confluence
```

### ソースからビルド

```bash
git clone https://github.com/tjun1/mcp-confluence.git
cd mcp-confluence
./install.sh
```

`~/.local/bin/mcp-confluence` にバイナリがインストールされる。

**前提条件**: [Bun](https://bun.sh/) がインストールされていること。

## セットアップ

### Atlassian API トークンの取得

1. [Atlassian API トークン管理ページ](https://id.atlassian.com/manage-profile/security/api-tokens) にアクセス
2. 「API トークンを作成」をクリック
3. トークンに名前を付けて「作成」
4. 表示されたトークンをコピーして安全に保管（再表示不可）

### スペース ID の確認方法

Confluence のスペースを開き、URL を確認する：

```
https://your-domain.atlassian.net/wiki/spaces/SPACE_KEY/...
                                         ^^^^^^^^^^
                                         これがスペースキー
```

または、スペース設定 → スペースの詳細 で確認できる。

## 環境変数

| 変数名 | 必須 | 説明 |
|--------|------|------|
| `CONFLUENCE_BASE_URL` | ○ | Confluence の URL（例: `https://your-domain.atlassian.net/wiki`） |
| `CONFLUENCE_EMAIL` | △ | Atlassian アカウントのメールアドレス |
| `CONFLUENCE_API_TOKEN` | △ | Atlassian API トークン |
| `CONFLUENCE_BEARER_TOKEN` | △ | Bearer トークン（Email + API Token の代わりに使用可） |
| `CONFLUENCE_DEFAULT_SPACES` | - | 検索対象のスペースをカンマ区切りで指定（例: `SPACE1,SPACE2`） |

**認証方式**: `CONFLUENCE_EMAIL` + `CONFLUENCE_API_TOKEN`（Basic認証）または `CONFLUENCE_BEARER_TOKEN` のいずれかが必要。

## MCP クライアントへの設定

### グローバル設定（~/.claude/）

すべてのプロジェクトで使いたい場合、`~/.claude/claude_desktop_config.json` に設定する：

```json
{
  "mcpServers": {
    "confluence": {
      "command": "/Users/your-name/.local/bin/mcp-confluence",
      "args": [],
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_DEFAULT_SPACES": "SPACE1,SPACE2"
      }
    }
  }
}
```

### プロジェクトローカル設定（.mcp.json）

特定のプロジェクトでのみ使いたい場合、プロジェクトルートに `.mcp.json` を作成する：

```json
{
  "mcpServers": {
    "confluence": {
      "command": "/Users/your-name/.local/bin/mcp-confluence",
      "args": [],
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_DEFAULT_SPACES": "PROJECT_SPACE"
      }
    }
  }
}
```

### .mcp.json をバージョン管理しない

`.mcp.json` には API トークンなどの認証情報が含まれるため、**絶対にバージョン管理に含めてはいけない**。

`.gitignore` に追加：

```
.mcp.json
```

チームで設定を共有したい場合は、`.mcp.json.example` のようなテンプレートファイルを用意し、各自がコピーして使う運用にする。

### VSCode + GitHub Copilot

VSCode の GitHub Copilot から mcp-confluence を利用できる。

**前提条件:**
- VS Code 1.102 以降
- GitHub Copilot 拡張機能
- GitHub Copilot Chat 拡張機能

#### セットアップ手順

プロジェクトルートに `.vscode/mcp.json` を作成する。設定方法は2つある。

##### 方法1: シンプルな設定（inputs 不使用）

API トークンを設定ファイルに直接記述する方法。

**手順:**

1. `.vscode` ディレクトリを作成（存在しない場合）
   ```bash
   mkdir -p .vscode
   ```

2. `.vscode/mcp.json` を作成して以下を記述
   ```json
   {
     "servers": {
       "confluence": {
         "command": "$HOME/.local/bin/mcp-confluence",
         "args": [],
         "env": {
           "CONFLUENCE_BASE_URL": "https://your-domain.atlassian.net/wiki",
           "CONFLUENCE_EMAIL": "your-email@example.com",
           "CONFLUENCE_API_TOKEN": "your-api-token",
           "CONFLUENCE_DEFAULT_SPACES": "SPACE1,SPACE2"
         }
       }
     }
   }
   ```

3. VSCode を再起動
4. GitHub Copilot Chat から `@confluence` として利用可能

##### 方法2: 推奨設定（inputs 使用）

API トークンを起動時にプロンプトで入力する方法。認証情報がファイルに残らないため安全。

**手順:**

1. `.vscode` ディレクトリを作成（存在しない場合）
   ```bash
   mkdir -p .vscode
   ```

2. `.vscode/mcp.json` を作成して以下を記述
   ```json
   {
     "inputs": {
       "confluenceApiToken": {
         "type": "promptString",
         "password": true,
         "description": "Confluence API Token"
       }
     },
     "servers": {
       "confluence": {
         "command": "$HOME/.local/bin/mcp-confluence",
         "args": [],
         "env": {
           "CONFLUENCE_BASE_URL": "https://your-domain.atlassian.net/wiki",
           "CONFLUENCE_EMAIL": "your-email@example.com",
           "CONFLUENCE_API_TOKEN": "${input:confluenceApiToken}",
           "CONFLUENCE_DEFAULT_SPACES": "SPACE1,SPACE2"
         }
       }
     }
   }
   ```

3. VSCode を再起動
4. GitHub Copilot を使用する際、API トークンの入力プロンプトが表示される（`password: true` により入力内容は隠される）

##### サンプルファイルの利用

プロジェクトルートの `mcp.vscode.example.json` をコピーして使うこともできる：

```bash
mkdir -p .vscode
cp mcp.vscode.example.json .vscode/mcp.json
# エディタで .vscode/mcp.json を開いて環境に合わせて編集
```

#### Claude Desktop との形式の違い

| 項目 | Claude Desktop | VSCode |
|------|----------------|--------|
| 設定ファイル | `~/.claude/claude_desktop_config.json` または `.mcp.json` | `.vscode/mcp.json` |
| ルートキー | `mcpServers` | `servers` |
| command | 絶対パスが必要 | `$HOME` 変数が使える |
| 機密情報 | env に直接記述 | inputs で変数化可能 |

#### 注意事項

- `.vscode/mcp.json` には認証情報が含まれるため、バージョン管理から除外すること（`.gitignore` に追加済み）
- チームで設定を共有する場合は、各自が `mcp.vscode.example.json` をコピーして `.vscode/mcp.json` を作成する運用にする

## 利用可能なツール

MCP クライアント（Claude など）に対して、ツール名を明示して指示するのが基本。
ただし、会話の文脈から判断してくれることもあるため、必須ではない。

### confluence_search

Confluence のコンテンツを検索する。

**使い方の例:**
- 「confluence_search を使って最新のスプリントレビューを探して」
- 「confluence_search でミーティング記録を検索して、新しい順に5件」

### confluence_get_page

ページの内容を取得する。

**使い方の例:**
- 「confluence_get_page でそのページの内容を見せて」
- 「confluence_get_page でページID 12345678 の詳細を取得して」

## 開発者向け情報

### 開発環境のセットアップ

```bash
git clone https://github.com/tjun1/mcp-confluence.git
cd mcp-confluence
bun install
```

### 環境変数の設定

`.env` ファイルを作成（Bun が自動で読み込む）：

```bash
CONFLUENCE_BASE_URL=https://your-domain.atlassian.net/wiki
CONFLUENCE_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token
CONFLUENCE_DEFAULT_SPACES=DEV,TEST
```

### 実行

```bash
bun run src/index.ts
```

### テスト

```bash
bun test
```

## License

MIT License. See [LICENSE](./LICENSE) for details.