prospectapis-mcp 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -6,6 +6,32 @@ All notable changes to `prospectapis-mcp` are documented here. The format follow
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-10-20
+
+### Added
+
+- Four playbooks, served as MCP resources (resources/list, resources/read) and as one prompt each (prompts/list, prompts/get), so a client can offer them as slash commands: newly funded prospects, pre-call brief, funding alerts to a webhook, and an investor's recent rounds. A prompt hands its playbook over as an embedded resource, so the recipe matches what resources/read serves, and a client that omits the optional `arguments` still gets it. Tests hold every name a playbook uses to the tool catalog.
+
+### Changed
+
+- The README's first sentence now names the product URL (https://prospectapis.com) and who it is for, because directory cards and search snippets copy that sentence alone and were linking GitHub only. A test pins both.
+- Added CODE_OF_CONDUCT.md (Contributor Covenant 2.1), which open-source programs ask for.
+
+## [0.2.4] - unreleased
+
+### Fixed
+
+- Every tool has a human title ("Search Funding Rounds", "Delete Watchlist"), sent as both the tool's `title` and `annotations.title`; before, the title was the raw tool name.
+- `watchlist_delete` now says `destructiveHint: true` (it removes the watchlist and its delivery history), so a client asks before running it; it said `false`, like every other tool. The other writes stay non-destructive: they only add a research job, a watchlist, a test event or a report.
+- `idempotentHint` is set where it is true: the free reads and `watchlist_delete`. `funding_search` and `funding_get` stay `false`, because every call that returns records is billed again. `openWorldHint` stays `true` on every tool.
+- One factory, `annotationsFor()` in `src/tools.js`, builds these annotations for the npm server and the hosted MCP door alike. `test/annotations.test.js` checks every served tool (a title that is not the raw name and has no underscore, every `*_delete` tool destructive and not read-only) and plants each regression to prove the check fails on it.
+
+- README opening rewritten for the listings that copy it word for word (Glama, mcpservers.org, the MCP Registry, npm): one paragraph on what the server does and costs, then the install lines and the website, plus a three-question FAQ. No tool or behaviour change; 14 tools.
+- `package-lock.json` carries the package version again (it still said 0.2.2).
+- `test/readme-opening.test.js` checks the opening against the package name, its Website line against `server.json` `websiteUrl`, every tool count the README states against `src/tools.js`, the stated Node floor against `engines`, and one version across `package.json`, `server.json` and `package-lock.json`.
+- The README no longer says every funding record carries its announcement URL: some records come back without one, so the opening and the FAQ now say records carry the public announcement URL when there is one, and `test/readme-opening.test.js` fails on any sentence that promises a URL on every record.
+- `test/package-scripts.test.js` checks that every file an npm script runs exists in the checkout.
+
 ## [0.2.3] - 2026-10-11
 
 ### Added

package/README.md

@@ -1,10 +1,12 @@
 # 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.
+prospectapis-mcp is the MCP server for ProspectAPIs (https://prospectapis.com), for sales and prospecting teams and the AI agents they run in Claude Code, Claude Desktop, Cursor and other MCP clients. It gives your agent fourteen tools over the ProspectAPIs API: search funding rounds by date, round, amount, company, investor and country, get new matching rounds pushed to your webhook, and order a cited research brief on any company or person. Funding records carry the public announcement URL when there is one. Records cost $0.02 each after 100 free a month, a completed brief costs $0.15, and there are no seats, no subscription and no card to sign up. It needs Node.js 22 or later.
+
+Install (Claude Code): `claude mcp add prospectapis -e PROSPECTAPIS_API_KEY=pa_live_... -- npx -y prospectapis-mcp`
+
+Other clients: run `npx -y prospectapis-mcp` with `PROSPECTAPIS_API_KEY` from https://prospectapis.com
+
+Website: https://prospectapis.com/mcp
 
 | Tool | Endpoint | Cost |
 |---|---|---|
@@ -50,6 +52,14 @@ Client config (for example `claude_desktop_config.json`):
 
 Claude Code: `claude mcp add prospectapis -e PROSPECTAPIS_API_KEY=pa_live_... -- npx -y prospectapis-mcp`.
 
+## FAQ
+
+**Where does the funding data come from?** Records carry the public announcement URL when there is one.
+
+**What is free?** 100 funding records a month, any search that matches nothing, watchlist management, and the balance, pricing and version tools.
+
+**Which clients work?** Claude Code, Claude Desktop, Cursor and any client that reads an mcpServers config, through `npx -y prospectapis-mcp`.
+
 ## Develop
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prospectapis-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "mcpName": "io.github.ProspectAPIs/prospectapis-mcp",
   "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",

package/src/playbooks.js

@@ -0,0 +1,113 @@
+// Playbooks: short recipes an agent runs with the tools in src/tools.js, served over the MCP RESOURCE primitive
+// (resources/list, resources/read) and offered as one PROMPT each (prompts/list, prompts/get), so a client can show
+// them as slash commands.
+//
+// WHY RESOURCES AND PROMPTS, NOT TOOLS. Every tool in src/tools.js is one REST endpoint (test/api-parity.test.js
+// holds the catalog to the API). A recipe wraps no endpoint; it is read-only context an agent fetches when it needs
+// it, which is what resources are for, and a prompt is how a client offers that recipe to a user.
+//
+// A DESCRIPTION IS LISTED, A BODY IS FETCHED. Clients show the title and description beside every tool, so those
+// state what the recipe does in plain product terms and never instruct the model. The body is returned only for a
+// URI or prompt the caller asked for by name, so it names tools freely.
+//
+// Every figure in a body (prices, page size, alert limit, poll interval) is the one the tool descriptions in
+// src/tools.js state, checked by review, not by a test. test/playbooks.test.js fails if a body names a tool,
+// parameter, value or response field the catalog does not have.
+
+export const PLAYBOOK_MIME = "text/markdown";
+
+const NEWLY_FUNDED = `# Newly funded prospects
+
+Build a short list of companies that just raised, worth reaching out to while the round is fresh.
+
+1. \`account_balance\` first. Each funding record returned costs $0.02 after 100 free a month, so know what is left
+   before you pull pages.
+2. \`funding_search\` with a tight window and the filters that describe the buyer: \`since\` (for example the last 30
+   days), \`round\` (such as \`seed,series_a\`), \`country\`, and \`min_amount_usd\` or \`max_amount_usd\`. Start with
+   \`limit\` 10 to 25. A search that matches nothing costs nothing, so narrow before you widen.
+3. Read the results. Each record has the company, its domain, the round, the amount, the investors and, when there is
+   one, the URL of the public announcement. Drop companies without a domain or outside the buyer profile.
+4. Page with \`cursor\` only if the first page is all good fits; pass \`next_cursor\` back exactly as returned. A null
+   \`next_cursor\` means there are no more matches.
+5. For the two or three best fits, run the pre-call brief playbook (\`research_submit\` with \`domain\`).
+6. Present the list as company, domain, round, amount, date, lead investors and the announcement URL where there is
+   one, so every line can be checked.
+`;
+
+const PRE_CALL_BRIEF = `# Pre-call brief
+
+A cited brief on one company or person before a call or a first email.
+
+1. \`research_submit\` with exactly ONE identifier: \`domain\` is best; otherwise \`website_url\`, \`company_name\`, a work
+   \`email\`, or \`person_name\` together with \`company_name\`. Set \`purpose\` to \`pre_call\` for objections and discovery
+   questions, or \`outreach\` for sourced hooks with draft first lines. Add \`context\` (your own product, up to 1,000
+   characters) to get a \`fit\` section.
+2. It returns \`research_id\` at once. The brief takes 20 to 90 seconds: call \`research_get\` with that id every 10 to 15
+   seconds until \`status\` is \`completed\` or \`failed\`. Polling is free.
+3. A brief is charged only when it completes, at the \`research_price_usd\` that \`account_balance\` reports, and refunded
+   in full if it fails. Free records do not apply to research.
+4. Every field in \`result\` is \`{value, sources, confidence}\`. Quote the sources with the claims you use, and say when
+   a field came back empty rather than filling the gap.
+`;
+
+const FUNDING_ALERTS = `# Funding alerts to a webhook
+
+Get every new funding round that matches a profile pushed to your own endpoint, instead of searching again.
+
+1. Decide the filters with \`funding_search\` first (\`round\`, \`country\`, \`min_amount_usd\`, \`max_amount_usd\`,
+   \`investor\`, \`company\` or \`domain\`), and check the results look right. Date windows and paging do not apply to an
+   alert.
+2. \`watchlist_create\` with a \`name\`, those \`filters\` and an https \`webhook_url\` on a public host. Save the \`secret\`
+   it returns: it is shown once, and every delivery is signed with it in the Prospect-Signature header
+   (t=..,v1=HMAC-SHA256). Creating is free; each delivered event costs one record, charged only when your webhook
+   answers 2xx. An account can have 20 active alerts.
+3. \`watchlist_test\` sends a signed sample event now, so the receiver can be built and checked before a real round
+   arrives. Free, 5 a minute.
+4. Later, \`watchlist_deliveries\` shows the last 50 deliveries and their outcome (delivered, retry, failed,
+   no_credit), and \`watchlist_get\` shows whether the alert is active and why it was paused.
+`;
+
+const INVESTOR_ROUNDS = `# An investor's recent rounds
+
+See which companies an investor has backed lately, to find warm introductions or a portfolio to sell into.
+
+1. \`funding_search\` with \`investor\` set to the investor's exact name (case-insensitive) and a \`since\` date, newest
+   first. Add \`round\` to keep to one stage.
+2. Each record lists every investor named and the lead investors, so you can tell a lead from a participation.
+3. Group the results by round and by country, and give the announcement URL with each line that has one.
+4. To follow this investor from now on, run the funding alerts playbook with \`investor\` as the filter.
+`;
+
+export const PLAYBOOKS = Object.freeze([
+  {
+    name: "newly-funded-prospects",
+    uri: "prospectapis://playbooks/newly-funded-prospects",
+    title: "Newly funded prospects",
+    description: "Build a short list of companies that raised recently, filtered by round, country and amount, with the announcement for each.",
+    text: NEWLY_FUNDED,
+    prompt: { arg: "profile", describe: "Who you sell to, for example 'seed and Series A fintech in the US'.", ask: (v) => `Run this playbook for: ${v}` },
+  },
+  {
+    name: "pre-call-brief",
+    uri: "prospectapis://playbooks/pre-call-brief",
+    title: "Pre-call brief",
+    description: "A cited research brief on one company or person before a call or a first email.",
+    text: PRE_CALL_BRIEF,
+    prompt: { arg: "prospect", describe: "The company domain, company name, or person and company.", ask: (v) => `Run this playbook for: ${v}` },
+  },
+  {
+    name: "funding-alerts",
+    uri: "prospectapis://playbooks/funding-alerts",
+    title: "Funding alerts to a webhook",
+    description: "Push every new funding round that matches a profile to your own https endpoint, signed, instead of searching again.",
+    text: FUNDING_ALERTS,
+  },
+  {
+    name: "investor-rounds",
+    uri: "prospectapis://playbooks/investor-rounds",
+    title: "An investor's recent rounds",
+    description: "The companies one investor has backed lately, split into lead and participation, with sources.",
+    text: INVESTOR_ROUNDS,
+    prompt: { arg: "investor", describe: "The investor's name, for example 'Example Ventures'.", ask: (v) => `Run this playbook for: ${v}` },
+  },
+]);

package/src/server.js

@@ -5,7 +5,10 @@
 
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { TOOLS, buildUrl, buildPath, buildBody } from "./tools.js";
+import { TOOLS, buildUrl, buildPath, buildBody, annotationsFor } from "./tools.js";
+import { z } from "zod";
+import { GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { PLAYBOOKS, PLAYBOOK_MIME } from "./playbooks.js";
 
 export const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 
@@ -91,13 +94,60 @@ export function createServer({
   }
 
   const server = new McpServer({ name: "prospectapis", version: VERSION }, { instructions: INSTRUCTIONS });
+
+  // Playbooks (src/playbooks.js): each one a resource (resources/list, resources/read) and a prompt (prompts/list,
+  // prompts/get). The prompt hands the playbook over as an embedded resource, so the recipe a user picks is exactly
+  // the one resources/read serves. Registering either declares that capability, which a server with none does not
+  // advertise.
+  for (const p of PLAYBOOKS) {
+    server.registerResource(
+      p.name,
+      p.uri,
+      { title: p.title, description: p.description, mimeType: PLAYBOOK_MIME },
+      async (uri) => ({ contents: [{ uri: uri.href, mimeType: PLAYBOOK_MIME, text: p.text }] }),
+    );
+  }
+  // `arguments` is optional on prompts/get (MCP spec), but the SDK validates a prompt that declares arguments against
+  // a required object, so a client that leaves it out would get -32602 for an argument it was told is optional. The
+  // SDK installs its prompts/get handler through the low-level Server the first time a prompt is registered; wrapping
+  // setRequestHandler before that defaults a missing `arguments` to {} and leaves every other request untouched.
+  {
+    const low = server.server;
+    const setRequestHandler = low.setRequestHandler.bind(low);
+    low.setRequestHandler = (schema, handler) =>
+      setRequestHandler(
+        schema,
+        schema === GetPromptRequestSchema
+          ? (request, extra) => handler({ ...request, params: { ...request.params, arguments: request.params?.arguments ?? {} } }, extra)
+          : handler,
+      );
+  }
+  for (const p of PLAYBOOKS) {
+    const argsSchema = p.prompt ? { [p.prompt.arg]: z.string().max(200).optional().describe(p.prompt.describe) } : undefined;
+    server.registerPrompt(
+      p.name,
+      { title: p.title, description: p.description, ...(argsSchema ? { argsSchema } : {}) },
+      async (args = {}) => {
+        const v = p.prompt ? String(args[p.prompt.arg] ?? "").trim() : "";
+        return {
+          description: p.description,
+          messages: [
+            { role: "user", content: { type: "resource", resource: { uri: p.uri, mimeType: PLAYBOOK_MIME, text: p.text } } },
+            { role: "user", content: { type: "text", text: p.prompt && v ? p.prompt.ask(v) : "Run this playbook." } },
+          ],
+        };
+      },
+    );
+  }
+
   for (const tool of TOOLS) {
     server.registerTool(
       tool.name,
       {
+        title: tool.title,
         description: tool.description,
         inputSchema: tool.shape,
-        annotations: { title: tool.name, readOnlyHint: !tool.write, destructiveHint: false, openWorldHint: true },
+        annotations: annotationsFor(tool),
       },
       (args) => callEndpoint(tool, args),
     );

package/src/tools.js

@@ -10,7 +10,13 @@
 //   - `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).
+//   - `auth: false` marks the tools the API serves without a key (pricing_get, api_version);
+//   - `title` is the human name a client shows instead of the raw tool name;
+//   - `idempotent: true` marks a tool whose repeat call with the same arguments changes nothing more: the free
+//     reads, and watchlist_delete (a second delete finds nothing to delete). funding_search and funding_get are
+//     read-only but NOT idempotent, because every call that returns records is billed again.
+// annotationsFor() below turns these fields into MCP tool annotations; the npm server and the hosted door
+// (apps/api/src/lib/mcp-door.js, through createServer) both register every tool with it, so they cannot drift.
 
 import { z } from "zod";
 
@@ -38,6 +44,7 @@ export const TOOLS = [
     name: "funding_search",
     method: "GET",
     path: "/v1/funding",
+    title: "Search Funding Rounds",
     write: false,
     format: { min_amount_usd: formatAmount, max_amount_usd: formatAmount },
     description:
@@ -55,7 +62,7 @@ export const TOOLS = [
       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."),
+      country: z.string().min(1).max(60).optional().describe("Headquarters country as a name or ISO code, such as US, United States or DE. Other text, such as a city, matches the stated location."),
       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`."),
     },
@@ -64,6 +71,7 @@ export const TOOLS = [
     name: "funding_get",
     method: "GET",
     path: "/v1/funding/{id}",
+    title: "Get Funding Round",
     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: {
@@ -74,6 +82,7 @@ export const TOOLS = [
     name: "research_submit",
     method: "POST",
     path: "/v1/research",
+    title: "Start Prospect Research",
     write: true,
     body: true,
     description:
@@ -103,6 +112,8 @@ export const TOOLS = [
     name: "research_get",
     method: "GET",
     path: "/v1/research/{id}",
+    title: "Get Research Brief",
+    idempotent: true,
     write: false,
     description:
       "Read a research job by the `research_id` research_submit returned: `status` (queued, running, completed, failed), `input`, " +
@@ -118,6 +129,7 @@ export const TOOLS = [
     name: "watchlist_create",
     method: "POST",
     path: "/v1/watchlists",
+    title: "Create Funding Watchlist",
     body: true,
     write: true,
     description:
@@ -145,6 +157,8 @@ export const TOOLS = [
     name: "watchlist_list",
     method: "GET",
     path: "/v1/watchlists",
+    title: "List Watchlists",
+    idempotent: true,
     write: false,
     description: "Your funding-signal alerts (without their secrets). Free.",
     shape: {},
@@ -153,6 +167,8 @@ export const TOOLS = [
     name: "watchlist_get",
     method: "GET",
     path: "/v1/watchlists/{id}",
+    title: "Get Watchlist",
+    idempotent: true,
     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.") },
@@ -161,6 +177,8 @@ export const TOOLS = [
     name: "watchlist_deliveries",
     method: "GET",
     path: "/v1/watchlists/{id}/deliveries",
+    title: "List Watchlist Deliveries",
+    idempotent: true,
     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.") },
@@ -169,6 +187,7 @@ export const TOOLS = [
     name: "watchlist_test",
     method: "POST",
     path: "/v1/watchlists/{id}/test",
+    title: "Send Watchlist Test Event",
     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.",
@@ -178,6 +197,8 @@ export const TOOLS = [
     name: "watchlist_delete",
     method: "DELETE",
     path: "/v1/watchlists/{id}",
+    title: "Delete Watchlist",
+    idempotent: true,
     write: true,
     description: "Delete a funding-signal alert and its delivery history. Free.",
     shape: { id: z.string().uuid().describe("The watchlist id.") },
@@ -186,6 +207,8 @@ export const TOOLS = [
     name: "account_balance",
     method: "GET",
     path: "/v1/account",
+    title: "Get Account Balance",
+    idempotent: true,
     write: false,
     description: "Your credit balance and the free records left this month. Free. Check it before a large paged search.",
     shape: {},
@@ -194,6 +217,7 @@ export const TOOLS = [
     name: "feedback_send",
     method: "POST",
     path: "/v1/feedback",
+    title: "Send Feedback",
     body: true,
     write: true,
     description:
@@ -212,6 +236,8 @@ export const TOOLS = [
     name: "pricing_get",
     method: "GET",
     path: "/pricing",
+    title: "Get Pricing",
+    idempotent: true,
     write: false,
     auth: false,
     description:
@@ -223,6 +249,8 @@ export const TOOLS = [
     name: "api_version",
     method: "GET",
     path: "/v1/version",
+    title: "Get API Version",
+    idempotent: true,
     write: false,
     auth: false,
     description: "The API's version and deployed build. Free, needs no key.",
@@ -270,3 +298,17 @@ export function buildBody(tool, args) {
   }
   return JSON.stringify(out);
 }
+
+// The one place a catalog entry becomes MCP tool annotations. A tool is destructive when it is a write whose
+// method is DELETE (watchlist_delete removes the watchlist and its delivery history); every other write only adds
+// (a research job, a watchlist, a test event, a report), so it is a write that is not destructive.
+export function annotationsFor(tool) {
+  const write = !!tool.write;
+  return {
+    title: tool.title,
+    readOnlyHint: !write,
+    destructiveHint: write && tool.method === "DELETE",
+    idempotentHint: !!tool.idempotent,
+    openWorldHint: true,
+  };
+}