HumanSurvey

Infraestructura de recopilación de comentarios para agentes de IA.

HumanSurvey permite a un agente que realiza un trabajo a largo plazo recopilar comentarios estructurados de un grupo de personas:

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

¿Qué es esto?

HumanSurvey es una API mínima y un servidor MCP para una tarea específica: permitir que los agentes recopilen comentarios estructurados de grupos de humanos y obtengan resultados utilizables por máquinas.

Está diseñado para:

• Agentes de IA que gestionan eventos, lanzamientos de productos o flujos de trabajo comunitarios que necesitan encuestar a un grupo

• Desarrolladores que crean productos de agentes que necesitan una primitiva ligera de recopilación de comentarios

No está diseñado para:

• Paneles de control de encuestas

• Creadores de formularios visuales

• Bibliotecas de plantillas

• Campañas de correo electrónico

• Interfaz de usuario de análisis/informes

Características

• Entrada de esquema JSON: estructurada, precisa y generada directamente por la máquina

• Servidor MCP: cree encuestas y lea los resultados directamente desde Claude Code

• Superficie de API mínima: rutas de creador autenticadas, envío público de encuestados

• Cuatro tipos de preguntas semánticas: choice, text, scale, matrix

• Lógica condicional: showIf en Markdown y esquema JSON

• Ciclo de vida explícito: cierre de encuestas, caducidad y límites máximos de respuesta

Principios del producto

• Semántica sobre visual: HumanSurvey tiene un protocolo pequeño, no un zoológico de tipos de campo específicos de la interfaz de usuario.

• E/S centrada en la IA: los agentes escriben la encuesta y los agentes consumen los resultados; los humanos están en el medio.

• Todo es una API: la funcionalidad del creador debe estar disponible a través de HTTP autenticado y MCP.

• El alcance limitado gana: si una característica sirve principalmente a los operadores de encuestas humanos, probablemente no pertenezca aquí.

Tipos de preguntas admitidos

• single_choice

• multi_choice

• text

• scale

• matrix

Sintaxis de 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 |

Preguntas de escala:

**Q4. How severe is this issue?**

[scale 1-5 min-label="Low" max-label="Critical"]

Lógica condicional:

**Q1. Did the deploy fail?**

- ☐ Yes
- ☐ No

**Q2. Which step failed?**

> show if: Q1 = "Yes"

> _______________________________________________

Inicio rápido

Uso con Claude Code

Añadir a su configuración de Claude Code (~/.claude.json):

{
  "mcpServers": {
    "survey": {
      "command": "npx",
      "args": ["-y", "humansurvey-mcp"],
      "env": {
        "HUMANSURVEY_API_KEY": "hs_sk_your_key_here"
      }
    }
  }
}

Luego en Claude Code:

> Create a post-event feedback survey with a 1-5 rating, open text, and a yes/no question

Herramientas disponibles:

• create_survey: crear a partir de un esquema JSON; opcional max_responses, expires_at, webhook_url

• get_results: resultados agregados + respuestas sin procesar

• list_surveys: listar encuestas propiedad de su clave

• close_survey: cerrar una encuesta inmediatamente

Usar la API HTTP

curl -X POST https://www.humansurvey.co/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"my claude agent"}'

Luego cree una encuesta:

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?" }
        ]
      }]
    }
  }'

Respuesta:

{
  "survey_url": "/s/abc123",
  "question_count": 1
}

Leer resultados:

curl https://www.humansurvey.co/api/surveys/abc123/responses \
  -H "Authorization: Bearer hs_sk_..."

Superficie pública

• Página de documentación: https://www.humansurvey.co/docs

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

• Índice de IA: https://www.humansurvey.co/llms.txt

Pila tecnológica

Estructura del proyecto

├── apps/web/          # Next.js app (API + frontend)
├── packages/parser/   # Markdown → Survey JSON parser
├── packages/mcp-server/ # MCP server for Claude Code
└── docs/              # Architecture docs

Contribución

Lea CONTRIBUTING.md antes de abrir una solicitud de extracción (PR). La regla más importante es la disciplina de alcance: las nuevas variantes de interfaz de usuario, los paneles de análisis y las funciones de operador humano generalmente están fuera del alcance.

Desarrollo

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

Licencia

MIT