@coldleads/mcp-server 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Tkachenko
+
+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,164 @@
-# Temporary Holding Version
+# Cold Leads 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.
+Model Context Protocol server for [Cold Leads](https://coldleads.app/developers?utm_source=github&utm_medium=readme&utm_campaign=mcp-server), the B2B outreach CRM. It exposes the hosted workspace tools to local MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code): contacts, imports, synced conversations, templates, campaigns, website capture, lead search, and verification. Without an API key, it can also ask the human owner to approve a subscription.
+
+```bash
+npx -y @coldleads/mcp-server
+```
+
+## Try it without a key
+
+The hosted demo server has the same tools over a sample workspace (fictional contacts on `.example` domains). It never sends e-mail and uses no credits:
+
+```bash
+claude mcp add --transport http coldleads-demo https://coldleads.app/api/mcp/demo
+```
+
+Then ask: *"Verify these three contacts and prepare outreach drafts. Don't send anything until I approve. Jana Dvořák <jana.dvorak@ridgeline.example>, info@harborlane.example, Piotr Kowalski <piotr@quillmetrics.example>"*. Any client that supports remote (Streamable HTTP) MCP servers can use the same URL. A complete agent built on it: [cold-leads-ai-sales-agent](https://github.com/anttka4cz/cold-leads-ai-sales-agent).
+
+Demo limits:
+
+| Limit | Value |
+| --- | --- |
+| Session | 24 hours from its start (not extended), visible only to that session |
+| Contacts | 10, including the 4 sample contacts |
+| Templates | 1 of your own (besides the sample template; update it with `template_id`) |
+| Campaign drafts | 1 |
+| Text length | notes 100 characters, template body 500, message 200 |
+| Requests | 120 per minute and 20 new sessions per hour per IP address |
+| Verification | sample results for the three demo prospects; other addresses get syntax, disposable-domain and role checks only (no MX or mailbox check) |
+| Sending | never: `send_contact_message` and `launch_campaign` still require approval, then return `demo_not_sent` |
+
+## Tools
+
+| Tool | What it does | Cost |
+| --- | --- | --- |
+| `verify_email` | Verification of one address: syntax, disposable domain, role account and MX records, plus an SMTP mailbox and catch-all check when Cold Leads can open an SMTP connection to the recipient's mail server (otherwise `reasons` contains `smtp_unreachable` and `catch_all` is `null`). Returns `valid`, `risky` or `invalid`. Answers within 5 seconds. | 1 credit |
+| `search_leads` | Contacts already in your Cold Leads CRM for a company domain, with an optional role keyword: e-mail, name, company, stage, tags, verification status and a `do_not_contact` flag. Cold Leads has no third-party lead database. | free |
+| `list_contacts`, `import_contacts`, `update_contact` | List, import up to 100 parsed contact rows per call, and update contacts in your own workspace. Imports deduplicate, skip global DNC entries and do not send e-mail. CSV/XLSX parsing is done by the assistant. | free |
+| `get_conversation`, `send_contact_message` | Read mailbox-synced contact conversations or send one e-mail after explicit approval of recipient and content. Opt-outs, bounces and DNC are blocked. | sender/provider limits |
+| `list_templates`, `save_template` | Review, create and update workspace templates; content screening applies. | free |
+| `list_campaigns`, `create_campaign_draft`, `launch_campaign` | Inspect campaigns, prepare drafts and audience estimates, and launch only after human review and explicit confirmation. | plan and recipient limits |
+| `get_lead_context`, `get_sales_next_actions`, `schedule_follow_up`, `get_agent_activity` | Everything known about one lead (contactability, history, last reply class, next action); the queue of replies waiting for an answer and due follow-ups; set a contact's next action (never sends e-mail); the audit log of API and MCP calls. | free |
+| `get_workspace_info`, `setup_website_lead_capture` | Read non-secret workspace/mailbox status or generate a public-only form key/snippet for your website. Website submissions are inquiry leads, not automatic cold-outreach consent. | free |
+| `provision_account_and_get_payment_link` | For agents without a key: creates a pending account for the human owner and returns a Stripe payment link for the Business plan. The human decides and pays. | — |
+| `check_provisioning_status` | After the owner paid: returns the API key exactly once (with the `claim_token`). The server starts using it immediately. | — |
+
+Responses are compact JSON in a text block. An illustrative result for an address whose mailbox could not be checked (example.com is reserved for documentation):
+
+```json
+{"status":"success","email":"jane.doe@example.com","validity":"valid","catch_all":null,"score":75,"reasons":["smtp_unreachable"],"disposable":false,"role_account":false}
+```
+
+Errors come back as tool results with `isError: true`, for example `{"status":"error","error":"rate_limited","message":"…","http_status":429,"retry_after_seconds":60}`.
+
+## Requirements
+
+- A Cold Leads **secret API key** (`sk_…`) from **Settings → API keys**. The API is included in the **Business** plan (10,000 verification and API credits a month; extra packs available).
+- Node.js 20 or newer (CI tests 20 and 22).
+- No key yet? Start the server without one and let your agent call `provision_account_and_get_payment_link` — see [Agent onboarding](#agent-onboarding-without-a-key).
+
+## Setup
+
+### Claude Desktop
+
+`claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "coldleads": {
+      "command": "npx",
+      "args": ["-y", "@coldleads/mcp-server"],
+      "env": { "COLDLEADS_API_KEY": "sk_your_secret_key" }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf
+
+`~/.cursor/mcp.json` (Cursor) or `~/.codeium/windsurf/mcp_config.json` (Windsurf) — the same `mcpServers` block as above.
+
+### Claude Code
+
+```bash
+claude mcp add coldleads --env COLDLEADS_API_KEY=sk_your_secret_key -- npx -y @coldleads/mcp-server
+```
+
+### VS Code
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "coldleads": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@coldleads/mcp-server"],
+      "env": { "COLDLEADS_API_KEY": "sk_your_secret_key" }
+    }
+  }
+}
+```
+
+### Hosted endpoint (no install)
+
+Clients that support remote servers can connect directly with a secret key:
+
+```json
+{
+  "mcpServers": {
+    "coldleads": {
+      "url": "https://coldleads.app/api/mcp",
+      "headers": { "Authorization": "Bearer sk_your_secret_key" }
+    }
+  }
+}
+```
+
+The stdio server discovers workspace tools from `https://coldleads.app/api/mcp` and forwards their calls to the hosted MCP service, so the hosted and local tools use the same account, policy and sending safeguards. It also includes keyless onboarding tools. ChatGPT connects to the hosted endpoint with OAuth 2.1; enable Developer mode in ChatGPT, add the endpoint, sign in to Cold Leads and review the requested access. Other remote MCP clients can use the API-key header shown above.
+
+### Docker
+
+```bash
+docker build -t coldleads-mcp-server .
+docker run -i --rm -e COLDLEADS_API_KEY=sk_your_secret_key coldleads-mcp-server
+```
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `COLDLEADS_API_KEY` | — | Secret API key (`sk_…`). Optional at start-up: without it the server still starts, lists tools and can run agent onboarding. |
+| `COLDLEADS_API_BASE` | `https://coldleads.app` | API base URL (for local development against a Cold Leads dev server). |
+
+## Agent onboarding without a key
+
+1. The agent calls `provision_account_and_get_payment_link` with the owner's e-mail.
+2. It shows the returned `checkout_url` to the human. The human reviews the plan and price on the secure Stripe page and decides whether to pay. The API gives the agent no way to pay, and the agent is told never to open or pay the link.
+3. The agent polls `check_provisioning_status` with `session_id` and `claim_token` every 15–30 seconds.
+4. After payment the first call returns `api_key` once; this server switches to it immediately. Store it as `COLDLEADS_API_KEY` for the next start.
+5. The owner receives an e-mail to open the Cold Leads web app, where they can manage the subscription or rotate the key.
+
+Only a request that carries the `claim_token` can collect the key; a status lookup without it never returns the key.
+
+## Responsible use
+
+- A verified address is not consent. You need a lawful basis to contact each person.
+- Never e-mail leads with `do_not_contact: true` (opted out, bounced or on the do-not-contact list).
+- Limits: 120 requests per minute per key; each verification costs 1 credit.
+
+## Development
+
+```bash
+npm ci
+npm run build
+npm test                      # schema, server and stdio child-process tests
+COLDLEADS_API_KEY_FILE=path/to/key COLDLEADS_API_BASE=http://localhost:3000 node scripts/smoke.mjs   # live checks
+```
+
+## License
+
+[MIT](LICENSE) © 2026 Anton Tkachenko

package/dist/api.d.ts

@@ -0,0 +1,42 @@
+export type ApiOk = {
+    ok: true;
+    status: number;
+    data: Record<string, unknown>;
+};
+export type ApiFail = {
+    ok: false;
+    status: number;
+    error: string;
+    hint?: string;
+    data?: Record<string, unknown>;
+};
+export type ApiResult = ApiOk | ApiFail;
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export declare const DEFAULT_BASE = "https://coldleads.app";
+export declare const VERIFY_SERVER_BUDGET_MS = 4000;
+export declare const VERIFY_CLIENT_TIMEOUT_MS = 4900;
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export declare const USER_AGENT = "coldleads-mcp-server/1.0.0";
+export declare class ColdLeadsClient {
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private key;
+    private hostedNames;
+    constructor(apiKey: string, baseUrl?: string, fetchImpl?: FetchLike);
+    get apiKey(): string;
+    hasKey(): boolean;
+    setKey(apiKey: string): void;
+    request(method: "GET" | "POST", path: string, body?: unknown, timeoutMs?: number, auth?: boolean, extraHeaders?: Record<string, string>): Promise<ApiResult>;
+    verifyEmail(email: string): Promise<ApiResult>;
+    searchLeads(domain: string, role: string | undefined, limit: number): Promise<ApiResult>;
+    provision(ownerEmail: string, agentId: string, callbackUrl?: string): Promise<ApiResult>;
+    provisioningStatus(sessionId: string, claimToken: string): Promise<ApiResult>;
+    hostedTools(): Promise<Record<string, unknown>[]>;
+    callHostedTool(name: string, args: unknown): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: boolean;
+    }>;
+}

package/dist/api.js

@@ -0,0 +1,96 @@
+export const DEFAULT_BASE = "https://coldleads.app";
+export const VERIFY_SERVER_BUDGET_MS = 4000;
+export const VERIFY_CLIENT_TIMEOUT_MS = 4900;
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export const USER_AGENT = "coldleads-mcp-server/1.0.0";
+export class ColdLeadsClient {
+    baseUrl;
+    fetchImpl;
+    key;
+    hostedNames = null;
+    constructor(apiKey, baseUrl = DEFAULT_BASE, fetchImpl = (u, i) => fetch(u, i)) {
+        this.baseUrl = baseUrl;
+        this.fetchImpl = fetchImpl;
+        this.key = apiKey.trim();
+    }
+    get apiKey() {
+        return this.key;
+    }
+    hasKey() {
+        return this.key.length > 0;
+    }
+    // the key issued after the owner paid is used for the rest of this session (the agent should also persist it)
+    setKey(apiKey) {
+        this.key = apiKey.trim();
+    }
+    async request(method, path, body, timeoutMs = DEFAULT_TIMEOUT_MS, auth = true, extraHeaders = {}) {
+        const url = `${this.baseUrl.replace(/\/+$/, "")}${path}`;
+        const headers = { Accept: "application/json", "User-Agent": USER_AGENT, ...extraHeaders };
+        if (auth)
+            headers.Authorization = `Bearer ${this.key}`;
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let res;
+        try {
+            res = await this.fetchImpl(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs), redirect: "error" });
+        }
+        catch (e) {
+            const name = e instanceof Error ? e.name : "";
+            if (name === "TimeoutError" || name === "AbortError")
+                return { ok: false, status: 0, error: "timeout", hint: `no answer from Cold Leads within ${timeoutMs} ms` };
+            return { ok: false, status: 0, error: "network_error", hint: e instanceof Error ? e.message : String(e) };
+        }
+        let data = {};
+        try {
+            data = (await res.json());
+        }
+        catch {
+            data = {};
+        }
+        if (res.ok)
+            return { ok: true, status: res.status, data };
+        return { ok: false, status: res.status, error: typeof data.error === "string" ? data.error : `http_${res.status}`, hint: typeof data.hint === "string" ? data.hint : undefined, data };
+    }
+    verifyEmail(email) {
+        return this.request("POST", "/api/v1/verify", { email, timeout_ms: VERIFY_SERVER_BUDGET_MS }, VERIFY_CLIENT_TIMEOUT_MS);
+    }
+    searchLeads(domain, role, limit) {
+        const q = new URLSearchParams({ domain, limit: String(limit) });
+        if (role)
+            q.set("role", role);
+        return this.request("GET", `/api/v1/leads?${q.toString()}`);
+    }
+    // agent onboarding without a key (no Authorization header)
+    provision(ownerEmail, agentId, callbackUrl) {
+        return this.request("POST", "/api/agent/provision", { owner_email: ownerEmail, agent_id: agentId, ...(callbackUrl ? { callback_url: callbackUrl } : {}) }, DEFAULT_TIMEOUT_MS, false);
+    }
+    provisioningStatus(sessionId, claimToken) {
+        return this.request("GET", `/api/agent/status?session_id=${encodeURIComponent(sessionId)}`, undefined, DEFAULT_TIMEOUT_MS, false, { "X-Claim-Token": claimToken });
+    }
+    async hostedTools() {
+        const r = await this.request("POST", "/api/mcp", { jsonrpc: "2.0", id: 1, method: "tools/list" }, DEFAULT_TIMEOUT_MS, this.hasKey());
+        if (!r.ok) {
+            this.hostedNames = new Set();
+            return [];
+        }
+        const result = r.data.result;
+        const tools = Array.isArray(result?.tools) ? result.tools : [];
+        this.hostedNames = new Set(tools.map((t) => String(t.name ?? "")));
+        return tools;
+    }
+    async callHostedTool(name, args) {
+        if (!this.hasKey())
+            return { content: [{ type: "text", text: JSON.stringify({ status: "error", error: "missing_api_key", message: "Set COLDLEADS_API_KEY to a secret key (sk_…) to use workspace tools." }) }], isError: true };
+        if (!this.hostedNames && !(await this.hostedTools()).length)
+            return { content: [{ type: "text", text: JSON.stringify({ status: "error", error: "unknown_tool", message: `Unknown Cold Leads tool: ${name}` }) }], isError: true };
+        if (!this.hostedNames?.has(name))
+            return { content: [{ type: "text", text: JSON.stringify({ status: "error", error: "unknown_tool", message: `Unknown Cold Leads tool: ${name}` }) }], isError: true };
+        const r = await this.request("POST", "/api/mcp", { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, DEFAULT_TIMEOUT_MS);
+        if (!r.ok)
+            return { content: [{ type: "text", text: JSON.stringify({ status: "error", error: r.error, message: r.hint ?? r.error, http_status: r.status }) }], isError: true };
+        const rpc = r.data.result;
+        if (rpc?.content?.length)
+            return { content: rpc.content, ...(rpc.isError ? { isError: true } : {}) };
+        return { content: [{ type: "text", text: JSON.stringify({ status: "error", error: "invalid_mcp_response" }) }], isError: true };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ColdLeadsClient, DEFAULT_BASE } from "./api.js";
+import { createServer } from "./server.js";
+// Stdio entry point: `npx -y @coldleads/mcp-server` with COLDLEADS_API_KEY in the environment.
+// Starts and lists tools without a key (so clients and registries can inspect it); calls need the key.
+// Logs go to stderr only — stdout carries JSON-RPC.
+const key = process.env.COLDLEADS_API_KEY ?? "";
+const base = process.env.COLDLEADS_API_BASE || DEFAULT_BASE;
+const server = createServer(new ColdLeadsClient(key, base));
+await server.connect(new StdioServerTransport());
+process.stderr.write(`coldleads MCP server ready (api ${base}, key ${key ? "set" : "missing"})\n`);

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ColdLeadsClient } from "./api.js";
+export declare const SERVER_INFO: {
+    name: string;
+    title: string;
+    version: string;
+};
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export declare function callTool(client: ColdLeadsClient, name: string, rawArgs: unknown, clientName?: string): Promise<ToolResult | null>;
+export declare function createServer(client: ColdLeadsClient): Server;
+export {};

package/dist/server.js

@@ -0,0 +1,137 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { LEADS_DEFAULT, LEADS_MAX, TOOLS } from "./tools.js";
+export const SERVER_INFO = { name: "coldleads", title: "Cold Leads", version: "1.0.0" };
+const INSTRUCTIONS = "Cold Leads tools: search and verify leads; import and manage workspace contacts; read conversations; send one message only after explicit user confirmation; manage templates and campaign drafts; launch campaigns only after human review and confirmation; check non-secret workspace settings; and set up website lead forms. Only authenticated workspace data is accessible. Never e-mail opted-out, bounced or do-not-contact addresses. Verification is not consent; the user needs a lawful basis to contact each person. Website forms create inquiry contacts and do not establish cold-outreach consent. Without an API key, provision_account_and_get_payment_link creates a payment link for the human owner to approve; check_provisioning_status then returns the key once.";
+const text = (obj, isError = false) => ({ content: [{ type: "text", text: JSON.stringify(obj) }], ...(isError ? { isError: true } : {}) });
+const toolError = (error, message, extra = {}) => text({ status: "error", error, message, ...extra }, true);
+const MESSAGES = {
+    missing_api_key: "COLDLEADS_API_KEY is not set. Create a secret key (sk_…) in Cold Leads → Settings → API keys (Business plan) and add it to the MCP server environment.",
+    bad_api_key: "The Cold Leads API key was rejected. Check COLDLEADS_API_KEY (a secret key starting with sk_).",
+    publishable_key_not_allowed: "A publishable key (lk_…) cannot call the API; use a secret key (sk_…).",
+    api_not_in_plan: "This Cold Leads plan does not include the API (Business plan required).",
+    account_suspended: "The Cold Leads account is suspended; contact support@coldleads.app.",
+    no_credits: "No verification credits left this month; the account owner can add credits in Cold Leads settings.",
+    rate_limited: "Rate limit reached (120 requests per minute per key). Wait a minute and retry.",
+    timeout: "Cold Leads did not answer in time. Retry later.",
+    account_exists: "This e-mail already has a Cold Leads workspace. Ask the owner to create a secret API key in Settings → API keys (Business plan) and set it as COLDLEADS_API_KEY.",
+    not_found: "No provisioning found for this session_id.",
+    invalid_owner_email: "owner_email must be the human owner's e-mail address.",
+    invalid_callback_url: "callback_url must be an https URL on a public host.",
+    not_configured: "Payments are not configured on this Cold Leads server.",
+    gateway: "The payment provider could not create a checkout; retry later.",
+    network_error: "Cold Leads could not be reached.",
+};
+function fromApi(f) {
+    const extra = { http_status: f.status };
+    if (f.hint)
+        extra.hint = f.hint;
+    if (f.error === "rate_limited")
+        extra.retry_after_seconds = 60;
+    return toolError(f.error, MESSAGES[f.error] ?? `Cold Leads API error (${f.error}).`, extra);
+}
+function objectArgs(a) {
+    return a && typeof a === "object" && !Array.isArray(a) ? a : null;
+}
+function unknownKeys(a, allowed) {
+    return Object.keys(a).filter((k) => !allowed.includes(k));
+}
+const KNOWN = ["verify_email", "search_leads", "provision_account_and_get_payment_link", "check_provisioning_status"];
+export async function callTool(client, name, rawArgs, clientName = "client") {
+    if (!KNOWN.includes(name))
+        return client.callHostedTool(name, rawArgs ?? {});
+    const args = objectArgs(rawArgs ?? {});
+    if (!args)
+        return toolError("invalid_arguments", "arguments must be an object");
+    if (name === "provision_account_and_get_payment_link") {
+        const extra = unknownKeys(args, ["owner_email", "agent_id", "callback_url"]);
+        if (extra.length)
+            return toolError("invalid_arguments", `unknown argument(s): ${extra.join(", ")}`);
+        if (typeof args.owner_email !== "string" || args.owner_email.trim().length < 3)
+            return toolError("invalid_arguments", "owner_email is required");
+        if (args.agent_id !== undefined && (typeof args.agent_id !== "string" || !args.agent_id.trim() || args.agent_id.length > 100))
+            return toolError("invalid_arguments", "agent_id must be a non-empty string of up to 100 characters");
+        if (args.callback_url !== undefined && (typeof args.callback_url !== "string" || !args.callback_url.startsWith("https://")))
+            return toolError("invalid_arguments", "callback_url must start with https://");
+        const agentId = args.agent_id?.trim() || `mcp:${clientName}`.slice(0, 100);
+        const r = await client.provision(args.owner_email.trim(), agentId, args.callback_url);
+        if (!r.ok)
+            return fromApi(r);
+        return text(r.data);
+    }
+    if (name === "check_provisioning_status") {
+        const extra = unknownKeys(args, ["session_id", "claim_token"]);
+        if (extra.length)
+            return toolError("invalid_arguments", `unknown argument(s): ${extra.join(", ")}`);
+        if (typeof args.session_id !== "string" || typeof args.claim_token !== "string" || args.claim_token.length < 10)
+            return toolError("invalid_arguments", "session_id and claim_token are required");
+        const r = await client.provisioningStatus(args.session_id, args.claim_token);
+        if (!r.ok)
+            return fromApi(r);
+        const data = { ...r.data };
+        if (typeof data.api_key === "string" && data.api_key.startsWith("sk_")) {
+            client.setKey(data.api_key);
+            data.session_key_updated = true;
+            data.message = `${String(data.message ?? "")} This MCP server now uses the new key for the rest of the session; also set COLDLEADS_API_KEY so it is used after a restart.`.trim();
+        }
+        return text(data);
+    }
+    if (name === "verify_email") {
+        const extra = unknownKeys(args, ["email"]);
+        if (extra.length)
+            return toolError("invalid_arguments", `unknown argument(s): ${extra.join(", ")}`);
+        const email = typeof args.email === "string" ? args.email.trim() : "";
+        if (email.length < 3 || email.length > 254)
+            return toolError("invalid_arguments", "email is required (3–254 characters)");
+        if (!client.hasKey())
+            return toolError("missing_api_key", MESSAGES.missing_api_key);
+        const r = await client.verifyEmail(email);
+        if (!r.ok)
+            return fromApi(r);
+        const d = r.data;
+        const reasons = Array.isArray(d.reasons) ? d.reasons : [];
+        return text({
+            status: "success",
+            email: d.email,
+            validity: d.status,
+            // catch_all is known only when the SMTP probe got an answer (ok / catch_all / mailbox_missing)
+            catch_all: reasons.some((x) => x === "ok" || x === "catch_all" || x === "mailbox_missing") ? d.catch_all === true : null,
+            score: d.score,
+            reasons,
+            disposable: d.disposable === true,
+            role_account: d.role === true,
+        });
+    }
+    const extra = unknownKeys(args, ["domain", "role", "limit"]);
+    if (extra.length)
+        return toolError("invalid_arguments", `unknown argument(s): ${extra.join(", ")}`);
+    const domain = typeof args.domain === "string" ? args.domain.trim() : "";
+    if (domain.length < 3 || domain.length > 253)
+        return toolError("invalid_arguments", "domain is required, e.g. example.com");
+    if (args.role !== undefined && (typeof args.role !== "string" || args.role.length > 80))
+        return toolError("invalid_arguments", "role must be a string of up to 80 characters");
+    if (args.limit !== undefined && (!Number.isInteger(args.limit) || args.limit < 1 || args.limit > LEADS_MAX)) {
+        return toolError("invalid_arguments", `limit must be an integer between 1 and ${LEADS_MAX}`);
+    }
+    if (!client.hasKey())
+        return toolError("missing_api_key", MESSAGES.missing_api_key);
+    const r = await client.searchLeads(domain, args.role, args.limit ?? LEADS_DEFAULT);
+    if (!r.ok)
+        return r.error === "domain_required" ? toolError("invalid_arguments", "domain is not a valid company domain, e.g. example.com") : fromApi(r);
+    return text({ status: "success", domain: r.data.domain, count: r.data.count, source: r.data.source, leads: r.data.leads });
+}
+export function createServer(client) {
+    const server = new Server(SERVER_INFO, { capabilities: { tools: { listChanged: false } }, instructions: INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const hosted = client.hasKey() ? await client.hostedTools() : [];
+        const onboarding = TOOLS.filter((t) => t.name === "provision_account_and_get_payment_link" || t.name === "check_provisioning_status");
+        return { tools: (hosted.length ? [...hosted, ...onboarding] : TOOLS) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const result = await callTool(client, req.params.name, req.params.arguments, server.getClientVersion()?.name ?? "client");
+        if (!result)
+            return toolError("unknown_tool", `Unknown tool: ${req.params.name}`);
+        return result;
+    });
+    return server;
+}

package/dist/tools.d.ts

@@ -0,0 +1,125 @@
+export declare const LEADS_MAX = 50;
+export declare const LEADS_DEFAULT = 10;
+export declare const TOOLS: readonly [{
+    readonly name: "search_leads";
+    readonly title: "Search leads by company domain";
+    readonly description: "Search the leads already in your Cold Leads CRM for a target company domain: contact e-mail, name, company, phone, stage, tags, verification status and a do_not_contact flag. Covers only contacts in your own workspace (Cold Leads has no third-party lead database). Free, uses no credits.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly domain: {
+                readonly type: "string";
+                readonly minLength: 3;
+                readonly maxLength: 253;
+                readonly description: "Company domain, e.g. example.com. A URL or an e-mail address is reduced to its domain.";
+            };
+            readonly role: {
+                readonly type: "string";
+                readonly maxLength: 80;
+                readonly description: "Optional keyword such as sales, ceo or marketing, matched against the contact's name, e-mail local part, tags, notes and type.";
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 50;
+                readonly default: 10;
+                readonly description: "Maximum number of leads to return (1–50, default 10).";
+            };
+        };
+        readonly required: readonly ["domain"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+    };
+}, {
+    readonly name: "verify_email";
+    readonly title: "Verify an e-mail address";
+    readonly description: "Verifies an e-mail address: syntax, disposable domain, role account and MX records, plus an SMTP mailbox and catch-all check when Cold Leads can open an SMTP connection to the recipient's mail server (otherwise reasons contains smtp_unreachable and catch_all is null). Returns validity (valid, risky or invalid), a score and reason codes. Answers within about 5 seconds; costs 1 credit.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly email: {
+                readonly type: "string";
+                readonly minLength: 3;
+                readonly maxLength: 254;
+                readonly description: "The e-mail address to verify, e.g. anna@example.com.";
+            };
+        };
+        readonly required: readonly ["email"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+}, {
+    readonly name: "provision_account_and_get_payment_link";
+    readonly title: "Set up Cold Leads for the human owner";
+    readonly description: "Use only when no working Cold Leads API key is available (other Cold Leads tools return missing_api_key or bad_api_key) and the human wants to use Cold Leads. Creates a pending Cold Leads account for the human owner's e-mail and returns a Stripe payment link for the Business plan with API access (price in plan.price, billed monthly until cancelled). Show checkout_url to the human and let them decide; never open, pay or share the link yourself. Keep claim_token secret, then call check_provisioning_status until status is active to receive the API key once.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly owner_email: {
+                readonly type: "string";
+                readonly minLength: 3;
+                readonly maxLength: 254;
+                readonly description: "E-mail address of the human who will own and pay for the Cold Leads account.";
+            };
+            readonly agent_id: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 100;
+                readonly description: "Name of your agent or product; shown to the human on the payment page.";
+            };
+            readonly callback_url: {
+                readonly type: "string";
+                readonly maxLength: 500;
+                readonly pattern: "^https://";
+                readonly description: "Optional https URL that receives a signed POST when the owner has paid (no secrets in the payload).";
+            };
+        };
+        readonly required: readonly ["owner_email"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: false;
+        readonly openWorldHint: true;
+    };
+}, {
+    readonly name: "check_provisioning_status";
+    readonly title: "Check the owner's payment and get the API key";
+    readonly description: "Checks an account created with provision_account_and_get_payment_link. Returns status pending_payment, active, expired or suspended. When active, the first call with the claim_token returns api_key exactly once: store it securely as COLDLEADS_API_KEY and send it as Authorization: Bearer <key>. Poll every 15–30 seconds while pending_payment.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly session_id: {
+                readonly type: "string";
+                readonly minLength: 3;
+                readonly maxLength: 200;
+                readonly description: "session_id returned by provision_account_and_get_payment_link.";
+            };
+            readonly claim_token: {
+                readonly type: "string";
+                readonly minLength: 10;
+                readonly maxLength: 200;
+                readonly description: "claim_token returned by provision_account_and_get_payment_link.";
+            };
+        };
+        readonly required: readonly ["session_id", "claim_token"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: false;
+        readonly openWorldHint: true;
+    };
+}];

package/dist/tools.js

@@ -0,0 +1,67 @@
+// Tool definitions of the stdio server (JSON Schema draft-07). Workspace tools are loaded from hosted /api/mcp;
+// onboarding remains local because it can run before the account has an API key.
+export const LEADS_MAX = 50;
+export const LEADS_DEFAULT = 10;
+export const TOOLS = [
+    {
+        name: "search_leads",
+        title: "Search leads by company domain",
+        description: "Search the leads already in your Cold Leads CRM for a target company domain: contact e-mail, name, company, phone, stage, tags, verification status and a do_not_contact flag. Covers only contacts in your own workspace (Cold Leads has no third-party lead database). Free, uses no credits.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                domain: { type: "string", minLength: 3, maxLength: 253, description: "Company domain, e.g. example.com. A URL or an e-mail address is reduced to its domain." },
+                role: { type: "string", maxLength: 80, description: "Optional keyword such as sales, ceo or marketing, matched against the contact's name, e-mail local part, tags, notes and type." },
+                limit: { type: "integer", minimum: 1, maximum: LEADS_MAX, default: LEADS_DEFAULT, description: `Maximum number of leads to return (1–${LEADS_MAX}, default ${LEADS_DEFAULT}).` },
+            },
+            required: ["domain"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    {
+        name: "verify_email",
+        title: "Verify an e-mail address",
+        description: "Verifies an e-mail address: syntax, disposable domain, role account and MX records, plus an SMTP mailbox and catch-all check when Cold Leads can open an SMTP connection to the recipient's mail server (otherwise reasons contains smtp_unreachable and catch_all is null). Returns validity (valid, risky or invalid), a score and reason codes. Answers within about 5 seconds; costs 1 credit.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                email: { type: "string", minLength: 3, maxLength: 254, description: "The e-mail address to verify, e.g. anna@example.com." },
+            },
+            required: ["email"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    {
+        name: "provision_account_and_get_payment_link",
+        title: "Set up Cold Leads for the human owner",
+        description: "Use only when no working Cold Leads API key is available (other Cold Leads tools return missing_api_key or bad_api_key) and the human wants to use Cold Leads. Creates a pending Cold Leads account for the human owner's e-mail and returns a Stripe payment link for the Business plan with API access (price in plan.price, billed monthly until cancelled). Show checkout_url to the human and let them decide; never open, pay or share the link yourself. Keep claim_token secret, then call check_provisioning_status until status is active to receive the API key once.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                owner_email: { type: "string", minLength: 3, maxLength: 254, description: "E-mail address of the human who will own and pay for the Cold Leads account." },
+                agent_id: { type: "string", minLength: 1, maxLength: 100, description: "Name of your agent or product; shown to the human on the payment page." },
+                callback_url: { type: "string", maxLength: 500, pattern: "^https://", description: "Optional https URL that receives a signed POST when the owner has paid (no secrets in the payload)." },
+            },
+            required: ["owner_email"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    {
+        name: "check_provisioning_status",
+        title: "Check the owner's payment and get the API key",
+        description: "Checks an account created with provision_account_and_get_payment_link. Returns status pending_payment, active, expired or suspended. When active, the first call with the claim_token returns api_key exactly once: store it securely as COLDLEADS_API_KEY and send it as Authorization: Bearer <key>. Poll every 15–30 seconds while pending_payment.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", minLength: 3, maxLength: 200, description: "session_id returned by provision_account_and_get_payment_link." },
+                claim_token: { type: "string", minLength: 10, maxLength: 200, description: "claim_token returned by provision_account_and_get_payment_link." },
+            },
+            required: ["session_id", "claim_token"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+];

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@coldleads/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Model Context Protocol server for Cold Leads (coldleads.app), the B2B outreach CRM: contacts, imports, e-mail verification, templates, campaign drafts, conversations, reply queue and follow-ups in your own workspace; sending needs explicit approval. Includes keyless agent onboarding.",
+  "mcpName": "io.github.anttka4cz/mcp-server-coldleads",
+  "type": "module",
+  "bin": {
+    "mcp-server-coldleads": "dist/index.js"
+  },
+  "main": "dist/server.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "email-verification",
+    "b2b",
+    "leads",
+    "crm",
+    "coldleads",
+    "sales",
+    "ai-agents"
+  ],
+  "homepage": "https://coldleads.app/developers?utm_source=npm&utm_medium=readme&utm_campaign=mcp-server",
+  "license": "MIT",
+  "author": "Anton Tkachenko",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "ajv": "^8.17.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anttka4cz/mcp-server-coldleads.git"
+  },
+  "bugs": {
+    "url": "https://github.com/anttka4cz/mcp-server-coldleads/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}