getdr-mcp 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,34 @@ and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-29
+
+### Added
+
+- Records of invalid targets carry `"error":"invalid target"` (also in
+  `outputSchema`). Through a getdr server, a target its Ahrefs refuses is no
+  longer reported as "no response".
+- The release workflow publishes `server.json` to the MCP Registry.
+
+### Fixed
+
+- Through the binary, a target starting with `#` was skipped as a comment of
+  the `-f -` list; such lists now go as arguments.
+
+### Changed
+
+- The binary backend needs getdr 0.2.0 or newer (for the `error` field).
+- Without `version`, the getdr server's or binary's config decides; before,
+  `dr3` was always sent.
+- The text result is only the JSON array: the note after it about targets
+  without a response is gone (their `checked_at` is `null`). An error for
+  "no response for any target" quotes getdr instead of guessing a cause.
+
+### Removed
+
+- The Ahrefs attribution line at the end of the `get_dr` text result and the
+  `attribution` field of `structuredContent` (and of `outputSchema`).
+
 ## [0.1.0] - 2026-10-28
 
 ### Added
@@ -26,5 +54,6 @@ and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Release workflow with npm trusted publishing, and `npm run release` with a
   version and tarball check for manual publishes.
 
-[Unreleased]: https://github.com/index-pages/getdr-mcp/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/index-pages/getdr-mcp/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/index-pages/getdr-mcp/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/index-pages/getdr-mcp/releases/tag/v0.1.0

package/README.md

@@ -47,8 +47,10 @@ Checked on every call, in this order:
 1. `GETDR_API` is set – one `POST $GETDR_API/dr` to that getdr server (`getdr serve`), with
    `Authorization: Bearer $GETDR_SERVE_TOKEN` when the token is set. The server holds the Ahrefs key and the
    shared cache, so this machine needs neither.
-2. `getdr` is on `PATH` – runs `getdr --format json -q --version V [--fresh] -f -` with the targets on
-   stdin, no shell. The binary uses its own config, cache and key (`AHREFS_KEY`), or its own `api` setting.
+2. `getdr` (0.2.0 or newer) is on `PATH` – runs `getdr --format json -q [--version V] [--fresh] -f -` with
+   the targets on stdin, no shell (as arguments after `--` when a target starts with `#`, which `-f` would
+   skip as a comment). The binary uses its own config, cache and key (`AHREFS_KEY`), or its own `api`
+   setting.
 3. Neither – the tool returns an error with setup instructions.
 
 Install the binary with `go install github.com/index-pages/getdr@latest` or from
@@ -68,7 +70,7 @@ support). The binary backend honours `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
 | argument | type | |
 |---|---|---|
 | `targets` | string[] | required, non-empty; domains or URLs |
-| `version` | `"dr3"` or `"dr4"` | DR formula, default `dr3` (always sent explicitly, so a server or config set to `dr4` does not change it); values are not comparable between versions |
+| `version` | `"dr3"` or `"dr4"` | DR formula; when left out, the backend's config decides: the getdr server's with `GETDR_API`, otherwise the binary's (also when that binary uses a server), `dr3` unless set; values are not comparable between versions |
 | `fresh` | boolean | ignore the cache and fetch again |
 
 Targets are normalized by getdr: a URL becomes its host, `www.` is dropped, everything is lower-cased and
@@ -76,26 +78,25 @@ duplicates are removed. Results follow the input order.
 
 ## Output
 
-The text result is a JSON array with one record per target, then the attribution line:
+The text result is a JSON array with one record per target, and nothing else:
 
 ```
 [
 {"target":"ahrefs.com","dr":91,"version":"dr3","checked_at":"2026-10-28T12:00:00Z","cached":true},
 {"target":"nodata.example","dr":null,"version":"dr3","checked_at":"2026-10-28T12:00:00Z","cached":false}
 ]
-
-Domain Rating by Ahrefs – https://ahrefs.com/
 ```
 
 The record is the getdr JSON contract, the same as `getdr --format json` and `getdr serve`. `dr` is `null`
-when Ahrefs has no data; `checked_at` is `null` too when there was no response (timeout, rate limit). Clients on
-MCP protocol 2025-06-18 or later also get `structuredContent` – `{"results": […], "attribution": "…"}` – and an
-`outputSchema` for it.
+when Ahrefs has no data; `checked_at` is `null` too when there was no response or the target is invalid. An
+invalid target (not a domain or URL, or refused by Ahrefs, such as `localhost`) also has
+`"error":"invalid target"`; no other record has an `error` key. Clients on MCP protocol 2025-06-18 or later
+also get `structuredContent` – `{"results": […]}` – and an `outputSchema` for it.
 
-When some targets got no response, the result is a normal one: all records, followed by a note naming those
-targets. Everything else comes back as a tool error (`isError: true`) with getdr's message:
+Invalid targets and targets without a response are part of a normal result. Failures come back as a tool
+error (`isError: true`) with getdr's message:
 
-- no target got a response – an error with the reason;
+- no target got a response at all;
 - getdr server answered 401 – the token is missing or wrong, set `GETDR_SERVE_TOKEN`;
 - getdr server answered 503, or the binary exited with code 3 – the Ahrefs key is missing or rejected;
 - the server is unreachable, the binary failed, or a call timed out.
@@ -107,7 +108,8 @@ handshake) and the `initialize`-based 2025-11-25, 2025-06-18, 2025-03-26 and 202
 
 Domain Rating data comes from [Ahrefs](https://ahrefs.com/) and is subject to the
 [Domain Rating License](https://ahrefs.com/legal/domain-rating-license), which requires the attribution
-"Domain Rating by Ahrefs". Every result ends with it. Keep it when you publish the numbers.
+"Domain Rating by Ahrefs" wherever you publish the numbers. The tool result carries only the data, with
+no attribution in it.
 
 getdr is not affiliated with Ahrefs.
 
@@ -145,10 +147,11 @@ For any manual publish use `npm run release` (build, tests, `check-release`, `np
 `npm publish`: with install scripts disabled (`ignore-scripts`) `prepack` does not run and the package would
 ship without `dist/`. `prepack` stays as a fallback for setups that run scripts.
 
-MCP Registry (manual, after the npm release): install `mcp-publisher` from the
-[registry releases](https://github.com/modelcontextprotocol/registry/releases), run
-`mcp-publisher login github` as a member of the `index-pages` GitHub org, then `mcp-publisher publish` in
-the repo root. It reads `server.json` and checks `mcpName` in the published npm package.
+The same workflow then publishes `server.json` to the [MCP Registry](https://registry.modelcontextprotocol.io)
+as `io.github.index-pages/getdr-mcp`: it waits until npm shows the new version (the registry checks `mcpName`
+in the npm package), proves the `index-pages` namespace with the workflow's OIDC token
+(`mcp-publisher login github-oidc`, no secret) and runs `mcp-publisher publish` with a pinned, checksummed
+`mcp-publisher`. A version already in the registry is skipped.
 
 ## License
 

package/dist/backends.js

@@ -13,7 +13,7 @@ export class BackendError extends Error {
 export const TIMEOUT_MS = 120_000;
 const MAX_DETAIL = 2000;
 export function isNoResponse(r) {
-    return r.dr === null && r.checked_at === null;
+    return r.dr === null && r.checked_at === null && r.error === undefined;
 }
 export function toRecord(v) {
     const o = v;
@@ -23,10 +23,14 @@ export function toRecord(v) {
         !(o.dr === null || typeof o.dr === "number") ||
         typeof o.version !== "string" ||
         !(o.checked_at === null || typeof o.checked_at === "string") ||
-        typeof o.cached !== "boolean") {
+        typeof o.cached !== "boolean" ||
+        !(o.error === undefined || typeof o.error === "string")) {
         throw new Error(`unexpected record ${JSON.stringify(v)?.slice(0, 200)}`);
     }
-    return { target: o.target, dr: o.dr, version: o.version, checked_at: o.checked_at, cached: o.cached };
+    const r = { target: o.target, dr: o.dr, version: o.version, checked_at: o.checked_at, cached: o.cached };
+    if (o.error !== undefined)
+        r.error = o.error;
+    return r;
 }
 function clip(s) {
     s = s.trim();
@@ -47,8 +51,10 @@ function serverError(body) {
 export async function viaApi(base, token, q) {
     const url = base.replace(/\/+$/, "") + "/dr";
     const where = `getdr server ${base} (GETDR_API)`;
-    // Always explicit, so a server configured for dr4 still answers dr3 by default.
-    const body = { targets: q.targets, version: q.version ?? "dr3" };
+    // Without a version the server's own default applies.
+    const body = { targets: q.targets };
+    if (q.version)
+        body.version = q.version;
     if (q.fresh)
         body.fresh = true;
     const headers = {
@@ -93,8 +99,7 @@ export async function viaApi(base, token, q) {
         if (!Array.isArray(parsed.results))
             throw new Error('no "results" array');
         const records = parsed.results.map(toRecord);
-        const detail = records.some(isNoResponse) ? "the getdr server got no answer from Ahrefs (timeout or rate limit)" : "";
-        return { records, detail };
+        return { records, detail: records.some(isNoResponse) ? "the getdr server got no answer from Ahrefs" : "" };
     }
     catch (err) {
         throw new BackendError(`${where} sent an unexpected response: ${err.message}`);
@@ -131,12 +136,18 @@ export function findBinary(env) {
 }
 export function viaBinary(bin, env, q) {
     // Targets go through stdin (-f -): no shell, no argv length limits, and a
-    // target that starts with "-" is never read as a flag.
+    // target that starts with "-" is never read as a flag. -f skips lines
+    // starting with "#", so such a list goes as arguments after "--" instead.
     const argv = ["--format", "json", "-q"];
-    argv.push("--version", q.version ?? "dr3"); // explicit: the binary's own config may say dr4
+    if (q.version)
+        argv.push("--version", q.version);
     if (q.fresh)
         argv.push("--fresh");
-    argv.push("-f", "-");
+    const asArgs = q.targets.some((t) => t.trim().startsWith("#"));
+    if (asArgs)
+        argv.push("--", ...q.targets);
+    else
+        argv.push("-f", "-");
     return new Promise((resolve, reject) => {
         const fail = (msg) => reject(new BackendError(msg));
         let child;
@@ -192,13 +203,14 @@ export function viaBinary(bin, env, q) {
                 return;
             }
             // Exit 2 without records is an error (bad flag, cache, no valid
-            // targets); with records it means some targets got no response.
+            // targets); with records it means some targets were invalid or got no
+            // response.
             if (code === 2 && records.length === 0) {
                 fail(stderr || "getdr failed (exit 2)");
                 return;
             }
             resolve({ records, detail: code === 2 ? stderr : "" });
         });
-        child.stdin.end(q.targets.join("\n") + "\n");
+        child.stdin.end(asArgs ? "" : q.targets.join("\n") + "\n");
     });
 }

package/dist/tool.js

@@ -1,7 +1,6 @@
 // The get_dr tool: argument checks, backend choice and the result shape.
 import { BackendError, findBinary, isNoResponse, viaApi, viaBinary } from "./backends.js";
 import { HOMEPAGE } from "./version.js";
-export const ATTRIBUTION = "Domain Rating by Ahrefs – https://ahrefs.com/";
 const DESCRIPTION = "Ahrefs Domain Rating (0–100) for domains or URLs, via getdr by Index Pages";
 export function toolDefinition(structured) {
     const tool = {
@@ -20,7 +19,7 @@ export function toolDefinition(structured) {
                 version: {
                     type: "string",
                     enum: ["dr3", "dr4"],
-                    description: "DR formula: dr3 or dr4 (the new one); default dr3, whatever the getdr config says. Values are not comparable between versions.",
+                    description: "DR formula: dr3 or dr4 (the new one); default: the getdr server's or binary's config, dr3 unless set there. Values are not comparable between versions.",
                 },
                 fresh: {
                     type: "boolean",
@@ -42,17 +41,17 @@ export function toolDefinition(structured) {
                         type: "object",
                         properties: {
                             target: { type: "string" },
-                            dr: { type: ["number", "null"], description: "null: no data, or no response when checked_at is null" },
+                            dr: { type: ["number", "null"], description: "null: no data, or no response or an invalid target when checked_at is null" },
                             version: { type: "string", enum: ["dr3", "dr4"] },
-                            checked_at: { type: ["string", "null"], description: "RFC 3339 UTC; null when there was no response" },
+                            checked_at: { type: ["string", "null"], description: "RFC 3339 UTC; null for no response or an invalid target" },
                             cached: { type: "boolean" },
+                            error: { type: "string", enum: ["invalid target"], description: "only on a target that is not a domain or URL" },
                         },
                         required: ["target", "dr", "version", "checked_at", "cached"],
                     },
                 },
-                attribution: { type: "string" },
             },
-            required: ["results", "attribution"],
+            required: ["results"],
         };
     }
     return tool;
@@ -114,19 +113,13 @@ export async function callGetDr(raw, opts) {
             return toolError(err.message);
         throw err;
     }
-    const missing = records.filter(isNoResponse);
-    if (records.length > 0 && missing.length === records.length) {
-        return toolError(`No response for any target${detail ? `: ${detail}` : " (timeout or rate limit on the Ahrefs side)"}. Try again later.`);
+    // Nothing answered at all is a failure of the backend, not a result.
+    if (records.length > 0 && records.every(isNoResponse)) {
+        return toolError(detail ? `No response for any target: ${detail}` : "No response for any target.");
     }
-    let text = records.length ? "[\n" + records.map((r) => JSON.stringify(r)).join(",\n") + "\n]\n" : "[]\n";
-    if (missing.length > 0) {
-        text +=
-            `\nNo response for ${missing.length} of ${records.length} target(s), dr and checked_at are null: ` +
-                `${missing.map((r) => r.target).join(", ")}. Try these again later.\n`;
-    }
-    text += `\n${ATTRIBUTION}`;
+    const text = records.length ? "[\n" + records.map((r) => JSON.stringify(r)).join(",\n") + "\n]\n" : "[]\n";
     const result = { content: [{ type: "text", text }] };
     if (opts.structured)
-        result.structuredContent = { results: records, attribution: ATTRIBUTION };
+        result.structuredContent = { results: records };
     return result;
 }

package/dist/version.js

@@ -1,4 +1,4 @@
 // Kept in sync with package.json (a test checks it).
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";
 export const HOMEPAGE = "https://index-pages.com/getdr";
 export const USER_AGENT = `getdr-mcp/${VERSION} (+${HOMEPAGE})`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getdr-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Ahrefs Domain Rating via getdr by Index Pages",
   "keywords": [
     "mcp",