HumanSurvey

Инфраструктура для сбора обратной связи для ИИ-агентов.

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-сервер для одной узкой задачи: позволить агентам собирать структурированную обратную связь от групп людей и получать результаты, пригодные для машинной обработки.

Он предназначен для:

ИИ-агентов, управляющих мероприятиями, запусками продуктов или рабочими процессами сообществ, которым необходимо провести опрос группы
Разработчиков, создающих агентские продукты, которым нужен легковесный примитив для сбора обратной связи

Он не предназначен для:

панелей управления опросами
визуальных конструкторов форм
библиотек шаблонов
email-рассылок
пользовательских интерфейсов для аналитики/отчетности

Возможности

Ввод JSON-схемы — структурированный, точный и создаваемый непосредственно машиной
MCP-сервер — создание опросов и чтение результатов напрямую из Claude Code
Минималистичный API — аутентифицированные маршруты для создателя, публичная отправка ответов респондентами
Четыре семантических типа вопросов — choice, text, scale, matrix
Условная логика — showIf в Markdown и JSON-схеме
Явный жизненный цикл — закрытие опросов, срок действия и лимиты на количество ответов

Принципы продукта

Семантика важнее визуализации: HumanSurvey имеет небольшой протокол, а не зоопарк специфичных для UI типов полей.
ИИ-ориентированный ввод-вывод: агенты пишут опрос, а агенты потребляют результаты; люди находятся посередине.
Все есть 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
ИИ-индекс: https://www.humansurvey.co/llms.txt

Технологический стек

Компонент	Технология
Фреймворк	Next.js (App Router)
База данных	Neon (serverless 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

Участие в разработке

Прочитайте CONTRIBUTING.md перед открытием PR. Самое важное правило — дисциплина области применения: новые варианты UI, аналитические панели и функции для операторов-людей обычно выходят за рамки проекта.

Разработка

pnpm install
pnpm dev              # Start Next.js dev server
pnpm --filter @mts/parser test
pnpm build            # Build all packages

Лицензия

MIT

humansurvey-mcp