@kajidog/connpass-mcp-server 0.3.0 → 0.4.0

package/README.md

@@ -4,149 +4,93 @@
 
 Connpass MCP Server は、MCP (Model Context Protocol) 経由で Connpass API を扱うためのツール群です。AI やエージェントが理解しやすいパラメータ設計になっており、自然言語に近い入力でイベント・グループ・ユーザー情報を取得できます。
 
+MCP Apps Extension 対応クライアントでは、インタラクティブなイベントブラウザ UI も利用できます。
+
 ## インストール
 
-### npx で即座に起動
+### npx で即座に起動（stdio モード）
 
 ```bash
-# HTTP トランスポートで起動（デフォルト）
+# 起動
 npx @kajidog/connpass-mcp-server
 
-# ポート指定
-npx @kajidog/connpass-mcp-server --port 8080
-
-# SSE トランスポートで起動
-npx @kajidog/connpass-mcp-server --transport sse
+# API キーを指定
+CONNPASS_API_KEY=your-api-key npx @kajidog/connpass-mcp-server
 
 # ヘルプを表示
 npx @kajidog/connpass-mcp-server --help
 ```
 
-環境変数を設定する場合：
+### HTTP モードで起動
 
 ```bash
-CONNPASS_API_KEY=your-api-key npx @kajidog/connpass-mcp-server
+npx @kajidog/connpass-mcp-server --http --port 3000
 ```
 
 ### グローバルインストール
 
 ```bash
-# インストール
 npm install -g @kajidog/connpass-mcp-server
-
-# 実行
 connpass-mcp-server
 ```
 
-## 開発用セットアップ
-
-1. 依存関係をインストールします。
-
-   ```bash
-   pnpm install
-   ```
-
-2. ビルドして利用可能な状態にします。
-
-   ```bash
-   pnpm --filter @kajidog/connpass-mcp-server build
-   ```
-
-3. Connpass API キーを環境変数で指定してサーバーを起動します。
-
-   ```bash
-   CONNPASS_API_KEY=あなたのAPIキー pnpm --filter @kajidog/connpass-mcp-server start
-   ```
+## 環境変数
 
-   > ローカル開発時などで API キーが未設定の場合、`dummy-key` が自動で使用されます。
+| 変数名 | 説明 | デフォルト |
+|--------|------|-----------|
+| `CONNPASS_API_KEY` | Connpass API キー | - |
+| `CONNPASS_DEFAULT_USER_ID` | `search_schedule` で `userId` 省略時に使うユーザー ID | - |
+| `CONNPASS_RATE_LIMIT_ENABLED` | API レート制限の有効化 | `true` |
+| `CONNPASS_RATE_LIMIT_DELAY_MS` | レート制限の遅延 (ms) | `1000` |
+| `MCP_HTTP_MODE` | HTTP モードで起動 | `false` |
+| `MCP_HTTP_PORT` | HTTP モードのポート | `3000` |
+| `MCP_HTTP_HOST` | HTTP モードのホスト | `0.0.0.0` |
+| `MCP_API_KEY` | HTTP モードの API キー認証 | - |
 
-必要に応じて、デフォルトで参照するユーザー ID を `CONNPASS_DEFAULT_USER_ID` に設定できます。`search_schedule` ツールで `userId` を省略した場合に利用されます。
+## ツール一覧
 
-## トランスポート方式
+### イベント
 
-Connpass MCP Server は2つのトランスポート方式に対応しています。
+| ツール名 | 説明 | 主な入力 |
+|----------|------|----------|
+| `search_events` | キーワードや日付でイベントを検索し、会話用の結果と `searchSessionId` を返す | `query`, `from`, `to`, `prefectures`, `sort`, `includeDetails` |
+| `browse_events` | `search_events` の `searchSessionId` を使ってインタラクティブ UI を開く | `searchSessionId` |
+| `get_event_detail` | イベント ID を指定して詳細をフル取得 | `eventId` |
+| `get_event_presentations` | イベントの発表情報を取得 | `eventId` |
+| `search_schedule` | ユーザーのスケジュールを検索 | `userId`, `nickname`, `fromDate`, `toDate`, `includeDetails` |
 
-### HTTP (Streamable HTTP) - デフォルト
+### グループ
 
-デフォルトのトランスポート方式です。HTTPリクエスト/レスポンスベースで通信します。
+| ツール名 | 説明 | 主な入力 |
+|----------|------|----------|
+| `search_groups` | グループをキーワードや所在地で検索 | `query`, `country`, `prefecture`, `sort` |
 
-```bash
-# デフォルトで HTTP トランスポートを使用 (ポート 3000)
-connpass-mcp-server
+### ユーザー
 
-# ポートを指定
-connpass-mcp-server --port 8080
-connpass-mcp-server -p 8080
+| ツール名 | 説明 | 主な入力 |
+|----------|------|----------|
+| `search_users` | ニックネームなどでユーザーを検索 | `nickname`, `userIds`, `sort` |
+| `get_user_groups` | ユーザーが所属するグループ一覧 | `userId` |
+| `get_user_attended_events` | ユーザーが参加したイベント一覧 | `userId`, `includeDetails` |
+| `get_user_presenter_events` | ユーザーが登壇したイベント一覧 | `userId`, `includeDetails` |
 
-# 明示的に HTTP トランスポートを指定
-connpass-mcp-server --transport http
-connpass-mcp-server -t http
-```
+### その他
 
-### SSE (Server-Sent Events)
+| ツール名 | 説明 |
+|----------|------|
+| `list_prefectures` | 利用可能な都道府県コード一覧 |
 
-Server-Sent Events を使用した双方向通信です。
+### `includeDetails` パラメータ
 
-```bash
-# SSE トランスポートを使用
-connpass-mcp-server --transport sse
+`search_events`, `search_schedule`, `get_user_attended_events`, `get_user_presenter_events` では、`includeDetails: true` を指定するとイベントの説明文（200文字まで）が含まれます。AI がおすすめイベントを判断する際に有用です。
 
-# ポートを指定
-connpass-mcp-server --transport sse --port 8080
-connpass-mcp-server -t sse -p 8080
-```
+デフォルト (`false`) では、タイトル・キャッチフレーズ・日時・会場・参加者数・URL などの基本情報のみを返します。
 
-### コマンドラインオプション
+個別イベントの完全な説明文が必要な場合は `get_event_detail` を使用してください。
 
-```
-Usage: connpass-mcp-server [options]
-
-Options:
-  -t, --transport <type>  Transport type: http or sse (default: http)
-  -p, --port <number>     Port number for http/sse transports (default: 3000)
-  -h, --help             Show this help message
+## 使い方の例
 
-Examples:
-  connpass-mcp-server                           # Start with HTTP transport on port 3000
-  connpass-mcp-server --transport sse --port 8080  # Start with SSE transport on port 8080
-  connpass-mcp-server -t http -p 5000          # Start with HTTP transport on port 5000
-```
-
-> **注意:** `PORT` および `MCP_TRANSPORT` 環境変数を設定することでも、ポートやトランスポート方式を変更できます。コマンドライン引数よりも環境変数が優先されます。
-
-### 環境変数一覧
-
-| 変数名 | 説明 | 既定値 |
-| --- | --- | --- |
-| `CONNPASS_API_KEY` | Connpass API Key。未設定の場合は `dummy-key` が使われます（本番利用不可）。 | `dummy-key` |
-| `CONNPASS_DEFAULT_USER_ID` | `search_schedule` で `userId` を省略したときに使うユーザー ID。 | 未設定 |
-| `CONNPASS_INCLUDE_PRESENTATIONS_DEFAULT` | `search_schedule` の `includePresentations` の既定値。`true/false` や `1/0` などで指定。 | 未設定（false と同等） |
-| `CONNPASS_RATE_LIMIT_ENABLED` | API クライアントのレート制限キューを有効/無効化します。`false` にすると 1 秒間隔の待機をスキップします。 | `true` |
-| `CONNPASS_RATE_LIMIT_DELAY_MS` | レート制限キューが適用する待機時間（ミリ秒）。Connpass 既定は 1000 ミリ秒です。 | `1000` |
-| `CONNPASS_PRESENTATION_CACHE_ENABLED` | プレゼンテーション取得結果をディスクキャッシュするかどうか。 | `true` |
-| `CONNPASS_PRESENTATION_CACHE_TTL_MS` | キャッシュ保持期間（ミリ秒）。 | `3600000` |
-| `CONNPASS_PRESENTATION_CACHE_PATH` | キャッシュファイルの保存先パス。 | `./data/presentation-cache.json` |
-| `CONNPASS_ENABLE_APPS_SDK_OUTPUT` | Apps SDK 互換の `structuredContent` をツール応答に含めるかどうか。`true/false` や `1/0` などで指定。 | `false` |
-| `MCP_BASE_PATH` | MCP エンドポイントのベースパス。リバースプロキシで `/mcp` を `/` に転送する場合などに `/` を指定。(SSE トランスポートのみ) | `/mcp` |
-| `MCP_TRANSPORT` | トランスポート方式 (`http`, `sse`)。コマンドライン引数より優先されます。 | 未設定 |
-| `PORT` | サーバーのポート番号 (http, sse トランスポートのみ)。コマンドライン引数より優先されます。 | `3000` |
-
-## ツール一覧
-
-| ツール名 | 説明 | 主な入力フィールド |
-| --- | --- | --- |
-| `search_events` | 自然言語の日付やキーワードでイベントを検索 | `query`, `anyQuery`, `on`, `from`, `to`, `participantNickname`, `hostNickname`, `groupIds`, `prefectures`, `page`, `pageSize`, `sort` |
-| `get_event_presentations` | 指定イベントの発表情報を取得 | `eventId` |
-| `search_groups` | グループをキーワードや所在地で検索 | `query`, `groupIds`, `country`, `prefecture`, `page`, `pageSize`, `sort` |
-| `search_users` | ニックネームなどでユーザーを検索 | `nickname`, `userIds`, `page`, `pageSize`, `sort` |
-| `get_user_groups` | 指定ユーザーが所属するグループ一覧 | `userId`, `limit`, `page` |
-| `get_user_attended_events` | 指定ユーザーが参加したイベント一覧 | `userId`, `limit`, `page`, `sort` |
-| `get_user_presenter_events` | 指定ユーザーが登壇したイベント一覧 | `userId`, `limit`, `page`, `sort` |
-| `search_schedule` | ユーザーのスケジュール（今日と今後のイベント）を検索 | `userId`, `nickname`, `daysAhead`, `maxEvents`, `includePresentations` |
-
-## シンプルな使い方
-
-### イベント検索（例）
+### イベント検索
 
 ```json
 {
@@ -156,73 +100,52 @@ Examples:
     "from": "2025-11-01",
     "to": "2025-11-07",
     "prefectures": "東京都",
-    "sort": "start-date-asc"
+    "sort": "start-date-asc",
+    "includeDetails": true
   }
 }
 ```
 
-- 日付は `"2025-11-01"` のような YYYY-MM-DD 形式、または `"20251101"` のような YYYYMMDD 形式で指定します。
-- `prefectures` や `on` は単一文字列でも配列でも指定可能です。
-
-### グループ検索（例）
+### スケジュール検索
 
 ```json
 {
-  "name": "search_groups",
-  "arguments": {
-    "query": "AI",
-    "country": "JP",
-    "sort": "most-members"
-  }
-}
-```
-
-### ユーザーの登壇イベント取得（例）
-
-```json
-{
-  "name": "get_user_presenter_events",
+  "name": "search_schedule",
   "arguments": {
-    "userId": 123456,
-    "limit": 30,
-    "sort": "newly-added"
+    "nickname": "kajidog",
+    "fromDate": "2025-11-01",
+    "toDate": "2025-11-07"
   }
 }
 ```
 
-### スケジュール検索（例）
+### イベント詳細取得
 
 ```json
 {
-  "name": "search_schedule",
+  "name": "get_event_detail",
   "arguments": {
-    "nickname": "kajidog",
-    "daysAhead": 10,
-    "includePresentations": true
+    "eventId": 12345
   }
 }
 ```
 
-- `userId` を省略すると、`CONNPASS_DEFAULT_USER_ID` 環境変数が使われます。
-- `nickname` を指定すると、そのニックネームでユーザーを検索してイベントを取得します。`userId` と `nickname` の両方が指定された場合は `nickname` が優先されます。
-- `includePresentations` を有効にすると、各イベントの発表詳細を個別に取得します（ Connpass API は 1 秒あたり 1 リクエストのレートリミットなので、イベント数が多いと時間がかかります）。省略時は `CONNPASS_INCLUDE_PRESENTATIONS_DEFAULT` の設定が利用されます。
-
-## 返り値
-
+## 開発
 
-`CONNPASS_ENABLE_APPS_SDK_OUTPUT` を `true` にすると、MCP の `call_tool` 応答へ OpenAI Apps SDK が扱いやすい `structuredContent` を追加します。Apps SDK 側では `toolOutput` として同じペイロードが受け取れるため、カスタム UI でデータをレンダリングしやすくなります。既存のテキスト出力は変わりません。
+```bash
+# 依存関係をインストール
+pnpm install
 
-### Apps SDK 向けウィジェット
+# ビルド
+pnpm --filter @kajidog/connpass-mcp-server build
 
-- `search_events` の実行結果にはカルーセルウィジェット、`search_schedule` の実行結果にはスケジュールウィジェットが付与されます。どちらもフルスクリーン詳細に切り替え可能です。
-- `CONNPASS_ENABLE_APPS_SDK_OUTPUT=true` を指定すると、`openai/outputTemplate` メタデータが `ui://connpass/widgets/events-carousel` を指し、Apps SDK 側で iframe がレンダリングされます。
-- ウィジェットの HTML は `packages/mcp-server/src/widgets/connpass-events.html` に置いており、`pnpm --filter @kajidog/connpass-mcp-server build` 実行時に `dist/widgets/` へコピーされます。
-- カルーセルでは参加者数バッジや Connpass への外部リンクを表示。`詳細を見る` ボタンを押すと `requestDisplayMode` API で全画面表示に切り替わり、イベント概要・発表セッション・外部リンクを閲覧できます。
-- サーバーをサブパスで公開する場合は `MCP_BASE_PATH` を設定してください（例: リバースプロキシで `/mcp` を `/` にリライトする場合は `MCP_BASE_PATH=/`）。`GET ${MCP_BASE_PATH}` が SSE ストリーム、`${MCP_BASE_PATH}/messages` が POST エンドポイントになります。
+# 開発モード (stdio)
+pnpm --filter @kajidog/connpass-mcp-server dev
 
-## 開発補助
+# 開発モード (HTTP)
+pnpm --filter @kajidog/connpass-mcp-server dev:http
+```
 
-- 型チェック: `pnpm --filter @kajidog/connpass-mcp-server typecheck`
-- ウォッチビルド: `pnpm --filter @kajidog/connpass-mcp-server dev`
+## ライセンス
 
-ツールの追加や更新を行った際は、`pnpm build` 実行後に README も更新して最新の引数仕様を反映するようにしてください。
+MIT

package/dist/index.d.ts

@@ -1,3 +1 @@
 #!/usr/bin/env node
-export {};
-//# sourceMappingURL=index.d.ts.map