prospectapis-mcp 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to `prospectapis-mcp` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html), independently of the API's version.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-02
+
+First release published to npm (0.1.0 was never published).
+
+### Changed
+
+- Licensed MIT; `private` removed; homepage https://prospectapis.com/mcp. The README configures the server
+  with `npx -y prospectapis-mcp`.
+
+### Added
+
+- `watchlist_create`, `watchlist_list`, `watchlist_deliveries`, `watchlist_test` and `watchlist_delete`
+  (`/v1/watchlists`) create funding watchlists that post matching rounds to your webhook, list them, read their
+  delivery log, send a test delivery and delete them.
+- `feedback_send` (`POST /v1/feedback`) reports a bug, a wrong field or a missing capability to the team.
+- `watchlist_get` (`GET /v1/watchlists/:id`) reads one watchlist, without its secret, so every watchlist route has a
+  tool.
+- `pricing_get` (`GET /pricing`, no key) returns the live price list, so an agent can quote a cost before a call.
+- `research_submit` (`POST /v1/research`, the arguments sent as a JSON body) starts a prospect research brief and
+  returns its `research_id`; `research_get` (`GET /v1/research/:id`) polls it. `research_submit` is the package's
+  first tool that is not read-only, and its `purpose` is `account_research`, `pre_call` or `outreach`.
+- A `503` from the API carries a hint, for research that is not priced yet.
+
+### Fixed
+
+- `funding_search` bounds `min_amount_usd` and `max_amount_usd` (0 to 999999999999999) and sends them as
+  fixed decimals with at most 4 places, so a float such as `0.1 + 0.2` no longer reaches the API as a value it
+  rejects.
+
+## [0.1.0] - 2026-10-01
+
+### Added
+
+- stdio MCP server built on `@modelcontextprotocol/sdk`, configured by `PROSPECTAPIS_API_KEY` and
+  `PROSPECTAPIS_BASE_URL` (default `https://api.prospectapis.com`).
+- `funding_search` (`GET /v1/funding`, every filter plus cursor paging), `funding_get`
+  (`GET /v1/funding/:id`), `account_balance` (`GET /v1/account`) and `api_version` (`GET /v1/version`), all
+  read-only.
+- API errors reach the model with the HTTP status, a short hint and the API's own body, so a rejected
+  filter is named and a 402 carries its top-up link.
+- `createServer` exported from `prospectapis-mcp/server` for hosts that supply their own fetch or auth.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProspectAPIs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# prospectapis-mcp
+
+MCP server for the ProspectAPIs funding data and research API. It gives an MCP client (Claude Desktop, Claude
+Code, Cursor and others) fourteen tools over `https://api.prospectapis.com`, one per customer endpoint (the
+liveness probe `GET /health` has none; `api_version` answers the same question). Five tools change state:
+`research_submit` (starts a paid research job), `watchlist_create`, `watchlist_test`, `watchlist_delete` and
+`feedback_send`; every other tool only reads.
+
+| Tool | Endpoint | Cost |
+|---|---|---|
+| `funding_search` | `GET /v1/funding` | $0.02 per record returned, after 100 free records a month; no match is free |
+| `funding_get` | `GET /v1/funding/:id` | $0.02 when found; a missing id is free |
+| `research_submit` | `POST /v1/research` | one research at `research_price_usd` (see `account_balance`), charged only when the brief completes; refunded on failure |
+| `research_get` | `GET /v1/research/:id` | free; poll until `status` is `completed` or `failed` |
+| `watchlist_create`, `watchlist_list`, `watchlist_get`, `watchlist_deliveries`, `watchlist_test`, `watchlist_delete` | `/v1/watchlists` | free to manage; a delivered event costs one record, only when your webhook answers 2xx |
+| `account_balance` | `GET /v1/account` | free |
+| `feedback_send` | `POST /v1/feedback` | free; reports a bug, wrong field or missing capability to the team (10 an hour per key) |
+| `pricing_get` | `GET /pricing` | free, no key needed; the live price list |
+| `api_version` | `GET /v1/version` | free, no key needed |
+
+`funding_search` filters: `since`, `until` (YYYY-MM-DD), `round` (comma list such as `seed,series_a`),
+`min_amount_usd`, `max_amount_usd`, `company`, `domain`, `investor`, `country`, `limit` (1 to 100) and
+`cursor` (the previous page's `next_cursor`, passed back unchanged).
+
+`research_submit` takes exactly one prospect identifier (`domain`, `website_url`, `company_name`,
+`company_linkedin_url`, a work `email` or `linkedin_url`), or `person_name` with `company_name`, plus an optional
+`context` (your own product, at most 1,000 characters) and `purpose` (`account_research`, `pre_call` or
+`outreach`). It returns a `research_id` at once; a brief takes 20 to 90 seconds.
+
+## Configure
+
+| Variable | Required | Default |
+|---|---|---|
+| `PROSPECTAPIS_API_KEY` | yes (all tools except `pricing_get` and `api_version`) | none |
+| `PROSPECTAPIS_BASE_URL` | no | `https://api.prospectapis.com` |
+
+Client config (for example `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "prospectapis": {
+      "command": "npx",
+      "args": ["-y", "prospectapis-mcp"],
+      "env": { "PROSPECTAPIS_API_KEY": "pa_live_..." }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add prospectapis -e PROSPECTAPIS_API_KEY=pa_live_... -- npx -y prospectapis-mcp`.
+
+## Develop
+
+```bash
+cd mcp
+npm install
+npm test        # mocked fetch over an in-memory MCP transport, no network
+npm run check
+```
+
+The package is versioned independently of the API (SemVer, `CHANGELOG.md` in this folder). It is marked
+`private` so it cannot be published by accident; publishing is done only from the product's own npm identity.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "prospectapis-mcp",
+  "version": "0.2.0",
+  "description": "MCP server for ProspectAPIs: search funding rounds, run paid prospect research briefs, manage funding watchlists, read your balance and the live price list.",
+  "type": "module",
+  "bin": {
+    "prospectapis-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "check": "node --check src/index.js && node --check src/server.js && node --check src/tools.js",
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "funding",
+    "venture-capital",
+    "prospecting",
+    "prospectapis",
+    "sales-research",
+    "agents"
+  ],
+  "homepage": "https://prospectapis.com/mcp",
+  "author": "ProspectAPIs",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// stdio entry point. Configuration comes from the MCP client's environment:
+//   PROSPECTAPIS_API_KEY    required for every tool except api_version
+//   PROSPECTAPIS_BASE_URL   optional, default https://api.prospectapis.com
+// Logs go to stderr: stdout is the protocol channel.
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TOOLS } from "./tools.js";
+import { createServer, DEFAULT_BASE_URL } from "./server.js";
+
+const API_KEY = process.env.PROSPECTAPIS_API_KEY;
+const BASE_URL = process.env.PROSPECTAPIS_BASE_URL || DEFAULT_BASE_URL;
+
+if (!API_KEY) {
+  console.error(
+    "[prospectapis-mcp] PROSPECTAPIS_API_KEY is not set. Tools are registered, but every call except api_version will fail until it is.",
+  );
+}
+
+async function main() {
+  const { server, baseUrl } = createServer({ apiKey: API_KEY, baseUrl: BASE_URL });
+  await server.connect(new StdioServerTransport());
+  console.error(`[prospectapis-mcp] ready, ${TOOLS.length} tools, base ${baseUrl}`);
+}
+
+main().catch((err) => {
+  console.error("[prospectapis-mcp] fatal:", err);
+  process.exit(1);
+});

package/src/server.js

@@ -0,0 +1,107 @@
+// MCP server wiring: one registered tool per catalog entry, each a single
+// authenticated request (a GET, or a POST with a JSON body for research_submit)
+// against the ProspectAPIs REST API. Exported as a factory
+// (createServer) so tests inject a fake fetch and a host could inject auth.
+
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TOOLS, buildUrl, buildPath, buildBody } from "./tools.js";
+
+export const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+
+export const DEFAULT_BASE_URL = "https://api.prospectapis.com";
+export const DEFAULT_TIMEOUT_MS = 30000;
+export const SIGNUP_URL = "https://prospectapis.com/signup?utm_source=mcp";
+export const TOP_UP_URL = "https://prospectapis.com/dashboard/credits?utm_source=mcp";
+
+export const INSTRUCTIONS =
+  "ProspectAPIs MCP server: funding rounds data and prospect research briefs. funding_search and funding_get cost $0.02 per record returned, " +
+  "after 100 free records per calendar month; a search that matches nothing costs nothing. account_balance, pricing_get and api_version are free. " +
+  "Use filters (dates, round, amount, domain, investor, country) to keep result sets small, and call account_balance before a large paged search. " +
+  "research_submit starts a cited brief on one prospect and returns a research_id; poll research_get (free) until it is completed or failed. " +
+  "A research is charged only when it completes, at the research_price_usd account_balance reports. " +
+  "If a call fails in a way the user has to work around, a field comes back wrong or empty, or a capability is missing, " +
+  "offer to report it with feedback_send (free); send only when the user agrees.";
+
+export function hintFor(status) {
+  if (status === 401) return " (missing or invalid API key: set PROSPECTAPIS_API_KEY to a key from the dashboard)";
+  // research never draws on free records, so the hint does not promise any (PR #23 review, L4)
+  if (status === 402) return ` (not enough credit for this call; the body says what it costs: top up at ${TOP_UP_URL})`;
+  if (status === 400) return " (an argument was rejected: the body says which one)";
+  if (status === 404) return " (not found: the id may be wrong, or the record is not published)";
+  if (status === 429) return " (rate limited: wait a few seconds and retry)";
+  if (status === 503) return " (unavailable: the body says why, for example research that is not priced yet)";
+  if (status >= 500) return " (server error: retry in a moment)";
+  return "";
+}
+
+export function createServer({
+  apiKey,
+  baseUrl = DEFAULT_BASE_URL,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  fetchImpl = fetch,
+  authHeaders = null,
+} = {}) {
+  const BASE_URL = String(baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const TIMEOUT = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  async function callEndpoint(tool, args) {
+    const needsKey = tool.auth !== false;
+    if (needsKey && !apiKey && !authHeaders) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Missing PROSPECTAPIS_API_KEY. Create a key at ${SIGNUP_URL}, set it in the MCP client config, then retry this call.`,
+          },
+        ],
+      };
+    }
+    const url = buildUrl(BASE_URL, tool, args);
+    const body = buildBody(tool, args);
+    const headers = {
+      accept: "application/json",
+      "user-agent": `prospectapis-mcp/${VERSION}`,
+      ...(body !== null ? { "content-type": "application/json" } : {}),
+      ...(needsKey ? authHeaders || { authorization: `Bearer ${apiKey}` } : {}),
+    };
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT);
+    try {
+      const res = await fetchImpl(url, {
+        method: tool.method || "GET",
+        headers,
+        ...(body !== null ? { body } : {}),
+        signal: ctrl.signal,
+      });
+      const text = await res.text();
+      if (!res.ok) {
+        // The API's own error body is passed through: it names the bad filter,
+        // and a 402 carries top_up_url for the user.
+        return { isError: true, content: [{ type: "text", text: `HTTP ${res.status}${hintFor(res.status)}: ${text.slice(0, 1500)}` }] };
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      const msg = err?.name === "AbortError" ? `timed out after ${TIMEOUT}ms` : err?.message || String(err);
+      return { isError: true, content: [{ type: "text", text: `Request failed: ${msg}` }] };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  const server = new McpServer({ name: "prospectapis", version: VERSION }, { instructions: INSTRUCTIONS });
+  for (const tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.shape,
+        annotations: { title: tool.name, readOnlyHint: !tool.write, destructiveHint: false, openWorldHint: true },
+      },
+      (args) => callEndpoint(tool, args),
+    );
+  }
+
+  return { server, callEndpoint, baseUrl: BASE_URL, timeoutMs: TIMEOUT, buildPath };
+}

package/src/tools.js

@@ -0,0 +1,268 @@
+// Tool catalog and pure request builders. Kept apart from the server wiring so
+// the catalog is unit-tested without a transport or a network.
+//
+// One tool per REST endpoint. Each entry is { name, path, method, shape, write }:
+//   - `shape` is the zod input schema; its keys map 1:1 to query parameters,
+//     except `{name}` placeholders in `path`, which are interpolated into the
+//     URL and removed from the query string;
+//   - `body: true` sends the arguments as a JSON body instead of a query
+//     string (research_submit, a POST);
+//   - `write: true` marks a tool that changes state or spends credits
+//     (research_submit starts a paid job); the server turns `write` into MCP's
+//     readOnlyHint, so every other tool is read-only;
+//   - `auth: false` marks the tools the API serves without a key (pricing_get, api_version).
+
+import { z } from "zod";
+
+// The API accepts an amount of at most 15 integer digits and 4 decimals
+// (AMOUNT_RE in apps/api/src/services/funding.js). Numbers are bounded here and
+// written as fixed decimals, so 0.1 + 0.2 or 1e21 can never reach the API as
+// "0.30000000000000004" or "1e+21" and come back as a 400.
+export const MAX_AMOUNT_USD = 999999999999999;
+export function formatAmount(v) {
+  return Number(v).toFixed(4).replace(/\.?0+$/, "");
+}
+const AMOUNT = z.number().nonnegative().max(MAX_AMOUNT_USD).optional();
+
+// The research purposes the API accepts (apps/api/src/services/research.js).
+export const RESEARCH_PURPOSES = ["account_research", "pre_call", "outreach"];
+const URL_ARG = z.string().min(1).max(2048);
+
+const DATE = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/, "YYYY-MM-DD")
+  .optional();
+
+export const TOOLS = [
+  {
+    name: "funding_search",
+    method: "GET",
+    path: "/v1/funding",
+    write: false,
+    format: { min_amount_usd: formatAmount, max_amount_usd: formatAmount },
+    description:
+      "Search funding rounds (venture rounds, debt, grants, IPOs), newest announcement first. Costs $0.02 per record returned, after 100 free records a month; a search that matches nothing is free. " +
+      "Page with `cursor`: pass back `next_cursor` exactly as returned; a null `next_cursor` means there are no more matches. Narrow with filters before raising `limit`.",
+    shape: {
+      since: DATE.describe("Earliest announcement date, inclusive (YYYY-MM-DD)."),
+      until: DATE.describe("Latest announcement date, inclusive (YYYY-MM-DD)."),
+      round: z
+        .string()
+        .optional()
+        .describe("Comma-separated round stages, for example `seed,series_a,series_b`."),
+      min_amount_usd: AMOUNT.describe("Smallest round size in USD."),
+      max_amount_usd: AMOUNT.describe("Largest round size in USD."),
+      company: z.string().min(1).max(100).optional().describe("Company name contains this text (case-insensitive)."),
+      domain: z.string().min(3).max(253).optional().describe("Exact company domain, for example `example.com`."),
+      investor: z.string().min(1).max(100).optional().describe("Exact investor name, case-insensitive."),
+      country: z.string().min(1).max(60).optional().describe("Headquarters country, case-insensitive."),
+      limit: z.number().int().min(1).max(100).optional().describe("Records per page, 1 to 100 (default 25). Each record returned is billed."),
+      cursor: z.string().max(200).optional().describe("Opaque cursor from the previous page's `next_cursor`."),
+    },
+  },
+  {
+    name: "funding_get",
+    method: "GET",
+    path: "/v1/funding/{id}",
+    write: false,
+    description: "Read one funding record by id. Costs $0.02 when found (free records are used first); a missing id is free.",
+    shape: {
+      id: z.string().uuid().describe("The funding record id from a `funding_search` result."),
+    },
+  },
+  {
+    name: "research_submit",
+    method: "POST",
+    path: "/v1/research",
+    write: true,
+    body: true,
+    description:
+      "Start a cited pre-call research brief on one prospect: company, funding, traction, competitors, news, people, risks, regions, " +
+      "plus a `fit` section when you pass `context`. Give exactly ONE identifier (domain, website_url, company_name, company_linkedin_url, " +
+      "a work email, or linkedin_url), or person_name together with company_name. Returns `research_id` at once; the brief takes 20 to 90 seconds, " +
+      "so poll research_get every 10 to 15 seconds until `status` is `completed` or `failed`. " +
+      "Costs one research at the price account_balance reports as `research_price_usd`, held when you submit, charged only when the brief " +
+      "completes and refunded in full if it fails. Free records do not apply.",
+    shape: {
+      domain: z.string().min(3).max(253).optional().describe("The company's domain, for example `acme.com`."),
+      website_url: URL_ARG.optional().describe("Any http(s) URL on the company's website."),
+      company_name: z.string().min(1).max(200).optional().describe("The company's name. With person_name, the company that person works at."),
+      company_linkedin_url: URL_ARG.optional().describe("The company's linkedin.com/company/... URL, used as a name hint only."),
+      email: z.string().min(3).max(254).optional().describe("A work email; its domain identifies the company. Free-mail addresses are refused."),
+      person_name: z.string().min(1).max(200).optional().describe("A person's name; needs company_name as well."),
+      linkedin_url: URL_ARG.optional().describe("A person's linkedin.com/in/... URL, used as a name hint only."),
+      context: z.string().min(1).max(1000).optional().describe("Your own product, at most 1,000 characters. Turns on the `fit` section."),
+      purpose: z
+        .enum(RESEARCH_PURPOSES)
+        .optional()
+        .describe("What the brief is for: `account_research` (default), `pre_call` (objections, discovery questions) or `outreach` (sourced hooks with draft first lines)."),
+    },
+  },
+  {
+    name: "research_get",
+    method: "GET",
+    path: "/v1/research/{id}",
+    write: false,
+    description:
+      "Read a research job by the `research_id` research_submit returned: `status` (queued, running, completed, failed), `input`, " +
+      "`result` (the brief, once completed) and `error` (once failed). Free; only your own account's jobs are visible.",
+    shape: {
+      id: z.string().uuid().describe("The `research_id` from research_submit."),
+    },
+  },
+  {
+    name: "watchlist_create",
+    method: "POST",
+    path: "/v1/watchlists",
+    body: true,
+    write: true,
+    description:
+      "Save a funding-signal alert: a set of funding_search filters plus an https webhook. Each NEW funding event that " +
+      "matches is POSTed to the webhook, signed with the returned `secret` (header Prospect-Signature: t=..,v1=HMAC-SHA256). " +
+      "Creating is free; each delivered event costs one record ($0.02, free records first), charged only when the webhook " +
+      "answers 2xx. The `secret` is shown once. Max 20 active per account.",
+    shape: {
+      name: z.string().min(1).max(100).describe("A label, such as 'Series A robotics'."),
+      filters: z
+        .object({
+          round: z.string().optional(),
+          min_amount_usd: z.number().nonnegative().optional(),
+          max_amount_usd: z.number().nonnegative().optional(),
+          company: z.string().optional(),
+          domain: z.string().optional(),
+          investor: z.string().optional(),
+          country: z.string().optional(),
+        })
+        .describe("At least one funding_search filter; date windows and paging do not apply to alerts."),
+      webhook_url: z.string().url().max(2048).describe("Your https endpoint on a public host."),
+    },
+  },
+  {
+    name: "watchlist_list",
+    method: "GET",
+    path: "/v1/watchlists",
+    write: false,
+    description: "Your funding-signal alerts (without their secrets). Free.",
+    shape: {},
+  },
+  {
+    name: "watchlist_get",
+    method: "GET",
+    path: "/v1/watchlists/{id}",
+    write: false,
+    description: "One funding-signal alert: its name, filters, webhook URL, whether it is active and why it was paused (never its secret). Free.",
+    shape: { id: z.string().uuid().describe("The watchlist id.") },
+  },
+  {
+    name: "watchlist_deliveries",
+    method: "GET",
+    path: "/v1/watchlists/{id}/deliveries",
+    write: false,
+    description: "The last 50 deliveries of one alert and their outcome (delivered, retry, failed, no_credit). Free.",
+    shape: { id: z.string().uuid().describe("The watchlist id.") },
+  },
+  {
+    name: "watchlist_test",
+    method: "POST",
+    path: "/v1/watchlists/{id}/test",
+    body: true,
+    write: true,
+    description: "Send a signed sample event to the alert's webhook now, to build and verify the receiver. Free; 5 a minute.",
+    shape: { id: z.string().uuid().describe("The watchlist id.") },
+  },
+  {
+    name: "watchlist_delete",
+    method: "DELETE",
+    path: "/v1/watchlists/{id}",
+    write: true,
+    description: "Delete a funding-signal alert and its delivery history. Free.",
+    shape: { id: z.string().uuid().describe("The watchlist id.") },
+  },
+  {
+    name: "account_balance",
+    method: "GET",
+    path: "/v1/account",
+    write: false,
+    description: "Your credit balance and the free records left this month. Free. Check it before a large paged search.",
+    shape: {},
+  },
+  {
+    name: "feedback_send",
+    method: "POST",
+    path: "/v1/feedback",
+    body: true,
+    write: true,
+    description:
+      "Report a bug, a wrong or empty field, a missing capability or a question about ProspectAPIs to the team. Free; " +
+      "limited to 10 delivered reports an hour per account (a 429 means wait, do not retry in a loop). Before reporting that a field is wrong or a parameter is ignored, re-run the " +
+      "call with a value that could only match if it were honoured. Put the exact call, what came back and what you " +
+      "expected in `details`; never include secrets or API keys. Send only when the user agrees.",
+    shape: {
+      kind: z.enum(["bug", "feature", "question"]).optional().describe("bug (default), feature or question."),
+      title: z.string().min(1).max(200).describe("One line: what is wrong or missing."),
+      details: z.string().min(1).max(8000).describe("The exact call, what came back, what you expected, and ids such as research_id."),
+      tool: z.string().regex(/^[a-z][a-z0-9_]{0,59}$/).optional().describe("The tool the report is about, such as research_get."),
+    },
+  },
+  {
+    name: "pricing_get",
+    method: "GET",
+    path: "/pricing",
+    write: false,
+    auth: false,
+    description:
+      "The live price list: funding records (price per record and free records a month), research (whether it is " +
+      "available and its price per brief) and watchlist deliveries. Free, needs no key. Use it to quote a cost before a large call.",
+    shape: {},
+  },
+  {
+    name: "api_version",
+    method: "GET",
+    path: "/v1/version",
+    write: false,
+    auth: false,
+    description: "The API's version and deployed build. Free, needs no key.",
+    shape: {},
+  },
+];
+
+export function buildQuery(args) {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(args || {})) {
+    if (v !== undefined && v !== null && String(v).length > 0) qs.set(k, String(v));
+  }
+  return qs.toString();
+}
+
+export function buildPath(template, args) {
+  const used = new Set();
+  const path = String(template).replace(/\{(\w+)\}/g, (_, k) => {
+    used.add(k);
+    const v = args?.[k];
+    return encodeURIComponent(v == null ? "" : String(v));
+  });
+  const rest = {};
+  for (const [k, v] of Object.entries(args || {})) if (!used.has(k)) rest[k] = v;
+  return { path, rest };
+}
+
+/** Full request URL for a tool call. A `body` tool sends no query string. */
+export function buildUrl(baseUrl, tool, args) {
+  const { path, rest } = buildPath(tool.path, args);
+  for (const [k, fmt] of Object.entries(tool.format || {})) {
+    if (rest[k] !== undefined && rest[k] !== null) rest[k] = fmt(rest[k]);
+  }
+  const q = tool.body ? "" : buildQuery(rest);
+  return `${String(baseUrl).replace(/\/+$/, "")}${path}${q ? `?${q}` : ""}`;
+}
+
+/** The JSON body for a `body` tool (null for every other tool): the arguments not used in the path, empty ones dropped. */
+export function buildBody(tool, args) {
+  if (!tool.body) return null;
+  const { rest } = buildPath(tool.path, args);
+  const out = {};
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== undefined && v !== null && !(typeof v === "string" && v.length === 0)) out[k] = v;
+  }
+  return JSON.stringify(out);
+}