# sunsiyuan/human-survey [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/sunsiyuan/human-survey  
**GitHub Stars:** 1  
**npm Downloads (last month):** 197  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sunsiyuan-human-survey

## Description
Feedback collection for AI agents. Create surveys from JSON schema, collect structured responses from groups of people, and retrieve aggregated results. 4 MCP tools for long-horizon agent workflows: post-event feedback, product launches, team health checks.

## Tools
Capabilities this server exposes over MCP:

- **login** — Sign in with an email address and store an API key on this machine. Called with only an email, it mails a six-digit code and returns nothing usable — the code has to come from the person, out of their inbox. Called with the email and that code, it stores a key at ~/.humansurvey/credentials and reports where it was written. The key itself is never printed. Signing in and signing up are the same act: an address that has never been used gets an account.
- **get_catalog** — List the platforms HumanSurvey knows: the slug to use as catalog_slug, the display label, and which class of channel it is. These are the named channels a respondent can be shown — TikTok, ChatGPT, LinkedIn, Reddit and so on — plus the descriptive options that have no brand behind them, like "a friend or colleague told me". No API key needed.
- **list_forms** — List the forms on this account: id, name, respondent URL, whether it is active or paused, whether it has been configured with questions yet, and how many responses it has collected.
- **get_form** — Read one form: its settings, and the question configuration currently shown to respondents — every question, every candidate, and the order mode. Returns the configuration as JSON, because that is the exact shape a configuration write takes.
- **create_form** — Create a form and return its id, its respondent URL, and the iframe and postMessage listener to embed that URL in a host page. The form has no questions yet and shows nothing to respondents until it is configured. allowed_origins restricts which sites may embed it; leaving it empty allows any site, which means any site can spend this account’s response quota.
- **configure_form** — Set the questions and candidates a form shows. Replaces the whole configuration and stores it as a new immutable version, so responses already collected keep describing the list they were actually shown. Re-sending an identical configuration reuses the existing version rather than making another.

A form is one single-select question, optionally expanding into a second. Give a candidate an `expands` naming another question to reveal it when that candidate is picked — that is how "TikTok" becomes "which account".

Candidate ids must be stable keys that survive a rename. Using a handle as an id splits that creator’s history in two the day they change it.

Set catalog_slug to take a candidate’s label and logo from the platform catalog. Order defaults to "rotate", which randomizes per respondent and is what makes the reported shares unbiased; "fixed" keeps your order and accepts that earlier options get picked more often for being earlier.
- **get_attribution** — What respondents said, aggregated. Reports, per question, how many completed responses named each candidate out of how many answered that question, the unresolved answers in the same list, how often a follow-up question failed to find an answer, and revenue where conversion events have been recorded.

Computed fresh on every call, including any mappings made since — so a rollup of a past window can legitimately change between two reads.
- **list_unresolved** — The answers respondents typed instead of picking from the list, grouped by the exact text and ordered by how often it was typed. Reports the spelling variants seen, when each was first and last typed, and whether a mapping already covers it.

These are verbatim words. Two texts that read alike may be different people, and a text may name somebody who is not on the candidate list at all.
- **remap** — Record that a specific typed answer means a specific candidate. It applies to every response already carrying that text as well as every future one, so numbers reported for past windows change.

The original text is never altered and a mapping can be revoked, but a report may already have been read. Only map a text whose meaning is established — a text that merely resembles a candidate’s name is not evidence that it is that candidate.

One live mapping per text per question.
- **revoke_remap** — Stop a mapping from applying. The typed answers it covered return to the unresolved list — in past windows as well as future ones, because rollups join mappings when they are read rather than when they are made. Numbers already reported for those windows will therefore change.

Nothing is deleted: the mapping is marked revoked and kept, so a report produced while it was live can still be explained. Revoking an already-revoked mapping is not an error and does not move the time it stopped applying.

Mapping ids appear beside any text that is already mapped in the free-text listing, and in the confirmation given when a mapping is created.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `HUMANSURVEY_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What sunsiyuan/human-survey MCP server does

The sunsiyuan/human-survey MCP server gives an agent access to HumanSurvey's self-reported attribution service. It is intended for products that embed a short “how did you hear about us?” form in signup, onboarding, or payment flows. Respondents choose a platform and, where configured, a related creator or other follow-up candidate.

The service separates form configuration from respondent collection. An agent can create a form, configure its candidate nodes, and then provide the resulting form URL to a host application. The host controls how people reach the form, including a direct `/s/{id}` URL or an iframe embed.

## How it works

HumanSurvey stores each response against the configuration snapshot shown to the respondent. This means later configuration changes do not rewrite the historical choices. Candidate order can be rotated for each render using a client-generated `render_id`; callers can also request fixed ordering when that is appropriate.

The first answer is saved before a follow-up is presented. A person who leaves before completing the follow-up still contributes a recorded first response. Completed responses can be read as a cursor-based stream or looked up using an external identity supplied by the host. The service also exposes aggregated rollups for analyzing candidate counts over a date range.

Free-text answers remain available for review when they cannot yet be matched. A remap can associate that text with a candidate, and subsequent reads apply the mapping without requiring historical data to be rewritten. The `external_id` field provides the link between attribution records and the host's own user or conversion data.

## Setup and configuration

The sunsiyuan/human-survey MCP server is launched with the published `humansurvey-mcp` npm package. A Claude Code configuration uses the `npx -y humansurvey-mcp` command and passes the `HUMANSURVEY_API_KEY` environment variable. The key is obtained from HumanSurvey's email-code authentication flow; anonymous key creation is not supported.

After authentication, create a form through the service and configure its nodes before embedding it. Platform labels, marks, and aliases can be taken from HumanSurvey's attribution catalog. Creator candidates are supplied by the caller, so identifying or matching creators against an external creator database is outside this server's stated role. The host should also configure allowed origins when creating a form.

## Tools and capabilities

The MCP package is described in the repository as exposing ten tools for the attribution API.

- Create and configure attribution forms.
- Retrieve catalog data for platform candidates.
- Read aggregate rollups by candidate and date range.
- Stream responses with cursors or filter them by `external_id`.
- Find unresolved free-text responses.
- Add remaps that resolve previously unmatched text.
- Support attribution data associated with a host's own conversion events and identifiers.

These operations suit long-running agent workflows where an agent keeps candidate lists current, prepares a form for an event or product flow, and periodically reads results for analysis.

## Limitations and notes

The sunsiyuan/human-survey MCP server is focused on attribution rather than general survey authoring. The project says arbitrary question types, Markdown authoring, and conditional logic are outside its current scope. It does not provide a human-facing analytics dashboard; aggregate results are exposed as API resources for the agent or host to consume.

HumanSurvey does not contact respondents or recruit an audience. The embedding application owns distribution and placement. Creator candidate data must be supplied by the caller, and matching vague respondent descriptions to a creator database is upstream work.

The project is licensed under MIT. Its documented stack includes the MCP SDK, a Next.js application, and a serverless Postgres database, but running the hosted service through the package does not require operating those components locally.

_Full upstream README: https://allmcps.com/mcp/sunsiyuan-human-survey/readme_