@50heads/mcp 2026.925.2 → 2026.1009.1

package/dist/types/server.d.ts

@@ -66,6 +66,7 @@ export declare function clientName(ctx: ServerContext): string | undefined;
 export declare function createServer(opts: ServerOptions): McpServer;
 /**
  * A first draft from a goal and assets: two image URLs make an A or B question; listed
- * options make a single choice; otherwise a yes, mostly or no check. The model refines it.
+ * options make a single choice; otherwise a yes or no check. The model refines it. Mostly is
+ * yes_mostly_no, and only when the asker asks for that middle answer.
  */
 export declare function draftFromGoal(goal: string, assets?: string): Record<string, unknown>;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@50heads/mcp",
-  "version": "2026.925.2",
+  "version": "2026.1009.1",
   "mcpName": "com.50heads/mcp",
-  "description": "50heads MCP: ask fifty verified real people from Claude, ChatGPT, Cursor or your own agent.",
+  "description": "50heads MCP: ask fifty verified people from Claude, ChatGPT, Cursor or your own agent.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -13,8 +13,7 @@
   "homepage": "https://50heads.com/docs/mcp",
   "repository": {
     "type": "git",
-    "url": "https://github.com/50heads/mcp.git",
-    "directory": "packages/mcp"
+    "url": "https://github.com/50heads/mcp.git"
   },
   "bugs": "https://github.com/50heads/mcp/issues",
   "license": "MIT",
@@ -54,14 +53,14 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/client": "2.2.0",
     "@types/node": "^22.18.0",
     "esbuild": "^0.28.2",
     "typescript": "^5.9.3",
-    "@50heads/brand": "0.0.0",
     "@50heads/login": "0.0.0",
-    "@50heads/tsconfig": "0.0.0",
-    "@50heads/shared": "0.0.0"
+    "@50heads/brand": "0.0.0",
+    "@50heads/shared": "0.0.0",
+    "@50heads/tsconfig": "0.0.0"
   },
   "scripts": {
     "generate": "node scripts/generate.ts",

package/server.json

@@ -2,13 +2,12 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "com.50heads/mcp",
   "title": "50heads",
-  "description": "Ask fifty verified real people a five-second question and get the split back.",
-  "version": "2026.925.2",
+  "description": "Ask fifty verified people a five-second question and get the split back.",
+  "version": "2026.1009.1",
   "websiteUrl": "https://50heads.com/agents",
   "repository": {
     "url": "https://github.com/50heads/mcp",
-    "source": "github",
-    "subfolder": "packages/mcp"
+    "source": "github"
   },
   "icons": [
     {
@@ -45,7 +44,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@50heads/mcp",
-      "version": "2026.925.2",
+      "version": "2026.1009.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -78,7 +77,7 @@
           "account:read"
         ]
       },
-      "skillVersion": "2026.925.2"
+      "skillVersion": "2026.1009.1"
     }
   }
 }

package/skills/50heads/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: 50heads
-description: Ask fifty verified real people a five-second question and get a distribution back; use when the work in hand needs a human preference, first impression or sanity check that a model cannot supply.
+description: Ask fifty verified people a five-second question and get a distribution back; use when the work in hand needs a human preference, first impression or sanity check that a model cannot supply.
 license: MIT
 metadata:
-  version: "2026.925.2"
+  version: "2026.1009.1"
   homepage: https://50heads.com/agents
 allowed-tools: "50heads:*"
 ---

package/skills/50heads/references/pricing.md

@@ -8,11 +8,11 @@ Per answer = tier base × length × format, plus images and targeting traits, ti
 | --- | --- | --- | --- |
 | 1 | phone-verified | 20 | 1000 |
 | 2 | ID-verified | 42 | 2100 |
-| 3 | trusted panel | 80 | 4000 |
+| 3 | established heads | 80 | 4000 |
 
 Length (question, context and options together): up to 150 characters × 1.0, up to 300 × 1.1, up to 600 × 1.25.
 
-Format: `single_choice` × 1.0, `multi_choice` × 1.1, `ab_image` × 1.0, `pairwise` × 1.1, `scale_1_5` × 1.0, `ranking` × 1.3, `yes_mostly_no` × 1.0, `free_text` × 2.0, `click_test` × 1.5, `reaction` × 1.0.
+Format: `single_choice` × 1.0, `multi_choice` × 1.1, `ab_image` × 1.0, `pairwise` × 1.1, `scale_1_5` × 1.0, `ranking` × 1.3, `yes_no` × 1.0, `yes_mostly_no` × 1.0, `free_text` × 2.0, `click_test` × 1.5, `reaction` × 1.0.
 
 A reason with every answer (`reason`, not for free_text) adds to the format: optional + 0.3, required + 0.6. A required reason on a Tier 1 single choice is 20 × 1.6 = 32 credits an answer. Heads get the same share of the higher price.
 
@@ -22,6 +22,8 @@ Targeting: countries are free. Age, gender and each tag group are one trait each
 
 Heads: 10 to 5000, default 50.
 
+Your audience (`answered_by: "private"`): a link you share instead of heads, 5 credits an accepted answer, reserved for the most answers the link accepts (`n`, default 100) and refunded for the rest when it closes. No tier, rush, targeting or images surcharge; no time estimate (people answer when you share the link); every result says the answers were not verified by 50heads.
+
 Every connection has a daily spend cap (default 5,000 credits), set when you connect and editable in the dashboard. Call `balance` to see what is left.
 
 Always call `estimate` first: it returns the exact price, the time and any fixes the question needs, and never spends.

package/skills/50heads/references/question-types.md

@@ -4,7 +4,7 @@ Every question has `type`, `text` (8 to 600 characters), `language` (such as `en
 
 The format multiplier is part of the price: per answer = tier base × length × format, plus 5 credits an image.
 
-Five-second test: add `exposure_ms` (usually 5000) to an image stimulus on single_choice, multi_choice, yes_mostly_no, scale_1_5, reaction or free_text. The app shows the image for that long, hides it, then asks, so the answer is a first impression or what people remember. × 1.3.
+Five-second test: add `exposure_ms` (usually 5000) to an image stimulus on single_choice, multi_choice, yes_no, yes_mostly_no, scale_1_5, reaction or free_text. The app shows the image for that long, hides it, then asks, so the answer is a first impression or what people remember. × 1.3.
 Every type except `free_text` can ask for a short written reason with each answer: `reason: "optional"` (format + 0.3) or `"required"` (format + 0.6), 10 to 140 characters. Reasons come back on each answer, translated into your language when heads wrote in another, and `get_results` summarises them (themes with counts and quotes, a sentiment split and a takeaway). Use it instead of a follow-up when you want the which and the why from the same heads.
 
 ## Single choice (`single_choice`)
@@ -161,9 +161,26 @@ Every type except `free_text` can ask for a short written reason with each answe
 }
 ```
 
+## Yes or no (`yes_no`)
+
+- Use: A binary check. Heads answer Yes or No. This is the yes/no type. For a middle answer, use yes_mostly_no.
+- Options: Fixed: Yes, No. Do not send options.
+- Answer: Yes or No.
+- Tier: any. Format × 1.0.
+
+```json
+{
+  "type": "yes_no",
+  "text": "Does this button label tell you what will happen?",
+  "context": "Button: Save and continue",
+  "language": "en",
+  "n": 50
+}
+```
+
 ## Yes, mostly or no (`yes_mostly_no`)
 
-- Use: A quick check with room for a middle answer: does this make sense, would you trust it.
+- Use: Yes, Mostly or No. Set this type when you want the middle answer. A plain yes/no question is yes_no.
 - Options: Fixed: Yes, Mostly, No. Do not send options.
 - Answer: One of the three.
 - Tier: any. Format × 1.0.

package/skills/50heads/references/tools.md

@@ -5,16 +5,18 @@ The core loop is `estimate`, `ask`, then the task (or `wait_for_results`) and `g
 ## Before asking
 
 - `upload_image`: for a local file or a generated image, send it as base64 in `data` (JPEG, PNG or WebP, up to 5 MB; about 700 KB through the hosted server, which takes 1 MB requests). For an image already online, pass `image_url` and 50heads copies it. Use the returned `image_url` in the question. Costs nothing.
+- `list_audiences`: interest audiences, panels of heads who proved they fit (UK commuter cyclists, for example). Put an id in `question.audience` to ask one instead of targeting; the price is the audience's at the minimum grade.
 - `list_targeting`: countries with the languages their heads read and pool size bands, and the tag ids you can target at Tier 2 and 3. Each condition shrinks the pool; `estimate` shows `pool_size`.
 - `build_ask_link`: when a person should press Ask themselves, give them this link. It opens the portal composer with the question filled in and asks nothing. It also opens a template (`template_id`), a follow-up (`follow_up_of`) or a re-ask of the unanswered part (`reask`).
-- `templates` and `list_questions`: a fixed-price template may fit, and a recent answer may already cover the question.
+- `templates` and `list_questions`: a fixed-price template may fit, and a recent answer may already cover the question. `list_questions` takes `set_id` to list one set's questions in order.
+- `ask_set`: two to ten questions for the person's own audience behind one link, answered in order, about five seconds each. Same question shapes as `ask` without tier, rush, targeting, reasons or free text; `max_answers`, `open_for_days`, `shown_as` and `public_results` are set once for the set. Returns the link, the `question_ids` in order and the reserve (questions × max answers × 5 credits). Results are per question.
 
 ## After the answers
 
 - `get_answers`: individual answers, 50 a page (up to 200), newest first, with `next_cursor`. Filter by `option` (0 is the first), `tier`, `country`, `age_band` or a keyword `q` in written answers and reasons. Country and age filters show nothing when fewer than 5 answers match, so no head can be singled out.
 - `add_heads`: when the margin is under 10 points with 50 heads, ask more of the same question instead of a new one. It needs its own fresh `idempotency_key` and spends at the same price per answer; say the price and time before you do it when a person is present.
 - `flag_answer`: an answer that is off-topic, low effort, offensive or a duplicate, by its `attestation_ref`. Upheld flags remove the answer and refund it. Never flag an answer because you dislike it.
-- `export`: `csv` has every answer (with the same filters as `get_answers`); `pdf` is a one-page report and `png` the result card where the API serves them.
+- `export`: `csv` has every answer (with the same filters as `get_answers`); `pdf` is a one-page report and `png` the result card. The API serves all three.
 - `cancel`: stops a live question and refunds the heads who have not answered.
 
 ## Help
@@ -22,4 +24,4 @@ The core loop is `estimate`, `ask`, then the task (or `wait_for_results`) and `g
 - `search_help`: the help centre, for questions about credits, refunds, verification, tiers, the API or this server.
 - `send_feedback`: tells support about a problem or an idea. Signed out, add `email`. Leave out personal data about other people.
 
-Tools that are new to the API (`add_heads`, `flag_answer`, PDF and PNG `export`) answer `unavailable` until the API serves them. That is not a failure of your call: carry on without them.
+`add_heads`, `flag_answer` and `export` (CSV, PDF and PNG) are served by the API. Use them when the result calls for it.

package/skills/50heads/scripts/estimate.py

@@ -20,6 +20,22 @@ import urllib.request
 API_URL = os.environ.get("FIFTYHEADS_API_URL", "https://api.50heads.com").rstrip("/")
 
 
+def user_agent():
+    """50heads-skill/<version>. Cloudflare answers 1010 to the bare Python-urllib agent."""
+    skill = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "SKILL.md")
+    version = "dev"
+    try:
+        with open(skill, encoding="utf-8") as handle:
+            for line in handle:
+                stripped = line.strip()
+                if stripped.startswith("version:"):
+                    version = stripped.split(":", 1)[1].strip().strip("\"'")
+                    break
+    except OSError:
+        pass
+    return "50heads-skill/" + version
+
+
 def to_draft(q):
     """The MCP question object (snake_case) to the API draft (camelCase)."""
     draft = {
@@ -62,7 +78,12 @@ def main():
     source = sys.stdin if sys.argv[1] == "-" else open(sys.argv[1], encoding="utf-8")
     question = json.load(source)
     body = json.dumps({"draft": to_draft(question), "surface": "web"}).encode("utf-8")
-    headers = {"content-type": "application/json", "accept": "application/json", "x-50heads-source": "mcp"}
+    headers = {
+        "content-type": "application/json",
+        "accept": "application/json",
+        "User-Agent": user_agent(),
+        "x-50heads-source": "mcp",
+    }
     key = os.environ.get("FIFTYHEADS_API_KEY")
     if key:
         headers["authorization"] = "Bearer " + key
@@ -71,8 +92,15 @@ def main():
         with urllib.request.urlopen(request, timeout=20) as response:
             quote = json.load(response)
     except urllib.error.HTTPError as err:
-        detail = json.loads(err.read().decode("utf-8") or "{}").get("error", {})
-        print(detail.get("message", "The estimate failed (HTTP %d)." % err.code), file=sys.stderr)
+        raw = err.read().decode("utf-8", "replace")
+        message = "The estimate failed (HTTP %d)." % err.code
+        try:
+            detail = json.loads(raw or "{}").get("error", {})
+            if isinstance(detail, dict) and detail.get("message"):
+                message = detail["message"]
+        except json.JSONDecodeError:
+            pass
+        print(message, file=sys.stderr)
         return 1
     n = question.get("n", 50)
     # The price is in the key's account currency (credits alone when the API sends none).