uniqueness-mcp 0.4.2 → 0.5.0

package/index.mjs

@@ -1,174 +1,358 @@
 #!/usr/bin/env node
-// Uniqueness Engine MCP server. Exposes the connection brief as an agent tool.
-// Auth: UNIQUENESS_API_KEY env (get one: POST /api/signup, or `npx uniqueness signup`).
-//
-// Claude/Cursor/Codex config:
-//   { "mcpServers": { "uniqueness": {
-//       "command": "npx", "args": ["-y", "uniqueness-mcp"],
-//       "env": { "UNIQUENESS_API_KEY": "uq_live_..." } } } }
-
+// Uniqueness Engine MCP server. This is a thin, conservative wrapper around
+// the public API: it can ask a human to act, but it never purchases a pack,
+// saves a payment method, enables auto-recharge, or subscribes by inference.
+import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
 const BASE = process.env.UNIQUENESS_API_URL || "https://uniquenessengine.com";
-const KEY = process.env.UNIQUENESS_API_KEY || "";
+let KEY = process.env.UNIQUENESS_API_KEY || "";
+const signupContinuations = new Map();
 
-// Keep in step with mcp/package.json — cli/release-parity.test.ts asserts they match.
-const server = new McpServer({ name: "uniqueness", version: "0.4.2" });
+const server = new McpServer({ name: "uniqueness", version: "0.5.0" });
 
-server.tool(
-  "get_connection_brief",
-  "Given a LinkedIn URL (or name + company, or email), return a fact-checked Connection Brief: " +
-    "verified personal + professional signal, each claim grounded in a source (`evidence_quote` + " +
-    "`source_url`), identity-gated (returns needs_review rather than guessing). Each delivered brief " +
-    "carries a `usage` object (cache_status, credits_charged, credits_remaining) and a `capabilities` " +
-    "block; optional `usage.card_gate_notice` is the server-authored pre-wall next action and should " +
-    "be shown as-is rather than inferred from the balance. A refusal or 0-fact brief is free. " +
-    "The response is COMPACT by default (identity + " +
-    "top-ranked facts + capabilities) — pass detail:'full' for the complete brief; set detail " +
-    "explicitly. The removed fields outreach_angles / gift_hook / safe_to_use_in_outreach are declared " +
-    "in `capabilities`, never returned. Machine-readable contract: " +
-    "https://uniquenessengine.com/openapi.json (free sample: GET /api/examples/kitchen-sink). " +
-    "Use before personalized outreach or call prep. " +
-    "Support: support@uniquenessengine.com.",
-  {
+const json = (value, isError = false) => ({
+  ...(isError ? { isError: true } : {}),
+  content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+});
+
+function pruneSignupContinuations() {
+  const now = Date.now();
+  for (const [id, continuation] of signupContinuations) {
+    if (continuation.expiresAt <= now) signupContinuations.delete(id);
+  }
+  while (signupContinuations.size > 100)
+    signupContinuations.delete(signupContinuations.keys().next().value);
+}
+
+function keyHeaders(body, auth) {
+  const headers = {};
+  if (body !== undefined) headers["content-type"] = "application/json";
+  if (auth && KEY) headers.authorization = `Bearer ${KEY}`;
+  return headers;
+}
+
+async function api(path, { method = "POST", body, auth = true } = {}) {
+  if (auth && !KEY) return { status: 401, body: { error: "missing_api_key" } };
+  const response = await fetch(`${BASE}${path}`, {
+    method,
+    headers: keyHeaders(body, auth),
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+  return { status: response.status, body: await response.json().catch(() => ({})) };
+}
+
+function isPaymentRequired(value) {
+  return value && value.error === "payment_required" && value.reason === "insufficient_credits" &&
+    value.credits && value.retry && typeof value.billing_url === "string";
+}
+
+function spendableBalance(value) {
+  const candidates = [
+    value?.total_credits,
+    value?.credits_remaining,
+    value?.balance?.total_credits,
+    value?.balance?.spendable_credits,
+  ];
+  return candidates.find((candidate) => typeof candidate === "number" && Number.isFinite(candidate)) ?? null;
+}
+
+function paymentAction(contract) {
+  return json({
+    status: "human_action_required",
+    action: "checkout",
+    message: "Ask a human before surfacing a purchase action. After explicit consent, use payment_required.recommended_offer.checkout_url for the offered pack, or payment_required.billing_url if the human wants to choose another pack. This MCP server has not bought anything, saved a payment method, enabled auto-recharge, or started a subscription. It stores no unpaid target. After payment, the host may call resume_connection_brief with the original target, the returned retry.idempotency_key, and the previously observed available balance; the service verifies both the new balance and retry identity.",
+    payment_required: contract,
+    resume_tool: "resume_connection_brief",
+    resume_requires: [
+      "original target fields",
+      "payment_required.retry.idempotency_key",
+      "payment_required.credits.available",
+    ],
+    fixture: contract.fixture,
+  });
+}
+
+function authenticationRequired() {
+  return json({
+    status: "human_action_required",
+    action: "programmatic_signup",
+    message: "No API key is configured. Begin named email approval; do not use a key from another person or assume approval.",
+    begin_tool: "begin_programmatic_signup",
+  }, true);
+}
+
+async function pollBrief(jobId) {
+  const deadline = Date.now() + 210000;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+    const poll = await api(`/api/jobs/${jobId}`, { method: "GET" });
+    if (poll.body.status === "done") return { kind: "brief", brief: poll.body.result };
+    if (poll.body.status === "refused") return { kind: "brief", brief: poll.body.result || { status: "needs_review", note: "Identity could not be confidently resolved." } };
+    if (poll.body.status === "failed") return { kind: "error", error: poll.body.error || "job_failed" };
+  }
+  return { kind: "pending", job_id: jobId };
+}
+
+async function submitBrief(args, idempotencyKey) {
+  const payload = { ...args, idempotency_key: idempotencyKey };
+  const submit = await api("/api/enrich", { body: payload });
+  if (submit.status === 402 && isPaymentRequired(submit.body)) return { kind: "payment_required", contract: submit.body };
+  if (submit.status === 401) return { kind: "unauthorized" };
+  if (submit.status === 409 && (submit.body.error === "idempotency_key_expired" || submit.body.error === "idempotency_key_mismatch"))
+    return { kind: "retry_rejected", error: submit.body.error };
+  if (submit.status >= 400) return { kind: "error", error: submit.body.error || `http_${submit.status}`, message: submit.body.message };
+  if (submit.body.brief) return { kind: "brief", brief: submit.body.brief };
+  if (!submit.body.job_id) return { kind: "error", error: "invalid_enrich_response" };
+  return pollBrief(submit.body.job_id);
+}
+
+function briefInputSchema() {
+  return {
     linkedin_url: z.string().optional().describe("LinkedIn profile URL"),
     name: z.string().optional().describe("Full name (use with company)"),
     company: z.string().optional().describe("Company name (use with name)"),
     email: z.string().optional().describe("Work email (optional disambiguator)"),
-    detail: z
-      .enum(["compact", "full"])
-      .optional()
-      .describe("Response shape — compact (default, rolling out) or full"),
+    detail: z.enum(["compact", "full"]).optional().describe("Response shape"),
+  };
+}
+
+function cleanBriefArgs(args) {
+  const body = {};
+  for (const key of ["linkedin_url", "name", "company", "email", "detail"])
+    if (args[key]) body[key] = args[key];
+  return body;
+}
+
+server.tool(
+  "begin_programmatic_signup",
+  "Start named API-key setup. It sends an approval link to a human-controlled email. Do not infer approval or claim a key until the approval endpoint reports approved. If claimed, the key is kept only by this running MCP process; durable named-key setup belongs to a human in Account.",
+  {
+    email: z.string().email().describe("Human-controlled email address"),
+    device_name: z.string().max(120).optional().describe("Named device the human should recognize"),
   },
   async (args) => {
-    if (!KEY) {
-      return {
-        isError: true,
-        content: [{ type: "text", text: "Missing UNIQUENESS_API_KEY. Get a free key: POST https://uniquenessengine.com/api/signup {email}." }],
-      };
+    const response = await api("/api/signup", {
+      auth: false,
+      body: { email: args.email, client_name: "Uniqueness MCP", device_name: args.device_name || "MCP host" },
+    });
+    if (response.status !== 202 || response.body.status !== "email_verification_required")
+      return json({
+        status: "signup_failed",
+        error: response.body.error || response.status,
+        ...(response.body.error === "verification_delivery_failed"
+          ? {
+              retry_after_seconds: response.body.retry_after_seconds || 60,
+              message:
+                "No key was created. Start a new named signup after the retry interval.",
+            }
+          : {}),
+      }, true);
+    if (
+      typeof response.body.transaction_id !== "string" ||
+      !response.body.transaction_id ||
+      typeof response.body.polling_token !== "string" ||
+      !response.body.polling_token
+    )
+      return json({ status: "signup_failed", error: "invalid_verification_response" }, true);
+    pruneSignupContinuations();
+    const continuationId = randomUUID();
+    const parsedExpiry = Date.parse(response.body.expires_at || "");
+    signupContinuations.set(continuationId, {
+      transactionId: response.body.transaction_id,
+      pollingToken: response.body.polling_token,
+      claimAttempted: false,
+      expiresAt: Number.isFinite(parsedExpiry)
+        ? parsedExpiry
+        : Date.now() + 15 * 60 * 1000,
+    });
+    return json({
+      status: "human_action_required",
+      action: "email_approval",
+      message: "Ask the human to approve the named MCP/device request in their email. Approval is not inferred from this tool call.",
+      continuation_id: continuationId,
+      expires_at: response.body.expires_at,
+      complete_tool: "complete_programmatic_signup",
+    });
+  },
+);
+
+server.tool(
+  "complete_programmatic_signup",
+  "Check the in-process named email-approval request and claim a one-time key only after the server reports approved. The polling secret and key never appear in MCP output. A successful claim configures this running process only; a human must use Account for durable named-key setup.",
+  { continuation_id: z.string().uuid() },
+  async ({ continuation_id }) => {
+    pruneSignupContinuations();
+    const continuation = signupContinuations.get(continuation_id);
+    if (!continuation)
+      return json({
+        status: "verification_expired",
+        message:
+          "This process no longer holds that verification. Start a new named signup.",
+      });
+    if (continuation.claimAttempted)
+      return json({
+        status: "claim_already_attempted",
+        human_action_required: true,
+        action: "account_key_setup",
+        account_url: `${BASE}/account`,
+        message:
+          "To preserve the one-time claim boundary, this process will not call claim again. A human can sign in to Account for durable named-key setup.",
+      });
+    const path = `/api/signup/verification/${encodeURIComponent(continuation.transactionId)}`;
+    const headers = { "x-verification-token": continuation.pollingToken };
+    const poll = await fetch(`${BASE}${path}`, { headers });
+    const state = await poll.json().catch(() => ({}));
+    if (state.status !== "approved") {
+      const result = json({
+        status: state.status || "pending",
+        human_action_required: state.status === "pending",
+        message: state.status === "pending" ? "Approval is still pending. Wait for the human email action." : "This approval request cannot issue a key. Start a new named signup if needed.",
+      });
+      if (state.status && state.status !== "pending")
+        signupContinuations.delete(continuation_id);
+      return result;
     }
-    if (!args.linkedin_url && !args.name) {
-      return { isError: true, content: [{ type: "text", text: "Provide linkedin_url, or name (+ company)." }] };
+    // The service intentionally makes this a one-time disclosure. Do not retry a
+    // claim after an ambiguous response: the key could have been issued, and only
+    // a human Account session is appropriate for durable recovery/setup.
+    continuation.claimAttempted = true;
+    let issued;
+    try {
+      const claim = await fetch(`${BASE}${path}/claim`, { method: "POST", headers });
+      issued = await claim.json().catch(() => ({}));
+    } catch {
+      return json({
+        status: "claim_uncertain",
+        human_action_required: true,
+        action: "account_key_setup",
+        account_url: `${BASE}/account`,
+        message:
+          "The one-time claim response was not received. It will not be repeated here; a human can sign in to Account for durable named-key setup.",
+      }, true);
     }
-    const body = {};
-    if (args.linkedin_url) body.linkedin_url = args.linkedin_url;
-    if (args.name) body.name = args.name;
-    if (args.company) body.company = args.company;
-    if (args.email) body.email = args.email;
-    if (args.detail) body.detail = args.detail;
-
-    // Async enrich+poll (mirrors cli/uniqueness.mjs `brief`). The sync /api/brief
-    // path returns {} to the client past the ~124s delivery cliff on fresh
-    // (uncached) profiles; /api/enrich submits a job we can poll to completion.
-    // A cache hit / immediate brief comes back inline on the submit.
-    const auth = { "content-type": "application/json", authorization: `Bearer ${KEY}` };
-    const sub = await fetch(`${BASE}/api/enrich`, {
-      method: "POST",
-      headers: auth,
-      body: JSON.stringify(body),
+    if (issued.status !== "approved" || !issued.api_key)
+      return json({
+        status: "claim_failed",
+        error: issued.status || "unknown",
+        human_action_required: true,
+        action: "account_key_setup",
+        account_url: `${BASE}/account`,
+        message:
+          "The one-time claim was not configured in this process. It will not be repeated here; a human can sign in to Account for durable named-key setup.",
+      }, true);
+    KEY = issued.api_key;
+    signupContinuations.delete(continuation_id);
+    return json({
+      status: "configured",
+      scope: "current_process_only",
+      account_url: `${BASE}/account`,
+      message: "MCP is configured only for this currently running process. The key was received once and is intentionally never repeated in tool output. For a durable named key or a future MCP configuration, have the human sign in to Account; do not ask an agent to expose or relay the key.",
     });
-    const subJson = await sub.json().catch(() => ({}));
-    if (sub.status === 401) return { isError: true, content: [{ type: "text", text: "401 unauthorized — invalid API key." }] };
-    if (sub.status === 402) {
-      if (subJson.error === "payment_method_required") {
-        const reason = subJson.reason === "daily_free_budget_reached"
-          ? "The shared daily free lookup budget is used. It resets daily; cached lookups still work. A completed purchase removes this cap."
-          : subJson.reason === "uncached_live_run"
-            ? "A card is required for another uncached live lookup. Any remaining credits still work on cached lookups."
-            : "This lookup is blocked by the card gate. Cached lookups still work.";
-        const setup = subJson.setup_url
-          ? ` POST ${subJson.setup_url} with the Bearer key and follow the Stripe URL it returns.`
-          : "";
-        return { isError: true, content: [{ type: "text", text: `Card gate: ${reason}${setup}` }] };
-      }
-      if (subJson.error === "insufficient_credits") {
-        return { isError: true, content: [{ type: "text", text: "Out of credits. Add credits or save a card with POST /api/billing/setup." }] };
-      }
-      return { isError: true, content: [{ type: "text", text: subJson.error || "Payment required." }] };
+  },
+);
+
+server.tool(
+  "get_connection_brief",
+  "Submit one full-quality written enrichment. A real target requires spendable credit. On canonical 402 this returns structured human_action_required; it never buys, saves a method, enables auto-recharge, or subscribes. Refusal, wrong-person, no-result, and system-failure outcomes release the exact credit. Support: support@uniquenessengine.com.",
+  briefInputSchema(),
+  async (args) => {
+    if (!KEY) return authenticationRequired();
+    if (!args.linkedin_url && !args.name) return json({ error: "invalid_input", message: "Provide linkedin_url, or name (+ company)." }, true);
+    const body = cleanBriefArgs(args);
+    const result = await submitBrief(body, randomUUID());
+    if (result.kind === "payment_required") {
+      return paymentAction(result.contract);
     }
+    if (result.kind === "unauthorized") return json({ error: "unauthorized" }, true);
+    if (result.kind === "pending") return json({ status: "pending", job_id: result.job_id, message: "The job is still processing; call get_connection_brief again with the same input to poll a fresh server request." });
+    if (result.kind === "retry_rejected") return json({ error: result.error, message: "Submit a new request with a new idempotency key." }, true);
+    if (result.kind === "error") return json({ error: result.error, message: result.message }, true);
+    return json(result.brief);
+  },
+);
 
-    // Fast path: cache hit / immediate brief.
-    let brief = subJson.brief || null;
-    let jobId = subJson.job_id || null;
-    if (!brief) {
-      if (!jobId) {
-        return { isError: true, content: [{ type: "text", text: `enrich failed (${sub.status}): ${subJson.error || subJson.message || ""}` }] };
-      }
-      // Poll GET /api/jobs/:id every 3s until a terminal state or the deadline.
-      // Briefs run ~45-180s, so give it up to ~210s before handing back the job_id.
-      const deadline = Date.now() + 210000;
-      while (Date.now() < deadline && !brief) {
-        await new Promise((r) => setTimeout(r, 3000));
-        const pr = await fetch(`${BASE}/api/jobs/${jobId}`, { headers: { authorization: `Bearer ${KEY}` } });
-        const pj = await pr.json().catch(() => ({}));
-        const st = pj.status;
-        if (st === "done") brief = pj.result;
-        else if (st === "refused") brief = pj.result || { status: "needs_review", note: "Identity could not be confidently resolved." };
-        else if (st === "failed") return { isError: true, content: [{ type: "text", text: `job failed: ${pj.error || "unknown"}` }] };
-      }
-      if (!brief) {
-        // Never return {} — hand back the job_id so the caller can re-run to keep polling.
-        return {
-          content: [{ type: "text", text: `Still processing (job ${jobId}). The brief is taking longer than usual — re-run get_connection_brief with the same inputs to keep polling.` }],
-        };
-      }
+server.tool(
+  "resume_connection_brief",
+  "After a human has completed Checkout, verify spendable credit with the service and only then resubmit caller-supplied original target fields with the 402 retry idempotency key. The MCP server stores no unpaid target and never trusts a payment assertion alone.",
+  {
+    ...briefInputSchema(),
+    idempotency_key: z.string().min(1).max(200).describe("payment_required.retry.idempotency_key from the original 402"),
+    previous_available: z.number().int().nonnegative().describe("payment_required.credits.available from the original 402"),
+  },
+  async (args) => {
+    if (!KEY) return authenticationRequired();
+    const body = cleanBriefArgs(args);
+    if (!body.linkedin_url && !body.name)
+      return json({ error: "invalid_input", message: "Resupply the original linkedin_url, or name (+ company). No unpaid target is stored by this MCP server." }, true);
+    const account = await api("/api/account", { method: "GET" });
+    const balance = spendableBalance(account.body);
+    if (account.status !== 200 || balance === null || balance <= args.previous_available) {
+      return json({
+        status: "human_action_required",
+        action: "verify_checkout",
+        message: "The service does not yet show more spendable credit than the original 402, so the caller-supplied target was not retried. Complete/check Checkout and call this tool again; do not claim payment as proof.",
+        observed_balance: balance,
+      });
     }
+    const result = await submitBrief(body, args.idempotency_key);
+    if (result.kind === "payment_required") return paymentAction(result.contract);
+    if (result.kind === "pending") return json({ status: "pending", job_id: result.job_id });
+    if (result.kind === "retry_rejected")
+      return json({ error: result.error, message: "Retry metadata is no longer valid. Submit a new request with a new idempotency key." }, true);
+    if (result.kind === "error" || result.kind === "unauthorized") return json({ error: result.error || "unauthorized", message: result.message }, true);
+    return json(result.brief);
+  },
+);
 
-    return { content: [{ type: "text", text: JSON.stringify(brief, null, 2) }] };
-  }
+server.tool(
+  "get_billing_status",
+  "Read spendable balance provenance and optional auto-recharge state. This is read-only; it never changes billing settings.",
+  {},
+  async () => {
+    if (!KEY) return authenticationRequired();
+    const [balance, recharge] = await Promise.all([
+      api("/api/account", { method: "GET" }),
+      api("/api/billing/auto-recharge", { method: "GET" }),
+    ]);
+    if (balance.status !== 200) return json({ error: balance.body.error || "balance_unavailable" }, true);
+    return json({
+      balance: balance.body,
+      auto_recharge: recharge.status === 200 ? recharge.body : { error: recharge.body.error || "unavailable" },
+      auto_recharge_note: "Auto-recharge is off by default. This MCP server cannot enable, retry, or disable it; a human must make an explicit choice in billing settings.",
+    });
+  },
+);
+
+server.tool(
+  "preflight_connection_briefs",
+  "Read-only batch estimate. It never purchases credit, triggers auto-recharge, reserves credit, or starts a partial batch. Use the API directly with explicit human approval to submit an all-or-nothing batch.",
+  { profiles: z.array(z.object({ linkedin_url: z.string().optional(), name: z.string().optional(), company: z.string().optional(), email: z.string().optional() })).min(1).max(100) },
+  async ({ profiles }) => {
+    if (!KEY) return authenticationRequired();
+    const response = await api("/api/enrich/batch", { body: { profiles, estimate_only: true } });
+    if (response.status !== 200) return json({ error: response.body.error || `http_${response.status}`, message: response.body.message }, true);
+    return json({ status: "preflight", ...response.body, all_or_nothing: true });
+  },
 );
 
 server.tool(
   "submit_feedback",
-  "Rate a Connection Brief 👍/👎 so the engine can improve. Pass the canonical_id " +
-    "from the brief's identity (or the job_id if you have one) plus rating 'up' or 'down' " +
-    "and an optional note on what was right or wrong.",
+  "Rate a delivered Connection Brief. Feedback never changes billing.",
   {
-    rating: z.enum(["up", "down"]).describe("'up' or 'down'"),
-    canonical_id: z
-      .string()
-      .optional()
-      .describe("brief.identity.canonical_id (preferred)"),
-    job_id: z.string().optional().describe("job id, if you enriched async"),
-    note: z.string().optional().describe("what was right/wrong (optional)"),
+    rating: z.enum(["up", "down"]),
+    canonical_id: z.string().optional(),
+    job_id: z.string().optional(),
+    note: z.string().optional(),
   },
   async (args) => {
-    if (!KEY) {
-      return {
-        isError: true,
-        content: [{ type: "text", text: "Missing UNIQUENESS_API_KEY." }],
-      };
-    }
-    if (!args.canonical_id && !args.job_id) {
-      return {
-        isError: true,
-        content: [
-          { type: "text", text: "Provide canonical_id (or job_id) to rate." },
-        ],
-      };
-    }
-    const res = await fetch(`${BASE}/api/feedback`, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        authorization: `Bearer ${KEY}`,
-      },
-      body: JSON.stringify({ ...args, source: "mcp" }),
-    });
-    const json = await res.json().catch(() => ({}));
-    if (!res.ok)
-      return {
-        isError: true,
-        content: [
-          {
-            type: "text",
-            text: `feedback failed (${res.status}): ${json.error || ""}`,
-          },
-        ],
-      };
-    return { content: [{ type: "text", text: "Thanks — feedback recorded." }] };
+    if (!KEY) return authenticationRequired();
+    if (!args.canonical_id && !args.job_id) return json({ error: "invalid_input", message: "Provide canonical_id or job_id." }, true);
+    const response = await api("/api/feedback", { body: { ...args, source: "mcp" } });
+    if (response.status !== 200) return json({ error: response.body.error || `http_${response.status}` }, true);
+    return json({ status: "recorded", message: "Feedback recorded." });
   },
 );
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "uniqueness-mcp",
-  "version": "0.4.2",
-  "description": "MCP server for Uniqueness Engine — fact-checked connection briefs as an agent tool.",
+  "version": "0.5.0",
+  "description": "Conservative human-in-the-loop MCP server for Uniqueness Engine fact-checked connection briefs.",
   "type": "module",
   "bin": {
     "uniqueness-mcp": "index.mjs"