opedd-mcp 0.6.12 → 0.6.14

package/README.md

@@ -89,11 +89,11 @@ Exposes up to 17 tools to any AI assistant (some are conditional on env vars):
 | Tool | Description |
 |------|-------------|
 | `lookup_content` | Look up an article by URL — returns title, publisher, pricing |
-| `purchase_license` | Buy a single-article license via Stripe — returns OP-XXXX-XXXX key |
+| `purchase_license` | Buy a single-article license via Stripe — returns OP-XXXX-XXXX key. Requires `terms_accepted: true` (genuine buyer assent to opedd.com/terms; recorded with the licence) |
 | `verify_license` | Verify a license key — returns validity, article, publisher, blockchain proof |
 | `browse_registry` | Browse the public Opedd registry — lists issued LICENSES (use `publisher_directory` to browse publishers themselves) |
 | `publisher_directory` | Browse the public Opedd publisher catalog — paginated publishers with article counts + pricing + sample articles (primary buyer-discovery surface for AI labs) |
-| `purchase_enterprise_license` | Buy a bulk enterprise license covering multiple publishers (Phase 10) — returns Stripe `client_secret` |
+| `purchase_enterprise_license` | Buy a bulk enterprise license covering multiple publishers (Phase 10) — returns Stripe `client_secret`. Requires `terms_accepted: true`; the current Master Services Agreement version label is recorded with the licence (the backend rejects superseded labels) |
 | `rsl_get` | Fetch a publisher's RSL Standard manifest — public discovery surface; `jsonld: true` returns CDSM Article 4(3) signed receipt (Phase 12 W1.1) |
 | `detect_platform` | Detect the content platform behind a URL — returns suggested onboarding workflow for Substack / Beehiiv / Ghost / Medium / Brevo / custom (Phase 12 W3.1) |
 
@@ -107,8 +107,8 @@ Exposes up to 17 tools to any AI assistant (some are conditional on env vars):
 
 | Tool | Description |
 |------|-------------|
-| `list_feed` | List articles from a buyer's licensed catalog with `since` delta-feed support (Phase 11 M5) |
-| `stream_feed_ndjson` | Bulk-export up to 1000 articles per call via NDJSON wire format (Phase 11 M3) |
+| `list_feed` | List articles from a buyer's licensed catalog with `since` delta-feed support (Phase 11 M5). Flat-fee scopes carry full `content_body`; metered (filtered-scope) keys get a discovery-only feed (`content_body: null`, `content_access: "metered_per_call"`) — fetch text via `get_content` (billed per call) |
+| `stream_feed_ndjson` | Bulk-export up to 1000 articles per call via NDJSON wire format (Phase 11 M3). Same per-scope content contract as `list_feed` — metered keys export metadata only |
 
 **Requires `OPEDD_BUYER_JWT` (Supabase JWT) — buyer account + audit + compliance + EU AI Act surfaces**
 
@@ -266,7 +266,7 @@ npm run build # compiles to dist/
 | | Opedd | Generic search APIs |
 |---|---|---|
 | **What you get** | Licensed content + license key + on-chain proof — all in one API call | Scraped web content, no rights |
-| **Content delivery** | Full article text delivered via API (JSON), real-time feed via webhooks | Scraped snippets or full-page dumps |
+| **Content delivery** | Full article text via API (JSON) — bulk on flat-fee licenses, per-call (metered) on filtered licenses; real-time feed via webhooks | Scraped snippets or full-page dumps |
 | **Content quality** | Curated publisher content (niche B2B newsletters, expert analysis) | Whatever's on the open web |
 | **Rights** | Verifiable license key per article, publisher-authorized | No rights clearance |
 | **Proof** | On-chain (Tempo blockchain) — independently verifiable | None |

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 = [
@@ -415,6 +436,9 @@ function buildTools(has) {
         TOOLS.push({
             name: "list_feed",
             description: "List articles from a buyer's licensed catalog via GET /enterprise-license (Phase 10 + 11). " +
+                "Content contract: flat-fee scopes (custom/platform_wide) include full content_body; METERED " +
+                "(filtered-scope) keys get a discovery-only feed — content_body is null and content_access is " +
+                "'metered_per_call'; fetch article text via get_content (each retrieval is billed). " +
                 "Returns JSON-format response with paginated articles. " +
                 "Use `since` (ISO 8601) for delta-feed polling — only articles published after the timestamp. " +
                 "Use `cursor` for pagination across pages. " +
@@ -442,6 +466,8 @@ function buildTools(has) {
             name: "stream_feed_ndjson",
             description: "Bulk-export a buyer's licensed catalog via GET /enterprise-license?format=ndjson (Phase 11 M3). " +
                 "Returns up to 1000 articles per call (collected from line-delimited JSON wire format). " +
+                "Same per-scope content contract as list_feed: METERED (filtered-scope) keys export metadata only " +
+                "(content_body null, content_access 'metered_per_call') — use get_content for article text. " +
                 "Each article emits one usage_records row (analytics-only sentinel 'bulk-export:<request_id>:<article_id>' — not metered-billable per the revenue-model bifurcation invariant). " +
                 "Use `since` (ISO 8601) for delta-feed. Use `cursor` to paginate beyond 1000. " +
                 "Backend supports 5000 articles per call; the MCP cap is 1000 for transport reasonability. " +
@@ -665,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
@@ -845,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({
@@ -866,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({
@@ -887,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({
@@ -909,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}` },
@@ -919,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)
@@ -942,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)
@@ -964,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" });
@@ -978,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.12",
+  "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",