opedd-mcp 0.1.2 → 0.3.0

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   ListToolsRequestSchema,
   type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
+import { pathToFileURL } from "node:url";
 
 // ─── Configuration ────────────────────────────────────────────────────────────
 
@@ -17,7 +18,9 @@ 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 (bk_live_...)
+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 ─────────────────────────────────────────────────────────────
 
@@ -37,6 +40,46 @@ async function opeddFetch(path: string, options: RequestInit = {}): Promise<unkn
   return body;
 }
 
+// Fetch an NDJSON endpoint and collect parsed lines into an array.
+// Last line is typically `{"_meta": {...}}`; surfaced as `meta` field on the
+// returned object so the MCP tool result has both shape pieces inline.
+async function opeddFetchNdjson(
+  path: string,
+  options: RequestInit = {},
+): Promise<{ articles: unknown[]; meta: unknown }> {
+  const url = `${API_BASE}${path}`;
+  const headers: Record<string, string> = {
+    Accept: "application/x-ndjson",
+    ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
+    ...(options.headers as Record<string, string> ?? {}),
+  };
+  const res = await fetch(url, { ...options, headers });
+  if (!res.ok) {
+    let msg = `HTTP ${res.status}`;
+    try {
+      const errBody = await res.json();
+      msg = (errBody as any)?.error || (errBody as any)?.message || msg;
+    } catch {
+      // non-JSON error body — keep the HTTP-status default
+    }
+    throw new Error(msg);
+  }
+  const text = await res.text();
+  const articles: unknown[] = [];
+  let meta: unknown = null;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const row = JSON.parse(line) as { _meta?: unknown };
+    if (row._meta !== undefined) {
+      meta = row._meta;
+    } else {
+      articles.push(row);
+    }
+  }
+  return { articles, meta };
+}
+
 // ─── MCP response helpers ─────────────────────────────────────────────────────
 
 type TextContent = { type: "text"; text: string };
@@ -52,7 +95,7 @@ function err(msg: string): ToolResult {
 
 // ─── Tool definitions ─────────────────────────────────────────────────────────
 
-const TOOLS: Tool[] = [
+export const TOOLS: Tool[] = [
   {
     name: "lookup_content",
     description:
@@ -165,6 +208,155 @@ 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 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: {
+      type: "object",
+      required: ["publisher_ids", "buyer_email", "buyer_org"],
+      properties: {
+        publisher_ids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Array of publisher UUIDs. Required for scope='custom'; ignored for platform_wide/filtered (resolved server-side).",
+        },
+        buyer_email: {
+          type: "string",
+          description: "Email to deliver the access key after payment",
+        },
+        buyer_org: {
+          type: "string",
+          description: "Buyer organization name (for billing + audit ledger)",
+        },
+        billing_type: {
+          type: "string",
+          enum: ["annual", "monthly", "annual_plus_monthly"],
+          description: "Billing cadence (default: annual)",
+        },
+        license_tier: {
+          type: "string",
+          enum: ["rag", "training", "inference", "full_ai"],
+          description: "License tier (default: rag)",
+        },
+        duration_months: {
+          type: "number",
+          description: "License duration in months (default: 12)",
+        },
+        scope: {
+          type: "string",
+          enum: ["custom", "platform_wide", "filtered"],
+          description: "Coverage scope (default: custom)",
+        },
+        filter_rules: {
+          type: "object",
+          description: "Required when scope='filtered'. See Phase 10 docs for shape: excluded_publisher_ids / direct_license_carveouts / categories / max_price_per_event.",
+        },
+        buyer_webhook_url: {
+          type: "string",
+          description: "Optional HMAC-signed webhook for content.published events on covered publishers",
+        },
+      },
+    },
+  },
 ];
 
 // If a buyer token is configured, expose content delivery tooling
@@ -172,10 +364,13 @@ if (BUYER_TOKEN) {
   TOOLS.push({
     name: "get_content",
     description:
-      "Retrieve the full body of a licensed article using a buyer API token (bk_live_...). " +
+      "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.",
+      "The publisher must have content delivery enabled and must have pushed content for the article. " +
+      "Phase 11 M2 RAG-extended shape: response includes 7 RAG-essential metadata fields — author, language, word_count, content_hash, image_urls, canonical_url, tags. " +
+      "On pre-2026-05-14 historical articles, optional fields (author/language/image_urls/canonical_url/tags) may be NULL. " +
+      "NULL means 'data unavailable for this article', NOT 'explicitly empty' — treat as data-missing when filtering; do not interpret as anti-match.",
     inputSchema: {
       type: "object",
       required: ["article_id"],
@@ -186,7 +381,188 @@ if (BUYER_TOKEN) {
         },
         buyer_token: {
           type: "string",
-          description: "Buyer API token (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.",
+        },
+      },
+    },
+  });
+}
+
+// If an enterprise access key is configured, expose feed tools
+if (ACCESS_KEY) {
+  TOOLS.push({
+    name: "list_feed",
+    description:
+      "List articles from a buyer's licensed catalog via GET /enterprise-license (Phase 10 + 11). " +
+      "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 (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",
+      properties: {
+        since: {
+          type: "string",
+          description: "ISO 8601 timestamp — return only articles with published_at > since",
+        },
+        cursor: {
+          type: "string",
+          description: "Opaque cursor from prior response's _meta.next_cursor",
+        },
+        limit: {
+          type: "number",
+          description: "Max articles per response (default: 50, max: 200)",
+        },
+      },
+    },
+  });
+  TOOLS.push({
+    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). " +
+      "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. " +
+      "Real bulk-ingest pipelines should use the Python SDK (pip install opedd) directly — not via MCP. " +
+      "Requires OPEDD_ACCESS_KEY (ent_*).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        since: {
+          type: "string",
+          description: "ISO 8601 timestamp — return only articles with published_at > since",
+        },
+        cursor: {
+          type: "string",
+          description: "Opaque cursor from prior response's _meta.next_cursor",
+        },
+        limit: {
+          type: "number",
+          description: "Max articles per response (default: 200, max: 1000)",
+        },
+      },
+    },
+  });
+}
+
+// If a Supabase buyer JWT is configured, expose audit + compliance tools
+if (BUYER_JWT) {
+  TOOLS.push({
+    name: "get_audit_events",
+    description:
+      "Browse per-event audit rows for the authenticated buyer via GET /buyer-audit (Phase 9.x). " +
+      "Each row carries license_terms + Tempo on-chain attestation (merkle_root + inclusion_proof when blockchain_status='confirmed'). " +
+      "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).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: {
+          type: "string",
+          description: "ISO 8601 timestamp lower bound (inclusive)",
+        },
+        to: {
+          type: "string",
+          description: "ISO 8601 timestamp upper bound (inclusive)",
+        },
+        event_type: {
+          type: "string",
+          enum: ["content_access", "bulk_content_access", "compliance_report_generated"],
+          description: "Optional event-class filter",
+        },
+        cursor: {
+          type: "string",
+          description: "Opaque cursor for pagination",
+        },
+        limit: {
+          type: "number",
+          description: "Max events per response (default: 50, max: 200)",
+        },
+      },
+    },
+  });
+  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:
+      "Generate a procurement-defense compliance dossier via GET /buyer-compliance-report (Phase 11 M4). " +
+      "Per-row dossier shape: 25+ fields including 17 RAG-essential article fields + full license_terms + on_chain_attestation block. " +
+      "Bulk envelopes fan out into per-article rows by iterating metadata.article_ids[]. " +
+      "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.",
+    inputSchema: {
+      type: "object",
+      required: ["from", "to"],
+      properties: {
+        from: {
+          type: "string",
+          description: "ISO 8601 timestamp lower bound (inclusive)",
+        },
+        to: {
+          type: "string",
+          description: "ISO 8601 timestamp upper bound (inclusive). Window cap 90 days.",
+        },
+        cursor: {
+          type: "string",
+          description: "Opaque cursor for pagination",
         },
       },
     },
@@ -225,15 +601,28 @@ if (API_KEY) {
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "opedd-mcp", version: "0.1.2" },
+  { 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 ─────────────────────────────────────────────────────
@@ -354,6 +743,238 @@ 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 {
+          publisher_ids,
+          buyer_email: pelEmail,
+          buyer_org,
+          billing_type = "annual",
+          license_tier = "rag",
+          duration_months = 12,
+          scope = "custom",
+          filter_rules,
+          buyer_webhook_url,
+        } = args as {
+          publisher_ids?: string[];
+          buyer_email?: string;
+          buyer_org?: string;
+          billing_type?: string;
+          license_tier?: string;
+          duration_months?: number;
+          scope?: string;
+          filter_rules?: Record<string, unknown>;
+          buyer_webhook_url?: string;
+        };
+
+        if (!Array.isArray(publisher_ids) || publisher_ids.length === 0) {
+          if (scope === "custom") {
+            return err("publisher_ids array is required for scope='custom'");
+          }
+        }
+        if (!pelEmail) return err("buyer_email is required");
+        if (!buyer_org) return err("buyer_org is required");
+
+        const body: Record<string, unknown> = {
+          publisher_ids: publisher_ids ?? [],
+          buyer_email: pelEmail,
+          buyer_org,
+          billing_type,
+          license_tier,
+          duration_months,
+          scope,
+          ...(filter_rules ? { filter_rules } : {}),
+          ...(buyer_webhook_url ? { buyer_webhook_url } : {}),
+        };
+
+        const data = await opeddFetch("/enterprise-license", {
+          method: "POST",
+          body: JSON.stringify(body),
+        });
+        return ok(data);
+      }
+
+      // ── list_feed (Phase 10 + 11) ──────────────────────────────────────────
+      case "list_feed": {
+        if (!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;
+          cursor?: string;
+          limit?: number;
+        };
+        const params = new URLSearchParams({
+          access_key: ACCESS_KEY,
+          format: "json",
+          limit: String(Math.min(Number(limit) || 50, 200)),
+        });
+        if (since) params.set("since", since);
+        if (cursor) params.set("cursor", cursor);
+
+        const data = await opeddFetch(`/enterprise-license?${params.toString()}`);
+        return ok(data);
+      }
+
+      // ── 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 (ent_* enterprise access key)");
+        }
+        const { since, cursor, limit = 200 } = args as {
+          since?: string;
+          cursor?: string;
+          limit?: number;
+        };
+        const params = new URLSearchParams({
+          access_key: ACCESS_KEY,
+          format: "ndjson",
+          limit: String(Math.min(Number(limit) || 200, 1000)),
+        });
+        if (since) params.set("since", since);
+        if (cursor) params.set("cursor", cursor);
+
+        const data = await opeddFetchNdjson(`/enterprise-license?${params.toString()}`);
+        return ok(data);
+      }
+
+      // ── get_audit_events (Phase 9.x + 10 M5 attestation) ───────────────────
+      case "get_audit_events": {
+        if (!BUYER_JWT) {
+          return err("OPEDD_BUYER_JWT env var is required for this tool (Supabase session JWT)");
+        }
+        const { from, to, event_type, cursor, limit = 50 } = args as {
+          from?: string;
+          to?: string;
+          event_type?: string;
+          cursor?: string;
+          limit?: number;
+        };
+        const params = new URLSearchParams({
+          limit: String(Math.min(Number(limit) || 50, 200)),
+        });
+        if (from) params.set("from", from);
+        if (to) params.set("to", to);
+        if (event_type) params.set("event_type", event_type);
+        if (cursor) params.set("cursor", cursor);
+
+        const data = await opeddFetch(`/buyer-audit?${params.toString()}`, {
+          headers: { Authorization: `Bearer ${BUYER_JWT}` },
+        });
+        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) {
+          return err("OPEDD_BUYER_JWT env var is required for this tool (Supabase session JWT)");
+        }
+        const { from, to, cursor } = args as {
+          from?: string;
+          to?: string;
+          cursor?: string;
+        };
+        if (!from) return err("from (ISO 8601 timestamp) is required");
+        if (!to) return err("to (ISO 8601 timestamp) is required");
+
+        const params = new URLSearchParams({
+          from,
+          to,
+          format: "json",
+        });
+        if (cursor) params.set("cursor", cursor);
+
+        const data = await opeddFetch(`/buyer-compliance-report?${params.toString()}`, {
+          headers: { Authorization: `Bearer ${BUYER_JWT}` },
+        });
+        return ok(data);
+      }
+
       // ── list_publisher_content ─────────────────────────────────────────────
       case "list_publisher_content": {
         if (!API_KEY) {
@@ -382,10 +1003,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");
+}