HumanSurvey

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は、エージェントが人間グループから構造化されたフィードバックを収集し、機械で利用可能な結果を取得するという、1つの狭い目的のための最小限のAPIおよびMCPサーバーです。

以下のような用途向けに設計されています：

イベント管理、製品ローンチ、コミュニティワークフローを実行し、グループへのアンケートが必要なAIエージェント
軽量なフィードバック収集プリミティブを必要とするエージェント製品を構築する開発者

以下のような用途向けには設計されていません：

アンケートダッシュボード
ビジュアルフォームビルダー
テンプレートライブラリ
メールキャンペーン
分析/レポートUI

特徴

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_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"}'

次に、アンケートを作成します：

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

humansurvey-mcp