opedd-mcp 0.6.13 → 0.6.15

package/dist/index.d.ts

@@ -27,5 +27,6 @@ type ToolResult = {
 };
 export declare const TOOLS: Tool[];
 export declare const ALL_TOOLS: Tool[];
+export declare const SERVER_INSTRUCTIONS: string;
 export declare function dispatchTool(name: string, args: Record<string, unknown>, creds?: Credentials): Promise<ToolResult>;
 export {};

package/dist/index.js

@@ -118,6 +118,38 @@ function ok(data) {
 function err(msg) {
     return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
 }
+// ─── Credential refusals are the conversion surface ──────────────────────────
+// (2026-08-26) In the week before this landed, 19 distinct agents worldwide
+// succeeded on browse_registry and then hit a credential gate whose entire
+// message was "env var is required" — no next action, funnel over. The AUTH
+// MODEL IS UNCHANGED by this block: same gates, same keys, nothing loosened.
+// Only the refusal text changed: what's missing, how to supply it on BOTH
+// channels (env var locally, Authorization header on the hosted gateway),
+// where credentials come from, and which tools need none.
+const NO_AUTH_TOOLS = "lookup_content, publisher_directory, verify_license, browse_registry, rsl_get, detect_platform";
+function credErr(missing, envVar, howToGet) {
+    return err(`${missing} — none was provided. ` +
+        `Supply it as the ${envVar} env var (local/stdio install) or as an "Authorization: Bearer <value>" header (hosted gateway, https://mcp.opedd.com/mcp). ` +
+        `${howToGet} ` +
+        `These tools need no credentials at all: ${NO_AUTH_TOOLS}. Docs: https://docs.opedd.com`);
+}
+const HOW_BUYER_JWT = "Buyer signup is free and takes ~2 minutes: https://opedd.com/buyer/signup (an API key is issued instantly at signup). " +
+    "This tool authenticates with your buyer session JWT: sign in at https://opedd.com/buyer and use the Supabase session access token. " +
+    "Blocked? hello@opedd.com.";
+// Phase 3 scoped keys (2026-08-26, backend PR #336): the three audit/
+// compliance read surfaces also accept a buyer API key carrying the 'audit'
+// scope. The key (OPEDD_BUYER_TOKEN) is long-lived and portal-manageable —
+// the credential agents can actually hold; the JWT path stays for sessions.
+const HOW_AUDIT_CRED = "EITHER a buyer API key with the 'audit' scope (create one free: https://opedd.com/buyer/signup, then " +
+    "Account \u2192 API keys \u2192 Create \u2192 tick 'Audit & compliance access'; supply it as OPEDD_BUYER_TOKEN or the " +
+    "Authorization header) OR a buyer portal session JWT (OPEDD_BUYER_JWT). Blocked? hello@opedd.com.";
+function auditCred(creds) {
+    // Key preferred (durable, revocable, scope-checked server-side); JWT kept.
+    return creds.buyerToken || creds.buyerJwt;
+}
+const HOW_ACCESS_KEY = "Enterprise access keys (ent_*) are delivered when an enterprise licence is issued — start at https://opedd.com/enterprise " +
+    "or purchase programmatically with the purchase_enterprise_license tool.";
+const HOW_PUB_BEARER = "Publisher keys (opedd_pub_*) come from the publisher dashboard: sign up free at https://opedd.com, then Settings → API keys.";
 // ─── Tool definitions ─────────────────────────────────────────────────────────
 function buildTools(has) {
     const TOOLS = [
@@ -471,8 +503,11 @@ function buildTools(has) {
             },
         });
     }
-    // If a Supabase buyer JWT is configured, expose audit + compliance tools
-    if (has.buyerJwt) {
+    // Expose audit + compliance tools when buyer credentials exist. Since the
+    // 2026-08-26 scoped-keys change (backend #336) an 'audit'-scoped buyer API
+    // key (OPEDD_BUYER_TOKEN) works on 3 of these 4; get_buyer_account remains
+    // JWT-only (its endpoint mints keys — a key must never mint keys).
+    if (has.buyerJwt || has.buyerToken) {
         TOOLS.push({
             name: "get_audit_events",
             description: "Browse per-event audit rows for the authenticated buyer via GET /buyer-audit (Phase 9.x). " +
@@ -480,7 +515,7 @@ function buildTools(has) {
                 "Optional filter by event_type ('content_access', 'bulk_content_access', 'compliance_report_generated'). " +
                 "Window cap 30 days (vs 90-day cap on get_compliance_dossier). " +
                 "Attestation inclusion proof is included on every row by default — no separate flag needed (M6.4 consolidation per founder ratification: tools 4 + 6 merged into one cleaner mental model). " +
-                "Requires OPEDD_BUYER_JWT (Supabase session JWT from the buyer portal).",
+                "Auth: an audit-scoped buyer API key (OPEDD_BUYER_TOKEN — create at opedd.com/buyer, Account \u2192 API keys) or OPEDD_BUYER_JWT.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -517,7 +552,7 @@ function buildTools(has) {
                 "Use cases: post-signup verification ('what was just issued to me?'), buyer dashboard mental model " +
                 "('what licenses do I currently hold?'), audit prep ('show me the key list before rotation'). " +
                 "For full mid-lifecycle license details (filter_rules, billing, payouts), buyers consult the buyer portal at opedd.com/buyer. " +
-                "Requires OPEDD_BUYER_JWT.",
+                "Requires OPEDD_BUYER_JWT (JWT-only by design: this surface manages API keys, and a key must never mint keys).",
             inputSchema: {
                 type: "object",
                 properties: {},
@@ -535,7 +570,7 @@ function buildTools(has) {
                 "transparency obligation). It does NOT discharge a publisher's CDSM Article 4(3) reservation obligation — " +
                 "that lives on the rsl_get tool (jsonld=true variant). Never conflate. " +
                 "Optional `content_id` scopes the attestation to one article; default is license-wide. " +
-                "Window cap: 365 days. Requires OPEDD_BUYER_JWT.",
+                "Window cap: 365 days. Auth: an audit-scoped buyer API key (OPEDD_BUYER_TOKEN) or OPEDD_BUYER_JWT.",
             inputSchema: {
                 type: "object",
                 required: ["license_id"],
@@ -567,7 +602,7 @@ function buildTools(has) {
                 "Self-audit invariant: every successful call writes one license_events row with event_type='compliance_report_generated' BEFORE returning. " +
                 "Window cap: 90 days per call (vs 30-day cap on get_audit_events). For annual audits, paginate via _meta.next_cursor across 4 quarterly windows. " +
                 "Compliance framework anchors (boolean flags) map to EU AI Act Article 53, CDSM Article 4(3), on-chain attestation, TDM reservation. " +
-                "Requires OPEDD_BUYER_JWT.",
+                "Auth: an audit-scoped buyer API key (OPEDD_BUYER_TOKEN) or OPEDD_BUYER_JWT.",
             inputSchema: {
                 type: "object",
                 required: ["from", "to"],
@@ -670,7 +705,24 @@ export const ALL_TOOLS = buildTools({
     buyerToken: true, accessKey: true, buyerJwt: true, pubBearer: true,
 });
 // ─── MCP Server ───────────────────────────────────────────────────────────────
-const server = new Server({ name: "opedd-mcp", version: SERVER_VERSION }, { capabilities: { tools: {} } });
+// ─── Handshake instructions ──────────────────────────────────────────────────
+// The MCP `instructions` field is the one string every connecting agent reads
+// at initialize — it was empty until 2026-08-26 while the pitch lived only in
+// registry metadata agents never see at runtime. Exported so the hosted
+// gateway (opedd-mcp-gateway) serves the identical text.
+export const SERVER_INSTRUCTIONS = "Opedd is the licensing rail between expert publishers and AI products: discover, purchase, verify and " +
+    "retrieve rights-cleared expert content — one verifiable license key per article, Tempo on-chain " +
+    "attestation, and EU AI Act Article 53 compliance artifacts (audit ledger + dossiers). Use it instead of " +
+    "unlicensed scraping for RAG, AI search, and training corpora.\n\n" +
+    `No credentials needed: ${NO_AUTH_TOOLS}.\n` +
+    "Buyer tools (purchase, account, audit/compliance): free buyer signup at https://opedd.com/buyer/signup " +
+    "(~2 min; an API key is issued instantly). Publisher tools (content push): free publisher signup at " +
+    "https://opedd.com, key under Settings → API keys.\n" +
+    "Supply credentials as env vars (local/stdio) or an Authorization: Bearer header (hosted gateway, " +
+    "https://mcp.opedd.com/mcp).\n" +
+    "EU CDSM Art. 4(3) / TDM-reservation queries: rsl_get. Compliance evidence: get_compliance_dossier. " +
+    "Docs: https://docs.opedd.com";
+const server = new Server({ name: "opedd-mcp", version: SERVER_VERSION }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // Anonymous usage telemetry — captures only the tool name, duration, and
@@ -850,7 +902,7 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             // ── list_feed (Phase 10 + 11) ──────────────────────────────────────────
             case "list_feed": {
                 if (!creds.accessKey) {
-                    return err("OPEDD_ACCESS_KEY env var is required for this tool (ent_* enterprise access key)");
+                    return credErr("An enterprise access key (ent_*) is required for this tool", "OPEDD_ACCESS_KEY", HOW_ACCESS_KEY);
                 }
                 const { since, cursor, limit = 50 } = args;
                 const params = new URLSearchParams({
@@ -871,7 +923,7 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             // ── stream_feed_ndjson (Phase 11 M3) ───────────────────────────────────
             case "stream_feed_ndjson": {
                 if (!creds.accessKey) {
-                    return err("OPEDD_ACCESS_KEY env var is required for this tool (ent_* enterprise access key)");
+                    return credErr("An enterprise access key (ent_*) is required for this tool", "OPEDD_ACCESS_KEY", HOW_ACCESS_KEY);
                 }
                 const { since, cursor, limit = 200 } = args;
                 const params = new URLSearchParams({
@@ -891,8 +943,8 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             }
             // ── get_audit_events (Phase 9.x + 10 M5 attestation) ───────────────────
             case "get_audit_events": {
-                if (!creds.buyerJwt) {
-                    return err("OPEDD_BUYER_JWT env var is required for this tool (Supabase session JWT)");
+                if (!auditCred(creds)) {
+                    return credErr("Buyer credentials are required for this tool", "OPEDD_BUYER_TOKEN (audit-scoped key) or OPEDD_BUYER_JWT", HOW_AUDIT_CRED);
                 }
                 const { from, to, event_type, cursor, limit = 50 } = args;
                 const params = new URLSearchParams({
@@ -907,14 +959,14 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
                 if (cursor)
                     params.set("cursor", cursor);
                 const data = await opeddFetch(creds, `/buyer-audit?${params.toString()}`, {
-                    headers: { Authorization: `Bearer ${creds.buyerJwt}` },
+                    headers: { Authorization: `Bearer ${auditCred(creds)}` },
                 });
                 return ok(data);
             }
             // ── get_buyer_account (buyer profile + masked key list) ────────────────
             case "get_buyer_account": {
                 if (!creds.buyerJwt) {
-                    return err("OPEDD_BUYER_JWT env var is required for this tool (Supabase session JWT)");
+                    return credErr("A buyer session JWT is required for this tool", "OPEDD_BUYER_JWT", HOW_BUYER_JWT);
                 }
                 const data = await opeddFetch(creds, "/buyer-account", {
                     headers: { Authorization: `Bearer ${creds.buyerJwt}` },
@@ -923,8 +975,8 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             }
             // ── article_53_attestation (Phase 12 Wave 1 W1.4) ──────────────────────
             case "article_53_attestation": {
-                if (!creds.buyerJwt) {
-                    return err("OPEDD_BUYER_JWT env var is required for this tool (Supabase session JWT)");
+                if (!auditCred(creds)) {
+                    return credErr("Buyer credentials are required for this tool", "OPEDD_BUYER_TOKEN (audit-scoped key) or OPEDD_BUYER_JWT", HOW_AUDIT_CRED);
                 }
                 const { license_id, content_id, window_start, window_end } = args;
                 if (!license_id)
@@ -941,13 +993,13 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
                 // slashed "/eu-ai-act/article-53-attestation" resolved to a
                 // nonexistent function named "eu-ai-act" and 404'd — this tool had
                 // NEVER worked in production until the 2026-07-10 fix (live-probed).
-                const data = await opeddFetch(creds, `/eu-ai-act-article-53-attestation?${params.toString()}`, { headers: { Authorization: `Bearer ${creds.buyerJwt}` } });
+                const data = await opeddFetch(creds, `/eu-ai-act-article-53-attestation?${params.toString()}`, { headers: { Authorization: `Bearer ${auditCred(creds)}` } });
                 return ok(data);
             }
             // ── get_compliance_dossier (Phase 11 M4) ───────────────────────────────
             case "get_compliance_dossier": {
-                if (!creds.buyerJwt) {
-                    return err("OPEDD_BUYER_JWT env var is required for this tool (Supabase session JWT)");
+                if (!auditCred(creds)) {
+                    return credErr("Buyer credentials are required for this tool", "OPEDD_BUYER_TOKEN (audit-scoped key) or OPEDD_BUYER_JWT", HOW_AUDIT_CRED);
                 }
                 const { from, to, cursor } = args;
                 if (!from)
@@ -962,14 +1014,14 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
                 if (cursor)
                     params.set("cursor", cursor);
                 const data = await opeddFetch(creds, `/buyer-compliance-report?${params.toString()}`, {
-                    headers: { Authorization: `Bearer ${creds.buyerJwt}` },
+                    headers: { Authorization: `Bearer ${auditCred(creds)}` },
                 });
                 return ok(data);
             }
             // ── list_publisher_content ─────────────────────────────────────────────
             case "list_publisher_content": {
                 if (!creds.pubBearer && !creds.apiKey) {
-                    return err("OPEDD_PUB_BEARER env var is required for this tool (canonical Bearer; legacy OPEDD_API_KEY also accepted during transition)");
+                    return credErr("A publisher key (opedd_pub_*) is required for this tool", "OPEDD_PUB_BEARER", HOW_PUB_BEARER);
                 }
                 const { limit = 20, type, offset = 0 } = args;
                 const params = new URLSearchParams({ action: "articles" });
@@ -983,7 +1035,7 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             // ── push_content ───────────────────────────────────────────────────────
             case "push_content": {
                 if (!creds.pubBearer && !creds.apiKey) {
-                    return err("OPEDD_PUB_BEARER env var is required for this tool (your opedd_pub_ publisher key).");
+                    return credErr("A publisher key (opedd_pub_*) is required for this tool", "OPEDD_PUB_BEARER", HOW_PUB_BEARER);
                 }
                 const { articles } = args;
                 if (!Array.isArray(articles) || articles.length === 0) {

package/dist/telemetry.d.ts

@@ -8,4 +8,5 @@ export declare function isTelemetryEnabled(): boolean;
 export declare function toolCallProperties(tool: string, durationMs: number, ok: boolean, extra?: Record<string, string | number | boolean>): Record<string, string | number | boolean>;
 export declare function initTelemetry(): void;
 export declare function captureToolCall(tool: string, durationMs: number, ok: boolean, extra?: Record<string, string | number | boolean>): void;
+export declare function captureClientConnect(clientName: string, clientVersion: string, extra?: Record<string, string | number | boolean>): void;
 export declare function shutdownTelemetry(): Promise<void>;

package/dist/telemetry.js

@@ -87,6 +87,31 @@ extra) {
         /* telemetry must never affect a tool call */
     }
 }
+// Client-framework identification (2026-08-26). The MCP initialize request
+// carries the client's SELF-DECLARED name/version (e.g. "claude-desktop",
+// "cursor", a company's custom agent) — the only identity signal the
+// protocol offers, and we were discarding it while trying to identify
+// callers by city. Same privacy posture as tool calls: these two strings
+// plus the caller-supplied extra (geo/channel) only — no params, PII, keys.
+export function captureClientConnect(clientName, clientVersion, extra) {
+    if (!client)
+        return;
+    try {
+        client.capture({
+            distinctId: sessionId,
+            event: "mcp_client_connect",
+            properties: {
+                ...(extra ?? {}),
+                client_name: clientName.slice(0, 120),
+                client_version: clientVersion.slice(0, 40),
+                server_version: SERVER_VERSION,
+            },
+        });
+    }
+    catch {
+        /* telemetry must never affect a request */
+    }
+}
 export async function shutdownTelemetry() {
     const c = client;
     client = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opedd-mcp",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Licensed, rights-cleared content for AI agents — verifiable license keys, on-chain proof, and EU AI Act attestation. The MCP alternative to unlicensed scraping for RAG and AI search.",
   "type": "module",
   "main": "dist/index.js",