Connpass MCP Server

# Connpass MCP Server Connpass MCP Server は、[connpass](https://connpass.com/) API を使用してIT勉強会やイベント情報を取得する Model Context Protocol (MCP) サーバーです。 ## 機能 1. **get_user_attended_events** - ユーザーの参加イベント取得 2. **get_group_events** - グループのイベント一覧取得 3. **list_available_groups** - 利用可能なグループ一覧表示 4. **search_events_by_location** - 地域・キーワードでのイベント検索 5. **search_events_by_keyword_or** - OR条件でのキーワード検索 6. **list_available_prefectures** - 検索可能な都道府県一覧表示 ## セットアップ ### 1. 環境構築 ```bash git clone https://github.com/tyukei/commpass_mcp_server.git uv venv --python python3.12 source .venv/bin/activate uv sync ``` ### 2. 環境変数の設定 `.env.example` ファイルをコピーして `.env` ファイルを作成し、Connpass API キーを設定： ```env CONNPASS_API=your_connpass_api_key_here ``` **注意**: Connpass API キーの取得方法については、[Connpass API ドキュメント](https://connpass.com/about/api/)を参照してください。 ### 3. サーバーの起動 ```bash python src/main.py ``` ## 使用例 ### ユーザーの参加イベント取得 ```python await get_user_attended_events("nickname", start=1, count=10) ``` ### グループのイベント取得 ```python await get_group_events("LLMCraft", start=1, count=10) ``` ### 地域でのイベント検索 ```python await search_events_by_location(prefecture="沖縄", start=1, count=10) ``` ### キーワードでのイベント検索 ```python await search_events_by_keyword_or("LLM", start=1, count=10) ``` ## テスト テストスクリプトを実行してAPIの動作を確認できます： ```bash # ユーザー関連のテスト uv run python tests/test_user.py # 場所検索のテスト uv run python tests/test_location.py # レート制限のテスト uv run python tests/test_rate_limit.py ``` **注意**: レート制限テストは実際のAPIを使用するため、完了まで数秒かかります。 ## MCP クライアントでの使用 このサーバーは MCP（Model Context Protocol）に対応しているため、MCP クライアント（Claude Desktop など）から利用できます。 ### Claude Desktop での設定例 ```json { "mcpServers": { "connpass": { "command": "python", "args": ["/path/to/commpass_mcp_server/src/main.py"], "env": { "CONNPASS_API": "your_api_key_here" } } } } ``` ## ファイル構成 ``` commpass_mcp_server/ ├── src/ │ ├── __init__.py # パッケージ初期化 │ ├── main.py # MCPサーバーエントリポイント │ ├── config.py # 設定・定数管理 │ ├── errors.py # エラーハンドリング │ ├── api_client.py # Connpass API クライアント │ └── tools.py # MCPツール実装 ├── tests/ │ ├── __init__.py │ ├── test_user.py # ユーザー関連テスト │ └── test_location.py # 場所検索テスト ├── pyproject.toml # プロジェクト設定 ├── README.md # このファイル ├── ARCHITECTURE.md # アーキテクチャドキュメント └── .env # 環境変数（要作成） ``` 詳細なアーキテクチャについては [ARCHITECTURE.md](ARCHITECTURE.md) を参照してください。 ## 開発 ### 新しいグループの追加 `src/config.py` の `GROUP_MAPPING` 辞書に新しいグループを追加： ```python GROUP_MAPPING = { "LLMCraft": 16032, "新しいグループ名": グループID } ``` ※ グループIDはconnpassのグループページのURLから取得可能です。 ### 新しい機能の追加 1. `src/api_client.py` に新しいAPIエンドポイントのメソッドを追加（必要な場合） 2. `src/tools.py` に新しいツールのロジックを追加 3. `src/main.py` で `@mcp.tool()` デコレータを使用して新しい関数を登録 詳細は [ARCHITECTURE.md](ARCHITECTURE.md) を参照してください。 ## ライセンス このプロジェクトは MIT ライセンスの下で公開されています。 ## 貢献 バグ報告や機能リクエスト、プルリクエストを歓迎します。 ## 重要な制限事項と注意点 ### APIアクセス制限 - **レート制限**: 1秒間に1リクエストまで（過剰アクセスでHTTP 429エラー発生） - **認証必須**: すべてのAPIエンドポイントでAPIキーが必要 - テスト時は複数のAPIを連続実行すると制限に引っかかるため、間隔を空けて実行してください ### よくあるエラーと対処法 #### HTTP 404 Not Found ``` エラー: HTTP 404: {"detail": "Not Found"} ``` - **原因**: 存在しないユーザー名を指定した場合 - **対処**: 正確なconnpassユーザーのニックネームを確認して再実行 #### HTTP 429 Too Many Requests ``` エラー: HTTP 429: {"detail": "Too many requests."} ``` - **原因**: 1秒間に複数回のAPIリクエストを送信 - **対処**: 1秒以上の間隔を空けてから再実行してください #### HTTP 401 Unauthorized - **原因**: 無効なAPIキーまたは未設定 - **対処**: `.env`ファイルのAPIキーを確認してください ### セキュリティ - APIキーは安全に管理し、公開リポジトリにコミットしないよう注意してください - 本プロジェクトはconnpassの公式プロジェクトではありません # Appendix ## プロジェクト作成コマンド ```bash uv init commpass_mcp_server --python python3.13 source .venv/bin/activate uv add "mcp[cli]>=1.13.1" httpx python-dotenv ```