Summary
The model conducts the interview; the server keeps the state.
Each response comes back with the questions that just became eligible and refreshed suggestions, so conditional branches appear at the right moment without the model tracking them itself. Sessions resume with everything restored, which is what lets a long survey survive a dropped conversation.
What it is
A TypeScript server that owns the survey lifecycle. It loads survey definitions from a directory, tracks each session's state, and tells the model which questions are currently eligible and why.
What you get
- Eight tools covering the whole lifecycle
- Surveys discovered from the definitions directory with id, title, description, estimated duration and question count — survey_list_available
- A session started with the full survey loaded up front, initial suggested questions, and conversational guidance for the model — survey_start_session
- A question's eligibility refreshed after the state changes, with the reason attached — survey_get_question
- An answer validated against the question's constraints, scored, and returned with updated progress and newly eligible questions — survey_submit_response
- Completion status, current score, and remaining required and optional questions — survey_get_progress
- A finished session finalised with a score summary, and results exported as CSV or JSON with filters — survey_complete_session, survey_export_results
- An incomplete session resumed with its full context restored — survey_resume_session
- Skip logic, multi-tenant filtering and pluggable storage backends
Requirements
Bun v1.3.0 or higher, or Node.js. SURVEY_DEFINITIONS_PATH points at the directory the server scans recursively for survey definitions.
Setup effort
One command — bunx @cyanheads/survey-mcp-server@latest