scrupp-mcp-server 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wism Corp
+
+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

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# Scrupp MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server over the Scrupp Jobs API, so an agent can pull leads without anyone
+writing HTTP calls. Ships as `scrupp-mcp-server` on npm and as a listing in the MCP
+registry; that registry is what a growing number of agent runtimes read when they pick
+a tool, which is why this is the channel where the buyer is not a person.
+
+## In Claude (no install)
+
+Add `https://mcp.scrupp.com/sn` as a custom connector in Claude and sign in to Scrupp.
+Setup steps, what each tool needs and troubleshooting: https://scrupp.com/docs/api/claude
+
+## In Claude Code (plugin)
+
+```
+/plugin install scrupp --marketplace Wism-Corp/scrupp-mcp-server
+```
+
+On Claude Code older than 2.1.275, in two steps:
+
+```
+/plugin marketplace add Wism-Corp/scrupp-mcp-server
+/plugin install scrupp@scrupp
+```
+
+The plugin connects Claude Code to the hosted connector at `https://mcp.scrupp.com/sn`,
+the same full tool set as the private Claude connector, so nothing is installed
+locally. The first time a tool runs, open `/mcp`, pick `scrupp` and sign in to Scrupp.
+
+The plugin carries two things:
+
+- `.mcp.json` — the hosted connector above, signed in with OAuth.
+- `skills/scrupp-prospecting` — how Claude should use the tools: check credits
+  first, pick the tool from what the user has, export five records as a sample
+  before the whole search, collect long jobs with `scrupp_get_job`, and what to
+  say when a tool refuses.
+
+Check it before a release with `claude plugin validate .`.
+
+## Using it
+
+```json
+{
+  "mcpServers": {
+    "scrupp": {
+      "command": "npx",
+      "args": ["-y", "scrupp-mcp-server"],
+      "env": { "SCRUPP_API_KEY": "sk_live_..." }
+    }
+  }
+}
+```
+
+`SCRUPP_WAIT_SECONDS` (default 120) caps how long a tool blocks. A job that outruns it
+comes back as `{ status: "running", job_id }` with a note telling the agent to call
+`scrupp_get_job` — better than holding a conversation open for twenty minutes on a
+2,500-record export.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `scrupp_export_sales_navigator_search` | People out of a Sales Navigator search URL |
+| `scrupp_export_linkedin_search` | People out of a LinkedIn people-search URL |
+| `scrupp_run_apollo_search` | People out of an Apollo search URL (needs a connected account) |
+| `scrupp_enrich_linkedin_profiles` | Full profile data for profile URLs |
+| `scrupp_lookup_company` | Company data by domain, LinkedIn URL or name |
+| `scrupp_find_decision_makers` | Who to write to at a company |
+| `scrupp_find_emails` | Verified work emails from name + domain |
+| `scrupp_verify_emails` | Deliverability check for addresses you already have (1 credit each) |
+| `scrupp_get_job` | Status and records for a job that was still running |
+| `scrupp_credits` | Remaining credits and plan |
+
+Every tool carries a `title` and `readOnlyHint` / `destructiveHint` annotations — the
+Claude connectors directory rejects a server without them.
+
+## Hosted connector (Streamable HTTP)
+
+`node src/http.js` (or `scrupp-mcp-http`) serves the same server over Streamable HTTP
+at `POST /mcp`, stateless, with `GET /health` for a load balancer. `PORT` defaults to
+8787. Each request authenticates with the caller's own key as
+`Authorization: Bearer sk_live_...`; the key is scoped to that request, so one process
+serves many accounts without mixing them up.
+
+The hosted connector exposes a **narrower tool set** than the local server: email
+finding, email verification, job status and credits. The tools that gather data from
+LinkedIn (Sales Navigator, LinkedIn search, profile enrichment) or answer from the
+shared lead base (company lookup, decision makers), and the Apollo export, stay
+local-only — they run through accounts that are not the caller's, which is not
+something to put in a public directory listing.
+
+Try it in Claude Code against a deployed instance:
+
+```bash
+claude mcp add --transport http scrupp https://mcp.scrupp.com/mcp \
+  --header "Authorization: Bearer sk_live_..."
+```
+
+### Private connector with the full API (`/sn`)
+
+`POST /sn` serves a second tool set for Scrupp customers who add it by URL
+(Claude.ai: Settings → Connectors → Add custom connector →
+`https://mcp.scrupp.com/sn`). It is not listed in the directory and works on
+every Scrupp plan. On top of the core tools it has the rest of the API:
+`scrupp_build_sales_navigator_search` (audience in words → a Sales Navigator
+search URL with the size Sales Navigator reports, no credits),
+`scrupp_export_sales_navigator_search`, `scrupp_export_linkedin_search`,
+`scrupp_run_apollo_search`, `scrupp_enrich_linkedin_profiles` (optionally with
+emails), `scrupp_lookup_company` and `scrupp_find_decision_makers`.
+
+All of them run only on the caller's own accounts connected with the Scrupp
+extension. The Scrupp API enforces that, not this server: with this key it
+hands out only the caller's own LinkedIn sessions and refuses the job when
+there is none.
+
+The OAuth resource is what tells the two apart: the protected-resource metadata
+for `/sn` names `https://mcp.scrupp.com/sn`, and app.scrupp.com issues the
+private connector's key (`connector:claude-sn`) only for that resource. A key
+from the `/mcp` connector gets 403 on everything beyond email finding even if
+it is sent to `/sn`.
+
+### Connecting with OAuth
+
+Users of Claude.ai, Claude Desktop and Claude Code don't paste a key: they press
+Connect, sign in to Scrupp and allow access. The server advertises its
+authorization server at `/.well-known/oauth-protected-resource` (RFC 9728) and answers
+an unauthenticated request with `401` and a `WWW-Authenticate` header pointing there.
+The authorization server itself lives in the Scrupp app at `app.scrupp.com`
+(`/oauth/register`, `/oauth/authorize`, `/oauth/token`); the access token it issues is
+an ordinary Scrupp API key marked `connector:claude`, which the API restricts to the
+four tools above. Access tokens last an hour, so the server checks the token before
+each request (cached for a minute) and answers `401 invalid_token` when it has expired,
+which is what makes the client refresh it.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `PORT` | `8787` | Listen port |
+| `MCP_PUBLIC_URL` | `https://mcp.scrupp.com` | Public URL of this server, used in the metadata |
+| `SCRUPP_AUTH_SERVER_URL` | `https://app.scrupp.com` | Where OAuth tokens are issued |
+| `SCRUPP_API_URL` | `https://api.scrupp.com/api/v1` | Scrupp API the tools call |
+
+Tool descriptions are written for a model, not a human: they say when to reach for the
+tool, not just what it does. That is the whole ranking signal in a registry — a listed
+server with vague descriptions gets picked and then misused.
+
+## Publishing
+
+1. Move this directory to its own repo, `Wism-Corp/scrupp-mcp-server` — the MCP registry
+   validates ownership from the repository and the `mcpName` in `package.json`.
+2. `npm publish --access public` with provenance from GitHub Actions, the same workflow
+   shape as `n8n-nodes-scrupp`.
+3. Publish the registry entry:
+   ```bash
+   npx @modelcontextprotocol/publisher login github
+   npx @modelcontextprotocol/publisher publish
+   ```
+   It reads `server.json`, checks the npm package carries the matching `mcpName`, and
+   lists the server.
+4. Then the downstream directories, which read from the registry or take a form:
+   Smithery, Glama, mcp.so, PulseMCP, and Anthropic's connectors directory.
+
+## Testing before publishing
+
+```bash
+npm install
+SCRUPP_API_KEY=... npx @modelcontextprotocol/inspector node src/index.js
+```
+
+Run `scrupp_credits` first (free), then `scrupp_find_emails` with two people — the
+cheapest call that exercises create → poll → result.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "scrupp-mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server for Scrupp \u2014 export LinkedIn, Sales Navigator and Apollo searches, find decision makers, and find and verify work emails",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "scrupp",
+    "linkedin",
+    "sales-navigator",
+    "apollo",
+    "lead-generation",
+    "email-finder"
+  ],
+  "license": "MIT",
+  "homepage": "https://scrupp.com/docs/api/integrations-jobs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wism-Corp/scrupp-mcp-server.git"
+  },
+  "type": "module",
+  "bin": {
+    "scrupp-mcp": "src/index.js",
+    "scrupp-mcp-http": "src/http.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "start:http": "node src/http.js"
+  },
+  "files": [
+    "src",
+    "server.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "mcpName": "io.github.wism-corp/scrupp",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "zod": "^3.24.0"
+  }
+}

package/server.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.wism-corp/scrupp",
+  "description": "Export LinkedIn, Sales Navigator and Apollo searches, find decision makers at a company, and find and verify work email addresses",
+  "repository": {
+    "url": "https://github.com/Wism-Corp/scrupp-mcp-server",
+    "source": "github"
+  },
+  "version": "0.2.0",
+  "websiteUrl": "https://scrupp.com/docs/api/integrations-jobs",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "scrupp-mcp-server",
+      "version": "0.2.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "SCRUPP_API_KEY",
+          "description": "Scrupp API key, from Settings → API Keys at app.scrupp.com",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "SCRUPP_WAIT_SECONDS",
+          "description": "How long a tool waits for a job before handing back its id instead. Default 120.",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

package/src/client.js

@@ -0,0 +1,149 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const BASE_URL = process.env.SCRUPP_API_URL ?? "https://api.scrupp.com/api/v1";
+
+// Over HTTP every request carries its own caller's key; over stdio there is one
+// caller and the key comes from the environment. Scoping the key to the request
+// keeps one shared process from ever answering with somebody else's account.
+const requestKey = new AsyncLocalStorage();
+
+export const withApiKey = (apiKey, fn) => requestKey.run(apiKey, fn);
+
+class ScruppError extends Error {
+	constructor(message, code, status) {
+		super(message);
+		this.name = "ScruppError";
+		this.code = code;
+		this.status = status;
+	}
+}
+
+async function call(path, { method = "GET", body, headers } = {}) {
+	const apiKey = requestKey.getStore() ?? process.env.SCRUPP_API_KEY;
+	if (!apiKey) {
+		throw new ScruppError("No Scrupp API key: set SCRUPP_API_KEY or send Authorization: Bearer.", "invalid_api_key");
+	}
+
+	const response = await fetch(`${BASE_URL}${path}`, {
+		method,
+		headers: {
+			Authorization: `Bearer ${apiKey}`,
+			"Content-Type": "application/json",
+			...headers,
+		},
+		body: body === undefined ? undefined : JSON.stringify(body),
+	});
+
+	const payload = await response.json().catch(() => ({}));
+
+	// A 409 on the result endpoint means "not finished yet" — the caller decides.
+	if (!response.ok && response.status !== 409) {
+		throw new ScruppError(
+			errorText(payload.message ?? payload.error, `Scrupp returned ${response.status}`),
+			payload.error_code ?? payload.error?.code,
+			response.status,
+		);
+	}
+
+	return { status: response.status, payload };
+}
+
+/**
+ * Scrupp answers errors in two shapes: `{message, error_code}` and
+ * `{error: {code, message}}` (the Jobs API). Passing the object straight into
+ * Error gave Claude "[object Object]" instead of the reason.
+ */
+export function errorText(error, fallback) {
+	if (typeof error === "string" && error) return error;
+	if (error && typeof error === "object" && typeof error.message === "string" && error.message) return error.message;
+	return fallback;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function ping() {
+	const { payload } = await call("/ping");
+	return payload;
+}
+
+export async function credits() {
+	const { payload } = await call("/account/credits");
+	return payload;
+}
+
+/** One address per call, one credit each — the API has no batch form. */
+export async function verifyEmail(email) {
+	const { payload } = await call("/email/verify", { method: "POST", body: { email } });
+	return payload;
+}
+
+/**
+ * Describe an audience in words, get a Sales Navigator search URL whose size
+ * Sales Navigator itself reported. No credits for records — it only builds.
+ */
+export async function buildSearch(prompt) {
+	const { payload } = await call("/search/build", { method: "POST", body: { prompt } });
+	return payload;
+}
+
+export async function createJob(type, input, idempotencyKey) {
+	const { payload } = await call("/jobs", {
+		method: "POST",
+		body: { type, input },
+		headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : undefined,
+	});
+	return payload;
+}
+
+export async function jobStatus(jobId) {
+	const { payload } = await call(`/jobs/${jobId}`);
+	return payload;
+}
+
+export async function jobResult(jobId) {
+	const { status, payload } = await call(`/jobs/${jobId}/result`);
+	return { ready: status === 200, payload };
+}
+
+/**
+ * Create a job and wait, but only for as long as an agent should reasonably
+ * block. If the job outlives that budget we hand back the job id rather than
+ * holding the conversation open — the agent can call `scrupp_get_job` later.
+ */
+export async function runJob({ type, input, idempotencyKey, waitSeconds }) {
+	const created = await createJob(type, input, idempotencyKey);
+	const deadline = Date.now() + waitSeconds * 1000;
+
+	while (Date.now() < deadline) {
+		const state = await jobStatus(created.job_id);
+
+		if (state.status === "failed") {
+			throw new ScruppError(
+				`Job ${created.job_id} failed: ${errorText(state.error, "unknown error")}`,
+				"upstream_error",
+			);
+		}
+
+		if (state.status === "succeeded") {
+			const { payload } = await jobResult(created.job_id);
+			return {
+				job_id: created.job_id,
+				status: "succeeded",
+				items: payload?.data?.items ?? [],
+			};
+		}
+
+		await sleep(Math.max(1, state.retry_after ?? 5) * 1000);
+	}
+
+	return {
+		job_id: created.job_id,
+		status: "running",
+		items: [],
+		note:
+			`The job is still running after ${waitSeconds}s. It keeps going on Scrupp — ` +
+			`call scrupp_get_job with job_id ${created.job_id} to collect the records.`,
+	};
+}
+
+export { ScruppError };

package/src/http.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * The hosted connector: Streamable HTTP, stateless, one server per request.
+ *
+ * Auth is a bearer token that the Scrupp API accepts: either a key the user
+ * pasted, or the key app.scrupp.com issued through OAuth when they pressed
+ * Connect in Claude. This server never sees a password or a code — it only
+ * points the client at the authorization server (RFC 9728) and forwards the
+ * token. What a connector key may reach is enforced by the API itself
+ * (ConnectorKeyGuard in the Scrupp app), not here.
+ */
+import { createServer as createHttpServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { credits, ScruppError, withApiKey } from "./client.js";
+import { createServer } from "./server.js";
+
+const PORT = Number(process.env.PORT ?? 8787);
+const MAX_BODY_BYTES = 1024 * 1024;
+// The public URL of this server and of the Scrupp app that issues its tokens.
+// Both are absolute in the metadata, so they come from config, not the request.
+const PUBLIC_URL = (process.env.MCP_PUBLIC_URL ?? "https://mcp.scrupp.com").replace(/\/$/, "");
+const AUTH_SERVER_URL = (process.env.SCRUPP_AUTH_SERVER_URL ?? "https://app.scrupp.com").replace(/\/$/, "");
+const RESOURCE_METADATA_URL = `${PUBLIC_URL}/.well-known/oauth-protected-resource`;
+
+/**
+ * Two connectors on one server. `/mcp` is the public one (emails only, listed
+ * in the Claude directory). `/sn` is the private Sales Navigator connector that
+ * customers add by URL. They differ in the OAuth resource: app.scrupp.com
+ * issues a Sales Navigator key only for the `/sn` resource, and the API, not
+ * this server, decides what each key may reach.
+ */
+const ENDPOINTS = {
+	"/mcp": { toolset: "core", metadataUrl: RESOURCE_METADATA_URL },
+	"/sn": { toolset: "sn", metadataUrl: `${RESOURCE_METADATA_URL}/sn` },
+};
+
+const resourceMetadata = (path) => ({
+	resource: `${PUBLIC_URL}${path}`,
+	authorization_servers: [AUTH_SERVER_URL],
+	bearer_methods_supported: ["header"],
+	resource_documentation: "https://scrupp.com/docs/api/claude",
+});
+
+// OAuth access tokens expire hourly. A client only refreshes on HTTP 401 from
+// this server, and a dead token would otherwise surface as a tool error inside
+// a 200 — the connector would just stop working after an hour. So the token is
+// checked before the request is handled, and the answer cached briefly.
+const TOKEN_CHECK_TTL_MS = 60 * 1000;
+const checkedTokens = new Map();
+
+async function tokenIsValid(apiKey) {
+	const cached = checkedTokens.get(apiKey);
+	if (cached && cached > Date.now()) {
+		return true;
+	}
+	try {
+		await withApiKey(apiKey, () => credits());
+	} catch (error) {
+		if (error instanceof ScruppError && (error.status === 401 || error.code === "invalid_api_key")) {
+			checkedTokens.delete(apiKey);
+			return false;
+		}
+		// Scrupp being down is not the token's fault: let the tool report it.
+		return true;
+	}
+	if (checkedTokens.size > 10000) {
+		checkedTokens.clear();
+	}
+	checkedTokens.set(apiKey, Date.now() + TOKEN_CHECK_TTL_MS);
+	return true;
+}
+
+const unauthorized = (res, metadataUrl, message, error) => {
+	res.setHeader(
+		"WWW-Authenticate",
+		`Bearer resource_metadata="${metadataUrl}"${error ? `, error="${error}"` : ""}`,
+	);
+	return reply(res, 401, { jsonrpc: "2.0", error: { code: -32001, message }, id: null });
+};
+
+const reply = (res, status, body) => {
+	res.writeHead(status, { "Content-Type": "application/json" });
+	res.end(JSON.stringify(body));
+};
+
+const readJson = (req) =>
+	new Promise((resolve, reject) => {
+		let size = 0;
+		const chunks = [];
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > MAX_BODY_BYTES) {
+				reject(new Error("Request body too large"));
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => {
+			try {
+				resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : undefined);
+			} catch (error) {
+				reject(error);
+			}
+		});
+		req.on("error", reject);
+	});
+
+const httpServer = createHttpServer(async (req, res) => {
+	const { pathname } = new URL(req.url, "http://localhost");
+
+	if (pathname === "/health") {
+		return reply(res, 200, { ok: true });
+	}
+	// RFC 9728: where a client learns which server issues tokens for a resource.
+	if (pathname === "/.well-known/oauth-protected-resource" || pathname === "/.well-known/oauth-protected-resource/mcp") {
+		return reply(res, 200, resourceMetadata("/mcp"));
+	}
+	if (pathname === "/.well-known/oauth-protected-resource/sn") {
+		return reply(res, 200, resourceMetadata("/sn"));
+	}
+	const endpoint = ENDPOINTS[pathname];
+	if (!endpoint) {
+		return reply(res, 404, { error: "not_found" });
+	}
+	// Stateless: no sessions to resume or close, so only POST means anything.
+	if (req.method !== "POST") {
+		return reply(res, 405, { jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed." }, id: null });
+	}
+
+	const apiKey = /^Bearer\s+(\S+)$/i.exec(req.headers.authorization ?? "")?.[1];
+	if (!apiKey) {
+		return unauthorized(res, endpoint.metadataUrl, "Connect your Scrupp account, or send a Scrupp API key as Authorization: Bearer <key>.");
+	}
+	if (!(await tokenIsValid(apiKey))) {
+		return unauthorized(res, endpoint.metadataUrl, "The Scrupp token is expired or revoked.", "invalid_token");
+	}
+
+	let body;
+	try {
+		body = await readJson(req);
+	} catch {
+		return reply(res, 400, { jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null });
+	}
+
+	const server = createServer({ toolset: endpoint.toolset });
+	const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+	res.on("close", () => {
+		transport.close();
+		server.close();
+	});
+
+	try {
+		await server.connect(transport);
+		await withApiKey(apiKey, () => transport.handleRequest(req, res, body));
+	} catch (error) {
+		console.error(error);
+		if (!res.headersSent) {
+			reply(res, 500, { jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null });
+		}
+	}
+});
+
+httpServer.listen(PORT, () => {
+	console.error(`Scrupp MCP connector listening on :${PORT}/mcp and :${PORT}/sn`);
+});

package/src/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+
+await createServer({ toolset: "full" }).connect(new StdioServerTransport());

package/src/server.js

@@ -0,0 +1,336 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { buildSearch, credits, jobResult, jobStatus, runJob, ScruppError, verifyEmail } from "./client.js";
+
+const DEFAULT_WAIT_SECONDS = Number(process.env.SCRUPP_WAIT_SECONDS ?? 120);
+
+/**
+ * Tool annotations the Claude connectors directory requires on every tool.
+ * Spending credits is not "read-only", but nothing a tool does deletes or
+ * overwrites the caller's data, so none of them is destructive.
+ */
+const READS = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+const SPENDS = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+
+/**
+ * `toolset: "full"` is every tool, for a user running the server on their own
+ * machine with their own key. `"core"` is what the hosted connector exposes:
+ * no tool that gathers data from LinkedIn or out of the shared lead base, only
+ * email finding and verification plus the bookkeeping tools. `"sn"` is the
+ * private connector (mcp.scrupp.com/sn): core plus the rest of the API —
+ * Sales Navigator search built from words, LinkedIn and Apollo searches,
+ * profiles, companies, decision makers — which the Scrupp API runs only on the
+ * caller's own connected accounts.
+ */
+export function createServer({ toolset = "full" } = {}) {
+	// Claude reads `instructions` when the server connects: the one place to point
+	// it at the setup guide, so a missing LinkedIn account or empty balance ends
+	// with a link the person can follow, not a guess.
+	const server = new McpServer(
+		{ name: "scrupp", version: "0.3.0" },
+		{
+			instructions:
+				"Scrupp setup guide and troubleshooting: https://scrupp.com/docs/api/claude. " +
+				"When a tool reports missing credits or no connected LinkedIn account, give the person " +
+				"the link from the error (or https://app.scrupp.com/app/plans for credits) and ask them to try again after.",
+		},
+	);
+	const full = toolset === "full";
+	const sn = toolset === "sn";
+
+	const json = (value) => ({
+		content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+	});
+
+	const failure = (error) => ({
+		isError: true,
+		content: [
+			{
+				type: "text",
+				text:
+					error instanceof ScruppError
+						? `${error.code ?? "error"}: ${error.message}`
+						: String(error?.message ?? error),
+			},
+		],
+	});
+
+	/**
+	 * Every extraction tool is the same shape, so register them from a table.
+	 * Keeping the descriptions concrete matters more here than anywhere else — the
+	 * caller choosing between these tools is a model reading exactly this text.
+	 */
+	function extractionTool({ name, title, description, schema, toInput, type }) {
+		server.registerTool(
+			name,
+			{
+				title,
+				description,
+				annotations: { title, ...SPENDS },
+				inputSchema: {
+					...schema,
+					wait_seconds: z
+						.number()
+						.int()
+						.min(0)
+						.optional()
+						.describe(
+							`How long to wait for the job before returning its id instead (default ${DEFAULT_WAIT_SECONDS}).`,
+						),
+				},
+			},
+			async (args) => {
+				try {
+					const jobType = typeof type === "function" ? type(args) : type;
+					const result = await runJob({
+						type: jobType,
+						input: toInput(args),
+						idempotencyKey: `mcp-${jobType}-${JSON.stringify(toInput(args))}`.slice(0, 200),
+						waitSeconds: args.wait_seconds ?? DEFAULT_WAIT_SECONDS,
+					});
+					return json(result);
+				} catch (error) {
+					return failure(error);
+				}
+			},
+		);
+	}
+
+	const searchSchema = {
+		url: z.string().url().describe("The search URL, copied from the platform after building the filters."),
+		with_emails: z.boolean().optional().describe("Also find work email addresses. Defaults to true."),
+		max: z
+			.number()
+			.int()
+			.min(1)
+			.optional()
+			.describe("Upper bound on records. Drives the credit hold; unused credits are refunded. Defaults to 100."),
+		account: z.string().optional().describe("Connected account email to run the search with."),
+	};
+
+	const searchInput = (args) => ({
+		url: args.url,
+		with_emails: args.with_emails ?? true,
+		max: args.max ?? 100,
+		...(args.account ? { account: args.account } : {}),
+	});
+
+	if (sn) {
+		server.registerTool(
+			"scrupp_build_sales_navigator_search",
+			{
+				title: "Build a Sales Navigator search",
+				annotations: { title: "Build a Sales Navigator search", readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+				description:
+					"Turn a plain-words audience (role, industry, country or cities, company size) into a Sales Navigator search URL, " +
+					"and report how many people Sales Navigator says it matches. Costs no credits. Runs on the user's own connected " +
+					"Sales Navigator account. Pass the returned `url` to scrupp_export_sales_navigator_search. If the size is far " +
+					"from what the user wants, rephrase the audience and build again before exporting.",
+				inputSchema: {
+					audience: z
+						.string()
+						.min(3)
+						.describe('The audience in words, e.g. "operations directors in logistics, United States, 50-200 employees".'),
+				},
+			},
+			async ({ audience }) => {
+				try {
+					return json(await buildSearch(audience));
+				} catch (error) {
+					return failure(error);
+				}
+			},
+		);
+
+		extractionTool({
+			name: "scrupp_export_sales_navigator_search",
+			title: "Export a Sales Navigator search",
+			description:
+				"Extract the people from a LinkedIn Sales Navigator search URL (linkedin.com/sales/search/people), with titles, " +
+				"companies and, by default, verified work emails. Runs only on the user's own Sales Navigator account connected " +
+				"with the Scrupp extension. One credit per record; check scrupp_credits first and start with a small `max` " +
+				"to confirm the list looks right before exporting the whole search.",
+			schema: {
+				...searchSchema,
+				account: z
+					.string()
+					.optional()
+					.describe("Which of the user's own connected LinkedIn accounts to use, by email. Defaults to one with Sales Navigator."),
+			},
+			toInput: searchInput,
+			type: "sales_navigator.search",
+		});
+	}
+
+	if (full) {
+		extractionTool({
+			name: "scrupp_export_sales_navigator_search",
+			title: "Export a Sales Navigator search",
+			description:
+				"Extract the people from a LinkedIn Sales Navigator search URL, with their titles, companies and (by default) verified work emails. Use this when the user has a Sales Navigator search they want as a list.",
+			schema: searchSchema,
+			toInput: searchInput,
+			type: "sales_navigator.search",
+		});
+	}
+
+	// The rest of the API. On the private connector every one of these runs on the
+	// user's own connected accounts only: the Scrupp API holds the connector's key
+	// to the caller's sessions and refuses rather than borrowing anyone else's.
+	const ownAccounts = sn
+		? " Runs only on the user's own accounts connected with the Scrupp extension; without one it is refused, never run on someone else's."
+		: "";
+
+	if (full || sn) {
+		extractionTool({
+			name: "scrupp_export_linkedin_search",
+			title: "Export a LinkedIn search",
+			description:
+				"Extract the people from a regular LinkedIn people-search URL. Use this for linkedin.com/search/results/people URLs; use the Sales Navigator tool for linkedin.com/sales URLs." + ownAccounts,
+			schema: searchSchema,
+			toInput: searchInput,
+			type: "linkedin.search",
+		});
+
+		extractionTool({
+			name: "scrupp_run_apollo_search",
+			title: "Run an Apollo search",
+			description:
+				"Extract the people from an Apollo search URL. Requires a connected Apollo account, passed as `account`." + ownAccounts,
+			schema: { ...searchSchema, account: z.string().describe("Connected Apollo account email. Required.") },
+			toInput: searchInput,
+			type: "apollo.search",
+		});
+
+		extractionTool({
+			name: "scrupp_enrich_linkedin_profiles",
+			title: "Enrich LinkedIn profiles",
+			description:
+				"Full profile data for LinkedIn profile URLs: current title, company, location, experience." + ownAccounts,
+			schema: {
+				profile_urls: z.array(z.string().url()).min(1).describe("LinkedIn profile URLs."),
+				with_emails: z
+					.boolean()
+					.optional()
+					.describe("Also find and verify work emails (billed per enriched profile plus per email found). Defaults to false."),
+			},
+			toInput: (args) => ({ items: args.profile_urls }),
+			type: (args) => (args.with_emails ? "email.linkedin" : "linkedin.profile"),
+		});
+
+		extractionTool({
+			name: "scrupp_lookup_company",
+			title: "Look up a company",
+			description:
+				"Company data — size, industry, location, website, LinkedIn — from a domain, a company LinkedIn URL, or a name." + ownAccounts,
+			schema: {
+				lookup_by: z.enum(["domain", "linkedin", "name"]).describe("What the values in `companies` are."),
+				companies: z.array(z.string()).min(1).describe("Domains, LinkedIn URLs or names."),
+			},
+			toInput: (args) => ({ items: args.companies }),
+			type: (args) => `company.${args.lookup_by}`,
+		});
+
+		extractionTool({
+			name: "scrupp_find_decision_makers",
+			title: "Find decision makers at a company",
+			description:
+				"The people worth writing to at a company you only know the domain, LinkedIn URL or name of. Returns names, titles and (where found) work emails." + ownAccounts,
+			schema: {
+				find_by: z.enum(["domain", "linkedin", "name"]).describe("What the values in `companies` are."),
+				companies: z.array(z.string()).min(1).describe("Domains, LinkedIn URLs or names."),
+				max: z.number().int().min(1).max(2500).optional().describe("Decision makers per company. Defaults to 10."),
+			},
+			toInput: (args) => ({ items: args.companies, max: args.max ?? 10 }),
+			type: (args) => `contact.decision_maker.${args.find_by}`,
+		});
+	}
+
+	extractionTool({
+		name: "scrupp_find_emails",
+		title: "Find work emails",
+		description:
+			"Find and verify work email addresses from first name, last name and company domain. Addresses that cannot be verified come back marked rather than guessed.",
+		schema: {
+			people: z
+				.array(
+					z.object({
+						first_name: z.string(),
+						last_name: z.string(),
+						domain: z.string().describe("Company domain, for example acme.com."),
+					}),
+				)
+				.min(1),
+		},
+		toInput: (args) => ({ items: args.people }),
+		type: "email.initials",
+	});
+
+	server.registerTool(
+		"scrupp_get_job",
+		{
+			title: "Check or collect a Scrupp job",
+			annotations: { title: "Check or collect a Scrupp job", ...READS },
+			description:
+				"Status of a job, and its records once it has finished. Use this for a job that was still running when the tool that started it returned.",
+			inputSchema: { job_id: z.number().int().describe("The job id returned by an extraction tool.") },
+		},
+		async ({ job_id }) => {
+			try {
+				const state = await jobStatus(job_id);
+				if (state.status !== "succeeded") {
+					return json(state);
+				}
+				const { payload } = await jobResult(job_id);
+				return json({ job_id, status: "succeeded", items: payload?.data?.items ?? [] });
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	);
+
+	server.registerTool(
+		"scrupp_credits",
+		{
+			title: "Credit balance",
+			annotations: { title: "Credit balance", ...READS },
+			description:
+				"Remaining Scrupp credits and the current plan. Worth checking before starting a large export — one credit is one record requested.",
+			inputSchema: {},
+		},
+		async () => {
+			try {
+				return json(await credits());
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	);
+
+	server.registerTool(
+		"scrupp_verify_emails",
+		{
+			title: "Verify email addresses",
+			annotations: { title: "Verify email addresses", ...SPENDS, idempotentHint: false },
+			description:
+				"Check whether email addresses are deliverable before sending to them. Costs one credit per address; use it on addresses you already have, not on ones scrupp_find_emails just returned (those are verified already).",
+			inputSchema: {
+				emails: z.array(z.string().email()).min(1).max(100).describe("Addresses to verify, at most 100 per call."),
+			},
+		},
+		async ({ emails }) => {
+			const results = [];
+			for (const email of emails) {
+				try {
+					results.push({ email, ...(await verifyEmail(email)) });
+				} catch (error) {
+					// One bad address must not throw away the answers already paid for.
+					results.push({ email, error: error?.message ?? String(error) });
+				}
+			}
+			return json({ results });
+		},
+	);
+
+	return server;
+}