uniqueness-mcp 0.5.0 → 0.5.2

package/README.md

@@ -0,0 +1,67 @@
+# uniqueness-mcp
+
+[MCP](https://modelcontextprotocol.io) server for [Uniqueness Engine](https://uniquenessengine.com) — conservative, human-in-the-loop access to fact-checked **personal context**.
+
+Commercial contract: `hard-paid-v1`.
+
+## Install
+
+```bash
+npx -y uniqueness-mcp
+```
+
+Requires Node **18+**.
+
+## Cursor / Claude Desktop config
+
+```json
+{
+  "mcpServers": {
+    "uniqueness": {
+      "command": "npx",
+      "args": ["-y", "uniqueness-mcp"],
+      "env": {
+        "UNIQUENESS_API_KEY": "uq_live_..."
+      }
+    }
+  }
+}
+```
+
+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)
+
+- **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
+```
+
+## Docs
+
+- [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)
+
+Support: support@uniquenessengine.com

package/index.mjs

@@ -11,7 +11,7 @@ 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.0" });
+const server = new McpServer({ name: "uniqueness", version: "0.5.2" });
 
 const json = (value, isError = false) => ({
   ...(isError ? { isError: true } : {}),
@@ -63,9 +63,10 @@ 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.",
+    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_connection_brief",
+    resume_tool: "resume_personal_context",
+    resume_tool_alias: "resume_connection_brief",
     resume_requires: [
       "original target fields",
       "payment_required.retry.idempotency_key",
@@ -104,7 +105,8 @@ async function submitBrief(args, idempotencyKey) {
   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.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);
 }
@@ -115,7 +117,12 @@ function briefInputSchema() {
     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"),
+    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).',
+      ),
   };
 }
 
@@ -123,6 +130,9 @@ 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;
 }
 
@@ -254,11 +264,8 @@ server.tool(
   },
 );
 
-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) => {
+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);
@@ -267,44 +274,77 @@ server.tool(
       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 === "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);
-  },
-);
+  });
+}
 
-server.tool(
-  "resume_connection_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.",
-  {
-    ...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);
-  },
+);
+registerResumePersonalContext(
+  "resume_connection_brief",
+  "Deprecated alias for resume_personal_context. Prefer resume_personal_context.",
 );
 
 server.tool(
@@ -326,21 +366,18 @@ server.tool(
   },
 );
 
-server.tool(
-  "preflight_connection_briefs",
+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.",
-  { 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 });
-  },
+);
+registerPreflightPersonalContexts(
+  "preflight_connection_briefs",
+  "Deprecated alias for preflight_personal_contexts. Prefer preflight_personal_contexts.",
 );
 
 server.tool(
   "submit_feedback",
-  "Rate a delivered Connection Brief. Feedback never changes billing.",
+  "Rate a delivered personal context. Feedback never changes billing.",
   {
     rating: z.enum(["up", "down"]),
     canonical_id: z.string().optional(),

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "uniqueness-mcp",
-  "version": "0.5.0",
-  "description": "Conservative human-in-the-loop MCP server for Uniqueness Engine fact-checked connection briefs.",
+  "version": "0.5.2",
+  "description": "Conservative human-in-the-loop MCP server for Uniqueness Engine personal context.",
   "type": "module",
   "bin": {
     "uniqueness-mcp": "index.mjs"
   },
   "files": [
-    "index.mjs"
+    "index.mjs",
+    "README.md"
   ],
   "engines": {
     "node": ">=18"