@50heads/mcp 2026.925.1

package/dist/snippets.js

@@ -0,0 +1,100 @@
+// src/snippets.ts
+var CLIENTS = ["claude-desktop", "claude-code", "cursor", "chatgpt", "vscode", "windsurf", "generic"];
+var json = (v) => JSON.stringify(v, null, 2);
+function configSnippets(options = {}) {
+  const url = options.url ?? "https://mcp.50heads.com/mcp";
+  const key = options.apiKey ?? "fh_live_\u2026";
+  const npx = { command: "npx", args: ["-y", "@50heads/mcp"], env: { FIFTYHEADS_API_KEY: key } };
+  return [
+    {
+      client: "claude-desktop",
+      title: "Claude (claude.ai and Claude Desktop)",
+      where: "Settings, Connectors, Add custom connector. Paste the URL and sign in when asked. On Team and Enterprise plans an owner adds it for the organisation first.",
+      auth: "oauth",
+      format: "text",
+      body: url,
+      alternative: {
+        where: "Or with an API key, in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\\Claude\\).",
+        format: "json",
+        body: json({ mcpServers: { "50heads": npx } })
+      }
+    },
+    {
+      client: "claude-code",
+      title: "Claude Code",
+      where: "Run in a terminal, then /mcp in Claude Code to sign in.",
+      auth: "oauth",
+      format: "shell",
+      body: `claude mcp add --transport http 50heads ${url}`,
+      alternative: {
+        where: "Or with an API key (CI and scripts):",
+        format: "shell",
+        body: `claude mcp add --transport http 50heads ${url} --header "Authorization: Bearer ${key}"`
+      }
+    },
+    {
+      client: "cursor",
+      title: "Cursor",
+      where: "~/.cursor/mcp.json (or .cursor/mcp.json in a project). Cursor opens the sign-in page.",
+      auth: "oauth",
+      format: "json",
+      body: json({ mcpServers: { "50heads": { url } } }),
+      alternative: {
+        where: "Or with an API key:",
+        format: "json",
+        body: json({ mcpServers: { "50heads": { url, headers: { Authorization: `Bearer ${key}` } } } })
+      }
+    },
+    {
+      client: "chatgpt",
+      title: "ChatGPT",
+      where: "Settings, Apps and Connectors, Advanced settings, turn on Developer mode, then Create. Paste the URL and choose OAuth. On Business and Enterprise plans an admin turns on Developer mode first.",
+      auth: "oauth",
+      format: "text",
+      body: url
+    },
+    {
+      client: "vscode",
+      title: "VS Code",
+      where: ".vscode/mcp.json in the workspace, or MCP: Add Server from the command palette.",
+      auth: "oauth",
+      format: "json",
+      body: json({ servers: { "50heads": { type: "http", url } } }),
+      alternative: {
+        where: "Or from a terminal:",
+        format: "shell",
+        body: `code --add-mcp '${JSON.stringify({ name: "50heads", type: "http", url })}'`
+      }
+    },
+    {
+      client: "windsurf",
+      title: "Windsurf",
+      where: "~/.codeium/windsurf/mcp_config.json, or Windsurf Settings, Cascade, MCP servers, View raw config.",
+      auth: "key",
+      format: "json",
+      body: json({ mcpServers: { "50heads": npx } }),
+      alternative: {
+        where: "Or the hosted server with an API key:",
+        format: "json",
+        body: json({ mcpServers: { "50heads": { serverUrl: url, headers: { Authorization: `Bearer ${key}` } } } })
+      }
+    },
+    {
+      client: "generic",
+      title: "Any other host",
+      where: "Hosts that launch a local command. Needs Node 20 or later and an API key from the dashboard.",
+      auth: "key",
+      format: "shell",
+      body: `FIFTYHEADS_API_KEY=${key} npx -y @50heads/mcp`,
+      alternative: {
+        where: `Hosts that speak Streamable HTTP: ${url} with the header "Authorization: Bearer ${key}", or OAuth.`,
+        format: "json",
+        body: json({ mcpServers: { "50heads": { url, headers: { Authorization: `Bearer ${key}` } } } })
+      }
+    }
+  ];
+}
+export {
+  CLIENTS,
+  configSnippets
+};

package/dist/types/account.d.ts

@@ -0,0 +1,22 @@
+import { type Rates } from "@50heads/shared";
+import type { Client } from "@50heads/shared/client";
+import { type Currency } from "./pricing.js";
+export type Money = {
+    currency: Currency;
+    rates: Rates;
+};
+/**
+ * The account's display currency and the day's rates, each fetched at most once per server
+ * (one request on HTTP, one connection on stdio) and shared by every tool, resource and task.
+ * The currency comes from the billing balance; when that cannot be read (signed out, no
+ * account:read, or the API failed) it is UNKNOWN_CURRENCY, never a silent pound. A failed read
+ * is not cached, so the next call tries again. An explicit currency argument always wins.
+ */
+export declare function accountMoney(api: (tag: string) => Client, canReadAccount: boolean): {
+    rates: () => Promise<Rates>;
+    currency: (explicit?: Currency | null) => Promise<Currency>;
+    /** Both, in parallel. */
+    money: (explicit?: Currency | null) => Promise<Money>;
+    /** Records a currency already read (the balance tool), so no second request is made. */
+    remember(c: Currency): void;
+};

package/dist/types/actions.d.ts

@@ -0,0 +1,53 @@
+import type { Client } from "@50heads/shared/client";
+import { type HelpSearchEntry } from "@50heads/shared/help-search";
+import { type BuildAskLinkInput, type GetAnswersOutput } from "./schemas.js";
+/**
+ * Helpers behind the tools added for PickFu parity: image upload, answer pages, the pre-filled
+ * ask link, the help index and targeting. Pure where possible, so they are tested directly.
+ */
+/** The real image type of some bytes, or null (JPEG, PNG and WebP only, like the API). */
+export declare function sniffImage(b: Uint8Array): "image/jpeg" | "image/png" | "image/webp" | null;
+/** base64 (or a data: URL) → bytes and type, with the reason in plain words when it fails. */
+export declare function decodeImage(data: string, declared?: string): {
+    bytes: Uint8Array;
+    contentType: string;
+};
+export type AnswerFilter = {
+    option?: number;
+    tier?: number;
+    country?: string;
+    age_band?: string;
+    gender?: string;
+    q?: string;
+};
+/** The filter as the API's query names (analysis.ts RESULT_FILTER_PARAMS). */
+export declare function filterParams(f: AnswerFilter): Record<string, string>;
+/**
+ * A page of answers. Uses the API's filtered, paginated answers endpoint when this API has it;
+ * otherwise reads the result and filters and pages here (option, tier and keyword; country and
+ * age band need the server, which can check that a segment is big enough to show).
+ */
+export declare function answersPage(api: Client, questionId: string, filter: AnswerFilter, page: {
+    limit: number;
+    cursor?: string;
+}): Promise<GetAnswersOutput>;
+/**
+ * The portal composer's query parameters (apps/web/app/lib/portal/composer.ts draftFromForm and
+ * the ask loader). Documented in the help centre and on /docs/mcp; keep the three in step.
+ */
+export declare function buildAskLink(portalUrl: string, input: BuildAskLinkInput): {
+    url: string;
+    params: {
+        name: string;
+        value: string;
+    }[];
+    notes: string[];
+};
+/** The published help index for a locale (/search/<locale>.json), cached for an hour. */
+export declare function helpIndex(webUrl: string, locale: string, fetchImpl: typeof fetch): Promise<HelpSearchEntry[]>;
+export declare function searchHelp(entries: HelpSearchEntry[], query: string, limit: number, webUrl: string): {
+    title: string;
+    section: string;
+    excerpt: string;
+    url: string;
+}[];

package/dist/types/apps.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP Apps (io.modelcontextprotocol/apps) views: the quote card for `estimate` and the results
+ * view for `get_results` and the results resource. Each is one self-contained HTML document:
+ * brand tokens inline, no external requests (fonts fall back to the brand's stacks), under
+ * 30 KB. They talk to the host over the MCP Apps postMessage protocol and also read
+ * `window.openai.toolOutput` on hosts that expose it.
+ */
+export declare const APP_MIME_TYPE = "text/html;profile=mcp-app";
+export declare const RESULTS_VIEW_URI = "ui://50heads/results.html";
+export declare const QUOTE_VIEW_URI = "ui://50heads/quote.html";
+/** The results view: winner line, bars, confidence, a follow-up button. */
+export declare function resultsViewHtml(): string;
+/** The quote card: cost and time in one sentence, the breakdown, fixes, an ask button. */
+export declare function quoteViewHtml(): string;
+/** `_meta` a tool or resource carries to declare its view. */
+export declare function uiMeta(uri: string): {
+    ui: {
+        resourceUri: string;
+    };
+    "ui/resourceUri": string;
+    "openai/outputTemplate": string;
+};