Confluence MCP Server

Confluence MCP サーバー

Confluence API にアクセスするための Model Context Protocol サーバーシステムです。Personal Access Token を使用して Confluence と通信します。VPN 領域内で Confluence API にアクセスするための中継サーバーとして機能します。

システム構成

このプロジェクトは、2 つのサーバーで構成されています。

1. MCP サーバー（server.ts）：Confluence API と通信してデータを処理するメインサーバーです。

   • デフォルトポート：3000
   • RESTful API を提供
   • MCP プロトコルを処理

2. プロキシサーバー（proxyServer.ts）：MCP クライアントと MCP サーバーの間でプロキシとして機能します。

   • デフォルトポート：3001
   • MCP クライアントからリクエストを受け取り、メインサーバーに転送

この構成は、VPN 領域の問題を解決するために設計されています。MCP サーバーは VPN 内部で実行されて Confluence API にアクセスし、プロキシサーバーは外部からアクセス可能な環境で実行されます。

機能

• Confluence のすべてのスペースを一覧表示
• 特定のスペース内のすべてのページを一覧表示
• ページ ID を指定して特定のページ情報を取得
• 新しいページを作成
• 既存のページを更新

インストールと設定

必要条件

• Node.js 16.x 以上
• Bun 1.0.0 以上

インストール

# 저장소 클론
git clone https://github.com/yourusername/confluence-mcp-server.git
cd confluence-mcp-server

# 의존성 설치
bun install

環境変数の設定

プロジェクトのルートに .env ファイルを作成し、次の内容を追加します。

PORT=3000
PROXY_PORT=3001
MCP_SERVER_URL=http://localhost:3000
CONFLUENCE_BASE_URL=https://wiki.musinsa.com
PERSONAL_ACCESS_TOKEN=your_personal_access_token
NODE_ENV=development

実行

開発環境

# MCP 서버 실행 (Confluence API와 통신)
bun run dev

# 프록시 서버 실행 (MCP 클라이언트와 통신)
bun run dev:proxy

# MCP 서버 Stdio 모드 실행 (선택 사항)
bun run dev:stdio

本番環境

# 빌드
bun run build

# MCP 서버 실행
bun run serve

# 프록시 서버 실행
bun run serve:proxy

エンドポイント

MCP サーバーのエンドポイント（デフォルトポート：3000）

• POST /mcp - MCP リクエストを処理するメインエンドポイント
• GET /mcp/tools - 使用可能なツールの一覧を取得
• GET /api/spaces - すべてのスペースの一覧を取得
• GET /api/spaces/:spaceKey/pages - 特定のスペースのページ一覧を取得
• GET /api/pages/:pageId - 特定のページ情報を取得
• POST /api/pages - 新しいページを作成
• PUT /api/pages/:pageId - ページを更新
• GET /health - サーバーの状態を確認

プロキシサーバーのエンドポイント（デフォルトポート：3001）

• POST /mcp - MCP クライアントからリクエストを受け取り、MCP サーバーに転送
• GET /tools - 使用可能なツールの一覧を取得
• GET /health - プロキシサーバーの状態を確認

トラブルシューティング

VPN 領域の問題を解決する

このプロジェクトは、VPN 領域の問題を解決するために 2 つのサーバーに分割されています。

1. MCP サーバーは VPN 内部で実行し、Confluence API に直接アクセスします。
2. プロキシサーバーは外部からアクセス可能な環境で実行し、MCP クライアントからのリクエストを受け取ります。

この構成により、MCP クライアントが Confluence API に直接アクセスできない状況で中継できます。

「Error fetching spaces: Unable to connect」エラー

このエラーは、次のような問題が原因で発生することがあります。

1. HTTPS 証明書の問題：開発環境では SSL 証明書の検証が無効になっていますが、本番環境では正しい証明書を設定する必要があります。

2. ネットワーク接続の問題：ファイアウォールやプロキシの設定により、Confluence サーバーにアクセスできない場合です。

3. Personal Access Token の問題：トークンの有効期限が切れているか、形式が間違っている可能性があります。

解決方法

1. .env ファイルの CONFLUENCE_BASE_URL が正しいことを確認します。
2. Personal Access Token が有効であることを確認します。
3. ファイアウォールの設定を確認し、Confluence サーバーにアクセスできることを確認します。
4. ネットワーク管理者に問い合わせて、アクセス権限を確認します。
5. MCP サーバーとプロキシサーバー間の接続が正しく設定されていることを確認します（MCP_SERVER_URL の設定）。

テスト

# 모든 테스트 실행
bun test

# 특정 테스트 실행
bun test src/test/getSpaces.test.ts

デプロイ構成

推奨デプロイ構成

本番環境では、次のデプロイ構成を推奨します。

1. MCP サーバー：VPN 内部、または Confluence サーバーにアクセスできるネットワークにデプロイ
2. プロキシサーバー：MCP クライアントがアクセスできるネットワークにデプロイ

セキュリティに関する考慮事項

• プロキシサーバーと MCP サーバー間の通信には、HTTPS を使用して暗号化することを推奨します。
• Personal Access Token は安全に管理し、必要に応じて定期的に更新してください。
• 本番環境では、適切な認証メカニズムを追加して、プロキシサーバーへの不正アクセスを防止してください。

ライセンス

MIT