opedd-mcp 0.8.0 → 0.9.0

package/README.md

@@ -35,7 +35,7 @@ Then add it to your MCP host (see [Claude Desktop / Cursor / Windsurf setup](#cl
 
 ## Hosted endpoint — no install (mcp.opedd.com)
 
-Prefer zero-install? The same 17 tools are served hosted at **`https://mcp.opedd.com/mcp`** (Streamable HTTP). Auth is an `Authorization: Bearer` header with any Opedd key — public discovery tools need no auth at all.
+Prefer zero-install? The same 19 tools are served hosted at **`https://mcp.opedd.com/mcp`** (Streamable HTTP). Auth is an `Authorization: Bearer` header with any Opedd key — public discovery tools need no auth at all.
 
 **Claude Messages API** (production agents):
 
@@ -82,7 +82,7 @@ Key routing: `opedd_sk_*` (legacy `opedd_pub_*`) → publisher tools · `opedd_b
 
 ## What it does
 
-Exposes up to 17 tools to any AI assistant (some are conditional on env vars):
+Exposes up to 19 tools to any AI assistant (some are conditional on env vars):
 
 **Always available — discovery + per-article purchase + onboarding + rights signaling**
 
@@ -90,11 +90,11 @@ Exposes up to 17 tools to any AI assistant (some are conditional on env vars):
 |------|-------------|
 | `search_content` | Full-text search across everything licensable (v0.8.0) — ranked matches with publisher, prices, word count and a description snippet; quotes for phrases, `-word` to exclude |
 | `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. Requires `terms_accepted: true` (genuine buyer assent to opedd.com/terms; recorded with the licence) |
+| `purchase_license` | Buy a Human republication licence for one article 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`. Requires `terms_accepted: true`; the current Master Services Agreement version label is recorded with the licence (the backend rejects superseded labels) |
+| `place_licence_order` | Place a licence order for one or more publishers: AI answers (`monthly` full text, or `metered` pay-per-request snippets ≤300 words / 25%), AI training (`one_time`, back catalogue), client display (`monthly` × end clients). Each publisher is its own Schedule at its own price; returns the order, lines, `unavailable` publishers and `hosted_invoice_url`. Needs `OPEDD_BUYER_JWT` and `terms_accepted: true` |
 | `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) |
 
@@ -102,20 +102,21 @@ Exposes up to 17 tools to any AI assistant (some are conditional on env vars):
 
 | Tool | Description |
 |------|-------------|
-| `get_content` | Retrieve a licensed article — includes 7 Phase 11 M2 RAG metadata fields (author, language, word_count, content_hash, image_urls, canonical_url, tags) |
+| `get_content` | Retrieve a licensed article — full text for AI answers monthly and client display orders, a snippet (≤300 words / 25%) for pay-per-request; includes 7 RAG metadata fields (author, language, word_count, content_hash, image_urls, canonical_url, tags) |
 
 **Requires `OPEDD_ACCESS_KEY` (ent_*) — buyer-side feed surfaces**
 
 | Tool | Description |
 |------|-------------|
-| `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 |
+| `list_feed` | List articles from a buyer's licensed catalog with `since` delta-feed support. AI training orders carry full `content_body` (back catalogue up to the order date, `content_access: "included"`); every other order is discovery-only (`content_body: null`, `content_access: "retrieval_per_article"` or `"metered_per_call"`) — fetch text via `get_content` |
+| `stream_feed_ndjson` | Bulk-export up to 1000 articles per call via NDJSON wire format. Same content contract as `list_feed` — full text for AI training orders only |
 
 **Requires `OPEDD_BUYER_JWT` (Supabase JWT) — buyer account + audit + compliance + EU AI Act surfaces**
 
 | Tool | Description |
 |------|-------------|
 | `get_buyer_account` | Fetch buyer profile + masked API key list — buyer-dashboard mental model |
+| `list_licence_orders` | The buyer's licence orders and lines; with `order_id`, each line's Schedule document and its SHA-256 (the fingerprint recorded on Tempo). Also works with an audit-scoped `OPEDD_BUYER_TOKEN` |
 | `get_audit_events` | Per-event audit ledger with Tempo on-chain attestation inclusion proofs inline (Phase 9.x + 10 M5) |
 | `get_compliance_dossier` | Procurement-defense compliance dossier mapping retrievals to license terms (Phase 11 M4) |
 | `article_53_attestation` | Signed JWT attesting EU AI Act Article 53(1)(d) compliance for a license — the artifact AI labs hand to legal/procurement (Phase 12 W1.4) |
@@ -159,7 +160,7 @@ Set environment variables to pre-configure the server:
 | `OPEDD_PAYMENT_METHOD_ID` | Recommended | Stripe `pm_...` ID — used for autonomous per-article purchasing |
 | `OPEDD_BUYER_TOKEN` | Optional | Buyer API token (`opedd_buyer_live_*` canonical; `opedd_buyer_test_*` for sandbox) — enables `get_content` |
 | `OPEDD_ACCESS_KEY` | Optional | Enterprise access key (`ent_*`) — enables `list_feed` + `stream_feed_ndjson` |
-| `OPEDD_BUYER_JWT` | Optional | Supabase session JWT from the buyer portal — enables `get_buyer_account` + `get_audit_events` + `get_compliance_dossier` + `article_53_attestation` |
+| `OPEDD_BUYER_JWT` | Optional | Supabase session JWT from the buyer portal — enables `place_licence_order` + `list_licence_orders` + `get_buyer_account` + `get_audit_events` + `get_compliance_dossier` + `article_53_attestation` |
 | `OPEDD_PUB_BEARER` | Optional | Publisher API key (`opedd_sk_<32-hex>`, canonical since 2026-08-27; older `opedd_pub_<32-hex>` keys keep working) — from the Opedd dashboard, Settings → Developers. Enables `list_publisher_content` (+ `include_body`) and `push_content`. |
 | `OPEDD_API_KEY` | Deprecated | Legacy Publisher API key (`op_...`) — fallback during the transition window; will stop working when opedd-backend Phase C deploys. Migrate to `OPEDD_PUB_BEARER`. |
 | `OPEDD_API_URL` | Optional | Override the API base URL (default: Opedd production) |

package/dist/index.js

@@ -148,7 +148,7 @@ function auditCred(creds) {
     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.";
+    "or place a licence order with the place_licence_order tool.";
 const HOW_PUB_BEARER = "Publisher keys (opedd_sk_*, legacy opedd_pub_* still valid) come from the publisher dashboard: sign up free at https://opedd.com, then Settings → API keys.";
 // ─── Tool definitions ─────────────────────────────────────────────────────────
 function buildTools(has) {
@@ -192,7 +192,8 @@ function buildTools(has) {
                 "Returns a license key (format: OP-XXXX-XXXX) and a certificate URL. " +
                 "The buyer receives a Handshake Email with their license key. " +
                 "Set OPEDD_BUYER_EMAIL and OPEDD_PAYMENT_METHOD_ID env vars to avoid passing them on every call. " +
-                "License types: 'human' = republication rights, 'ai' = training dataset rights, 'ai_inference' = inference/RAG rights.",
+                "Single-article purchases are Human republication licences only (license_type 'human'). " +
+                "AI licences (AI answers, AI training, client display) are bought as licence orders: see place_licence_order.",
             inputSchema: {
                 type: "object",
                 required: ["license_type", "terms_accepted"],
@@ -212,8 +213,8 @@ function buildTools(has) {
                     },
                     license_type: {
                         type: "string",
-                        enum: ["human", "ai", "ai_inference"],
-                        description: "human = republication/editorial rights, ai = training dataset rights, ai_inference = inference/RAG rights",
+                        enum: ["human"],
+                        description: "human = Human republication (editorial republication of one article)",
                     },
                     buyer_email: {
                         type: "string",
@@ -371,61 +372,27 @@ function buildTools(has) {
         },
         // ─── 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). " +
-                "The buyer must accept the Opedd Master Services Agreement (opedd.com/terms) before purchase — set terms_accepted=true to record it.",
+            name: "place_licence_order",
+            description: "Place a licence order with Opedd for one or more publishers. One order = one licence and one billing mode; " +
+                "each publisher becomes its own Schedule priced from that publisher's settings (publishers that do not offer it are " +
+                "returned in `unavailable` and never charged). Licences: 'enterprise' (AI answers: 'monthly' full text per article, or " +
+                "'metered' pay-per-request snippets of up to 300 words or 25% of the article), 'training' (AI training of the back " +
+                "catalogue up to the order date: 'one_time', bulk export via stream_feed_ndjson), 'display' (client display: 'monthly', " +
+                "quantity = number of end clients). Returns the order, its lines, the access key (works once paid) and " +
+                "hosted_invoice_url — the buyer (your principal) pays there. Requires a buyer session (OPEDD_BUYER_JWT) and " +
+                "terms_accepted=true after the buyer has accepted the Opedd Master Services Agreement (opedd.com/terms).",
             inputSchema: {
                 type: "object",
-                required: ["publisher_ids", "buyer_email", "buyer_org", "terms_accepted"],
+                required: ["licence", "billing_mode", "publisher_ids", "terms_accepted"],
                 properties: {
+                    licence: { type: "string", enum: ["enterprise", "training", "display"], description: "enterprise = AI answers, training = AI training, display = client display" },
+                    billing_mode: { type: "string", enum: ["monthly", "metered", "one_time"], description: "enterprise: monthly | metered; training: one_time; display: monthly" },
+                    publisher_ids: { type: "array", items: { type: "string" }, description: "Publisher UUIDs (1-500; at most 18 for metered)" },
+                    quantity: { type: "number", description: "display only: number of end clients (1-500)" },
                     terms_accepted: {
                         type: "boolean",
-                        description: "REQUIRED. Set true only after the buyer (your principal) has accepted the Opedd Master Services Agreement at opedd.com/terms. " +
-                            "The current MSA version label is recorded with the licence; purchases without genuine acceptance are rejected (HTTP 400).",
-                    },
-                    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",
+                        description: "REQUIRED. Set true only after the buyer has accepted the Opedd Master Services Agreement at opedd.com/terms. " +
+                            "The current version label is recorded with the order; orders without genuine acceptance are rejected.",
                     },
                 },
             },
@@ -437,7 +404,9 @@ function buildTools(has) {
             name: "get_content",
             description: "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). " +
+                "Works for per-article Human republication licences (token scoped to that article) and licence orders: AI answers " +
+                "monthly and client display return full text; AI answers pay-per-request always returns a snippet (up to 300 words " +
+                "or 25% of the article, whatever delivery_mode is asked). Articles the publisher stopped licensing answer 403 ARTICLE_EXCLUDED. " +
                 "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. " +
@@ -463,9 +432,10 @@ 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). " +
+                "Content contract: AI training orders include full content_body for the back catalogue up to the order date " +
+                "(content_access 'included'). Every other order is discovery-only (content_body null): AI answers monthly and " +
+                "client display fetch text per article via get_content (content_access 'retrieval_per_article'); pay-per-request " +
+                "fetches billed snippets via get_content (content_access 'metered_per_call'). " +
                 "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. " +
@@ -493,8 +463,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. " +
+                "Same content contract as list_feed: full text for AI training orders only; every other order exports " +
+                "metadata (content_body null) — 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. " +
@@ -524,6 +494,21 @@ function buildTools(has) {
     // 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: "list_licence_orders",
+            description: "List the buyer's licence orders, newest first, each with its lines (publisher, licence, unit, price, quantity, status). " +
+                "Pass order_id to read one order: each line then carries its Schedule document text and SHA-256 — the licence " +
+                "fingerprint recorded on the Tempo blockchain when the line was issued. Read-only. Requires a buyer API key with " +
+                "the 'audit' scope (OPEDD_BUYER_TOKEN) or a buyer session (OPEDD_BUYER_JWT).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    order_id: { type: "string", description: "Read one order (UUID) including Schedule documents" },
+                    cursor: { type: "string", description: "Opaque cursor from the prior response's pagination.next_cursor" },
+                    limit: { type: "number", description: "Orders per page (default 20, max 100)" },
+                },
+            },
+        });
         TOOLS.push({
             name: "get_audit_events",
             description: "Browse per-event audit rows for the authenticated buyer via GET /buyer-audit (Phase 9.x). " +
@@ -907,41 +892,54 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
                 const data = await opeddFetch(creds, `/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, terms_accepted, } = args;
-                if (!Array.isArray(publisher_ids) || publisher_ids.length === 0) {
-                    if (scope === "custom") {
-                        return err("publisher_ids array is required for scope='custom'");
-                    }
+            // ── place_licence_order (licensing MVP, backend PR-B1) ─────────────────
+            // POST /enterprise-license requires a buyer SESSION since 2026-09-17
+            // (API keys are refused on money endpoints): the order is placed with
+            // OPEDD_BUYER_JWT and the buyer pays the hosted invoice.
+            case "place_licence_order": {
+                if (!creds.buyerJwt) {
+                    return credErr("A buyer session is required to place an order", "OPEDD_BUYER_JWT", HOW_BUYER_JWT);
                 }
-                if (!pelEmail)
-                    return err("buyer_email is required");
-                if (!buyer_org)
-                    return err("buyer_org is required");
+                const { licence, billing_mode, publisher_ids, quantity, terms_accepted } = args;
+                if (!licence || !billing_mode)
+                    return err("licence and billing_mode are required");
+                if (!Array.isArray(publisher_ids) || publisher_ids.length === 0)
+                    return err("publisher_ids must be a non-empty array");
                 if (terms_accepted !== true) {
-                    return err("terms_accepted must be true — confirm with the buyer that they accept the Opedd Master Services Agreement (opedd.com/terms) before purchasing.");
+                    return err("terms_accepted must be true — confirm with the buyer that they accept the Opedd Master Services Agreement (opedd.com/terms) before ordering.");
                 }
-                const body = {
-                    publisher_ids: publisher_ids ?? [],
-                    buyer_email: pelEmail,
-                    buyer_org,
-                    billing_type,
-                    license_tier,
-                    duration_months,
-                    scope,
-                    // Genuine assent moment: the agent asserted terms_accepted=true just
-                    // now. The backend requires the MSA version label (fail-closed since
-                    // 2026-07-31) and rejects superseded labels — on an MSA version bump
-                    // this constant must be updated (new package release) to match
-                    // opedd-backend _shared/msa-version.ts CURRENT_MSA_VERSION.
-                    terms_version: CURRENT_MSA_VERSION,
-                    ...(filter_rules ? { filter_rules } : {}),
-                    ...(buyer_webhook_url ? { buyer_webhook_url } : {}),
-                };
                 const data = await opeddFetch(creds, "/enterprise-license", {
                     method: "POST",
-                    body: JSON.stringify(body),
+                    headers: { Authorization: `Bearer ${creds.buyerJwt}` },
+                    body: JSON.stringify({
+                        licence,
+                        billing_mode,
+                        publisher_ids,
+                        ...(quantity !== undefined ? { quantity } : {}),
+                        // Genuine assent moment: the agent asserted terms_accepted=true just
+                        // now. On an MSA version bump this constant must be updated (new
+                        // package release) to match opedd-backend _shared/msa-version.ts.
+                        terms_version: CURRENT_MSA_VERSION,
+                    }),
+                });
+                return ok(data);
+            }
+            // ── list_licence_orders (GET /buyer-orders) ──────────────────────────
+            case "list_licence_orders": {
+                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 { order_id, cursor, limit } = args;
+                const params = new URLSearchParams();
+                if (order_id)
+                    params.set("order_id", order_id);
+                if (cursor)
+                    params.set("cursor", cursor);
+                if (limit !== undefined)
+                    params.set("limit", String(Math.min(Math.max(Number(limit) || 20, 1), 100)));
+                const qs = params.toString();
+                const data = await opeddFetch(creds, `/buyer-orders${qs ? `?${qs}` : ""}`, {
+                    headers: { Authorization: `Bearer ${auditCred(creds)}` },
                 });
                 return ok(data);
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opedd-mcp",
-  "version": "0.8.0",
-  "description": "Licensed, rights-cleared content for AI agents \u2014 verifiable license keys, on-chain proof, and EU AI Act attestation. The MCP alternative to unlicensed scraping for RAG and AI search.",
+  "version": "0.9.0",
+  "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",
   "mcpName": "com.opedd/opedd-mcp",
@@ -60,4 +60,4 @@
   "overrides": {
     "esbuild": "^0.28.1"
   }
-}
+}