humansurvey-mcp
HumanSurvey
网站: humansurvey.co · 文档: humansurvey.co/docs · 常见问题: humansurvey.co/faq
为 AI 智能体提供的反馈收集基础设施。
HumanSurvey 让执行长期任务的智能体能够从人群中收集结构化反馈:
Agent is doing a job
→ needs structured feedback from a group
→ creates survey from JSON schema
→ shares /s/{id} URL with respondents
→ humans respond over hours or days
→ agent retrieves structured JSON results and acts on them这是什么?
HumanSurvey 是一个极简的 API 和 MCP 服务器,专注于单一任务:让智能体从人类群体中收集结构化反馈,并获取机器可用的结果。
它专为以下场景设计:
运行活动管理、产品发布或社区工作流的 AI 智能体,需要对群体进行调查
构建智能体产品的开发者,需要轻量级的反馈收集原语
它不适用于:
调查仪表板
可视化表单构建器
模板库
电子邮件营销活动
分析/报告 UI
Related MCP server: Datapoint MCP
功能特性
JSON 模式输入 — 结构化、精确,且可直接由机器生成
MCP 服务器 — 直接从 Claude Code 创建调查并读取结果
极简 API 接口 — 经过身份验证的创建者路由,公开的受访者提交
四种语义问题类型 —
choice(选择)、text(文本)、scale(量表)、matrix(矩阵)条件逻辑 — Markdown 和 JSON 模式中的
showIf明确的生命周期 — 关闭调查、过期设置和最大响应限制
产品原则
语义优先于视觉:HumanSurvey 拥有一个小型的协议,而不是一堆特定于 UI 的字段类型。
AI 优先的 I/O:智能体编写调查,智能体消费结果;人类处于中间环节。
一切皆 API:创建者功能必须通过经过身份验证的 HTTP 和 MCP 提供。
窄范围胜出:如果某个功能主要服务于人类调查操作员,那么它可能不属于这里。
支持的问题类型
single_choice(单选)multi_choice(多选)text(文本)scale(量表)matrix(矩阵)
Markdown 语法
# Survey Title
**Description:** Instructions for the respondent.
## Section Name
**Q1. Your question here?**
- ☐ Option A
- ☐ Option B
- ☐ Option C
**Q2. Multi-select question?** (select all that apply)
- ☐ Choice 1
- ☐ Choice 2
- ☐ Choice 3
**Q3. Open-ended question:**
> _______________
| # | Item | Rating |
|---|------|--------|
| 1 | Item A | ☐Good ☐OK ☐Bad |
| 2 | Item B | ☐Good ☐OK ☐Bad |量表问题:
**Q4. How severe is this issue?**
[scale 1-5 min-label="Low" max-label="Critical"]条件逻辑:
**Q1. Did the deploy fail?**
- ☐ Yes
- ☐ No
**Q2. Which step failed?**
> show if: Q1 = "Yes"
> _______________________________________________快速入门
在 Claude Code 中使用
添加到你的 Claude Code 配置 (~/.claude.json) 中:
{
"mcpServers": {
"survey": {
"command": "npx",
"args": ["-y", "humansurvey-mcp"],
"env": {
"HUMANSURVEY_API_KEY": "hs_sk_your_key_here"
}
}
}
}然后在 Claude Code 中:
> Create a post-event feedback survey with a 1-5 rating, open text, and a yes/no question可用工具:
create_key— 自行配置 API 密钥;无需人工设置create_survey— 从 JSON 模式创建;可选max_responses、expires_at、webhook_urlget_results— 汇总结果 + 原始响应list_surveys— 列出你的密钥拥有的调查close_survey— 立即关闭调查
使用 HTTP API
curl -X POST https://www.humansurvey.co/api/keys \
-H "Content-Type: application/json" \
-d '{
"name": "my claude agent",
"email": "you@example.com",
"wallet_address": "eip155:8453:0xabc..."
}'所有字段均为可选。wallet_address 使用 CAIP-10 格式 — 未来将用于智能体原生支付。
然后创建一个调查:
curl -X POST https://www.humansurvey.co/api/surveys \
-H "Authorization: Bearer hs_sk_..." \
-H "Content-Type: application/json" \
-d '{
"schema": {
"title": "Post-Event Feedback",
"sections": [{
"questions": [
{ "type": "scale", "label": "How would you rate the event?", "min": 1, "max": 5 },
{ "type": "text", "label": "What should we improve?" }
]
}]
}
}'响应:
{
"survey_url": "/s/abc123",
"question_count": 1
}读取结果:
curl https://www.humansurvey.co/api/surveys/abc123/responses \
-H "Authorization: Bearer hs_sk_..."公开资源
文档页面:
https://www.humansurvey.co/docsOpenAPI:
https://www.humansurvey.co/api/openapi.jsonAI 索引:
https://www.humansurvey.co/llms.txt
技术栈
组件 | 技术 |
框架 | Next.js (App Router) |
数据库 | Neon (无服务器 Postgres) |
解析器 | remark (unified 生态系统) |
前端 | React + Tailwind CSS |
MCP 服务器 | @modelcontextprotocol/sdk |
部署 | Vercel |
项目结构
├── apps/web/ # Next.js app (API + frontend)
├── packages/parser/ # Markdown → Survey JSON parser
├── packages/mcp-server/ # MCP server for Claude Code
└── docs/ # Architecture docs贡献
在提交 PR 之前,请阅读 CONTRIBUTING.md。最重要的规则是保持范围克制:新的 UI 变体、分析仪表板和人类操作员功能通常不在本项目的范围内。
开发
pnpm install
pnpm dev # Start Next.js dev server
pnpm --filter @mts/parser test
pnpm build # Build all packages许可证
MIT
Available Tools
5 toolsclose_surveyClose SurveyA
Permanently close a survey so it no longer accepts new responses. Use this when you have enough responses or the data collection window has passed. Returns the final response count. Closing is irreversible via MCP — use PATCH /api/surveys/{id} to re-open.
Inputs: survey_id (required).
create_keyCreate API KeyA
Create a new HumanSurvey API key. Call this before any other tool if HUMANSURVEY_API_KEY is not set. Returns a key — store it as HUMANSURVEY_API_KEY in your MCP config. The key cannot be retrieved again after creation.
Inputs: name, email, wallet_address.
create_surveyCreate SurveyA
Use this when an agent task involves collecting structured feedback or data from a group of people. Common cases: post-event attendee feedback, product satisfaction after a launch, team health checks, customer ratings after support resolution. The schema parameter is fully typed — follow the field types rather than guessing. Returns a survey_url to share with respondents and a survey_id to pass to get_results later. The survey accepts responses immediately and stays open until you close it or it expires. Embedding: append "?embed=1" to the returned survey_url to render inside an on any host site (onboarding/lead-capture flows). The embedded form posts events to window.parent with source: "humansurvey" — type "loaded", "resize" (with height), and "submitted" (with responseId and answers). See https://www.humansurvey.co/llms.txt for the full embed contract.
Inputs: schema (required), max_responses, expires_at, webhook_url.
get_resultsGet ResultsA
Retrieve aggregated results for a survey. Shows survey status (open/closed), total response count, and per-question results: choice tallies with percentages, scale mean/median/distribution, and recent text responses. If the survey is still open, call again later to check for new responses — the output will tell you. Use close_survey when you have enough responses.
Inputs: survey_id (required).
list_surveysList SurveysA
List all surveys created with the current API key, ordered newest first. Use this to find a survey_id you need for get_results or close_survey, or to check which surveys are still open.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct, non-overlapping purpose: creating API keys, creating surveys, listing surveys, retrieving results, and closing surveys. No ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (create_key, create_survey, list_surveys, get_results, close_survey), making them predictable and easy to distinguish.
With 5 tools, the server is well-scoped for managing surveys. Each tool serves a necessary function without unnecessary bloat, fitting within the ideal range of 3-15 tools.
Covers core survey lifecycle (create, list, results, close) but lacks update and delete operations. While re-opening is possible via API, it's not exposed as a tool, creating a notable gap.
Maintenance
Related MCP Connectors
Create forms, share the link and read responses as JSON or CSV from your AI agent.
Create surveys, feedback and classification campaigns. Collect human answers and export results.
AI-native survey & form builder. Manage surveys, responses, analytics, and webhooks.
Ask people questions, get approvals and keep team decisions, from any AI agent.
Related MCP Servers
- AlicenseBqualityDmaintenanceCollects user feedback with text and image support through an Electron app, allowing AI tools to gather and process user input with customizable prompts and multiple response options.19 npm2Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to recruit real humans for evaluation tasks like surveys, A/B tests, and ratings on text, images, audio, and video, returning aggregated results directly into the conversation.137MIT
- AlicenseAqualityBmaintenanceFeedback ingestion for AI agents. Record your screen and talk; your agent does the rest — files the bugs, writes the spec, builds the backlog.997 PyPI35MIT
- AlicenseAqualityCmaintenanceReal human judgment as agent tools -- an AI agent can ask a question and get back a structured, schema-validated JSON answer from a real quality-scored human. 16 response types (yes/no, ratings, rankings, A/B tests, sentiment, image/video/audio review, voice/video/photo capture). Fully programmatic signup with a $5 free trial credit, no card required.747 npmMIT