survey-mcp-server

Check session statusand completion eligibility.

- 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)
- canCompleteboolean indicating if session can be finalized
- completionBlockersarray explaining what's preventing completion

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

Finalize a completed sessionwhen all required questions have been answered.

- Validates that all required questions (including conditionally required) are answered
- Updates session status tocompletedand setscompletedAttimestamp
- Returns summary with total questions answered, session duration, and final score (if scoring enabled)
- Prevents duplicate completion

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

Export session datafor analysis and reporting.

- 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

- "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"

Resume an incomplete sessionwith full context restoration.

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

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

- Declarative Tools: Define capabilities in single, self-contained files. The framework handles registration, validation, and execution.
- Robust Error Handling: A unifiedMcpErrorsystem ensures consistent, structured error responses.
- Pluggable Authentication: Secure your server with zero-fuss support fornone,jwt, oroauthmodes.
- 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 withtsyringefor 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 forSurvey 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 skip logic and complexAND/ORmulti-condition branching with eligibility tracking.
- JSON-Based Survey Definitions: Define surveys in simple JSON files with recursive directory scanning.
- Multiple Question Types:free-form,multiple-choice,multiple-select,rating-scale,email,number,boolean, and advanced types likedate,datetime,time, andmatrixgrids.
- Validation Engine: Min/max length, patterns, required fields, custom constraints, and date/time rules with extensible validator map pattern.
- Session Resume: Built-in state management allows participants to pause and continue later.
- Help Text: AhelpTextfield on questions provides LLMs with context and guidance for asking questions naturally.
- Pagination Support: Scalable data retrieval with configurable pagination for session queries and exports.

Add the following to your MCP Client configuration file (e.g.,cline_mcp_settings.json).

All configuration is centralized and validated at startup insrc/config/index.ts. Key environment variables in your.envfile include:

# 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

For strict rules when using this server with an AI agent, refer to the.clinerulesfile (orAGENTS.md) in this repository. Key principles include:

- Logic Throws, Handlers Catch: Never usetry/catchin your toollogic. Throw anMcpErrorinstead.
- Pass the Context: Always pass theRequestContextobject through your call stack for logging and tracing.
- Use the Barrel Exports: Register new tools and resources only in theindex.tsbarrel files within their respectivedefinitionsdirectories.

Issues and pull requests are welcome! If you plan to contribute, please run the local checks and tests before submitting your PR.

Automated document processing and extraction

Great Question is an Agentic UX research platform for product builders. Its MCP lets AI agents create studies directly from any AI tool, surface insights, find the right research candidates, and query your entire research repository.

Create and edit Tally forms and analyze submissions

An MCP server for ActivityWatch, allowing interaction with your personal time tracking data.

AI2Fin | Intelligent Financial Management

Tools for expense tracking, tax deductions, bill management, and financial analysis.

Manage personal finances, track transactions, and create budgets with Budgetsco.

A simple calculator server for performing basic arithmetic operations.

Math evaluation, simplification, derivatives