# 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
```