opedd-mcp 0.2.0 → 0.4.0

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   ListToolsRequestSchema,
   type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
+import { pathToFileURL } from "node:url";
 
 // ─── Configuration ────────────────────────────────────────────────────────────
 
@@ -16,9 +17,18 @@ const API_BASE =
 
 const BUYER_EMAIL = process.env.OPEDD_BUYER_EMAIL;
 const PAYMENT_METHOD_ID = process.env.OPEDD_PAYMENT_METHOD_ID;
-const API_KEY = process.env.OPEDD_API_KEY; // publisher API key (op_...)
-const BUYER_TOKEN = process.env.OPEDD_BUYER_TOKEN; // buyer API token (opedd_buyer_live_... or bk_live_...)
-const ACCESS_KEY = process.env.OPEDD_ACCESS_KEY; // enterprise access key (eak_*); for /enterprise-license GET feed
+// B91 v0.4.0 migration (2026-05-26): canonical Bearer auth.
+// OPEDD_PUB_BEARER is the new canonical opedd_pub_<env>_<32-hex> key
+// (issued via POST /publishers-api-keys action=create_api_key).
+// OPEDD_API_KEY retained as backward-compat alias for legacy op_ keys
+// during the dual-mode transition window on the /api endpoint (Phase A
+// shipped opedd-backend 2026-05-26). Backend Phase C will drop the
+// op_ path entirely; users MUST migrate to OPEDD_PUB_BEARER before
+// then. Prefer Bearer if both set.
+const PUB_BEARER = process.env.OPEDD_PUB_BEARER; // canonical opedd_pub_<env>_<32-hex>
+const API_KEY = process.env.OPEDD_API_KEY; // LEGACY op_<32-hex> — retiring per backend Phase C
+const BUYER_TOKEN = process.env.OPEDD_BUYER_TOKEN; // buyer API token (opedd_buyer_live_... or opedd_buyer_test_...)
+const ACCESS_KEY = process.env.OPEDD_ACCESS_KEY; // enterprise access key (ent_*); for /enterprise-license GET feed
 const BUYER_JWT = process.env.OPEDD_BUYER_JWT; // Supabase JWT; for /buyer-audit + /buyer-compliance-report
 
 // ─── HTTP helpers ─────────────────────────────────────────────────────────────
@@ -27,7 +37,9 @@ async function opeddFetch(path: string, options: RequestInit = {}): Promise<unkn
   const url = `${API_BASE}${path}`;
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
-    ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
+    // B91 v0.4.0 (2026-05-26): canonical Bearer preferred; legacy X-API-Key
+    // accepted only as fallback during transition window
+    ...(PUB_BEARER ? { Authorization: `Bearer ${PUB_BEARER}` } : (API_KEY ? { "X-API-Key": API_KEY } : {})),
     ...(options.headers as Record<string, string> ?? {}),
   };
   const res = await fetch(url, { ...options, headers });
@@ -49,7 +61,8 @@ async function opeddFetchNdjson(
   const url = `${API_BASE}${path}`;
   const headers: Record<string, string> = {
     Accept: "application/x-ndjson",
-    ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
+    // B91 v0.4.0 (2026-05-26): canonical Bearer preferred; legacy fallback
+    ...(PUB_BEARER ? { Authorization: `Bearer ${PUB_BEARER}` } : (API_KEY ? { "X-API-Key": API_KEY } : {})),
     ...(options.headers as Record<string, string> ?? {}),
   };
   const res = await fetch(url, { ...options, headers });
@@ -94,7 +107,7 @@ function err(msg: string): ToolResult {
 
 // ─── Tool definitions ─────────────────────────────────────────────────────────
 
-const TOOLS: Tool[] = [
+export const TOOLS: Tool[] = [
   {
     name: "lookup_content",
     description:
@@ -207,13 +220,106 @@ const TOOLS: Tool[] = [
       },
     },
   },
+  // ─── Public buyer-discovery — catalog browse ──────────────────────────────
+  {
+    name: "publisher_directory",
+    description:
+      "Browse the public Opedd publisher catalog via GET /publisher-directory. " +
+      "Returns paginated publishers with article counts, pricing (per-article + annual + monthly-forward-feed), " +
+      "plan, and sample articles (RAG-extended metadata). " +
+      "**The primary discovery surface for AI labs to find Opedd-licensable publishers** — distinct from " +
+      "`browse_registry` (which lists issued LICENSES, not publishers). " +
+      "Filter by category (case-insensitive substring), min_articles, or verified status. " +
+      "Public no-auth — useful pre-purchase scoping before buyers commit to enterprise-license POST.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description: "Case-insensitive substring filter on publisher category (e.g. 'finance', 'AI').",
+        },
+        min_articles: {
+          type: "number",
+          description: "Filter to publishers with at least this many licensable articles.",
+        },
+        verified: {
+          type: "string",
+          description: "'true' to show only verified publishers (default), 'false' for unverified.",
+        },
+        limit: {
+          type: "number",
+          description: "Page size cap.",
+        },
+        offset: {
+          type: "number",
+          description: "Pagination offset.",
+        },
+      },
+    },
+  },
+  // ─── Phase 12 Wave 3 W3.1 — onboarding helpers ────────────────────────────
+  {
+    name: "detect_platform",
+    description:
+      "Detect the content platform behind a URL via POST /detect-platform (Phase 12 Wave 3 W3.1). " +
+      "Public no-auth lookup. Given a URL, identifies what platform powers it " +
+      "(Substack / Beehiiv / Ghost / Medium / Brevo / custom) and returns the suggested onboarding workflow. " +
+      "Hostname-detectable platforms (Substack subdomain, Beehiiv suffix, etc.) resolve in milliseconds; " +
+      "custom domains may take ~few seconds while the detector probes well-known platform endpoints in parallel. " +
+      "Returns: {platform, confidence, archive_method, forward_method, required_credentials, instructions}. " +
+      "The archive_method + forward_method fields are the two onboarding-workflow inputs Opedd's setup wizard reads " +
+      "(one for historical content backfill, one for new-content forward stream). " +
+      "instructions is human-readable operator copy explaining the inferred path.",
+    inputSchema: {
+      type: "object",
+      required: ["url"],
+      properties: {
+        url: {
+          type: "string",
+          description: "Publisher URL to inspect (any well-formed URL works; hostname-match short-circuits the probe path).",
+        },
+      },
+    },
+  },
+  // ─── Phase 12 Wave 1 W1.1 — public RSL Standard manifest ─────────────────
+  {
+    name: "rsl_get",
+    description:
+      "Fetch a publisher's RSL Standard manifest via GET /rsl-manifest (Phase 12 Wave 1 W1.1). " +
+      "Public no-auth endpoint — discovery surface for AI agents/crawlers wanting to know what's licensable " +
+      "from a publisher BEFORE going through the buyer-account signup flow. " +
+      "Returns the 4 canonical license types (ai_retrieval, ai_training, human_per_article, human_full_archive) " +
+      "the publisher has opted into, plus the EU CDSM Article 4(3) opt-out posture (`tdm_reservation`). " +
+      "Set `jsonld: true` to request the JSON-LD shape with embedded HMAC-SHA256 signed receipt over the " +
+      "CDSM Article 4(3) reservation state + `tdm:reservationSignedAt` timestamp — regulators can post-hoc " +
+      "verify the reservation was the claimed value at the claimed time. Default `jsonld: false` returns " +
+      "the raw RSL Standard JSON manifest. " +
+      "Per INVARIANTS.md W1.6: this is the PUBLISHER-side CDSM Article 4(3) declaration surface. It is NOT " +
+      "an EU AI Act Article 53 attestation (which is buyer-side, JWT-auth, via article_53_attestation tool).",
+    inputSchema: {
+      type: "object",
+      required: ["publisher_id"],
+      properties: {
+        publisher_id: {
+          type: "string",
+          description: "UUID of the publisher whose RSL manifest to fetch. Publisher must be verified.",
+        },
+        jsonld: {
+          type: "boolean",
+          description:
+            "If true, request JSON-LD shape (Accept: application/ld+json) with embedded HMAC-SHA256 signed receipt. " +
+            "Default false returns raw RSL Standard JSON shape.",
+        },
+      },
+    },
+  },
   // ─── Phase 10 + 11 buyer-side surfaces (M6.4) ─────────────────────────────
   {
     name: "purchase_enterprise_license",
     description:
       "Purchase a bulk enterprise license covering multiple publishers (Phase 10). " +
       "Returns a Stripe client_secret for payment completion + the enterprise_license_id. " +
-      "After payment, an eak_* access key is emailed to buyer_email. " +
+      "After payment, an ent_* access key is emailed to buyer_email. " +
       "Scopes: 'custom' (pass-through publisher_ids), 'platform_wide' (auto-resolve all opted-in publishers), 'filtered' (Phase 10 filter_rules). " +
       "License tiers: 'rag' (= ai_retrieval), 'training' (= ai_training, flat-fee not metered), 'inference' (= ai_retrieval), 'full_ai' (writes both retrieval + training records).",
     inputSchema: {
@@ -270,7 +376,7 @@ if (BUYER_TOKEN) {
   TOOLS.push({
     name: "get_content",
     description:
-      "Retrieve the full body of a licensed article using a buyer API token (opedd_buyer_live_* canonical post-5.2.1a; bk_live_* legacy). " +
+      "Retrieve the full body of a licensed article using a buyer API token (opedd_buyer_live_* canonical; opedd_buyer_test_* for sandbox). " +
       "Requires OPEDD_BUYER_TOKEN env var (create one at opedd.com/licenses after purchasing). " +
       "Works for per-article licenses (token scoped to that article) and archive licenses (token covers all publisher content). " +
       "The publisher must have content delivery enabled and must have pushed content for the article. " +
@@ -287,7 +393,7 @@ if (BUYER_TOKEN) {
         },
         buyer_token: {
           type: "string",
-          description: "Buyer API token (opedd_buyer_live_* or bk_live_*). Falls back to OPEDD_BUYER_TOKEN env var.",
+          description: "Buyer API token (opedd_buyer_live_* or opedd_buyer_test_*). Falls back to OPEDD_BUYER_TOKEN env var.",
         },
       },
     },
@@ -303,7 +409,7 @@ if (ACCESS_KEY) {
       "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. " +
-      "Requires OPEDD_ACCESS_KEY (eak_* enterprise access key). " +
+      "Requires OPEDD_ACCESS_KEY (ent_* enterprise access key). " +
       "For larger bulk corpus pulls, use stream_feed_ndjson (up to 1000 articles per call vs 200 here).",
     inputSchema: {
       type: "object",
@@ -332,7 +438,7 @@ if (ACCESS_KEY) {
       "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. " +
       "Real bulk-ingest pipelines should use the Python SDK (pip install opedd) directly — not via MCP. " +
-      "Requires OPEDD_ACCESS_KEY (eak_*).",
+      "Requires OPEDD_ACCESS_KEY (ent_*).",
     inputSchema: {
       type: "object",
       properties: {
@@ -391,6 +497,59 @@ if (BUYER_JWT) {
       },
     },
   });
+  TOOLS.push({
+    name: "get_buyer_account",
+    description:
+      "Fetch the authenticated buyer's account profile + masked API key list via GET /buyer-account. " +
+      "Returns the enterprise_buyers row (contact_email, buyer_org, created_at, etc.) plus a list of all " +
+      "buyer-side API keys with masked prefixes (NEVER plaintext post-issuance — only the 12-char " +
+      "key_prefix is returned, e.g. 'opedd_buyer_'). " +
+      "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.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  });
+  TOOLS.push({
+    name: "article_53_attestation",
+    description:
+      "Issue a signed JWT attesting to EU AI Act Article 53 compliance for a specific license via " +
+      "GET /eu-ai-act/article-53-attestation (Phase 12 Wave 1 W1.4). " +
+      "Returns a freshly-signed HS256 JWT regulators can verify offline against the canonical signing key. " +
+      "Embeds: license context, usage-count over the attestation window, the most-recent Tempo Merkle root, " +
+      "and canonical claims (iss/sub/iat/exp/jti/aud). " +
+      "**The artifact AI labs hand to legal/procurement for EU AI Act Article 53(1)(d) transparency-obligation evidence.** " +
+      "Per INVARIANTS.md W1.6: this attests to EU AI Act Article 53 ONLY (buyer-side GPAI-model-provider " +
+      "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.",
+    inputSchema: {
+      type: "object",
+      required: ["license_id"],
+      properties: {
+        license_id: {
+          type: "string",
+          description: "UUID of the enterprise_license OR legacy individual license to attest. Buyer must own it.",
+        },
+        content_id: {
+          type: "string",
+          description: "Optional UUID of a specific article to scope the attestation. Default: license-wide.",
+        },
+        window_start: {
+          type: "string",
+          description: "ISO 8601 lower bound of the attestation window. Default: now - 90 days.",
+        },
+        window_end: {
+          type: "string",
+          description: "ISO 8601 upper bound. Default: now. Window may not exceed 365 days (hard cap).",
+        },
+      },
+    },
+  });
   TOOLS.push({
     name: "get_compliance_dossier",
     description:
@@ -423,11 +582,11 @@ if (BUYER_JWT) {
 }
 
 // If a publisher API key is configured, expose publisher-specific tooling
-if (API_KEY) {
+if (PUB_BEARER || API_KEY) {
   TOOLS.push({
     name: "list_publisher_content",
     description:
-      "List all licensable articles for the authenticated publisher (requires OPEDD_API_KEY). " +
+      "List all licensable articles for the authenticated publisher (requires OPEDD_PUB_BEARER, or legacy OPEDD_API_KEY). " +
       "Returns articles with titles, descriptions, pricing, and sales statistics. " +
       "Use article IDs from this list to purchase licenses via purchase_license.",
     inputSchema: {
@@ -454,15 +613,28 @@ if (API_KEY) {
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "opedd-mcp", version: "0.2.0" },
+  { name: "opedd-mcp", version: "0.3.0" },
   { capabilities: { tools: {} } }
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args = {} } = request.params;
+server.setRequestHandler(CallToolRequestSchema, async (request) =>
+  dispatchTool(request.params.name, (request.params.arguments ?? {}) as Record<string, unknown>),
+);
 
+// ─── Tool dispatcher (exported for unit tests) ────────────────────────────────
+//
+// Extracted from the inline handler 2026-05-24 EEST as part of the opedd-mcp
+// test cohort ship. Behavior-preserving: the server.setRequestHandler above
+// is a thin delegation to dispatchTool. Exporting allows unit tests to mock
+// global fetch + invoke each tool's handler directly without spawning a
+// stdio subprocess.
+
+export async function dispatchTool(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<ToolResult> {
   try {
     switch (name) {
       // ── lookup_content ─────────────────────────────────────────────────────
@@ -583,6 +755,55 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return ok(data);
       }
 
+      // ── publisher_directory (buyer-discovery catalog browse) ───────────────
+      case "publisher_directory": {
+        const { category, min_articles, verified, limit, offset } = args as {
+          category?: string;
+          min_articles?: number;
+          verified?: string;
+          limit?: number;
+          offset?: number;
+        };
+        const params = new URLSearchParams();
+        if (category) params.set("category", category);
+        if (min_articles !== undefined) params.set("min_articles", String(min_articles));
+        if (verified !== undefined) params.set("verified", verified);
+        if (limit !== undefined) params.set("limit", String(limit));
+        if (offset !== undefined) params.set("offset", String(offset));
+
+        const query = params.toString();
+        const data = await opeddFetch(`/publisher-directory${query ? `?${query}` : ""}`);
+        return ok(data);
+      }
+
+      // ── detect_platform (Phase 12 Wave 3 W3.1) ─────────────────────────────
+      case "detect_platform": {
+        const { url } = args as { url: string };
+        if (!url) return err("url is required");
+
+        const data = await opeddFetch("/detect-platform", {
+          method: "POST",
+          body: JSON.stringify({ url }),
+        });
+        return ok(data);
+      }
+
+      // ── rsl_get (Phase 12 Wave 1 W1.1) ─────────────────────────────────────
+      case "rsl_get": {
+        const { publisher_id, jsonld = false } = args as {
+          publisher_id: string;
+          jsonld?: boolean;
+        };
+        if (!publisher_id) return err("publisher_id is required");
+
+        const accept = jsonld ? "application/ld+json" : "application/json";
+        const data = await opeddFetch(
+          `/rsl-manifest?publisher_id=${encodeURIComponent(publisher_id)}`,
+          { headers: { Accept: accept } },
+        );
+        return ok(data);
+      }
+
       // ── purchase_enterprise_license (Phase 10) ─────────────────────────────
       case "purchase_enterprise_license": {
         const {
@@ -637,7 +858,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // ── list_feed (Phase 10 + 11) ──────────────────────────────────────────
       case "list_feed": {
         if (!ACCESS_KEY) {
-          return err("OPEDD_ACCESS_KEY env var is required for this tool (eak_* enterprise access key)");
+          return err("OPEDD_ACCESS_KEY env var is required for this tool (ent_* enterprise access key)");
         }
         const { since, cursor, limit = 50 } = args as {
           since?: string;
@@ -659,7 +880,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // ── stream_feed_ndjson (Phase 11 M3) ───────────────────────────────────
       case "stream_feed_ndjson": {
         if (!ACCESS_KEY) {
-          return err("OPEDD_ACCESS_KEY env var is required for this tool (eak_* enterprise access key)");
+          return err("OPEDD_ACCESS_KEY env var is required for this tool (ent_* enterprise access key)");
         }
         const { since, cursor, limit = 200 } = args as {
           since?: string;
@@ -704,6 +925,42 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return ok(data);
       }
 
+      // ── get_buyer_account (buyer profile + masked key list) ────────────────
+      case "get_buyer_account": {
+        if (!BUYER_JWT) {
+          return err("OPEDD_BUYER_JWT env var is required for this tool (Supabase session JWT)");
+        }
+        const data = await opeddFetch("/buyer-account", {
+          headers: { Authorization: `Bearer ${BUYER_JWT}` },
+        });
+        return ok(data);
+      }
+
+      // ── article_53_attestation (Phase 12 Wave 1 W1.4) ──────────────────────
+      case "article_53_attestation": {
+        if (!BUYER_JWT) {
+          return err("OPEDD_BUYER_JWT env var is required for this tool (Supabase session JWT)");
+        }
+        const { license_id, content_id, window_start, window_end } = args as {
+          license_id: string;
+          content_id?: string;
+          window_start?: string;
+          window_end?: string;
+        };
+        if (!license_id) return err("license_id is required");
+
+        const params = new URLSearchParams({ license_id });
+        if (content_id) params.set("content_id", content_id);
+        if (window_start) params.set("window_start", window_start);
+        if (window_end) params.set("window_end", window_end);
+
+        const data = await opeddFetch(
+          `/eu-ai-act/article-53-attestation?${params.toString()}`,
+          { headers: { Authorization: `Bearer ${BUYER_JWT}` } },
+        );
+        return ok(data);
+      }
+
       // ── get_compliance_dossier (Phase 11 M4) ───────────────────────────────
       case "get_compliance_dossier": {
         if (!BUYER_JWT) {
@@ -732,8 +989,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       // ── list_publisher_content ─────────────────────────────────────────────
       case "list_publisher_content": {
-        if (!API_KEY) {
-          return err("OPEDD_API_KEY env var is required for this tool");
+        if (!PUB_BEARER && !API_KEY) {
+          return err("OPEDD_PUB_BEARER env var is required for this tool (canonical Bearer; legacy OPEDD_API_KEY also accepted during transition)");
         }
 
         const { limit = 20, type, offset = 0 } = args as {
@@ -758,10 +1015,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const msg = e instanceof Error ? e.message : String(e);
     return err(`Request failed: ${msg}`);
   }
-});
+}
 
 // ─── Start ────────────────────────────────────────────────────────────────────
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error("[opedd-mcp] Server running on stdio");
+// Skip stdio bootstrap when imported as a module (unit tests need TOOLS +
+// dispatchTool without the server.connect side-effect). Detect via
+// `import.meta.url === pathToFileURL(process.argv[1]).href` — the canonical
+// "am I the entry point" check for ESM Node modules.
+if (
+  typeof process !== "undefined" &&
+  process.argv?.[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[opedd-mcp] Server running on stdio");
+}