Pleasanter MCP サーバー

Implem.Pleasanter統合のためのModel Context Protocol (MCP)サーバーです。AIアシスタントがPleasanterのプロジェクトや課題を操作できるようになります。

機能

ツール

• 課題管理: 課題の作成、読み取り、更新、削除
• 高度な検索: プロジェクト全体での複雑なフィルタリングと検索
• 分析機能: トレンド分析とプロジェクトステータスサマリー
• バルク操作: 複数課題の効率的な一括処理

リソース

• サイト: 利用可能なPleasanterプロジェクトへのアクセス
• ユーザー/グループ/部署: 組織構造情報
• 動的リソース: リアルタイムのプロジェクトステータスと課題データ

プロンプト

• プロジェクトステータスレポート: 自動化されたプロジェクト健全性レポート
• 課題分析: トレンド分析とレコメンデーション
• チーム生産性: パフォーマンス分析と洞察
• 優先タスク特定: 緊急タスクの特定とアクションプラン
• 週次スタンドアップ準備: チームミーティングの準備

インストール

1. サーバーコードのクローンまたはダウンロード

   Copy

   cd pleasanter-mcp-server

2. 依存関係のインストール

   Copy

   npm install

3. サーバーのビルド

   Copy

   npm run build

前提条件

• Node.js 18.0.0 以上（推奨: 24.x LTS）
• npm または yarn
• Pleasanter サーバーへのアクセス権限とAPIキー

動作確認済み環境

以下の環境でビルドと動作確認が完了しています：

• OS: Ubuntu 24.04.2 LTS (WSL2)
• Node.js: v24.2.0
• npm: v11.3.0
• TypeScript: v5.8.3
• プラットフォーム: WSL2 on Windows

設定

1. 環境ファイルの作成

   Copy

   cp .env.example .env

2. 設定の編集

   Copy

   # 必須設定
   PLEASANTER_BASE_URL=http://10.255.20.80:50001  # ローカルネットワーク内のPleasanterサーバー
   PLEASANTER_API_KEY=your-api-key-here          # PleasanterのAPIキー
   
   # オプション設定
   PLEASANTER_TIMEOUT=30000
   PLEASANTER_RETRIES=3
   LOG_LEVEL=info

   注意:

   • 本番環境ではHTTPSを使用してください
   • APIキーは安全に管理し、定期的にローテーションしてください

3. Pleasanter APIキーの取得

   • Pleasanterシステムにログイン
   • ユーザー設定に移動
   • APIキーを生成またはコピー
   • アカウントでAPIアクセスが有効になっていることを確認

Claude Desktopでの使用方法

macOS環境

1. Claude Desktop設定に追加

   ~/Library/Application Support/Claude/claude_desktop_config.json を編集:

   Copy

   {
     "mcpServers": {
       "pleasanter": {
         "command": "node",
         "args": ["/path/to/pleasanter-mcp-server/dist/index.js"],
         "env": {
           "PLEASANTER_BASE_URL": "https://your-pleasanter-server.com",
           "PLEASANTER_API_KEY": "your-api-key-here"
         }
       }
     }
   }

Windows環境

1. Claude Desktop設定に追加

   %APPDATA%\Claude\claude_desktop_config.json を編集:

   オプション1: WSLコマンドを使用（推奨）

   Copy

   {
     "mcpServers": {
       "pleasanter": {
         "command": "wsl",
         "args": [
           "node",
           "/home/ubuntu/github/Implem.Pleasanter/pleasanter-mcp-server/dist/index.js"
         ],
         "env": {
           "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
           "PLEASANTER_API_KEY": "your-api-key-here",
           "PLEASANTER_TIMEOUT": "30000",
           "PLEASANTER_RETRIES": "3",
           "LOG_LEVEL": "info"
         }
       }
     }
   }

   オプション2: WSL2パスを直接指定

   Copy

   {
     "mcpServers": {
       "pleasanter": {
         "command": "node",
         "args": [
           "\\\\wsl.localhost\\Ubuntu\\home\\ubuntu\\github\\Implem.Pleasanter\\pleasanter-mcp-server\\dist\\index.js"
         ],
         "env": {
           "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
           "PLEASANTER_API_KEY": "your-api-key-here"
         }
       }
     }
   }

   オプション3: Windows側にプロジェクトをコピーした場合

   Copy

   {
     "mcpServers": {
       "pleasanter": {
         "command": "node",
         "args": ["C:\\path\\to\\pleasanter-mcp-server\\dist\\index.js"],
         "env": {
           "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
           "PLEASANTER_API_KEY": "your-api-key-here"
         }
       }
     }
   }

Linux環境

1. Claude Desktop設定に追加

   ~/.config/Claude/claude_desktop_config.json を編集:

   Copy

   {
     "mcpServers": {
       "pleasanter": {
         "command": "node",
         "args": ["/path/to/pleasanter-mcp-server/dist/index.js"],
         "env": {
           "PLEASANTER_BASE_URL": "https://your-pleasanter-server.com",
           "PLEASANTER_API_KEY": "your-api-key-here"
         }
       }
     }
   }

2. Claude Desktopを再起動

3. 接続を確認

   Claude Desktopで以下のプロンプトを試して、MCPサーバーが正常に動作していることを確認してください:

   ステップ1: 基本接続確認

   Copy

   利用可能なPleasanterサイトを一覧表示できますか？

   期待される結果: サイト一覧が表示されるか、適切なエラーメッセージが表示される

   ステップ2: リソース確認

   Copy

   利用可能なPleasanterリソースにはどのようなものがありますか？

   期待される結果: pleasanter://sites、pleasanter://users等のリソース一覧が表示される

   ステップ3: ツール確認

   Copy

   Pleasanter関連で利用できるツールや機能を教えてください。

   期待される結果: pleasanter_create_issue、pleasanter_get_issues等のツール一覧が表示される

   ステップ4: ユーザー情報確認

   Copy

   Pleasanterのユーザー一覧を最初の5件だけ取得してください。

   期待される結果: JSON形式でユーザー情報が表示される

   もしエラーが発生した場合:

   • APIキーが正しく設定されているか確認
   • PLEASANTER_BASE_URLが正しいか確認
   • Claude Desktopを完全に再起動
   • MCPサーバーのログを確認（コンソールエラーなど）

利用可能なツール

課題管理

• pleasanter_create_issue: 新しい課題を作成
• pleasanter_get_issues: 課題を検索・取得
• pleasanter_update_issue: 既存の課題を更新
• pleasanter_delete_issue: 課題を削除
• pleasanter_bulk_create_issues: 複数の課題を一括作成

高度な検索・分析

• pleasanter_advanced_search: フィルターを使った複雑な検索
• pleasanter_multi_site_search: 複数プロジェクトの横断検索
• pleasanter_trend_analysis: プロジェクトトレンド分析
• pleasanter_status_summary: プロジェクトステータスサマリー

利用可能なリソース

• pleasanter://sites: 利用可能なプロジェクト一覧
• pleasanter://users: ユーザーディレクトリ
• pleasanter://groups: グループ情報
• pleasanter://depts: 部署構造
• pleasanter://sites/{siteId}/issues: プロジェクト固有の課題
• pleasanter://sites/{siteId}/summary: プロジェクトサマリー
• pleasanter://sites/{siteId}/status: プロジェクトステータス

利用可能なプロンプト

• project_status_report: 包括的なプロジェクトレポートを生成
• issue_analysis: 課題トレンドを分析し、レコメンデーションを提供
• team_productivity_report: チームパフォーマンス分析
• priority_task_identification: 緊急タスクを特定し、アクションプランを作成
• weekly_standup_preparation: 週次スタンドアップ情報を準備

開発

開発モードでの実行

npm run dev

ビルド

npm run build

テスト

npm test

リント

npm run lint

トラブルシューティング

よくある問題

1. 接続失敗

   • PLEASANTER_BASE_URLが正しいことを確認
   • APIキーの有効性をチェック
   • ネットワーク接続を確認

2. 認証エラー

   • APIキーが正しいことを確認
   • ユーザーのAPIアクセスが有効になっているかチェック
   • ユーザーに必要な権限があることを確認

3. レート制限

   • サーバーはPleasanterのレート制限を遵守します
   • リトライには指数バックオフを実装
   • 日次のAPI使用量を監視

デバッグモード

詳細なログを表示するには、環境変数で LOG_LEVEL=debug を設定してください。

Windows環境固有の問題

1. WSLコマンドが見つからない

   • Windows Subsystem for Linux (WSL)がインストールされているか確認
   • wsl --version でWSLのバージョンを確認

2. パスの区切り文字の問題

   • Windowsのパスはバックスラッシュ \ を使用
   • JSON内ではエスケープが必要: \\

3. ファイアウォールの問題

   • Claude DesktopがMCPサーバーにアクセスできない場合
   • Windows Defenderファイアウォールでポートを許可する必要がある場合があります

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

• APIキーは安全に保管してください
• 設定には環境変数を使用してください
• 適切なアクセス制御を実装してください
• API使用量を監視してください
• 定期的にキーをローテーションしてください

WSL2環境での開発

Windows環境でWSL2を使用している場合の特別な設定：

1. WSL2での環境構築

# WSL2 Ubuntu環境でのセットアップ
sudo apt update
sudo apt install nodejs npm

# プロジェクトのセットアップ
cd /home/ubuntu/github/Implem.Pleasanter/pleasanter-mcp-server
npm install
npm run build

2. 環境変数の設定

# WSL2環境でのPleasanter設定
cp .env.example .env

# .envファイルを編集
PLEASANTER_BASE_URL=http://10.255.20.80:50001
PLEASANTER_API_KEY=your-api-key-here

3. Windows側からのアクセス

• WSL2のファイルシステムは \\wsl.localhost\Ubuntu\ からアクセス可能
• Claude DesktopはWindows側で実行するため、WSLコマンドまたはWSL2パスを使用

Docker環境での実行

完全なDocker環境構築

PleasanterのWebサーバーとMCPサーバーを含む完全な環境を構築できます：

# 1. 環境変数を設定
cp .env.example .env
# .envファイルを編集してPleasanter APIキーを設定

# 2. Docker環境を起動
docker-compose up -d

# 3. 初回セットアップの確認
docker-compose logs codedefiner

# 4. Webアプリケーションにアクセス
# http://localhost:8080 でPleasanterにアクセス

# 5. MCPサーバーの動作確認
# http://localhost:3000 でMCPサーバーの状態確認

サービス構成

• pleasanter-web: PleasanterのWebアプリケーション (ポート8080)
• db: PostgreSQLデータベース (ポート5432)
• codedefiner: データベース初期化用 (一回のみ実行)
• mcp-server: MCPサーバー (ポート3000)

トラブルシューティング

コンテナ停止・再起動

# 全サービス停止
docker-compose down

# データベースも含めて完全削除
docker-compose down -v

# 再構築
docker-compose up --build -d

ログの確認

# 全サービスのログ
docker-compose logs

# 特定サービスのログ
docker-compose logs pleasanter-web
docker-compose logs mcp-server

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。