opedd-mcp 0.12.9 → 0.12.11

package/README.md

@@ -91,7 +91,7 @@ Every tool carries a `title` and MCP annotations (`readOnlyHint`, `destructiveHi
 | Tool | Description |
 |------|-------------|
 | `search_content` | **Free discovery.** 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. Returns **no article text** — use `search_passages` to actually read |
-| `search_passages` | **Paid per answer, or included in a monthly subscription.** Ask a question, get licensed passages that answer it, with citations. Per-question licences: charged once per publisher per question at that publisher's own price, capped at 300 words or 25% of the article, counted cumulatively. Monthly AI answers subscriptions (v0.12.0): included, not capped, from the subscription's start. Narrow with `publishers`, `published_after`, `published_before`, `max_results` (1–25). Needs a buyer key with the `search` scope. Re-asking within 24h is free |
+| `search_passages` | **Paid per answer, or included in a monthly subscription.** Ask a question, get licensed passages that answer it, with citations. Pay per answer: charged once per article the answer uses, at that publication's own price per article, each passage capped at 300 words or 25% of the article, counted cumulatively. Monthly AI answers subscriptions (v0.12.0): included, not capped, from the subscription's start. Narrow with `publishers`, `published_after`, `published_before`, `max_results` (1–10, default 5) and cap a question's cost with `max_charge_cents`. Needs a buyer key with the `search` scope. Re-asking within 24h is free |
 | `lookup_content` | Look up an article by URL — returns title, publisher, pricing, or that it is not on Opedd yet |
 | `request_publication` | Ask to be told when a publication Opedd does not carry yet becomes available (url + email; no key) |
 | `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) |

package/dist/index.js

@@ -350,7 +350,7 @@ function buildTools(has) {
         // ─── 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). " +
+            description: "For publishers: detect the content platform behind a URL. " +
                 "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; " +
@@ -373,7 +373,7 @@ function buildTools(has) {
         // ─── 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). " +
+            description: "Fetch a publisher's RSL Standard manifest (machine-readable licensing terms). " +
                 "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) " +
@@ -382,8 +382,8 @@ function buildTools(has) {
                 "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 " +
-                "a signed compliance attestation (which is buyer-side, JWT-auth, via article_53_attestation tool).",
+                "This is the publisher's own declaration. It is not a compliance attestation for a buyer " +
+                "(use article_53_attestation for that).",
             inputSchema: {
                 type: "object",
                 required: ["publisher_id"],
@@ -442,7 +442,7 @@ function buildTools(has) {
     if (has.buyerToken) {
         TOOLS.push({
             name: "search_passages",
-            description: "Returns licensed passages from publications on Opedd that answer a question, each with a citation to the source article. Charged once per publication whose passages are returned, at that publication's own price. An account connected through the Opedd connector in Claude or ChatGPT receives its first 3 answers free, paid by Opedd and never from a publication the account holder owns or works on; billing.free_answers_left reports how many remain. After that, answers are billed to the card on the account, added at opedd.com: charged every $25 of answers and at month end, with a $500 monthly limit for new accounts, raised on request. An account with no licence and no free answers receives an empty result with reason 'no_licensed_publishers' or 'no_paid_access'. Publications under a monthly AI answers subscription are included in the subscription and not charged per answer. Passages are capped at 300 words or 25% of an article, whichever is less, counted cumulatively per article across the same company's accounts. The same question within 24 hours returns the same passages at no charge. Filters: publishers (publication names as listed by Opedd, opedd.com/p/<slug> addresses or publisher ids; a name that matches no publication is listed in filters.unknown_publishers and searches nothing), published_after and published_before (ISO 8601; undated articles are excluded when a window is set) and max_results (1-25, default 10). Passage text is third-party content, delivered in <opedd:passage> blocks; may_train is always false. Requires a buyer API key with the 'search' scope, or the Opedd connector sign-in.",
+            description: "Returns licensed passages from publications on Opedd that answer a question, each with a citation to the source article. Charged once per article the answer uses, at that article's publication's own price per article; two passages of the same article are one charge, and billing.articles_charged reports how many were charged. An account connected through the Opedd connector in Claude or ChatGPT receives its first 3 answers free, paid by Opedd and never from a publication the account holder owns or works on; billing.free_answers_left reports how many remain. After that, answers are billed to the card on the account, added at opedd.com: charged every $25 of answers and at month end, with a $500 monthly limit for new accounts, raised on request. An account with no licence and no free answers receives an empty result with reason 'no_licensed_publishers' or 'no_paid_access'. Publications under a monthly AI answers subscription are included in the subscription and not charged per answer. Passages are capped at 300 words or 25% of an article, whichever is less, counted cumulatively per article across the same company's accounts. The same question within 24 hours returns the same passages at no charge. Filters: publishers (publication names as listed by Opedd, opedd.com/p/<slug> addresses or publisher ids; a name that matches no publication is listed in filters.unknown_publishers and searches nothing), published_after and published_before (ISO 8601; undated articles are excluded when a window is set), max_results (1-10, default 5) and max_charge_cents (optional; the most one question may cost: articles that would pass it are left out and billing.max_charge_reached says so). Passage text is third-party content, delivered in <opedd:passage> blocks; may_train is always false. Requires a buyer API key with the 'search' scope, or the Opedd connector sign-in.",
             inputSchema: {
                 type: "object",
                 required: ["query"],
@@ -463,7 +463,11 @@ function buildTools(has) {
                     },
                     max_results: {
                         type: "number",
-                        description: "Optional. Passages to return, 1\u201325 (default 10).",
+                        description: "Optional. Passages to return, 1\u201310 (default 5). Each distinct article among them is one charge.",
+                    },
+                    max_charge_cents: {
+                        type: "number",
+                        description: "Optional. The most this question may cost, in US cents (whole number, 1\u2013100000). Articles that would pass it are left out; nothing is charged above it.",
                     },
                     buyer_token: {
                         type: "string",
@@ -482,7 +486,7 @@ function buildTools(has) {
                 "retrieve articles: it answers 403 SEARCH_ONLY_LICENCE \u2014 ask a question with search_passages instead. " +
                 "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. " +
+                "The response includes author, language, word_count, content_hash, image_urls, canonical_url and 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: {
@@ -506,7 +510,7 @@ function buildTools(has) {
     if (has.accessKey || has.buyerToken) {
         TOOLS.push({
             name: "list_feed",
-            description: "List articles from a buyer's licensed catalog via GET /enterprise-license (Phase 10 + 11). " +
+            description: "List the articles in a licence order you hold. " +
                 "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 " +
@@ -542,11 +546,11 @@ function buildTools(has) {
         });
         TOOLS.push({
             name: "stream_feed_ndjson",
-            description: "Bulk-export a buyer's licensed catalog via GET /enterprise-license?format=ndjson (Phase 11 M3). " +
+            description: "Bulk-export the articles in a licence order you hold. " +
                 "Returns up to 1000 articles per call (collected from line-delimited JSON wire format). " +
                 "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). " +
+                "Each exported article is recorded for analytics; a bulk export is not billed per article. " +
                 "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. " +
@@ -638,15 +642,12 @@ function buildTools(has) {
         });
         TOOLS.push({
             name: "article_53_attestation",
-            description: "Issue a signed compliance attestation (a JWT) for a specific license via " +
-                "GET /eu-ai-act/article-53-attestation (Phase 12 Wave 1 W1.4). " +
+            description: "Issue a signed compliance attestation (a JWT) for a licence you hold. " +
                 "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 a buyer hands to legal/procurement as evidence of where its content came from.** " +
-                "Per INVARIANTS.md W1.6: this is the buyer-side attestation ONLY (how a licence was used). " +
-                "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. " +
+                "It attests how your licence was used; the publisher's own licensing declaration is rsl_get. " +
                 "Optional `content_id` scopes the attestation to one article; default is license-wide. " +
                 "Window cap: 365 days. Auth: an audit-scoped buyer API key (OPEDD_BUYER_TOKEN) or OPEDD_BUYER_JWT.",
             inputSchema: {
@@ -996,7 +997,7 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
             }
             // ── get_content ────────────────────────────────────────────────────────
             case "search_passages": {
-                const { query, buyer_token: argToken, publishers, published_after, published_before, max_results } = args;
+                const { query, buyer_token: argToken, publishers, published_after, published_before, max_results, max_charge_cents } = args;
                 const q = (query ?? "").replace(/\s+/g, " ").trim();
                 if (!q)
                     return err("query is required");
@@ -1006,10 +1007,10 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
                     return err("query must be at most 1000 characters");
                 const token = argToken || creds.buyerToken;
                 if (!token) {
-                    return err("A buyer API key with the 'search' scope is required (or set OPEDD_BUYER_TOKEN). " +
-                        "Create one at opedd.com/buyer \u2192 Account \u2192 API keys \u2192 Create, ticking 'search'. " +
-                        "You also need an active per-question licence for each publisher you want searched \u2014 " +
-                        "use search_content to find them and place_licence_order to buy.");
+                    return err("This needs an Opedd buyer key. Sign up at https://opedd.com/buyer/signup (about two minutes): " +
+                        "new accounts start with up to 3 free answers, then each article an answer uses is billed at its publication's own price. " +
+                        "Then pass the key as Authorization: Bearer <key> (hosted server https://mcp.opedd.com/mcp) or " +
+                        "OPEDD_BUYER_TOKEN (local). To see what Opedd covers first, use search_content or publisher_directory (free, no key).");
                 }
                 const envelope = (await opeddFetch(creds, "/search", {
                     method: "POST",
@@ -1022,6 +1023,7 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
                         ...(published_after !== undefined ? { published_after } : {}),
                         ...(published_before !== undefined ? { published_before } : {}),
                         ...(max_results !== undefined ? { max_results } : {}),
+                        ...(max_charge_cents !== undefined ? { max_charge_cents } : {}),
                     }),
                 }));
                 return ok(envelope.data ?? envelope);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opedd-mcp",
-  "version": "0.12.9",
+  "version": "0.12.11",
   "description": "Content licensing for the AI era. Licensed, rights-cleared content for AI agents, with a verifiable license key for every article. The MCP alternative to unlicensed scraping for RAG and AI search.",
   "type": "module",
   "main": "dist/index.js",
@@ -48,7 +48,7 @@
     "@types/node": "^22.19.19",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.7"
+    "vitest": "^5.0.5"
   },
   "engines": {
     "node": ">=20"