connpass-skill

Connpass のイベント・グループ・ユーザー情報を、外部 MCP サーバーなしでローカルから検索する Agent Skill

Connpass（connpass.com）のイベント・グループ・ユーザー情報を、Python スクリプト経由で connpass API v2 から直接取得します。

✨ できること

用途	スクリプト
イベント検索（キーワード・日付・都道府県など）	scripts/search_events.py
イベント詳細（イベント ID 指定）	scripts/get_event.py
グループ（コミュニティ）検索	scripts/search_groups.py
ユーザー検索（ニックネーム）	scripts/search_users.py
ユーザーの参加・主催スケジュール	scripts/get_schedule.py

📋 必要条件

• Python 3（標準ライブラリのみ使用、追加パッケージ不要）
• Connpass API キー — connpass API v2 で取得

⚙️ セットアップ

1. リポジトリを取得して作業ディレクトリに移動する

git clone https://github.com/Tomatio13/conpass-skill.git
cd conpass-skill

2. API キーを環境変数に設定する

export CONNPASS_API_KEY="your-api-key-here"

API v2 は X-API-Key ヘッダーによる認証が必須です。キー未設定の場合、スクリプトはエラーで停止します。

🚀 クイックスタート

API キーを設定したら、次のコマンドで動作確認できます。

export CONNPASS_API_KEY="your-api-key-here"
python3 scripts/search_events.py --keyword "Python" --prefecture 東京 --count 5 --format text

🤖 Agent Skill として使う

SKILL.md を Cursor などの Agent Skills として登録すると、エージェントが Connpass 関連の質問に対して適切なスクリプトを自動選択して実行できます。

典型的な利用例:

• 「来月の東京で AI 関連の勉強会を探して」
• 「イベント ID 123456 の詳細を教えて」
• 「Rust コミュニティを愛知で探して」
• 「ニックネーム alice の参加予定イベントを見せて」

agents/openai.yaml には OpenAI Agents 向けの表示名・デフォルトプロンプトが定義されています。

💻 CLI の使い方

すべてのスクリプトで --format json|text（デフォルト: json）を指定できます。

イベント検索

python3 scripts/search_events.py \
  --keyword "AI" \
  --prefecture 東京 \
  --local-start-date 2026-07-01 \
  --local-end-date 2026-07-31 \
  --count 10 \
  --order 2 \
  --format json

主なオプション:

• API 直結: --keyword, --keyword-or, --prefecture, --group-id, --subdomain, --ym, --ymd, --publish-ym, --publish-ymd, --count, --start, --order
• ローカル後段フィルタ（API パラメータではない）: --area, --local-start-date, --local-end-date
• --order: 1=更新順, 2=開催日順, 3=新着順

イベント詳細

python3 scripts/get_event.py --event-id 123456 --format json

グループ検索

イベント検索結果からグループ情報を間接的に抽出します。

python3 scripts/search_groups.py --keyword "Rust" --prefecture 愛知 --count 10 --format json

ユーザー検索

python3 scripts/search_users.py --nickname alice --role participant --count 10 --format json

--role は participant（参加者）または owner（主催者）を指定します。

スケジュール取得

python3 scripts/get_schedule.py \
  --nickname alice \
  --role participant \
  --local-start-date 2026-07-01 \
  --local-end-date 2026-07-31 \
  --count 20 \
  --format json

🗾 都道府県の指定

connpass API v2 の正式値は英字コードです。スクリプトは英字コードと日本語名の両方を受け付けます。

入力例	API 値
東京, 東京都	tokyo
オンライン	online
愛知	aichi

正式な英字コード一覧: online, hokkaido, aomori, … okinawa（SKILL.md 参照）

📁 プロジェクト構成

connpass-skill/
├── SKILL.md              # Agent Skill 定義（ワークフロー・ルーティング）
├── README.md
├── agents/
│   └── openai.yaml       # OpenAI Agents 向けメタデータ
├── scripts/
│   ├── _connpass.py      # 共通 API クライアント・ユーティリティ
│   ├── search_events.py
│   ├── get_event.py
│   ├── search_groups.py
│   ├── search_users.py
│   └── get_schedule.py
└── references/
    └── connpass-events-api-v2-spec.md  # API v2 仕様メモ

⚠️ エラーと制限

状況	対処
CONNPASS_API_KEY 未設定	環境変数を設定して再実行
HTTP 401	API キーを確認
HTTP 403 / 429	キーのスコープとレート制限を確認（公式: 1 秒 1 リクエスト）
検索結果 0 件	フィルタを緩めて再試行（日付 → エリア → キーワードの順）
ユーザー・イベントの特定不能	候補一覧を提示してユーザーに選択を求める

API エラー時はデータを捏造せず、リクエスト失敗として報告します。

🔗 参考リンク

• connpass API v2 ドキュメント
• イベント検索 API（OpenAPI）

📄 ライセンス

本リポジトリに LICENSE ファイルがない場合は、利用前に管理者に確認してください。