uniqueness-mcp 0.7.3 → 0.8.1

package/README.md

@@ -36,9 +36,10 @@ Requires Node 18+. After changing the pin, start a new client session so the too
 
 Hosted and stdio both expose:
 
-- `get_personal_context` (`get_connection_brief`)
+- `get_personal_context` (`get_connection_brief`) — optional `refresh:true` to force a fresh collection. Omit for ordinary repeat reads. Batch tools do not accept refresh.
 - `resume_personal_context` (`resume_connection_brief`)
 - `get_billing_status`
+- `request_higher_limits`
 - `preflight_personal_contexts` (`preflight_connection_briefs`)
 - `get_connection_brief_job`
 - `batch_connection_briefs`
@@ -55,4 +56,28 @@ Stdio also exposes `begin_programmatic_signup` and `complete_programmatic_signup
 
 MCP has no purchase, payment-method, auto-recharge, or subscription tools. On `402 payment_required`, present checkout URLs only after explicit human consent.
 
+## Usage limits
+
+Exact current limits are shown on the account page, in `GET /api/account` (`usage_limits`), in `uniqueness account` and in the MCP `get_billing_status` tool.
+
+**Public ladder**
+- free: 25 personal contexts per 24h, max batch 25
+- tier_1: 250 personal contexts per 24h, max batch 50
+- tier_2: 1,000 personal contexts per 24h, max batch 100
+- tier_3: 5,000 personal contexts per 24h, max batch 100
+- unlimited: by request, max batch 100
+
+**Automatic promotion:**
+- Any real credit pack, subscription or auto-recharge → tier_1.
+- 250 lifetime paid credits → tier_2.
+- 1,000 → tier_3.
+- Intro offers and 5-packs don't count.
+- Limits only go up, never down.
+- Accounts with custom limits we've set don't change automatically.
+
+**Window:** 24 hours starting from your first counted personal context. It's not midnight and not rolling. Cache re-serves don't count.
+
+How to request more: the account page button, `POST /api/account/usage-limits/request`, `uniqueness limits request`, or the MCP `request_higher_limits` tool.
+A 429 `usage_cap_exceeded` means a pace limit, not credits; honor `Retry-After`.
+
 [MCP quickstart](https://uniquenessengine.com/documentation/mcp/quickstart) · support@uniquenessengine.com

package/dist/server.js

@@ -2,7 +2,7 @@ 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.3";
+export const MCP_SERVER_VERSION = "0.8.1";
 export const MCP_TOOL_ALIASES = {
     get_personal_context: ["get_connection_brief"],
     resume_personal_context: ["resume_connection_brief"],
@@ -14,6 +14,7 @@ const CORE_TOOL_NAMES = [
     "resume_personal_context",
     "resume_connection_brief",
     "get_billing_status",
+    "request_higher_limits",
     "preflight_personal_contexts",
     "preflight_connection_briefs",
     "get_connection_brief_job",
@@ -107,12 +108,18 @@ const briefShape = {
     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.'),
+    refresh: z
+        .boolean()
+        .optional()
+        .describe("Set true only when the user asks to rerun, refresh, run again, look again, re-enrich, or check whether new UE changes are working. Ordinary repeat reads must omit this. Do not resubmit while polling an existing job."),
 };
 function cleanBriefArgs(args) {
     const body = {};
     for (const key of ["linkedin_url", "name", "company", "email", "detail"])
         if (args[key])
             body[key] = args[key];
+    if (typeof args.refresh === "boolean")
+        body.refresh = args.refresh;
     if (!body.detail)
         body.detail = "compact";
     return body;
@@ -284,7 +291,12 @@ export function createMcpServer(context) {
         });
     };
     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("get_personal_context", "Submit one full-quality written enrichment. Returns an inline result or a job_id for get_connection_brief_job. " +
+        "Use refresh=true only when the user says rerun, refresh, run again, look again, re-enrich, or asks whether new UE changes are working. " +
+        "Do not use refresh for ordinary repeat reads. Do not resubmit while polling an existing job. " +
+        "A normal repeat lookup is not proof that a fresh enrichment occurred. " +
+        "Only claim a rerun happened when there is a new job, usage.refresh_executed=true, or a new generated timestamp/source inventory. " +
+        "cache_status=hit means this request served an existing result; cache_status=miss means this request ran collection.");
     registerBrief(MCP_TOOL_ALIASES.get_personal_context[0], "Deprecated alias for get_personal_context.");
     const resumeShape = {
         ...briefShape,
@@ -310,10 +322,10 @@ export function createMcpServer(context) {
             });
         return submitBrief(args, args.idempotency_key);
     });
-    registerResume("resume_personal_context", "Verify increased spendable credit, then replay the original request with its idempotency key.");
+    registerResume("resume_personal_context", "Verify increased spendable credit, then replay the original request with its idempotency key. Pass the same refresh value as the 402 request — a refresh 402 resumed without refresh:true is a 409.");
     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.",
+        description: "Read spendable balance, usage limits (tier, daily limit, used in window, max batch) and auto-recharge state.",
         inputSchema: {},
         annotations: { readOnlyHint: true },
     }, async () => {
@@ -330,6 +342,20 @@ export function createMcpServer(context) {
                 : { error: recharge.body.error || "unavailable" },
         }, balance.status !== 200);
     });
+    server.registerTool("request_higher_limits", {
+        description: "Request an increase to your daily account usage limits.",
+        inputSchema: {
+            reason: z.string().max(1000).optional(),
+            desired_daily_limit: z.number().int().min(1).max(100000).optional(),
+        },
+    }, async (args) => {
+        if (!requireKey())
+            return authenticationRequired();
+        const response = await api("/api/account/usage-limits/request", {
+            body: args,
+        });
+        return json(response.body, response.status >= 400);
+    });
     const registerPreflight = (name, description) => server.registerTool(name, {
         description,
         inputSchema: { profiles: z.array(profileSchema).min(1).max(100) },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniqueness-mcp",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "Local stdio fallback for the hosted Uniqueness Engine MCP server.",
   "type": "module",
   "bin": {