Skip to main content
Glama
humansurvey-mcp

humansurvey-mcp

by sunsiyuan

HumanSurvey

ウェブサイト: humansurvey.co · ドキュメント: humansurvey.co/docs · FAQ: humansurvey.co/faq

human-survey MCP server

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サーフェス — 認証された作成者ルート、公開回答者送信

  • 4つのセマンティックな質問タイプ — 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_url を指定可能

  • get_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/docs

  • OpenAPI: https://www.humansurvey.co/api/openapi.json

  • AIインデックス: 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 tools
close_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

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a distinct, non-overlapping purpose: creating API keys, creating surveys, listing surveys, retrieving results, and closing surveys. No ambiguity.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Collects 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.
      1
      9 npm
      2
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      13
      7
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Real 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.
      7
      47 npm
      MIT