HumanSurvey

Infrastruktur zur Feedback-Sammlung für KI-Agenten.

HumanSurvey ermöglicht es einem Agenten, der langfristige Aufgaben ausführt, strukturiertes Feedback von einer Gruppe von Menschen einzuholen:

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

Was ist das?

HumanSurvey ist eine minimale API und ein MCP-Server für eine spezifische Aufgabe: Agenten sollen strukturiertes Feedback von Gruppen von Menschen einholen und maschinenlesbare Ergebnisse zurückerhalten können.

Es ist konzipiert für:

• KI-Agenten, die Event-Management, Produkteinführungen oder Community-Workflows steuern und eine Gruppe befragen müssen

• Entwickler, die Agenten-Produkte bauen und ein leichtgewichtiges Grundelement zur Feedback-Sammlung benötigen

Es ist nicht konzipiert für:

• Umfrage-Dashboards

• visuelle Formular-Builder

• Vorlagenbibliotheken

• E-Mail-Kampagnen

• Analyse-/Reporting-Benutzeroberflächen

Funktionen

• JSON-Schema-Eingabe — strukturiert, präzise und direkt maschinell generierbar

• MCP-Server — Umfragen erstellen und Ergebnisse direkt aus Claude Code lesen

• Minimale API-Oberfläche — authentifizierte Ersteller-Routen, öffentliche Einreichung durch Befragte

• Vier semantische Fragetypen — choice, text, scale, matrix

• Bedingte Logik — showIf in Markdown und JSON-Schema

• Expliziter Lebenszyklus — Umfragen schließen, Ablaufdatum und maximale Antwortbegrenzungen

Produktprinzipien

• Semantik vor Optik: HumanSurvey hat ein kleines Protokoll, keinen Zoo an UI-spezifischen Feldtypen.

• KI-First I/O: Agenten schreiben die Umfrage und Agenten konsumieren die Ergebnisse; Menschen stehen in der Mitte.

• Alles ist eine API: Ersteller-Funktionalität muss über authentifiziertes HTTP und MCP verfügbar sein.

• Enger Fokus gewinnt: Wenn eine Funktion hauptsächlich menschlichen Umfrage-Betreibern dient, gehört sie wahrscheinlich nicht hierher.

Unterstützte Fragetypen

• single_choice

• multi_choice

• text

• scale

• matrix

Markdown-Syntax

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

Skalenfragen:

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

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

Bedingte Logik:

**Q1. Did the deploy fail?**

- ☐ Yes
- ☐ No

**Q2. Which step failed?**

> show if: Q1 = "Yes"

> _______________________________________________

Schnellstart

Verwendung mit Claude Code

Zur Claude Code-Konfiguration hinzufügen (~/.claude.json):

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

Dann in Claude Code:

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

Verfügbare Tools:

• create_survey — Erstellen aus JSON-Schema; optional max_responses, expires_at, webhook_url

• get_results — aggregierte Ergebnisse + Rohantworten

• list_surveys — Auflisten der Umfragen, die Ihrem Schlüssel gehören

• close_survey — eine Umfrage sofort schließen

Verwendung der HTTP-API

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

Dann eine Umfrage erstellen:

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

Antwort:

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

Ergebnisse lesen:

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

Öffentliche Oberfläche

• Dokumentationsseite: https://www.humansurvey.co/docs

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

• KI-Index: https://www.humansurvey.co/llms.txt

Tech-Stack

Projektstruktur

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

Mitwirken

Lesen Sie CONTRIBUTING.md, bevor Sie einen PR öffnen. Die wichtigste Regel ist Disziplin beim Umfang: neue UI-Varianten, Analyse-Dashboards und Funktionen für menschliche Betreiber sind normalerweise außerhalb des Projektumfangs.

Entwicklung

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

Lizenz

MIT