@50heads/mcp 2026.1009.1 → 2026.1013.2

package/dist/types/constants.d.ts

@@ -4,34 +4,103 @@
  */
 export declare const SERVER_NAME = "50heads";
 /** Calendar version (YYYY.MDD.N). Stamped at release by scripts/release.ts; never edit by hand. */
-export declare const SERVER_VERSION = "2026.1009.1";
+export declare const SERVER_VERSION = "2026.1013.2";
 /** Sent by the CLI on every request, so the API can tell releases apart. */
-export declare const USER_AGENT = "50heads-mcp/2026.1009.1";
+export declare const USER_AGENT = "50heads-mcp/2026.1013.2";
 export declare const MCP_RESOURCE_URL = "https://mcp.50heads.com/mcp";
-/** The scope each tool needs (spec: Authorization → Scopes). null: no sign-in needed. */
-export declare const TOOL_SCOPES: {
-    readonly estimate: "questions:write";
-    readonly ask: "questions:write";
-    readonly ask_set: "questions:write";
-    readonly get_results: "questions:read";
-    readonly wait_for_results: "questions:read";
-    readonly list_questions: "questions:read";
-    readonly cancel: "questions:write";
-    readonly templates: null;
-    readonly balance: "account:read";
-    readonly upload_image: "questions:write";
-    readonly get_answers: "questions:read";
-    readonly add_heads: "questions:write";
-    readonly flag_answer: "questions:write";
-    readonly export: "questions:read";
-    readonly build_ask_link: null;
-    readonly list_targeting: null;
-    readonly list_audiences: null;
-    readonly search_help: null;
-    readonly send_feedback: null;
+/**
+ * The tools and, inside each, the actions it takes, with the scope each action needs (spec:
+ * Authorization → Scopes). null: no sign-in needed. A tool has at most MAX_TOOLS (10) entries
+ * (decision G12): hosts choose well from few tools, so related calls are actions of one tool, and
+ * every action is checked against its own scope, never the tool's.
+ */
+export declare const TOOL_ACTIONS: {
+    readonly estimate: {
+        readonly quote: "questions:write";
+        readonly balance: "account:read";
+        readonly templates: null;
+        readonly audiences: null;
+        readonly targeting: null;
+    };
+    readonly ask: {
+        readonly ask: "questions:write";
+        readonly set: "questions:write";
+        readonly upload_image: "questions:write";
+        readonly build_link: null;
+    };
+    readonly results: {
+        readonly get: "questions:read";
+        readonly wait: "questions:read";
+        readonly answers: "questions:read";
+        readonly export: "questions:read";
+        readonly list: "questions:read";
+    };
+    readonly questions: {
+        readonly cancel: "questions:write";
+        readonly add_heads: "questions:write";
+        readonly flag_answer: "questions:write";
+        readonly file: "questions:write";
+    };
+    readonly projects: {
+        readonly list: "questions:read";
+        readonly create: "questions:write";
+        readonly update: "questions:write";
+        readonly delete: "questions:write";
+        readonly labels: "questions:read";
+    };
+    readonly webhooks: {
+        readonly list: "webhooks:read";
+        readonly create: "webhooks:write";
+        readonly update: "webhooks:write";
+        readonly rotate_secret: "webhooks:write";
+        readonly test: "webhooks:write";
+        readonly deliveries: "webhooks:read";
+        readonly events: "webhooks:read";
+        readonly replay: "webhooks:write";
+        readonly delete: "webhooks:write";
+    };
+    readonly organization: {
+        readonly get: "organization:read";
+        readonly domains: "organization:read";
+        readonly scim: "organization:read";
+        readonly member_sessions: "members:read";
+        readonly service_accounts: "organization:read";
+        readonly apps: "apps:read";
+    };
+    readonly audit: {
+        readonly list: "audit:read";
+        readonly export: "audit:read";
+    };
+    readonly help: {
+        readonly search: null;
+        readonly feedback: null;
+        readonly status: null;
+        readonly whoami: "account:read";
+    };
 };
-export type ToolName = keyof typeof TOOL_SCOPES;
+export type ToolName = keyof typeof TOOL_ACTIONS;
 export declare const TOOL_NAMES: ToolName[];
+/** At most this many tools, ever (decision G12). A guard test fails above it. */
+export declare const MAX_TOOLS = 10;
+/** "tool.action" for every action: the id used in logs, tags and the tests. */
+export type ActionId = {
+    [T in ToolName]: `${T}.${keyof (typeof TOOL_ACTIONS)[T] & string}`;
+}[ToolName];
+export declare const ACTION_IDS: ActionId[];
+/** The actions of a tool, in the order the tool lists them. */
+export declare function actionsOf(tool: string): string[];
+/**
+ * The scope one action needs: a string, null when no sign-in is needed, or undefined when there
+ * is no such tool or action. Per action, not per tool.
+ */
+export declare function actionScope(tool: string, action: unknown): string | null | undefined;
+/**
+ * The actions that change something of the account's: asks and spends, uploads, cancels, flags,
+ * filing, projects and webhooks. Each needs a :write scope, so a read-only grant never reaches
+ * one. (The estimate quote also needs questions:write, as it always has, but changes nothing.
+ * Feedback opens a support ticket and needs no sign-in, so it is not an account change.)
+ */
+export declare const WRITE_ACTIONS: ReadonlySet<string>;
 /** Resources that need no sign-in; the rest need questions:read. */
 export declare const PUBLIC_RESOURCE_PREFIXES: string[];
 export declare function resourceScope(uri: string): string | null;

package/dist/types/draft.d.ts

@@ -1,8 +1,16 @@
-import type { FollowUpInput as ApiFollowUp, QuestionDraftInput, QuestionOption } from "@50heads/shared";
+import { type FollowUpInput as ApiFollowUp, type GoRule, type QuestionDraftInput, type QuestionOption } from "@50heads/shared";
 import type { z } from "zod";
 import type { FollowUpInput, QuestionInput, VariantInput } from "./schemas.js";
 /** The MCP question object → the API's draft. `language` must be settled by the caller. */
 export declare function toDraft(q: QuestionInput, language: string): QuestionDraftInput;
+/**
+ * The MCP go rule → the API's. Answers needed defaults to 80% of the heads asked, rounded down,
+ * at least the floor (the composer's default).
+ */
+export declare function toGoRule(g: {
+    go_above: number;
+    min_answers?: number;
+}, n: number): GoRule;
 /** A variant is the same question with translated text and options. */
 export declare function variantDraft(base: QuestionDraftInput, v: z.infer<typeof VariantInput>): QuestionDraftInput;
 export declare function toFollowUp(f: z.infer<typeof FollowUpInput>): ApiFollowUp;
@@ -20,4 +28,5 @@ export declare function fromDraft(d: {
     rush?: boolean;
     neither?: boolean;
     reason?: string;
+    goRule?: GoRule;
 }): Record<string, unknown>;

package/dist/types/errors.d.ts

@@ -14,7 +14,7 @@ export declare const ERROR_CODES: {
     readonly transient: -32000;
     readonly internal: -32603;
 };
-export type McpErrorCode = "validation" | "not_found" | "insufficient_credits" | "spend_cap_exceeded" | "idempotency_conflict" | "content_refused" | "underfilled" | "unauthorised" | "insufficient_scope" | "rate_limited" | "unavailable" | "internal";
+export type McpErrorCode = "validation" | "not_found" | "insufficient_credits" | "spend_cap_exceeded" | "idempotency_conflict" | "content_refused" | "underfilled" | "unauthorized" | "insufficient_scope" | "rate_limited" | "unavailable" | "internal";
 export type McpErrorData = {
     code: McpErrorCode;
     retryable: boolean;

package/dist/types/generated/skill.d.ts

@@ -1,6 +1,6 @@
 /** The skill's version (front matter metadata.version); advertised as skillVersion. */
-export declare const SKILL_VERSION = "2026.1009.1";
+export declare const SKILL_VERSION = "2026.1013.2";
 /** SKILL.md without its front matter: the 50heads://guide resource. */
-export declare const SKILL_BODY = "# Asking 50heads\n\n50heads puts one short question to verified people on their phones and returns how they split. Answers cost credits, priced in your currency; fifty take about ten minutes.\n\n## When to ask\n\nAsk when the answer is a human reaction: which name, headline, image or menu people prefer, whether copy is clear, what they notice first. Never ask for facts, predictions, advice or research. Before asking again, call `list_questions` and reuse a recent answer.\n\n## Eight rules for a good question\n\n1. One question a head can answer in five seconds.\n2. Ask about a preference or first impression, never a fact.\n3. Show the thing: images (`ab_image`, `upload_image`) for anything visual.\n4. Keep options short, parallel and few: two to four is best. Add Neither when a forced pick would mislead.\n5. Word it neutrally. No leading words, no hint of the answer you want.\n6. Put background in `context`, one line, only when a head needs it.\n7. Pick the type that fits: `single_choice` to pick, `pairwise` for two, `ranking` for order, `scale_1_5` for strength, `free_text` (Tier 2) for why.\n8. Match heads and tier to the stakes: 50 at Tier 1 for a quick read, 100 or more or Tier 2 for a decision; target the countries and language of the real audience.\n\n## How to ask\n\n1. Call `estimate` and, when a person is present, show them the price and time together: \"50 answers, about 10 minutes, $12.70.\"\n2. Call `ask` with a fresh UUID as `idempotency_key`. Reuse that key if you retry.\n3. Wait on the task, or call `wait_for_results` on older hosts. `get_results` shows it while live.\n\n## Reading results\n\nLead with the winner, the margin in points and the confidence. With 50 heads a margin under 10 points is noise: say so and suggest more heads, not a verdict. Report underfilled as underfilled. Quote the split, not adjectives.\n\n## Worked example\n\n\"Which menu would you order from?\" with two menu photos, `ab_image`, 50 heads, Tier 1. Menu B 68%, Menu A 32%: \"Menu B wins by 36 points. Confidence high.\" Follow up with 20 Tier 2 heads saying why.\n\n## Avoid\n\n- Double questions (\"Is it clear and friendly?\").\n- Yes-or-no questions that lead.\n- Asking for personal data or anything that identifies someone.\n- Re-asking the same question to fish for a different answer.\n\nMore: `references/question-types.md`, `pricing.md`, `tools.md`.\n";
+export declare const SKILL_BODY = "# Asking 50heads\n\n50heads puts one short question to verified people and shows what they think.\n\n## When to ask\n\nAsk when the answer is a human reaction: which name, headline, image or menu people prefer, whether copy is clear, what they notice first. Never ask for facts, predictions, advice or research. Check recent `results` (`list`) first.\n\n## Eight rules for a good question\n\n1. One question a head can answer in five seconds.\n2. Ask about a preference or first impression, never a fact.\n3. Show the thing: images (`ab_image`, `upload_image`) for anything visual.\n4. Keep options short, parallel and few: two to four is best. Add Neither when a forced pick would mislead.\n5. Word it neutrally, with no hint of the answer you want.\n6. Put needed background in `context`, one line.\n7. Pick the type that fits: `single_choice` to pick, `pairwise` for two, `ranking` for order, `scale_1_5` for strength, `yes_no` with `go_rule` to approve, `free_text` (Tier 2) for why.\n8. Match heads and tier to the stakes: 50 at Tier 1 for a quick read, 100 or more or Tier 2 for a decision. Target the real audience's countries and language.\n\n## How to ask\n\n1. Call `estimate` (`quote`); with a person present, show the price: \"50 answers, $12.70.\" Don't promise a time.\n2. Call `ask` with a fresh UUID as `idempotency_key`. Reuse it to retry.\n3. Wait on the task (older hosts: `results`, `wait`).\n\n## Reading results\n\nLead with the winner, the margin in points and the confidence. With 50 heads a margin under 10 points is noise: say so and suggest more heads. Report underfilled as underfilled. Quote the percentages, not adjectives.\n\nWith a `go_rule`, lead with the `verdict`: go, no go or unclear against the asker's line. `head_to_head` says who beats whom; overlapping ranges mean the lead may be chance.\n\n## Worked example\n\n\"Which menu would you order from?\": two photos, `ab_image`, 50 heads, Tier 1. B 68%, A 32%: \"Menu B wins by 36 points. Confidence high.\"\n\n## Avoid\n\n- Double questions (\"Is it clear and friendly?\").\n- Personal data, or anything that identifies someone.\n- Re-asking to fish for a different answer.\n\n## Your data\n\nWe don't use your questions, the answers you buy or the reasons heads write to train AI models, and we don't sell them.\n\nMore: `references/question-types.md`, `pricing.md`, `tools.md`.\n";
 /** Every file in the skill bundle, by path relative to skills/50heads. */
 export declare const SKILL_FILES: Record<string, string>;

package/dist/types/manifest.d.ts

@@ -4,7 +4,19 @@
  */
 export declare const REGISTRY_NAME = "com.50heads/mcp";
 export declare const NPM_PACKAGE = "@50heads/mcp";
-export declare const DESCRIPTION = "Ask fifty verified people a five-second question and get the split back.";
+export declare const DESCRIPTION = "Ask fifty verified people a five-second question and see what they think.";
+/**
+ * Public links every directory listing and the registry entry carry (docs/listings). The no-train
+ * statement is the Help article; the privacy policy has the same words under "AI and your data".
+ */
+export declare const LISTING_URLS: {
+    readonly website: "https://50heads.com/agents";
+    readonly documentation: "https://50heads.com/en-us/docs/mcp";
+    readonly privacyPolicy: "https://50heads.com/en-gb/legal/privacy";
+    readonly noTrain: "https://50heads.com/en-gb/help/privacy/ai-and-your-data";
+    readonly terms: "https://50heads.com/en-gb/legal/terms";
+    readonly support: "https://50heads.com/en-gb/contact?purpose=support";
+};
 export type ManifestOptions = {
     /** The hosted endpoint, https://mcp.50heads.com/mcp. */
     endpoint?: string;
@@ -35,7 +47,7 @@ export declare function serverCard(opts?: ManifestOptions): {
         schemes: string[];
         resourceMetadata: string;
         authorizationServers: string[];
-        scopes: ("questions:read" | "questions:write" | "templates:read" | "account:read")[];
+        scopes: ("questions:read" | "questions:write" | "templates:read" | "account:read" | "webhooks:read" | "webhooks:write" | "apps:read" | "apps:write" | "organization:read" | "organization:write" | "members:read" | "members:write" | "audit:read")[];
     };
     capabilities: {
         tools: {
@@ -75,8 +87,11 @@ export declare function serverCard(opts?: ManifestOptions): {
         };
     };
     tools: {
-        name: string;
-        scope: "questions:read" | "questions:write" | "account:read" | null;
+        name: "organization" | "ask" | "questions" | "results" | "projects" | "audit" | "estimate" | "webhooks" | "help";
+        actions: {
+            action: string;
+            scope: "questions:read" | "questions:write" | "account:read" | "webhooks:read" | "webhooks:write" | "apps:read" | "organization:read" | "members:read" | "audit:read" | null;
+        }[];
     }[];
     resources: string[];
     prompts: string[];
@@ -89,7 +104,7 @@ export declare function registryServerJson(): {
     title: string;
     description: string;
     version: string;
-    websiteUrl: string;
+    websiteUrl: "https://50heads.com/agents";
     repository: {
         url: string;
         source: string;
@@ -129,10 +144,15 @@ export declare function registryServerJson(): {
     _meta: {
         "io.modelcontextprotocol.registry/publisher-provided": {
             categories: string[];
+            documentationUrl: "https://50heads.com/en-us/docs/mcp";
+            privacyPolicyUrl: "https://50heads.com/en-gb/legal/privacy";
+            noTrainStatementUrl: "https://50heads.com/en-gb/help/privacy/ai-and-your-data";
+            termsOfServiceUrl: "https://50heads.com/en-gb/legal/terms";
+            supportUrl: "https://50heads.com/en-gb/contact?purpose=support";
             authorization: {
                 resourceMetadata: string;
                 authorizationServer: string;
-                scopes: ("questions:read" | "questions:write" | "templates:read" | "account:read")[];
+                scopes: ("questions:read" | "questions:write" | "templates:read" | "account:read" | "webhooks:read" | "webhooks:write" | "apps:read" | "apps:write" | "organization:read" | "organization:write" | "members:read" | "members:write" | "audit:read")[];
             };
             skillVersion: string;
         };

package/dist/types/organization.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The organization as the read-only tools return it (plan 2 stage 5): snake_case, credits, and one
+ * plain line per item for the text summary. Changes (domains, policies, single sign-on, SCIM,
+ * service accounts) are made in the portal: these tools never write.
+ */
+import type { AuditEvent, MemberSessions, Organization, OrganizationDomain, ScimSettings, ScimToken, ServiceAccount } from "@50heads/shared";
+import type { AuditEventOut, DomainOut, OrganizationOut, ServiceAccountOut } from "./schemas.js";
+export declare function toOrganization(o: Organization): OrganizationOut;
+/** "Acme (org_1): you are an admin. 2 workspaces; domains acme.com; single sign-on required; SCIM on." */
+export declare function organizationLine(o: OrganizationOut): string;
+export declare function toDomain(d: OrganizationDomain): DomainOut;
+/** "acme.com: verified on 2026-10-01." or "beta.com: pending. Publish TXT _50heads-challenge.beta.com = …" */
+export declare function domainLine(d: DomainOut): string;
+export declare function toAuditEvent(e: AuditEvent): AuditEventOut;
+/** "2026-10-11 09:30 · domain.added · acme.com · by Ana (API key)" */
+export declare function auditLine(e: AuditEventOut): string;
+export declare function scimStatus(settings: ScimSettings, tokens: ScimToken[]): {
+    base_url: string;
+    default_role: "admin" | "member" | "viewer" | "billing";
+    default_workspace_id: string | null;
+    provisioned_people: number;
+    active_people: number;
+    groups: number;
+    tokens: {
+        token_id: string;
+        label: string;
+        prefix: string;
+        created_at: string;
+        expires_at: string | null;
+        last_used_at: string | null;
+    }[];
+};
+export declare function memberSessions(m: MemberSessions): {
+    user_id: string;
+    sessions: {
+        session_id: string;
+        kind: "app" | "web";
+        label: string;
+        country: string | null;
+        sign_in_method: "apple" | "google" | "email" | "sso" | "passkey" | "break_glass" | null;
+        created_at: string;
+        last_seen_at: string | null;
+    }[];
+};
+export declare function toServiceAccount(s: ServiceAccount): ServiceAccountOut;
+/** "sa_1 · Nightly agent (on) in Acme: 400 of 10,000 credits spent today; last token 2026-10-11." */
+export declare function serviceAccountLine(s: ServiceAccountOut): string;

package/dist/types/pricing.d.ts

@@ -28,10 +28,8 @@ export declare function formatPrice(p: {
  * total stays the Tier 1 price from packages/shared (50 × per-answer credits).
  */
 export declare function readmeLead(): string;
-/** "about 10 minutes", "about 2 hours". */
-export declare function aboutMinutes(minutes: number): string;
-/** Cost and time in one sentence, per BRAND.md: "50 answers, about 10 minutes, $12.70." */
-export declare function costLine(n: number, etaMinutes: number, p: {
+/** The price in one sentence: "50 answers, $12.70." No time estimate. */
+export declare function costLine(n: number, p: {
     amount: number;
     currency: string;
 }): string;
@@ -89,7 +87,7 @@ export declare function pricingTable(currency: Currency, rates?: Rates): {
 };
 /**
  * The pricing reference as markdown (the skill's references/pricing.md). A static file read by
- * every account, so it is in credits; `estimate`, `balance` and 50heads://pricing give money
+ * every account, so it is in credits; `estimate` (quote and balance) and 50heads://pricing give money
  * in the account's own currency.
  */
 export declare function pricingMarkdown(): string;

package/dist/types/public.d.ts

@@ -9,7 +9,7 @@
  * ```
  */
 import type { McpServer } from "@modelcontextprotocol/server";
-export { MCP_RESOURCE_URL, PROMPT_SCOPES, SERVER_NAME, SERVER_VERSION, TOOL_NAMES, TOOL_SCOPES, type ToolName, } from "./constants.js";
+export { MCP_RESOURCE_URL, PROMPT_SCOPES, SERVER_NAME, SERVER_VERSION, TOOL_ACTIONS, TOOL_NAMES, type ActionId, type ToolName, } from "./constants.js";
 export { CLIENTS, configSnippets, type ClientId, type Snippet, type SnippetOptions } from "./snippets.js";
 export { SKILL_BODY, SKILL_FILES, SKILL_VERSION } from "./generated/skill.js";
 export { registryServerJson, serverCard } from "./manifest.js";

package/dist/types/results.d.ts

@@ -15,9 +15,16 @@ export declare function toFilter(a: {
 }): ResultFilterInput;
 /** A head's free-text answer as one quotable line: no control characters, no double quotes. */
 export declare function quoteAnswer(text: string): string;
+/** The verdict in the API's words, from the snake_case result. */
+export declare function verdictText(v: NonNullable<ResultsOutput["verdict"]>): string;
+/**
+ * Who beats whom in one line: each compared pair once, the one more people put above the other
+ * first, strongest rows first ("Mushroom over Olives 71%, ...").
+ */
+export declare function headToHeadText(h: NonNullable<ResultsOutput["head_to_head"]>): string;
 /**
  * One paragraph for hosts that only show text: "Menu B wins by 36 points (68% to 32%).
- * Confidence high. 50 of 50 answered, complete, £10.00."
+ * Confidence high. 50 of 50 answered, complete, £10.00." With a go rule the verdict leads.
  */
 export declare function resultsText(r: ResultsOutput): string;
 export declare function toListItem(q: QuestionV2): ListQuestionsOutput["questions"][number];