survey-mcp-server

---

🛠️ Tools Overview

This server provides eight powerful tools for managing the complete survey lifecycle with LLM-driven interactions:

Tool Name	Description
survey_list_available	Discover available surveys in the definitions directory.
survey_start_session	Initialize a new session with complete survey context, all questions, and initial suggested questions.
survey_get_question	Refresh a specific question's eligibility status after state changes (useful for conditional logic).
survey_submit_response	Record participant answers with validation, scoring, returning updated progress and next suggested questions.
survey_get_progress	Check completion status, current score, remaining required/optional questions, and completion eligibility.
survey_complete_session	Finalize a completed session with final score summary (requires all required questions answered).
survey_export_results	Export session data in CSV or JSON format with optional filtering by status, date range, etc.
survey_resume_session	Resume an incomplete session, restoring full context including answered questions and progress.

survey_list_available

Discover available surveys loaded from your survey definitions directory.

Key Features:

• Lists all surveys discovered via recursive directory scan of SURVEY_DEFINITIONS_PATH
• Returns survey metadata: ID, title, description, estimated duration, and question count
• Optional tenant filtering for multi-tenant deployments

Example Use Cases:

• "Show me all available surveys"
• "What surveys can participants take?"
• "List surveys for tenant X"

---

survey_start_session

Initialize a new survey session with complete context for LLM-driven conversations.

Key Features:

• Creates new session with unique session ID and participant tracking
• Loads complete survey definition with all questions upfront
• Returns initial suggested questions based on survey settings (configurable min/max, defaults to 3-5) based on eligibility (unconditional questions first, required before optional)
• Each question includes currentlyEligible flag and eligibilityReason for transparency
• Provides guidanceForLLM field with conversational instructions
• Supports session metadata for tracking source, user agent, etc.

Example Use Cases:

• "Start the customer satisfaction survey for participant ABC123"
• "Begin a new session for the Q1 feedback survey"
• "Initialize survey session with metadata: source=web, userAgent=Claude"

---

survey_get_question

Refresh a question's eligibility and details after session state changes.

Key Features:

• Returns current eligibility status based on latest session state
• Provides eligibility reason (e.g., "Conditional logic satisfied", "Always available")
• Indicates if question was already answered
• Useful for checking if conditional questions became available after previous answers

Example Use Cases:

• "Has question q2 become available yet?"
• "Check if the follow-up question is now eligible"
• "Refresh question details after the participant answered the dependency"

---

survey_submit_response

Record participant answers with validation and get dynamic response guidance.

Key Features:

• Validates responses against question constraints (min/max length, patterns, required fields, etc.)
• Calculates and returns score for response (if scoring is enabled on question options)
• Returns validation errors with specific, actionable feedback
• Updates session progress (percentage complete, questions answered, time remaining estimate, current score)
• Returns updatedEligibility array showing newly available conditional questions
• Provides refreshed nextSuggestedQuestions based on new state (count configurable per survey)
• Includes guidanceForLLM with context-aware instructions

Example Use Cases:

• "Submit answer 'very-satisfied' for question q1"
• "Record the participant's email: user@example.com"
• "Save free-form response with validation"

---

survey_get_progress

Check session status and completion eligibility.

Key Features:

• Returns completion status: in-progress, completed, abandoned
• Progress metrics: total questions, answered count, required remaining, percentage complete, current score
• Lists all unanswered required questions (with eligibility status)
• Lists all unanswered optional questions (with eligibility status)
• canComplete boolean indicating if session can be finalized
• completionBlockers array explaining what's preventing completion

Example Use Cases:

• "How much of the survey is complete?"
• "What required questions are still unanswered?"
• "Can we complete the survey now?"

---

survey_complete_session

Finalize a completed session when all required questions have been answered.

Key Features:

• Validates that all required questions (including conditionally required) are answered
• Updates session status to completed and sets completedAt timestamp
• Returns summary with total questions answered, session duration, and final score (if scoring enabled)
• Prevents duplicate completion

Example Use Cases:

• "Complete the survey session"
• "Finalize session sess_abc123"
• "Mark the survey as finished"

---

survey_export_results

Export session data for analysis and reporting.

Key Features:

• Export in CSV or JSON format
• Filter by survey ID, status, date range, and custom criteria
• Returns formatted data with record count and generation timestamp
• CSV format includes one row per session with flattened question responses
• JSON format preserves full session structure

Example Use Cases:

• "Export all completed responses for survey customer-satisfaction-q1-2025 as CSV"
• "Get JSON export of sessions completed in January 2025"
• "Export in-progress sessions for analysis"

---

survey_resume_session

Resume an incomplete session with full context restoration.

Key Features:

• Restores complete survey context and session state
• Returns all previously answered questions with responses
• Provides refreshed nextSuggestedQuestions for remaining questions (count configurable per survey)
• Shows elapsed time since last activity
• Current progress summary (percentage, remaining questions, current score)
• Includes guidanceForLLM with welcome-back messaging suggestions

Example Use Cases:

• "Resume session sess_abc123"
• "Continue the survey where the participant left off"
• "Restore session state for participant to finish later"

✨ Features

This server is built on the mcp-ts-template and inherits its rich feature set:

• Declarative Tools: Define capabilities in single, self-contained files. The framework handles registration, validation, and execution.
• Robust Error Handling: A unified McpError system ensures consistent, structured error responses.
• Pluggable Authentication: Secure your server with zero-fuss support for none, jwt, or oauth modes.
• Abstracted Storage: Swap storage backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) without changing business logic.
• Full-Stack Observability: Deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
• Dependency Injection: Built with tsyringe for a clean, decoupled, and testable architecture.
• Edge-Ready: Write code once and run it seamlessly on your local machine or at the edge on Cloudflare Workers.

Plus, specialized features for Survey Management:

• LLM-Driven Surveys: Tools provide rich context (progress, next suggested questions, validation results, scores) to guide natural conversation flow.
• Hybrid Flow Control: Guided mode with configurable suggested questions (defaults to 3-5) + flexible ordering based on conversation context.
• Scoring System: Support for quizzes and assessments with optional score fields on question options. Automatic score calculation and accumulation per session.
• Advanced Conditional Logic: Support for simple sk

---

README truncated. View full README on GitHub.