uniqueness-mcp 0.5.2 → 0.7.0

package/README.md

@@ -1,25 +1,25 @@
 # uniqueness-mcp
 
-[MCP](https://modelcontextprotocol.io) server for [Uniqueness Engine](https://uniquenessengine.com) — conservative, human-in-the-loop access to fact-checked **personal context**.
+Local stdio fallback for the hosted [Uniqueness Engine](https://uniquenessengine.com) MCP server.
 
-Commercial contract: `hard-paid-v1`.
+## Prefer the hosted MCP
 
-## Install
+Connect remote-capable clients to:
 
-```bash
-npx -y uniqueness-mcp
-```
+`https://uniquenessengine.com/mcp`
+
+Send `Authorization: Bearer uq_live_...` on every request. Hosted compatible fixes arrive without reinstalling this package.
 
-Requires Node **18+**.
+## Local stdio fallback
 
-## Cursor / Claude Desktop config
+Use this package only when your client cannot use remote Streamable HTTP or cannot set a bearer header:
 
 ```json
 {
   "mcpServers": {
     "uniqueness": {
       "command": "npx",
-      "args": ["-y", "uniqueness-mcp"],
+      "args": ["-y", "uniqueness-mcp@latest"],
       "env": {
         "UNIQUENESS_API_KEY": "uq_live_..."
       }
@@ -28,40 +28,12 @@ Requires Node **18+**.
 }
 ```
 
-Without `UNIQUENESS_API_KEY`, use `begin_programmatic_signup` and `complete_programmatic_signup` after human email approval.
-
-## Tools
-
-| Tool | Purpose |
-|------|---------|
-| `get_personal_context` | Submit one enrichment (`detail=compact` default). Alias: `get_connection_brief` |
-| `resume_personal_context` | After human Checkout, retry with 402 idempotency key. Alias: `resume_connection_brief` |
-| `get_billing_status` | Read spendable balance + auto-recharge state (read-only) |
-| `begin_programmatic_signup` / `complete_programmatic_signup` | Named-device verification flow |
-| `preflight_personal_contexts` | Batch estimate before spend. Alias: `preflight_connection_briefs` |
-| `submit_feedback` | Rate a delivered brief |
-
-## Safety (by design)
+Requires Node 18+.
 
-- **No purchase tools** — MCP never buys a pack, saves a payment method, enables auto-recharge, or subscribes.
-- **`402 payment_required`** returns structured `human_action_required`; present `recommended_offer.checkout_url` or `billing_url` only after explicit human consent.
-- **No unpaid target storage** — after Checkout, the host must call `resume_personal_context` with the original target fields, `payment_required.retry.idempotency_key`, and the previously observed available balance.
-
-Jordan Ellis is a **fictional static fixture** and the only free experience (`GET /api/examples/kitchen-sink`). Do not smoke-test real people without explicit human approval and paid credit.
-
-## Environment
-
-```bash
-export UNIQUENESS_API_KEY=uq_live_...
-export UNIQUENESS_API_URL=https://uniquenessengine.com   # optional override
-```
+The fallback and hosted endpoint use the same tool core. The fallback additionally exposes `begin_programmatic_signup` and `complete_programmatic_signup`; after human email approval, they configure only the current process and never return a key to the agent.
 
-## Docs
+Lifecycle tools include `get_personal_context`, `get_connection_brief_job`, `batch_connection_briefs`, `get_batch_status`, `get_batch_results`, `export_batch`, `cancel_job`, `retry_job`, `retry_failed_batch`, and `estimate_batch_cost`.
 
-- [MCP quickstart](https://uniquenessengine.com/documentation/mcp/quickstart)
-- [Agent setup](https://uniquenessengine.com/agents)
-- [llms.txt](https://uniquenessengine.com/llms.txt)
-- [OpenAPI](https://uniquenessengine.com/openapi.json)
-- [CLI](https://www.npmjs.com/package/uniqueness)
+MCP has no purchase, payment-method, auto-recharge, or subscription tools. On `402 payment_required`, present checkout URLs only after explicit human consent.
 
-Support: support@uniquenessengine.com
+[MCP quickstart](https://uniquenessengine.com/documentation/mcp/quickstart) · support@uniquenessengine.com

package/dist/server.js

@@ -0,0 +1,491 @@
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export const MCP_SERVER_NAME = "uniqueness";
+export const MCP_SERVER_VERSION = "0.7.0";
+export const MCP_TOOL_ALIASES = {
+    get_personal_context: ["get_connection_brief"],
+    resume_personal_context: ["resume_connection_brief"],
+    preflight_personal_contexts: ["preflight_connection_briefs"],
+};
+const CORE_TOOL_NAMES = [
+    "get_personal_context",
+    "get_connection_brief",
+    "resume_personal_context",
+    "resume_connection_brief",
+    "get_billing_status",
+    "preflight_personal_contexts",
+    "preflight_connection_briefs",
+    "get_connection_brief_job",
+    "batch_connection_briefs",
+    "estimate_batch_cost",
+    "get_batch_status",
+    "get_batch_results",
+    "export_batch",
+    "cancel_job",
+    "retry_job",
+    "retry_failed_batch",
+    "submit_feedback",
+];
+export const MCP_REMOTE_TOOL_NAMES = [...CORE_TOOL_NAMES];
+export const MCP_STDIO_TOOL_NAMES = [
+    "begin_programmatic_signup",
+    "complete_programmatic_signup",
+    ...CORE_TOOL_NAMES,
+];
+const json = (value, isError = false) => ({
+    ...(isError ? { isError: true } : {}),
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+});
+function isPaymentRequired(value) {
+    return (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, batch = false) {
+    return json({
+        status: "human_action_required",
+        action: "checkout",
+        message: batch
+            ? "Ask a human before presenting a purchase action. After explicit consent, use the offered checkout URL or billing URL, then resubmit the unchanged batch with the same idempotency key."
+            : "Ask a human before presenting a purchase action. After explicit consent, use the offered checkout URL or billing URL, then call resume_personal_context with the original target and retry fields.",
+        payment_required: contract,
+        resume_tool: batch ? "batch_connection_briefs" : "resume_personal_context",
+        ...(batch
+            ? {}
+            : {
+                resume_tool_alias: MCP_TOOL_ALIASES.resume_personal_context[0],
+            }),
+        resume_requires: batch
+            ? [
+                "original requests and options",
+                "original callback configuration, if any",
+                "payment_required.retry.idempotency_key",
+            ]
+            : [
+                "original target fields",
+                "payment_required.retry.idempotency_key",
+                "payment_required.credits.available",
+            ],
+        fixture: contract.fixture,
+    });
+}
+const profileSchema = z.object({
+    request_id: z.string().optional(),
+    linkedin_url: z.string().optional(),
+    name: z.string().optional(),
+    company: z.string().optional(),
+    email: z.string().optional(),
+});
+const detailSchema = z.enum(["compact", "full"]).optional();
+const batchOptionsSchema = z
+    .object({
+    detail: detailSchema,
+    public_sources_only: z.boolean().optional(),
+    include_sensitive_topics: z.boolean().optional(),
+    store_raw_quotes: z.boolean().optional(),
+    include_outreach_angles: z.boolean().optional(),
+})
+    .optional();
+const briefShape = {
+    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: detailSchema.describe('Response shape. Defaults to "compact"; use "full" for provenance sub-scores.'),
+};
+function cleanBriefArgs(args) {
+    const body = {};
+    for (const key of ["linkedin_url", "name", "company", "email", "detail"])
+        if (args[key])
+            body[key] = args[key];
+    if (!body.detail)
+        body.detail = "compact";
+    return body;
+}
+export function createMcpServer(context) {
+    const baseUrl = (context.baseUrl || "https://uniquenessengine.com").replace(/\/$/, "");
+    const signupContinuations = new Map();
+    const 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);
+    };
+    const api = async (path, options = {}) => {
+        const auth = options.auth !== false;
+        const key = context.getApiKey();
+        if (auth && !key)
+            return { status: 401, body: { error: "missing_api_key" } };
+        const headers = {};
+        if (options.body !== undefined)
+            headers["content-type"] = "application/json";
+        if (auth)
+            headers.authorization = `Bearer ${key}`;
+        const response = await fetch(`${baseUrl}${path}`, {
+            method: options.method || (options.body === undefined ? "GET" : "POST"),
+            headers,
+            ...(options.body === undefined
+                ? {}
+                : { body: JSON.stringify(options.body) }),
+        });
+        const contentType = response.headers.get("content-type") || "";
+        const body = contentType.includes("json")
+            ? await response.json().catch(() => ({}))
+            : { text: await response.text() };
+        return { status: response.status, body };
+    };
+    const authenticationRequired = () => json({
+        status: "human_action_required",
+        action: context.allowSignup ? "programmatic_signup" : "configure_api_key",
+        message: context.allowSignup
+            ? "No API key is configured. Use begin_programmatic_signup."
+            : "Configure the hosted MCP Authorization header with a Uniqueness Engine API key.",
+        ...(context.allowSignup
+            ? { begin_tool: "begin_programmatic_signup" }
+            : { account_url: `${baseUrl}/account` }),
+    }, true);
+    const requireKey = () => !!context.getApiKey();
+    const server = new McpServer({
+        name: MCP_SERVER_NAME,
+        version: MCP_SERVER_VERSION,
+    });
+    if (context.allowSignup) {
+        server.registerTool("begin_programmatic_signup", {
+            description: "Start named API-key setup. Human email approval is required.",
+            inputSchema: {
+                email: z.string().email(),
+                device_name: z.string().max(120).optional(),
+            },
+        }, async ({ email, device_name }) => {
+            pruneSignupContinuations();
+            const response = await api("/api/signup", {
+                auth: false,
+                body: {
+                    email,
+                    client_name: "Uniqueness MCP",
+                    device_name: device_name || "MCP host",
+                },
+            });
+            if (response.status !== 202 ||
+                response.body.status !== "email_verification_required" ||
+                typeof response.body.transaction_id !== "string" ||
+                typeof response.body.polling_token !== "string")
+                return json({
+                    status: "signup_failed",
+                    error: response.body.error || response.status,
+                    retry_after_seconds: response.body.retry_after_seconds,
+                }, true);
+            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",
+                continuation_id: continuationId,
+                expires_at: response.body.expires_at,
+                complete_tool: "complete_programmatic_signup",
+            });
+        });
+        server.registerTool("complete_programmatic_signup", {
+            description: "Complete a named signup only after human email approval.",
+            inputSchema: { continuation_id: z.string().uuid() },
+        }, async ({ continuation_id }) => {
+            pruneSignupContinuations();
+            const continuation = signupContinuations.get(continuation_id);
+            if (!continuation || continuation.expiresAt <= Date.now())
+                return json({
+                    status: "verification_expired",
+                    message: "Start a new named signup.",
+                }, true);
+            if (continuation.claimAttempted)
+                return json({
+                    status: "claim_already_attempted",
+                    action: "account_key_setup",
+                    account_url: `${baseUrl}/account`,
+                }, true);
+            const path = `/api/signup/verification/${encodeURIComponent(continuation.transactionId)}`;
+            const headers = { "x-verification-token": continuation.pollingToken };
+            const poll = await fetch(`${baseUrl}${path}`, { headers });
+            const state = await poll.json().catch(() => ({}));
+            if (state.status !== "approved") {
+                if (state.status && state.status !== "pending")
+                    signupContinuations.delete(continuation_id);
+                return json({
+                    status: state.status || "pending",
+                    human_action_required: state.status === "pending",
+                });
+            }
+            continuation.claimAttempted = true;
+            const claim = await fetch(`${baseUrl}${path}/claim`, {
+                method: "POST",
+                headers,
+            });
+            const issued = await claim.json().catch(() => ({}));
+            if (!claim.ok || typeof issued.api_key !== "string")
+                return json({
+                    status: "claim_failed",
+                    action: "account_key_setup",
+                    account_url: `${baseUrl}/account`,
+                }, true);
+            context.setApiKey?.(issued.api_key);
+            signupContinuations.delete(continuation_id);
+            return json({
+                status: "configured",
+                scope: "current_process_only",
+                account_url: `${baseUrl}/account`,
+                message: "This MCP process is configured. The API key was not exposed in tool output.",
+            });
+        });
+    }
+    const submitBrief = async (args, idempotencyKey) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api("/api/enrich", {
+            body: {
+                ...cleanBriefArgs(args),
+                idempotency_key: idempotencyKey || randomUUID(),
+            },
+        });
+        if (response.status === 402 && isPaymentRequired(response.body))
+            return paymentAction(response.body);
+        if (response.status >= 400)
+            return json(response.body, true);
+        if (response.body.personal_context || response.body.brief)
+            return json(response.body.personal_context || response.body.brief);
+        return json({
+            ...response.body,
+            message: response.body.job_id
+                ? "Call get_connection_brief_job with this job_id; do not resubmit the person."
+                : undefined,
+        });
+    };
+    const registerBrief = (name, description) => server.registerTool(name, { description, inputSchema: briefShape }, async (args) => submitBrief(args));
+    registerBrief("get_personal_context", "Submit one full-quality written enrichment. Returns an inline result or a job_id for get_connection_brief_job.");
+    registerBrief(MCP_TOOL_ALIASES.get_personal_context[0], "Deprecated alias for get_personal_context.");
+    const resumeShape = {
+        ...briefShape,
+        idempotency_key: z.string(),
+        previous_available: z.number().int().min(0),
+    };
+    const registerResume = (name, description) => server.registerTool(name, { description, inputSchema: resumeShape }, async (args) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const balance = await api("/api/account", { method: "GET" });
+        const available = spendableBalance(balance.body);
+        if (balance.status !== 200 || available === null)
+            return json({
+                status: "balance_unavailable",
+                message: "Could not verify spendable credit.",
+            }, true);
+        if (available <= args.previous_available)
+            return json({
+                status: "human_action_required",
+                action: "verify_checkout",
+                message: "Spendable credit has not increased since the 402 response.",
+                observed_balance: available,
+            });
+        return submitBrief(args, args.idempotency_key);
+    });
+    registerResume("resume_personal_context", "Verify increased spendable credit, then replay the original request with its idempotency key.");
+    registerResume(MCP_TOOL_ALIASES.resume_personal_context[0], "Deprecated alias for resume_personal_context.");
+    server.registerTool("get_billing_status", {
+        description: "Read spendable balance and auto-recharge state.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        if (!requireKey())
+            return authenticationRequired();
+        const [balance, recharge] = await Promise.all([
+            api("/api/account", { method: "GET" }),
+            api("/api/billing/auto-recharge", { method: "GET" }),
+        ]);
+        return json({
+            balance: balance.body,
+            auto_recharge: recharge.status === 200
+                ? recharge.body
+                : { error: recharge.body.error || "unavailable" },
+        }, balance.status !== 200);
+    });
+    const registerPreflight = (name, description) => server.registerTool(name, {
+        description,
+        inputSchema: { profiles: z.array(profileSchema).min(1).max(100) },
+        annotations: { readOnlyHint: true },
+    }, async ({ profiles }) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api("/api/enrich/batch", {
+            body: { profiles, estimate_only: true },
+        });
+        return json({ status: "preflight", ...response.body, all_or_nothing: true }, response.status >= 400);
+    });
+    registerPreflight("preflight_personal_contexts", "Read-only batch estimate; starts no work.");
+    registerPreflight(MCP_TOOL_ALIASES.preflight_personal_contexts[0], "Deprecated alias for preflight_personal_contexts.");
+    server.registerTool("get_connection_brief_job", {
+        description: "Retrieve one asynchronous job and its result when terminal.",
+        inputSchema: { job_id: z.string(), detail: detailSchema },
+        annotations: { readOnlyHint: true },
+    }, async ({ job_id, detail }) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api(`/api/jobs/${encodeURIComponent(job_id)}?detail=${detail || "full"}`, { method: "GET" });
+        return json(response.status < 400
+            ? {
+                ...response.body,
+                legacy_status: response.body.status,
+                status: response.body.lifecycle_status || response.body.status,
+            }
+            : response.body, response.status >= 400);
+    });
+    server.registerTool("batch_connection_briefs", {
+        description: "Submit up to 100 people as one durable batch; excess work remains queued.",
+        inputSchema: {
+            requests: z.array(profileSchema).min(1).max(100),
+            idempotency_key: z.string().optional(),
+            callback_url: z.string().url().optional(),
+            callback_secret: z.string().max(512).optional(),
+            options: batchOptionsSchema,
+        },
+    }, async (args) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api("/api/enrich/batch", { body: args });
+        if (response.status === 402 && isPaymentRequired(response.body))
+            return paymentAction(response.body, true);
+        return json(response.body, response.status >= 400);
+    });
+    server.registerTool("estimate_batch_cost", {
+        description: "Estimate batch cost without reserving credit.",
+        inputSchema: {
+            requests: z.array(profileSchema).min(1).max(100),
+            options: batchOptionsSchema,
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ requests, options }) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api("/api/enrich/batch", {
+            body: { requests, options, estimate_only: true },
+        });
+        return json(response.body, response.status >= 400);
+    });
+    server.registerTool("get_batch_status", {
+        description: "Retrieve aggregate and per-job batch status.",
+        inputSchema: { batch_id: z.string() },
+        annotations: { readOnlyHint: true },
+    }, async ({ batch_id }) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api(`/api/enrich/batch/${encodeURIComponent(batch_id)}`, { method: "GET" });
+        return json(response.body, response.status >= 400);
+    });
+    server.registerTool("get_batch_results", {
+        description: "Retrieve a stable page of batch results, including failures and needs-review outcomes.",
+        inputSchema: {
+            batch_id: z.string(),
+            cursor: z.string().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+            detail: detailSchema,
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ batch_id, cursor, limit, detail }) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const query = new URLSearchParams({
+            cursor: cursor || "0",
+            limit: String(limit || 50),
+            detail: detail || "full",
+        });
+        const response = await api(`/api/enrich/batch/${encodeURIComponent(batch_id)}/results?${query}`, { method: "GET" });
+        return json(response.body, response.status >= 400);
+    });
+    server.registerTool("export_batch", {
+        description: "Export a terminal batch as JSON, JSONL, CSV, or Markdown.",
+        inputSchema: {
+            batch_id: z.string(),
+            format: z.enum(["json", "jsonl", "csv", "markdown"]).optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ batch_id, format }) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const key = context.getApiKey();
+        const response = await fetch(`${baseUrl}/api/enrich/batch/${encodeURIComponent(batch_id)}/export?format=${format || "jsonl"}`, { headers: { authorization: `Bearer ${key}` } });
+        const text = await response.text();
+        return {
+            ...(response.ok ? {} : { isError: true }),
+            content: [{ type: "text", text }],
+        };
+    });
+    const registerJobAction = (name, action) => server.registerTool(name, {
+        description: action === "cancel"
+            ? "Cancel one queued or running job."
+            : "Retry one terminal system failure.",
+        inputSchema: { job_id: z.string() },
+        annotations: action === "cancel"
+            ? { destructiveHint: true }
+            : { idempotentHint: true },
+    }, async ({ job_id }) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api(`/api/jobs/${encodeURIComponent(job_id)}/${action}`, { body: {} });
+        return json(response.body, response.status >= 400);
+    });
+    registerJobAction("cancel_job", "cancel");
+    registerJobAction("retry_job", "retry");
+    server.registerTool("retry_failed_batch", {
+        description: "Submit a new batch containing only terminal system failures.",
+        inputSchema: {
+            batch_id: z.string(),
+            idempotency_key: z.string().optional(),
+        },
+        annotations: { idempotentHint: true },
+    }, async ({ batch_id, idempotency_key }) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api(`/api/enrich/batch/${encodeURIComponent(batch_id)}/retry`, { body: { idempotency_key } });
+        return json(response.body, response.status >= 400);
+    });
+    server.registerTool("submit_feedback", {
+        description: "Rate a delivered personal context.",
+        inputSchema: {
+            rating: z.enum(["up", "down"]),
+            canonical_id: z.string().optional(),
+            job_id: z.string().optional(),
+            note: z.string().optional(),
+        },
+    }, async (args) => {
+        if (!requireKey())
+            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" },
+        });
+        return json(response.body, response.status >= 400);
+    });
+    return server;
+}

package/index.mjs

@@ -1,398 +1,21 @@
 #!/usr/bin/env node
-// 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";
+// Local stdio fallback. Tool behavior lives in server.ts and is compiled into
+// dist/ for this npm package; the hosted MCP imports the same source directly.
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-
-const BASE = process.env.UNIQUENESS_API_URL || "https://uniquenessengine.com";
-let KEY = process.env.UNIQUENESS_API_KEY || "";
-const signupContinuations = new Map();
-
-const server = new McpServer({ name: "uniqueness", version: "0.5.2" });
-
-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_personal_context (alias: 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_personal_context",
-    resume_tool_alias: "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.personal_context || submit.body.brief)
-    return { kind: "brief", brief: submit.body.personal_context || 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. Defaults to "compact" (recommended for agents). Pass "full" for provenance sub-scores (debugging/eval/trust UI).',
-      ),
-  };
-}
-
-function cleanBriefArgs(args) {
-  const body = {};
-  for (const key of ["linkedin_url", "name", "company", "email", "detail"])
-    if (args[key]) body[key] = args[key];
-  // Agents should not inherit the HTTP production default (full). Compact is the
-  // recommended agent path; omit only means "use MCP default", not "use server default".
-  if (!body.detail) body.detail = "compact";
-  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) => {
-    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;
-    }
-    // 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);
-    }
-    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.",
-    });
+import { createMcpServer } from "./dist/server.js";
+
+let apiKey = process.env.UNIQUENESS_API_KEY || "";
+const server = createMcpServer({
+  baseUrl:
+    process.env.UNIQUENESS_API_URL || "https://uniquenessengine.com",
+  getApiKey: () => apiKey,
+  setApiKey: (value) => {
+    apiKey = value;
   },
-);
-
-function registerGetPersonalContext(toolName, description) {
-  server.tool(toolName, description, 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_personal_context 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);
-  });
-}
-
-function registerResumePersonalContext(toolName, description) {
-  server.tool(
-    toolName,
-    description,
-    {
-      ...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);
-    },
-  );
-}
-
-function registerPreflightPersonalContexts(toolName, description) {
-  server.tool(
-    toolName,
-    description,
-    { 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 });
-    },
-  );
-}
-
-registerGetPersonalContext(
-  "get_personal_context",
-  "Submit one full-quality written enrichment (personal context). A real target requires spendable credit. Defaults to detail=compact (recommended for agents); pass detail=full for provenance sub-scores. 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.",
-);
-registerGetPersonalContext(
-  "get_connection_brief",
-  "Deprecated alias for get_personal_context. Prefer get_personal_context.",
-);
-registerResumePersonalContext(
-  "resume_personal_context",
-  "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.",
-);
-registerResumePersonalContext(
-  "resume_connection_brief",
-  "Deprecated alias for resume_personal_context. Prefer resume_personal_context.",
-);
-
-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.",
-    });
-  },
-);
-
-registerPreflightPersonalContexts(
-  "preflight_personal_contexts",
-  "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.",
-);
-registerPreflightPersonalContexts(
-  "preflight_connection_briefs",
-  "Deprecated alias for preflight_personal_contexts. Prefer preflight_personal_contexts.",
-);
+  allowSignup: true,
+});
 
-server.tool(
-  "submit_feedback",
-  "Rate a delivered personal context. Feedback never changes billing.",
-  {
-    rating: z.enum(["up", "down"]),
-    canonical_id: z.string().optional(),
-    job_id: z.string().optional(),
-    note: z.string().optional(),
-  },
-  async (args) => {
-    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." });
-  },
+await server.connect(new StdioServerTransport());
+console.error(
+  "uniqueness-mcp ready (stdio; support@uniquenessengine.com)",
 );
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error("uniqueness-mcp ready (stdio)");

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "uniqueness-mcp",
-  "version": "0.5.2",
-  "description": "Conservative human-in-the-loop MCP server for Uniqueness Engine personal context.",
+  "version": "0.7.0",
+  "description": "Local stdio fallback for the hosted Uniqueness Engine MCP server.",
   "type": "module",
   "bin": {
     "uniqueness-mcp": "index.mjs"
   },
   "files": [
     "index.mjs",
+    "dist",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
   "engines": {
     "node": ">=18"
   },
@@ -17,5 +22,8 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.0"
   },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  },
   "license": "MIT"
 }