@50heads/mcp 2026.925.1

package/dist/types/constants.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Names, versions and scopes shared by the server, the edge and the published package. No
+ * imports from private workspace packages, so the published types stay self-contained.
+ */
+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.925.1";
+/** Sent by the CLI on every request, so the API can tell releases apart. */
+export declare const USER_AGENT = "50heads-mcp/2026.925.1";
+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 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 search_help: null;
+    readonly send_feedback: null;
+};
+export type ToolName = keyof typeof TOOL_SCOPES;
+export declare const TOOL_NAMES: ToolName[];
+/** 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;
+export declare const PROMPT_SCOPES: Record<string, string | null>;

package/dist/types/draft.d.ts

@@ -0,0 +1,23 @@
+import type { FollowUpInput as ApiFollowUp, QuestionDraftInput, 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;
+/** 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;
+/** Image count for the pricing line: option images plus a stimulus image. */
+export declare function imageCount(d: QuestionDraftInput): number;
+/** API draft → the MCP question object (templates). */
+export declare function fromDraft(d: {
+    type: string;
+    text: string;
+    context?: string;
+    language: string;
+    options: QuestionOption[];
+    n: number;
+    tier: number;
+    rush?: boolean;
+    neither?: boolean;
+    reason?: string;
+}): Record<string, unknown>;

package/dist/types/errors.d.ts

@@ -0,0 +1,58 @@
+import { ProtocolError } from "@modelcontextprotocol/server";
+import { ApiRequestError } from "@50heads/shared/client";
+import type { ApiErrorDetails, ValidationIssue } from "@50heads/shared";
+/**
+ * The MCP error model (spec: "Safety and error model"). Every failure a model sees is a
+ * JSON-RPC error with `error.data.code`, a `retryable` hint and one plain sentence it can act on.
+ */
+export declare const ERROR_CODES: {
+    /** JSON-RPC Invalid Params: schema/content validation and unknown questions or tasks. */
+    readonly invalidParams: -32602;
+    /** Account and policy refusals the caller can fix (credits, caps, keys, content). */
+    readonly refused: -32001;
+    /** Transient: rate limits, kill switches, maintenance, upstream failures. */
+    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 McpErrorData = {
+    code: McpErrorCode;
+    retryable: boolean;
+    /** Milliseconds to wait before retrying, when known. */
+    retry_after_ms?: number;
+    validation?: ValidationIssue[];
+    credits_required?: number;
+    credits_available?: number;
+    top_up_url?: string;
+    cap_remaining?: number;
+    resets_at?: string;
+    category?: string;
+    scope?: string;
+    until?: string | null;
+    /** W3C trace id, for support. */
+    trace_id?: string;
+};
+/** A tool, resource, prompt or task failure, carried as a JSON-RPC error. */
+export declare class McpToolError extends ProtocolError {
+    readonly mcpCode: McpErrorCode;
+    readonly details: McpErrorData;
+    constructor(code: McpErrorCode, message: string, extra?: Omit<McpErrorData, "code" | "retryable"> & {
+        retryable?: boolean;
+    });
+}
+type Urls = {
+    portalUrl: string;
+};
+/** Reads `{ error: { details } }` (or loose extra fields) from an API error body. */
+export declare function apiErrorDetails(err: ApiRequestError): ApiErrorDetails;
+/** Next UTC midnight, when daily caps reset. */
+export declare function nextUtcMidnight(now?: number): string;
+/**
+ * Maps an API error onto the MCP error model. The API speaks `{ error: { code, message } }`
+ * with an HTTP status; codes are matched first, statuses second, so a new API code still lands
+ * somewhere sensible.
+ */
+export declare function fromApiError(err: ApiRequestError, urls: Urls, traceId?: string): McpToolError;
+/** Any thrown value as an McpToolError. */
+export declare function toMcpError(err: unknown, urls: Urls, traceId?: string): McpToolError;
+export {};

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

@@ -0,0 +1,6 @@
+/** The skill's version (front matter metadata.version); advertised as skillVersion. */
+export declare const SKILL_VERSION = "2026.925.1";
+/** 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";
+/** Every file in the skill bundle, by path relative to skills/50heads. */
+export declare const SKILL_FILES: Record<string, string>;

package/dist/types/idempotency.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Idempotency keys, derived per the MCP spec: the caller supplies one UUID per ask; the server
+ * derives the key it sends to the API from the caller's principal, the tool and that UUID, so
+ * the same UUID from two connections never collides, a retry from the same connection always
+ * replays, and variants and follow-ups get stable keys of their own without the caller
+ * inventing more UUIDs. Keys are opaque, fixed length and never contain the principal.
+ */
+export declare function sha256(text: string): Promise<string>;
+/**
+ * The key sent to the API as `Idempotency-Key`: "mcp_" + 43 base64url characters.
+ * `parts` extend the derivation (a variant's language, a follow-up's position).
+ */
+export declare function deriveIdempotencyKey(principal: string, tool: string, clientKey: string, ...parts: string[]): Promise<string>;
+/**
+ * A stable principal for a bearer token when the connection id is not known: a hash of the
+ * token itself (API keys never change for their lifetime; OAuth tokens carry `conn`).
+ */
+export declare function principalForToken(token: string | null | undefined): Promise<string>;
+/**
+ * Stable fingerprint of what was asked, to spot an idempotency key reused for a different
+ * question: the API replays the first question for a repeated key, and if that question's
+ * fingerprint differs from this request's, the key was reused.
+ */
+export declare function draftFingerprint(d: {
+    type: string;
+    text: string;
+    language?: string;
+    options?: {
+        label: string;
+        imageUrl?: string;
+    }[];
+    n?: number;
+    tier?: number;
+    reason?: string;
+}): string;

package/dist/types/language.d.ts

@@ -0,0 +1,10 @@
+import { QUESTION_LANGUAGES } from "@50heads/shared";
+/**
+ * A small, conservative language guess for questions that arrive without `language`. It only
+ * answers when the text is clearly one of the languages heads answer in; otherwise the server
+ * asks the caller (elicitation) rather than guess.
+ */
+type Lang = (typeof QUESTION_LANGUAGES)[number];
+/** A language code, or null when the text is not clearly one language. */
+export declare function detectLanguage(text: string): Lang | null;
+export {};

package/dist/types/manifest.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Discovery documents: the server card at /.well-known/mcp.json (and
+ * /.well-known/mcp/server-card.json) and server.json for the official MCP registry.
+ */
+export declare const REGISTRY_NAME = "com.50heads/mcp";
+export declare const NPM_PACKAGE = "@50heads/mcp";
+export declare const DESCRIPTION = "Ask fifty verified real people a five-second question and get the split back.";
+export type ManifestOptions = {
+    /** The hosted endpoint, https://mcp.50heads.com/mcp. */
+    endpoint?: string;
+    webUrl?: string;
+    resourceMetadataUrl?: string;
+};
+/** The server card: enough for a directory or host to connect without a round trip. */
+export declare function serverCard(opts?: ManifestOptions): {
+    $schema: string;
+    version: string;
+    protocolVersion: string;
+    supportedProtocolVersions: string[];
+    serverInfo: {
+        name: string;
+        title: string;
+        version: string;
+    };
+    description: string;
+    instructions: string;
+    iconUrl: string;
+    documentationUrl: string;
+    transport: {
+        type: string;
+        endpoint: string;
+    };
+    authentication: {
+        required: boolean;
+        schemes: string[];
+        resourceMetadata: string;
+        authorizationServers: string[];
+        scopes: ("questions:read" | "questions:write" | "templates:read" | "account:read")[];
+    };
+    capabilities: {
+        tools: {
+            listChanged: boolean;
+        };
+        resources: {
+            listChanged: boolean;
+        };
+        prompts: {
+            listChanged: boolean;
+        };
+        extensions: {
+            "io.modelcontextprotocol/tasks": {
+                methods: string[];
+                tools: string[];
+                pollIntervalMs: number;
+            };
+            "io.modelcontextprotocol/apps": {
+                mimeTypes: string[];
+                views: string[];
+            };
+            "com.50heads/skills": {
+                skillVersion: string;
+                skills: {
+                    name: string;
+                    version: string;
+                    uri: string;
+                    files: string[];
+                    download: string;
+                }[];
+            };
+            "com.50heads/auth": {
+                authorizationServer: string;
+                apiKeys: string;
+                resourceMetadata?: string | undefined;
+            };
+        };
+    };
+    tools: {
+        name: string;
+        scope: "questions:read" | "questions:write" | "account:read" | null;
+    }[];
+    resources: string[];
+    prompts: string[];
+    skillVersion: string;
+};
+/** server.json for the official MCP registry: the hosted remote and the npm stdio package. */
+export declare function registryServerJson(): {
+    $schema: string;
+    name: string;
+    title: string;
+    description: string;
+    version: string;
+    websiteUrl: string;
+    repository: {
+        url: string;
+        source: string;
+        subfolder: string;
+    };
+    icons: {
+        src: string;
+        mimeType: string;
+        sizes: string[];
+    }[];
+    remotes: {
+        type: string;
+        url: string;
+        headers: {
+            name: string;
+            description: string;
+            isRequired: boolean;
+            isSecret: boolean;
+        }[];
+    }[];
+    packages: {
+        registryType: string;
+        registryBaseUrl: string;
+        identifier: string;
+        version: string;
+        runtimeHint: string;
+        transport: {
+            type: string;
+        };
+        environmentVariables: {
+            name: string;
+            description: string;
+            isRequired: boolean;
+            isSecret: boolean;
+            format: string;
+        }[];
+    }[];
+    _meta: {
+        "io.modelcontextprotocol.registry/publisher-provided": {
+            categories: string[];
+            authorization: {
+                resourceMetadata: string;
+                authorizationServer: string;
+                scopes: ("questions:read" | "questions:write" | "templates:read" | "account:read")[];
+            };
+            skillVersion: string;
+        };
+    };
+};

package/dist/types/pricing.d.ts

@@ -0,0 +1,89 @@
+import { DISPLAY_CURRENCIES, type Rates } from "@50heads/shared";
+export type Currency = (typeof DISPLAY_CURRENCIES)[number];
+export type Price = {
+    amount: number;
+    currency: Currency;
+};
+export declare function isCurrency(value: unknown): value is Currency;
+/**
+ * The currency to show when the account's is unknown (signed out, or the balance could not be
+ * read). US dollars, so nothing reads as UK-only; a signed-in account always sees its own.
+ */
+export declare const UNKNOWN_CURRENCY: Currency;
+/**
+ * The locale an amount in a currency is written in, so each reads the way a banking app in its
+ * home market writes it: "£10.00", "$12.70" (US and Canadian dollars alike), "11,80 €".
+ */
+export declare const MONEY_LOCALES: Record<Currency, string>;
+export declare function moneyLocale(currency: string): string;
+/** Credits as money in a display currency, to the cent. The ledger stays in credits. */
+export declare function price(credits: number, currency: Currency, rates?: Rates): Price;
+/** "£17.00", "$21.59", "20,06 €", in the currency's own locale (moneyLocale). */
+export declare function formatPrice(p: {
+    amount: number;
+    currency: string;
+}, locale?: string): 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: {
+    amount: number;
+    currency: string;
+}): string;
+/** The pricing document: tier bases, multipliers and image bands, in one currency. */
+export declare function pricingTable(currency: Currency, rates?: Rates): {
+    currency: "GBP" | "USD" | "EUR" | "CAD";
+    creditValue: Price;
+    tiers: {
+        tier: 1 | 2 | 3;
+        name: string;
+        verified: string;
+        goodFor: string;
+        creditsPerAnswer: number;
+        pricePerAnswer: Price;
+        priceFor50: Price;
+    }[];
+    length: {
+        upToCharacters: number;
+        multiplier: number;
+    }[];
+    format: {
+        [k: string]: number;
+    };
+    reason: {
+        optional: number;
+        required: number;
+        note: string;
+    };
+    images: {
+        creditsPerImagePerAnswer: number;
+        creditsPerAudioPerAnswer: number;
+        note: string;
+    };
+    rush: {
+        multiplier: number;
+        note: string;
+    };
+    fiveSecond: {
+        multiplier: number;
+        note: string;
+    };
+    targeting: {
+        creditsPerTraitPerAnswer: number;
+        maxTraits: number;
+        note: string;
+    };
+    heads: {
+        min: 10;
+        max: 5000;
+        default: number;
+    };
+    connectionDailyCapDefault: Price;
+    formula: string;
+};
+/**
+ * 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
+ * in the account's own currency.
+ */
+export declare function pricingMarkdown(): string;

package/dist/types/public.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The published entry of @50heads/mcp (npm). Inside the monorepo, apps import src/index.ts,
+ * which also exposes the internals the hosted server needs.
+ *
+ * ```ts
+ * import { serveStdio } from "@modelcontextprotocol/server/stdio";
+ * import { serverFactory } from "@50heads/mcp";
+ * serveStdio(serverFactory({ apiKey: process.env.FIFTYHEADS_API_KEY }));
+ * ```
+ */
+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 { 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";
+export type ServerFactoryOptions = {
+    /** An API key (fh_live_…) or an OAuth access token for https://mcp.50heads.com/mcp. */
+    apiKey?: string | null;
+    /** Called before each API request when tokens rotate; wins over apiKey. */
+    token?: () => Promise<string | null>;
+    apiUrl?: string;
+    portalUrl?: string;
+    webUrl?: string;
+};
+/**
+ * A server factory for `serveStdio` or `createMcpHandler` from @modelcontextprotocol/server:
+ * the 50heads tools, resources and prompts, calling the 50heads API directly.
+ */
+export declare function serverFactory(options?: ServerFactoryOptions): (ctx: {
+    era: "modern" | "legacy";
+}) => Promise<McpServer>;
+/**
+ * Runs the full stdio server (tools, resources, prompts and tasks) on this process's stdin
+ * and stdout: what `npx @50heads/mcp` does.
+ */
+export declare function serveStdioServer(options?: ServerFactoryOptions): Promise<void>;

package/dist/types/question-types.d.ts

@@ -0,0 +1,18 @@
+import { type QuestionType } from "@50heads/shared";
+/**
+ * Per-type rules and examples. One source for the 50heads://question-types resource, the skill's
+ * references/question-types.md (generated) and the tool descriptions.
+ */
+export type QuestionTypeGuide = {
+    type: QuestionType;
+    title: string;
+    use: string;
+    options: string;
+    minTier: 1 | 2;
+    /** How a head answers, and what the distribution counts. */
+    answer: string;
+    example: Record<string, unknown>;
+};
+export declare const QUESTION_TYPE_GUIDES: Record<QuestionType, QuestionTypeGuide>;
+/** The markdown for the question-types resource and the skill reference. */
+export declare function questionTypesMarkdown(): string;

package/dist/types/results.d.ts

@@ -0,0 +1,29 @@
+import { type QuestionV2, type ResultFilterInput, type ResultV2 } from "@50heads/shared";
+import { type Currency } from "./pricing.js";
+import type { ListQuestionsOutput, ResultsOutput } from "./schemas.js";
+import type { Rates } from "@50heads/shared";
+/** ResultV2 (API, camelCase) → the MCP results object (snake_case). Never carries a head id. */
+export declare function toResults(r: ResultV2, currency: Currency, rates?: Rates): ResultsOutput;
+/** The MCP filter arguments (snake_case, `keyword`) → the API filter. */
+export declare function toFilter(a: {
+    option?: number;
+    tier?: number;
+    country?: string;
+    age_band?: string;
+    gender?: "woman" | "man" | "non_binary";
+    keyword?: string;
+}): ResultFilterInput;
+/** A head's free-text answer as one quotable line: no control characters, no double quotes. */
+export declare function quoteAnswer(text: string): 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."
+ */
+export declare function resultsText(r: ResultsOutput): string;
+export declare function toListItem(q: QuestionV2): ListQuestionsOutput["questions"][number];
+export declare function listText(items: ListQuestionsOutput["questions"]): string;
+/** How long a result may be cached: seconds while live, a day once settled. */
+export declare function resultsCacheHint(status: ResultsOutput["status"]): {
+    ttlMs: number;
+    cacheScope: "private";
+};