scrupp-mcp-server 0.2.0 → 0.2.1

package/README.md

@@ -108,10 +108,10 @@ search URL with the size Sales Navigator reports, no credits),
 `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.
+When the caller has a LinkedIn account with Sales Navigator connected with the
+Scrupp extension, all of them run only on that account. Without one, they run
+on Scrupp's shared account pool, which is open to paid plans. The Scrupp API
+decides this, not this server.
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrupp-mcp-server",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server for Scrupp \u2014 export LinkedIn, Sales Navigator and Apollo searches, find decision makers, and find and verify work emails",
   "keywords": [
     "mcp",
@@ -20,6 +20,7 @@
   },
   "type": "module",
   "bin": {
+    "scrupp-mcp-server": "src/index.js",
     "scrupp-mcp": "src/index.js",
     "scrupp-mcp-http": "src/http.js"
   },

package/server.json

@@ -6,14 +6,14 @@
     "url": "https://github.com/Wism-Corp/scrupp-mcp-server",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.2.1",
   "websiteUrl": "https://scrupp.com/docs/api/integrations-jobs",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "scrupp-mcp-server",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "transport": {
         "type": "stdio"
       },

package/src/client.js

@@ -18,7 +18,7 @@ class ScruppError extends Error {
 	}
 }
 
-async function call(path, { method = "GET", body, headers } = {}) {
+async function call(path, { method = "GET", body, headers, notReadyOk = false } = {}) {
 	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");
@@ -37,7 +37,10 @@ async function call(path, { method = "GET", body, headers } = {}) {
 	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) {
+	// Anywhere else a 409 is a refusal (e.g. an Idempotency-Key reused with a
+	// different body on POST /jobs); letting it through as success made the
+	// caller poll /jobs/undefined and show the connector guard's 403 instead.
+	if (!response.ok && !(notReadyOk && response.status === 409)) {
 		throw new ScruppError(
 			errorText(payload.message ?? payload.error, `Scrupp returned ${response.status}`),
 			payload.error_code ?? payload.error?.code,
@@ -101,7 +104,7 @@ export async function jobStatus(jobId) {
 }
 
 export async function jobResult(jobId) {
-	const { status, payload } = await call(`/jobs/${jobId}/result`);
+	const { status, payload } = await call(`/jobs/${jobId}/result`, { notReadyOk: true });
 	return { ready: status === 200, payload };
 }
 

package/src/server.js

@@ -1,7 +1,21 @@
+import { createHash } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { buildSearch, credits, jobResult, jobStatus, runJob, ScruppError, verifyEmail } from "./client.js";
 
+/**
+ * Idempotency-Key for one tool call: a hash of the whole input, not its first
+ * 200 characters. Two Sales Navigator URLs share a long prefix, so the
+ * truncated form gave two different searches the same key and Scrupp refused
+ * the second with 409 idempotency_key_reused. The ten-minute bucket keeps
+ * client retries of one call deduplicated without replaying an old job when
+ * the person deliberately runs the same search again later.
+ */
+export function idempotencyKeyFor(jobType, input, now = Date.now()) {
+	const digest = createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 32);
+	return `mcp-${jobType}-${digest}-${Math.floor(now / 600_000)}`;
+}
+
 const DEFAULT_WAIT_SECONDS = Number(process.env.SCRUPP_WAIT_SECONDS ?? 120);
 
 /**
@@ -19,8 +33,9 @@ const SPENDS = { readOnlyHint: false, destructiveHint: false, idempotentHint: tr
  * 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.
+ * profiles, companies, decision makers — which the Scrupp API runs on the
+ * caller's own LinkedIn account with Sales Navigator when one is connected, and
+ * otherwise on Scrupp's shared account pool (paid plans).
  */
 export function createServer({ toolset = "full" } = {}) {
 	// Claude reads `instructions` when the server connects: the one place to point
@@ -85,7 +100,7 @@ export function createServer({ toolset = "full" } = {}) {
 					const result = await runJob({
 						type: jobType,
 						input: toInput(args),
-						idempotencyKey: `mcp-${jobType}-${JSON.stringify(toInput(args))}`.slice(0, 200),
+						idempotencyKey: idempotencyKeyFor(jobType, toInput(args)),
 						waitSeconds: args.wait_seconds ?? DEFAULT_WAIT_SECONDS,
 					});
 					return json(result);
@@ -124,7 +139,7 @@ export function createServer({ toolset = "full" } = {}) {
 				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 " +
+					"Sales Navigator account when there is one, otherwise on Scrupp's shared account pool (paid plans). 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
@@ -147,8 +162,8 @@ export function createServer({ toolset = "full" } = {}) {
 			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` " +
+				"companies and, by default, verified work emails. Runs on the user's own Sales Navigator account connected " +
+				"with the Scrupp extension when there is one, otherwise on Scrupp's shared account pool (paid plans). 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,
@@ -174,11 +189,12 @@ export function createServer({ toolset = "full" } = {}) {
 		});
 	}
 
-	// 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.
+	// The rest of the API. On the private connector the Scrupp API decides whose
+	// session runs each job: the caller's own LinkedIn account with Sales
+	// Navigator when one is connected, otherwise the shared account pool, which
+	// is open to paid plans only.
 	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."
+		? " Runs on the user's own LinkedIn account with Sales Navigator when one is connected with the Scrupp extension; otherwise on Scrupp's shared account pool (paid plans)."
 		: "";
 
 	if (full || sn) {