opedd-mcp 0.6.13 → 0.6.14

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,27 @@ 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.";
+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 = [
@@ -670,7 +691,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 +888,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 +909,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({
@@ -892,7 +930,7 @@ 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)");
+                    return credErr("A buyer session JWT is required for this tool", "OPEDD_BUYER_JWT", HOW_BUYER_JWT);
                 }
                 const { from, to, event_type, cursor, limit = 50 } = args;
                 const params = new URLSearchParams({
@@ -914,7 +952,7 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             // ── 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}` },
@@ -924,7 +962,7 @@ 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)");
+                    return credErr("A buyer session JWT is required for this tool", "OPEDD_BUYER_JWT", HOW_BUYER_JWT);
                 }
                 const { license_id, content_id, window_start, window_end } = args;
                 if (!license_id)
@@ -947,7 +985,7 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             // ── 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)");
+                    return credErr("A buyer session JWT is required for this tool", "OPEDD_BUYER_JWT", HOW_BUYER_JWT);
                 }
                 const { from, to, cursor } = args;
                 if (!from)
@@ -969,7 +1007,7 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             // ── 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 +1021,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.14",
   "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",