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는 단 하나의 좁은 작업을 위한 최소한의 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 |

척도(Scale) 질문:

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