opedd-mcp 0.12.7 → 0.12.9

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 20 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 21 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 20 tools to any AI assistant (some are conditional on env vars):
+Exposes up to 21 tools to any AI assistant (some are conditional on env vars):
 
 Every tool carries a `title` and MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so an assistant can tell which tools only read and which spend money or write (v0.12.0).
 
@@ -92,7 +92,8 @@ Every tool carries a `title` and MCP annotations (`readOnlyHint`, `destructiveHi
 |------|-------------|
 | `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 |
-| `lookup_content` | Look up an article by URL — returns title, publisher, pricing |
+| `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) |
 | `verify_license` | Verify a license key — returns validity, article, publisher, public-record proof |
 | `browse_registry` | Browse the public Opedd registry — lists issued LICENSES (use `publisher_directory` to browse publishers themselves) |

package/dist/index.js

@@ -53,6 +53,7 @@ async function opeddFetch(creds, path, options = {}) {
     // proxy must surface as "HTTP 502", not a JSON SyntaxError.
     if (!res.ok) {
         let msg = `HTTP ${res.status}`;
+        let details;
         try {
             const errBody = await res.json();
             // Backend envelope upgraded to structured errors ({ error: { code,
@@ -60,6 +61,8 @@ async function opeddFetch(creds, path, options = {}) {
             // object into Error() rendered "[object Object]" — every agent-facing
             // failure was unreadable (launch-gaps follow-on, 2026-07-17).
             const e = errBody?.error;
+            if (typeof e === "object" && e !== null)
+                details = e.details;
             msg =
                 (typeof e === "object" && e !== null ? [e.code, e.message].filter(Boolean).join(": ") : e) ||
                     errBody?.message ||
@@ -68,7 +71,10 @@ async function opeddFetch(creds, path, options = {}) {
         catch {
             // non-JSON error body — keep the HTTP-status default
         }
-        throw new Error(msg);
+        // The status rides on the error so a caller can treat one status as an
+        // answer (lookup_content: 404 = not on Opedd yet) without parsing text;
+        // error.details rides too (lookup_content: the publication at that site).
+        throw Object.assign(new Error(msg), { status: res.status, details });
     }
     return await res.json();
 }
@@ -134,7 +140,7 @@ function err(msg) {
 // Only the refusal text changed: what's missing, how to supply it on BOTH
 // channels (env var locally, Authorization header on the hosted gateway),
 // where credentials come from, and which tools need none.
-const NO_AUTH_TOOLS = "lookup_content, publisher_directory, verify_license, browse_registry, rsl_get, detect_platform";
+const NO_AUTH_TOOLS = "lookup_content, publisher_directory, verify_license, browse_registry, rsl_get, detect_platform, request_publication";
 function credErr(missing, envVar, howToGet) {
     return err(`${missing} — none was provided. ` +
         `Supply it as the ${envVar} env var (local/stdio install) or as an "Authorization: Bearer <value>" header (hosted gateway, https://mcp.opedd.com/mcp). ` +
@@ -182,7 +188,7 @@ function buildTools(has) {
     const TOOLS = [
         {
             name: "lookup_content",
-            description: "Looks up an article on Opedd by its web address. Returns the title, publication, available licence types and prices, or that the article is not on Opedd.",
+            description: "Looks up an article on Opedd by its web address. Returns the title, publication, available licence types and prices; for a publication's homepage, the publication and its licensing page; or that it is not on Opedd yet (then request_publication records the request).",
             inputSchema: {
                 type: "object",
                 required: ["url"],
@@ -194,6 +200,21 @@ function buildTools(has) {
                 },
             },
         },
+        {
+            name: "request_publication",
+            description: "Asks Opedd to tell you when a publication it does not carry yet becomes available to license. Use it after lookup_content says an article is not on Opedd. Records the request against the email given; nothing is bought. If the publication is already on Opedd, returns its licensing page instead. Free; no key needed.",
+            inputSchema: {
+                type: "object",
+                required: ["url", "email"],
+                properties: {
+                    url: { type: "string", description: "The web address of the publication or of one of its articles." },
+                    email: { type: "string", description: "Where Opedd should write when the publication is available (the user's email, with their consent)." },
+                    name: { type: "string", description: "Optional: the requester's name." },
+                    organization: { type: "string", description: "Optional: the requester's company or fund." },
+                    note: { type: "string", description: "Optional: what the content is needed for (max 1000 characters)." },
+                },
+            },
+        },
         {
             name: "search_content",
             description: "Full-text search of the articles licensable on Opedd. Returns matching articles with the publication, prices, word count and a short description; never article text. Supports quoted phrases and -word to exclude a word. Free; no key needed.",
@@ -760,6 +781,8 @@ function buildTools(has) {
 const read = (title) => ({ title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false });
 export const TOOL_ANNOTATIONS = {
     lookup_content: read("Look up an article's licence and price"),
+    // Writes one request row (a repeat for the same email writes nothing): not read-only, idempotent.
+    request_publication: { title: "Ask to be told when a publication is available", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     search_content: read("Find who covers a topic (free, no text)"),
     purchase_license: { title: "Buy an article licence", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     verify_license: read("Verify a licence key"),
@@ -850,8 +873,51 @@ export async function dispatchTool(name, args, creds = ENV_CREDS) {
                 const { url } = args;
                 if (!url)
                     return err("url is required");
-                const data = await opeddFetch(creds, `/lookup-article?url=${encodeURIComponent(url)}`);
-                return ok(data);
+                try {
+                    const data = await opeddFetch(creds, `/lookup-article?url=${encodeURIComponent(url)}`);
+                    return ok(data);
+                }
+                catch (e) {
+                    // A miss is an answer, not a failure (2026-10-22). Directories score
+                    // servers on error rates, and the honest reply is "not on Opedd yet"
+                    // with a way to ask for it, never "coming soon".
+                    if (e.status === 404) {
+                        // No article at this address, but the address is a publication on
+                        // Opedd (its homepage, or a piece not imported yet): say so, and
+                        // where to license it (2026-10-24). Agents that looked up a
+                        // publication's homepage were told it was not on Opedd.
+                        const details = e.details;
+                        if (details?.on_opedd === true && details.publication) {
+                            return ok({
+                                on_opedd: true,
+                                url,
+                                publication: details.publication,
+                                message: `There is no single article at this address, but ${details.publication.name ?? "this publication"} is on Opedd. ` +
+                                    "Its licences and prices are on its licensing page; use search_content or search_passages to find its articles.",
+                            });
+                        }
+                        return ok({
+                            on_opedd: false,
+                            url,
+                            message: "This article is not on Opedd yet. If you want to license this publication, call request_publication " +
+                                "with this url and an email, and Opedd will write when it becomes available.",
+                        });
+                    }
+                    throw e;
+                }
+            }
+            // ── request_publication ────────────────────────────────────────────────
+            case "request_publication": {
+                const { url, email, name, organization, note } = args;
+                if (!url)
+                    return err("url is required");
+                if (!email)
+                    return err("email is required: Opedd writes to it when the publication is available");
+                const envelope = (await opeddFetch(creds, "/publication-request", {
+                    method: "POST",
+                    body: JSON.stringify({ url, email, name, organization, note }),
+                }));
+                return ok(envelope.data ?? envelope);
             }
             // ── search_content ─────────────────────────────────────────────────────
             case "search_content": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opedd-mcp",
-  "version": "0.12.7",
+  "version": "0.12.9",
   "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",