@50heads/mcp 2026.925.1

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

@@ -0,0 +1,25 @@
+# 50heads tools beyond asking
+
+The core loop is `estimate`, `ask`, then the task (or `wait_for_results`) and `get_results`. These tools cover the rest.
+
+## 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_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.
+
+## 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.
+- `cancel`: stops a live question and refunds the heads who have not answered.
+
+## Help
+
+- `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.

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

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Price a 50heads question before asking it. Never spends.
+
+Usage:
+  python3 scripts/estimate.py question.json
+  echo '{"type":"single_choice","text":"Which name sounds most like a bakery?","language":"en","options":[{"label":"Crumb & Co"},{"label":"Loafers"}]}' | python3 scripts/estimate.py -
+
+The question is the same object the MCP `estimate` and `ask` tools take (see
+references/question-types.md). FIFTYHEADS_API_KEY is optional: estimates are public, but a key
+gives a higher rate limit. FIFTYHEADS_API_URL overrides https://api.50heads.com.
+Standard library only.
+"""
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+API_URL = os.environ.get("FIFTYHEADS_API_URL", "https://api.50heads.com").rstrip("/")
+
+
+def to_draft(q):
+    """The MCP question object (snake_case) to the API draft (camelCase)."""
+    draft = {
+        "type": q["type"],
+        "text": q["text"],
+        "language": q.get("language", "en"),
+        "options": [
+            {k: v for k, v in {"label": o.get("label", ""), "imageUrl": o.get("image_url")}.items() if v is not None}
+            for o in q.get("options", [])
+        ],
+        "n": q.get("n", 50),
+        "tier": q.get("tier", 2 if q["type"] == "free_text" else 1),
+        "rush": q.get("rush", False),
+        "neither": q.get("neither", False),
+    }
+    if q.get("context"):
+        draft["context"] = q["context"]
+    stimulus = q.get("stimulus") or {}
+    if stimulus:
+        draft["stimulus"] = {k: v for k, v in {"imageUrl": stimulus.get("image_url"), "text": stimulus.get("text")}.items() if v}
+    targeting = q.get("targeting") or {}
+    if targeting:
+        draft["targeting"] = {"countries": targeting.get("country", []), "tags": targeting.get("tags", [])}
+    return draft
+
+
+def money(price):
+    """{"amount": 12.70, "currency": "USD"} as "$12.70", "£10.00", "11,80 €"."""
+    amount, currency = price["amount"], price["currency"]
+    if currency == "EUR":
+        return ("%.2f" % amount).replace(".", ",") + "\u00a0€"
+    symbol = {"GBP": "£", "USD": "$", "CAD": "$"}.get(currency)
+    return symbol + "%.2f" % amount if symbol else "%.2f %s" % (amount, currency)
+
+
+def main():
+    if len(sys.argv) != 2:
+        print(__doc__.strip(), file=sys.stderr)
+        return 2
+    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"}
+    key = os.environ.get("FIFTYHEADS_API_KEY")
+    if key:
+        headers["authorization"] = "Bearer " + key
+    request = urllib.request.Request(API_URL + "/v1/billing/estimate", data=body, headers=headers, method="POST")
+    try:
+        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)
+        return 1
+    n = question.get("n", 50)
+    # The price is in the key's account currency (credits alone when the API sends none).
+    cost = "%d credits" % quote["creditsTotal"]
+    if quote.get("price"):
+        cost += " (%s)" % money(quote["price"])
+    print("%d answers, about %d minutes, %s." % (n, quote["etaMinutes"], cost))
+    print(quote.get("breakdownLine", ""))
+    for issue in quote.get("validation", []):
+        print("Fix: " + issue["message"])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())