survey-mcp-server

---

🛠️ ツールの概要

このサーバーは、LLM 主導の対話を通じてアンケートのライフサイクル全体を管理する、強力な 8 つのツールを提供します。

ツール名	説明
survey_list_available	定義ディレクトリにある利用可能なアンケートを検索します。
survey_start_session	アンケートの全コンテキスト、すべての質問、最初の推奨質問を含む新しいセッションを初期化します。
survey_get_question	状態変更後に、特定の質問の回答可否を更新します（条件分岐ロジックに便利です）。
survey_submit_response	回答者の回答を検証・採点して記録し、更新された進捗状況と次の推奨質問を返します。
survey_get_progress	完了状況、現在のスコア、残りの必須・任意の質問、完了可能かどうかを確認します。
survey_complete_session	最終スコアの概要とともに完了済みセッションを確定します（すべての必須質問への回答が必要です）。
survey_export_results	ステータスや期間などで絞り込んで、セッションデータを CSV または JSON 形式でエクスポートします。
survey_resume_session	未完了のセッションを再開し、回答済みの質問や進捗状況を含む完全なコンテキストを復元します。

survey_list_available

アンケート定義ディレクトリから読み込まれた利用可能なアンケートを検索します。

主な機能：

• SURVEY_DEFINITIONS_PATH を再帰的にディレクトリ走査し、検出されたすべてのアンケートを一覧表示します
• ID、タイトル、説明、推定所要時間、質問数などのアンケートメタデータを返します
• マルチテナント環境向けに、テナントで絞り込めます

使用例：

• 「利用可能なアンケートをすべて表示して」
• 「回答者が受けられるアンケートは何ですか？」
• 「テナント X のアンケートを一覧表示して」

---

survey_start_session

LLM 主導の会話に必要なコンテキストをすべて含めて、新しいアンケートセッションを初期化します。

主な機能：

• 一意のセッション ID と参加者の追跡情報を含む新しいセッションを作成します
• すべての質問をあらかじめ含むアンケート定義全体を読み込みます
• アンケートの設定に基づいて、最初に提案する質問を返します（最小数と最大数を設定可能。デフォルトは 3～5 問）。対象条件に基づき、無条件の質問を優先し、必須の質問を任意の質問より先に提示します
• 各質問には、透明性を確保するために currentlyEligible フラグと eligibilityReason が含まれます
• 会話の進め方を指示する guidanceForLLM フィールドを提供します
• 追跡元やユーザーエージェントなどのセッションメタデータをサポートします

使用例：

• 「参加者 ABC123 の顧客満足度アンケートを開始して」
• 「第 1 四半期のフィードバックアンケートの新しいセッションを開始して」
• 「メタデータ（source=web、userAgent=Claude）を指定してアンケートセッションを初期化して」

---

survey_get_question

セッションの状態が変わった後に、質問の対象条件と詳細を更新します。

主な機能：

• 最新のセッション状態に基づく現在の対象条件を返します
• 対象条件の理由（例：「条件付きロジックを満たしています」「常に利用可能です」）を提示します
• 質問にすでに回答済みかどうかを示します
• 前の回答によって条件付きの質問が利用可能になったかを確認するのに役立ちます

使用例：

• 「質問 q2 はもう回答できるようになった？」
• 「追加質問が対象になったか確認して」
• 「参加者が依存する質問に回答した後、質問の詳細を更新して」

---

survey_submit_response

参加者の回答を検証しながら記録し、動的な回答ガイダンスを取得します。

主な機能：

• 質問の制約（最小／最大文字数、パターン、必須項目など）に照らして回答を検証します
• 質問のオプションで採点が有効になっている場合、回答のスコアを計算して返します
• 具体的で実行可能なフィードバックとともに検証エラーを返します
• セッションの進捗状況（完了率、回答済みの質問数、残り時間の推定値、現在のスコア）を更新します
• 新たに回答可能になった条件付き質問を示す updatedEligibility 配列を返します
• 新しい状態に基づいて更新された nextSuggestedQuestions を返します（件数はアンケートごとに設定可能）
• コンテキストに応じた指示を含む guidanceForLLM を提供します

使用例：

• 「質問 q1 の回答として 'very-satisfied' を送信して」
• 「参加者のメールアドレス [email protected] を記録して」
• 「自由形式の回答を検証して保存して」

---

survey_get_progress

セッションの状態と完了可能かどうかを確認します。

主な機能：

• 完了状態（in-progress、completed、abandoned）を返します
• 進捗指標（質問の総数、回答済みの数、残っている必須質問の数、完了率、現在のスコア）を返します
• 未回答の必須質問をすべて（対象状況とともに）一覧表示します
• 未回答の任意の質問をすべて（対象状況とともに）一覧表示します
• セッションを確定できるかどうかを示す canComplete の真偽値を返します
• 完了を妨げている理由を説明する completionBlockers 配列を返します

使用例：

• 「アンケートはどのくらい完了している？」
• 「未回答の必須質問は何？」
• 「今すぐアンケートを完了できる？」

---

survey_complete_session

必須の質問にすべて回答済みの場合、完了したセッションを確定します。

主な機能：

• 条件付きで必須となる質問も含め、必須の質問にすべて回答済みであることを検証します
• セッションの状態を completed に更新し、completedAt タイムスタンプを設定します
• 回答した質問の総数、セッションの所要時間、最終スコア（採点が有効な場合）を含む概要を返します
• 重複した完了処理を防止します

使用例：

• 「アンケートセッションを完了して」
• 「セッション sess_abc123 を確定して」
• 「アンケートを終了済みにして」

---

survey_export_results

分析とレポート作成のためにセッションデータをエクスポートします。

主な機能：

• CSV または JSON 形式でエクスポートします
• アンケート ID、ステータス、日付範囲、カスタム条件でフィルタリングします
• レコード数と生成タイムスタンプを含む、整形済みのデータを返します
• CSV 形式には、質問への回答をフラット化した、セッションごとの 1 行が含まれます
• JSON 形式では、セッションの完全な構造が保持されます

使用例：

• 「アンケート customer-satisfaction-q1-2025 の完了済み回答をすべて CSV でエクスポートして」
• 「2025 年 1 月に完了したセッションの JSON エクスポートを取得して」
• 「分析のために進行中のセッションをエクスポートして」

---

survey_resume_session

中断したセッションを再開し、コンテキストを完全に復元します。

主な機能：

• アンケートの完全なコンテキストとセッション状態を復元します
• 回答済みの質問と回答をすべて返します
• 残りの質問に対する更新済みの nextSuggestedQuestions を提示します（件数はアンケートごとに設定可能）
• 前回のアクティビティからの経過時間を表示します
• 現在の進捗の概要を表示します（割合、残りの質問数、現在のスコア）
• 再開時のメッセージ案を含む guidanceForLLM を含みます

使用例：

• 「セッション sess_abc123 を再開して」
• 「参加者が中断したところからアンケートを続けて」
• 「参加者が後で完了できるようにセッション状態を復元して」

✨ 機能

このサーバーは mcp-ts-template を基盤としており、その豊富な機能を継承しています。

• 宣言的なツール：自己完結型の単一ファイルで機能を定義できます。フレームワークが登録、検証、実行を処理します。
• 堅牢なエラー処理：統一された McpError システムにより、一貫性のある構造化されたエラーレスポンスを実現します。
• プラグイン可能な認証：none、jwt、oauth の各モードを手軽に利用し、サーバーを保護できます。
• 抽象化されたストレージ：ビジネスロジックを変更せずに、ストレージバックエンド（in-memory、filesystem、Supabase、Cloudflare KV/R2）を切り替えられます。
• フルスタックの可観測性：構造化ログ（Pino）と、任意で利用できる自動計装対応の OpenTelemetry により、トレースとメトリクスを詳細に把握できます。
• 依存性注入：tsyringe を使用し、クリーンで疎結合かつテストしやすいアーキテクチャを実現します。
• エッジ対応：一度書いたコードを、ローカルマシンでも Cloudflare Workers のエッジでもシームレスに実行できます。

さらに、アンケート管理向けの専用機能も備えています。

• LLM 主導のアンケート：ツールが豊富なコンテキスト（進捗、次に推奨される質問、検証結果、スコア）を提供し、自然な会話の流れを導きます。
• ハイブリッドなフロー制御：設定可能な推奨質問（デフォルトは 3～5 件）を使うガイドモードと、会話のコンテキストに基づく柔軟な順序設定を組み合わせます。
• スコアリングシステム：質問の選択肢に任意のスコアフィールドを設定し、クイズや評価に対応します。セッションごとにスコアを自動計算し、累積します。
• 高度な条件ロジック：単純なスキップロジックに加え、AND／OR による複雑な複数条件分岐と、回答資格の追跡に対応します。
• JSON ベースのアンケート定義：シンプルな JSON ファイルでアンケートを定義でき、再帰的なディレクトリスキャンにも対応します。
• 複数の質問タイプ：free-form、multiple-choice、multiple-select、rating-scale、email、number、boolean のほか、date、datetime、time、matrix グリッドなどの高度なタイプにも対応します。
• 検証エンジン：最小／最大文字数、パターン、必須フィールド、カスタム制約、日付／時刻のルールに対応し、拡張可能なバリデーターマップパターンを備えています。
• セッション再開：組み込みの状態管理により、参加者はアンケートを一時停止し、後で続行できます。
• ヘルプテキスト：質問の helpText フィールドで、LLM に質問を自然に尋ねるためのコンテキストとガイダンスを提供します。
• ページネーション対応：セッションのクエリとエクスポートに設定可能なページネーションを用意し、スケーラブルなデータ取得を実現します。

🚀 はじめに

MCP クライアントの設定／構成

以下を MCP クライアントの設定ファイル（例：cline_mcp_settings.json）に追加します。

{
  "mcpServers": {
    "survey-mcp-server": {
      "command": "bunx",
      "args": ["@cyanheads/survey-mcp-server@latest"],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "SURVEY_DEFINITIONS_PATH": "./survey-definitions",
        "SURVEY_RESPONSES_PATH": "./survey-responses"
      }
    }
  }
}

前提条件

• Bun v1.2.0 以上。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/survey-mcp-server.git

2. ディレクトリに移動します：

cd survey-mcp-server

3. 依存関係をインストールします：

bun install

4. アンケートの例を確認します： survey-definitions/ ディレクトリには、さまざまな質問形式や機能を示す JSON ファイルの例が含まれています。これらを独自のアンケートを作成する際の出発点としてご利用ください。

🛠️ 主な機能：アンケートツール

このサーバーは、構造化されたデータ収集を維持しながら、動的で対話形式のアンケートを実施するための専用ツールを AI エージェントに提供します。

対話フローの例

1. LLM calls survey_start_session
   → Receives full survey context, all questions, and first 3-5 suggested questions

2. LLM asks questions naturally in conversation
   → Follows suggestions but can adapt order based on context
   → Uses natural language while ensuring survey questions are covered

3. For each answer, LLM calls survey_submit_response
   → Receives validation feedback (re-prompts if needed)
   → Gets score for response (if scoring enabled): "+5 points (Total: 45)"
   → Gets progress update (50% complete, 2 of 4 questions answered)
   → Refreshed suggestions with newly eligible conditional questions

4. LLM can check survey_get_progress anytime
   → Knows exactly what's required vs optional
   → Understands what remains before completion is possible

5. When all required questions answered, LLM calls survey_complete_session
   → Session finalized with timestamp, summary, and final score
   → Ready for export via survey_export_results

📖 詳細な仕様と例を見る →

⚙️ 設定

すべての設定は src/config/index.ts に集約されており、起動時に検証されます。.env ファイルで指定する主な環境変数は次のとおりです。

変数	説明	デフォルト
SURVEY_DEFINITIONS_PATH	アンケート JSON ファイルを含むディレクトリのパス（再帰的にスキャン）。	./survey-definitions
SURVEY_RESPONSES_PATH	セッションの回答を保存するディレクトリのパス（ファイルシステムモード）。	./survey-responses
MCP_TRANSPORT_TYPE	使用するトランスポート：stdio または http。	http
MCP_HTTP_PORT	HTTP サーバーのポート。	3019
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv、r2。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にするには true に設定します。	false
LOG_LEVEL	ログの最小レベル（debug、info、warn、error）。	info
MCP_AUTH_SECRET_KEY	jwt 認証で必須です。 32 文字以上のシークレットキー。	(none)
OAUTH_ISSUER_URL	oauth 認証で必須です。 OIDC プロバイダーの URL。	(none)

▶️ サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行します：

  # One-time build
  bun rebuild
  
  # Run the built server
  bun start:http
  # or
  bun start:stdio
  

• チェックとテストを実行します：

  bun devcheck # Lints, formats, type-checks, and more
  bun test # Runs the test suite
  

Cloudflare Workers

1. Worker バンドルをビルドします：

bun build:worker

2. Wrangler でローカル実行します：

bun deploy:dev

3. Cloudflare にデプロイします：

   bun deploy:prod
   

📂 プロジェクト構成

ディレクトリ	目的と内容
survey-definitions/	アンケート定義（JSON ファイル）。整理しやすいよう、ネストしたディレクトリにも対応しています。
survey-responses/	セッションの回答（filesystem プロバイダーを使用する場合）。テナント ID ごとに整理されます。
src/mcp-server/tools	アンケートツールの定義（survey-*.tool.ts）。ライフサイクル全体に対応する 8 つのツールがあります。
src/mcp-server/resources	アンケートのメタデータと検出用のリソース定義。
src/services/survey/	定義の読み込みに使用するファイルシステムプロバイダーを備えたアンケートサービス。
src/mcp-server/transports	認証ミドルウェアを含む、HTTP および STDIO トランスポートの実装。
src/storage	StorageService の抽象化と、すべてのストレージプロバイダーの実装。
src/container	依存性注入コンテナーの登録とトークン。
src/utils	ロギング、エラー処理、パフォーマンス、セキュリティのためのコアユーティリティ。
src/config	Zod を使用した環境変数の解析と検証。
tests/	src/ のディレクトリ構成を反映した単体テストと統合テスト。
docs/	詳細な仕様とガイド（survey-mcp-server-spec.md を参照）。

🧑‍💻 エージェント開発ガイド

このサーバーを AI エージェントと使用する際の厳格なルールについては、このリポジトリの .clinerules ファイル（または AGENTS.md）を参照してください。主な原則は次のとおりです。

• ロジックでスローし、ハンドラーでキャッチする：ツールの logic 内で try/catch を使用しないでください。代わりに McpError をスローしてください。
• コンテキストを渡す：ロギングとトレーシングのために、呼び出しスタックを通じて RequestContext オブジェクトを常に渡してください。
• バレルエクスポートを使用する：新しいツールとリソースは、それぞれの definitions ディレクトリ内にある index.ts のバレルファイルにのみ登録してください。

🤝 貢献

Issue とプルリクエストを歓迎します！貢献する場合は、PR を提出する前にローカルチェックとテストを実行してください。

bun run devcheck
bun test

📜 ライセンス

このプロジェクトは Apache 2.0 License のもとでライセンスされています。詳細については、LICENSE ファイルを参照してください。