getdr-mcp 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+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
+
+- `getdr-mcp`: MCP server over stdio, run with `npx -y getdr-mcp`; no runtime
+  dependencies.
+- Tool `get_dr`: Ahrefs Domain Rating for domains or URLs (`targets`, optional
+  `version` `dr3`/`dr4` and `fresh`).
+- Backends in order: a getdr server from `GETDR_API` (bearer token from
+  `GETDR_SERVE_TOKEN`), else the `getdr` binary on `PATH`; a tool error with
+  setup instructions when neither is there.
+- Result: the getdr JSON records as text, followed by the Ahrefs attribution;
+  `structuredContent` with an `outputSchema` for protocol 2025-06-18 and later.
+- MCP protocol versions 2026-07-28 (stateless, with `server/discover`) and the
+  `initialize`-based 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.
+- A request cancelled with `notifications/cancelled` gets no response.
+- `server.json` for the MCP Registry.
+- 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.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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Index Pages
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# getdr-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`getdr-mcp` is a small open-source [MCP](https://modelcontextprotocol.io/) server by
+[Index Pages](https://index-pages.com) that gives AI agents one tool, `get_dr`: Ahrefs Domain Rating (DR) for
+domains or URLs. It is a thin front for [getdr](https://index-pages.com/getdr) – it asks a getdr server or the
+`getdr` binary and makes no Ahrefs requests of its own. Stdio transport, no runtime dependencies. Docs:
+[index-pages.com/getdr](https://index-pages.com/getdr).
+
+## Setup
+
+Add it to your MCP client (Claude Desktop, Claude Code, Cursor and others use this shape):
+
+```json
+{
+  "mcpServers": {
+    "getdr": {
+      "command": "npx",
+      "args": ["-y", "getdr-mcp"]
+    }
+  }
+}
+```
+
+That uses the `getdr` binary on your `PATH`. To use a getdr server on your network instead:
+
+```json
+{
+  "mcpServers": {
+    "getdr": {
+      "command": "npx",
+      "args": ["-y", "getdr-mcp"],
+      "env": {
+        "GETDR_API": "http://lan-host:8080",
+        "GETDR_SERVE_TOKEN": "s3cret"
+      }
+    }
+  }
+}
+```
+
+Requires Node.js 18 or later.
+
+## Backends
+
+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` (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
+[Releases](https://github.com/index-pages/getdr/releases), then get a free Ahrefs API key:
+[index-pages.com/getdr#key](https://index-pages.com/getdr#key).
+
+Both backends return the same records. Calls time out after 120 seconds.
+
+Proxies: the HTTP backend uses Node's built-in `fetch`, which ignores `HTTP_PROXY`/`HTTPS_PROXY` unless
+`NODE_USE_ENV_PROXY=1` is set (Node 22.21 or later, or 24 and later; older versions have no built-in proxy
+support). The binary backend honours `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` as usual.
+
+## Tool
+
+`get_dr` – "Ahrefs Domain Rating (0–100) for domains or URLs, via getdr by Index Pages".
+
+| argument | type | |
+|---|---|---|
+| `targets` | string[] | required, non-empty; domains or URLs |
+| `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
+duplicates are removed. Results follow the input order.
+
+## Output
+
+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}
+]
+```
+
+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 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.
+
+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 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.
+
+Supported MCP protocol versions: 2026-07-28 (stateless: `server/discover` and per-request `_meta`, no
+handshake) and the `initialize`-based 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05, served side by side.
+
+## Attribution
+
+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" wherever you publish the numbers. The tool result carries only the data, with
+no attribution in it.
+
+getdr is not affiliated with Ahrefs.
+
+## No telemetry
+
+getdr-mcp connects to exactly one place: the getdr server in `GETDR_API`, when you set it. Otherwise it only
+starts the `getdr` binary. No telemetry, no update checks, no analytics, no pings. Requests carry the
+User-Agent `getdr-mcp/<version> (+https://index-pages.com/getdr)`. You can verify this in the source: the only
+outgoing request and the only child process are in `src/backends.ts`.
+
+## Development
+
+```sh
+npm ci
+npm run build
+npm test
+```
+
+The backend tests build `getdr` and its mock-backed server from the getdr source tree (`../bin`, or
+`GETDR_SRC`) and need Go; without it they are skipped. The live check runs only when `AHREFS_KEY` is set.
+
+## Releasing
+
+Bump the version in `package.json`, `server.json` (twice) and `src/version.ts`, update `CHANGELOG.md`, then
+push a tag `vX.Y.Z`. `.github/workflows/release.yml` builds, runs the tests against the getdr source at the
+same tag, checks that every version matches the tag and that the packed tarball holds `dist/index.js` with its
+shebang, and publishes with npm trusted publishing (OIDC, no token, provenance included).
+
+Trusted publishing can only be configured for a package that already exists on npm, so the first release is
+published by hand once: `npm login`, then `npm run release`. Right after that, add the trusted publisher on
+npmjs.com (package Settings → Trusted publishing: GitHub Actions, `index-pages` / `getdr-mcp`, workflow
+`release.yml`); the workflow has to complete its first publish within 2 days or the configuration expires.
+
+For any manual publish use `npm run release` (build, tests, `check-release`, `npm publish`), never a bare
+`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.
+
+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
+
+MIT, see [LICENSE](LICENSE). Made by [Index Pages](https://index-pages.com).

package/dist/backends.js

@@ -0,0 +1,216 @@
+// The two ways to get Domain Rating: a getdr server (GETDR_API) or the getdr
+// binary on PATH. Both return the same record shape. Nothing here talks to
+// Ahrefs directly.
+import { spawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import { HOMEPAGE, USER_AGENT } from "./version.js";
+// A failure to report to the model as a tool error.
+export class BackendError extends Error {
+}
+// Both the HTTP request and the binary run are bounded by this. A getdr
+// server may need several rate-limited Ahrefs batches for a long list.
+export const TIMEOUT_MS = 120_000;
+const MAX_DETAIL = 2000;
+export function isNoResponse(r) {
+    return r.dr === null && r.checked_at === null && r.error === undefined;
+}
+export function toRecord(v) {
+    const o = v;
+    if (typeof o !== "object" ||
+        o === null ||
+        typeof o.target !== "string" ||
+        !(o.dr === null || typeof o.dr === "number") ||
+        typeof o.version !== "string" ||
+        !(o.checked_at === null || typeof o.checked_at === "string") ||
+        typeof o.cached !== "boolean" ||
+        !(o.error === undefined || typeof o.error === "string")) {
+        throw new Error(`unexpected record ${JSON.stringify(v)?.slice(0, 200)}`);
+    }
+    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();
+    return s.length > MAX_DETAIL ? s.slice(0, MAX_DETAIL) + "…" : s;
+}
+// ---- getdr server -------------------------------------------------------
+function serverError(body) {
+    try {
+        const e = JSON.parse(body);
+        if (typeof e.error === "string" && e.error)
+            return e.error;
+    }
+    catch {
+        // not JSON, fall through
+    }
+    return clip(body) || "(empty body)";
+}
+export async function viaApi(base, token, q) {
+    const url = base.replace(/\/+$/, "") + "/dr";
+    const where = `getdr server ${base} (GETDR_API)`;
+    // 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 = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": USER_AGENT,
+    };
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    let status;
+    let text;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        status = res.status;
+        text = await res.text();
+    }
+    catch (err) {
+        const e = err;
+        if (e.name === "TimeoutError" || e.name === "AbortError") {
+            throw new BackendError(`${where} did not answer within ${TIMEOUT_MS / 1000} s. Try again later or with fewer targets.`);
+        }
+        const why = e.cause?.code ?? e.cause?.message ?? e.message;
+        throw new BackendError(`${where} is unreachable: ${why}. Check that GETDR_API points to a running getdr serve.`);
+    }
+    switch (status) {
+        case 200:
+            break;
+        case 401:
+            throw new BackendError(`${where} rejected the request: ${serverError(text)}. Set GETDR_SERVE_TOKEN to the server's token.`);
+        case 503:
+            throw new BackendError(`${where}: ${serverError(text)}`);
+        default:
+            throw new BackendError(`${where}: HTTP ${status}: ${serverError(text)}`);
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (!Array.isArray(parsed.results))
+            throw new Error('no "results" array');
+        const records = parsed.results.map(toRecord);
+        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}`);
+    }
+}
+// ---- getdr binary -------------------------------------------------------
+// Looks up getdr in PATH the way a shell would, without running a shell.
+// Empty and relative PATH entries are skipped so the working directory never
+// supplies the binary.
+export function findBinary(env) {
+    const win = process.platform === "win32";
+    const pathVar = (win ? (env.Path ?? env.PATH) : env.PATH) ?? "";
+    const names = win
+        ? (env.PATHEXT ?? ".EXE;.COM").split(";").filter(Boolean).map((ext) => "getdr" + ext.toLowerCase())
+        : ["getdr"];
+    for (const dir of pathVar.split(delimiter)) {
+        if (!dir || !isAbsolute(dir))
+            continue;
+        for (const name of names) {
+            const p = join(dir, name);
+            try {
+                if (!statSync(p).isFile())
+                    continue;
+                if (!win)
+                    accessSync(p, constants.X_OK);
+                return p;
+            }
+            catch {
+                // not here
+            }
+        }
+    }
+    return null;
+}
+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. -f skips lines
+    // starting with "#", so such a list goes as arguments after "--" instead.
+    const argv = ["--format", "json", "-q"];
+    if (q.version)
+        argv.push("--version", q.version);
+    if (q.fresh)
+        argv.push("--fresh");
+    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;
+        try {
+            child = spawn(bin, argv, { env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+        }
+        catch (err) {
+            fail(`cannot run ${bin}: ${err.message}`);
+            return;
+        }
+        const out = [];
+        const errOut = [];
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, TIMEOUT_MS);
+        child.stdout.on("data", (b) => out.push(b));
+        child.stderr.on("data", (b) => errOut.push(b));
+        child.stdin.on("error", () => {
+            // the binary exited before reading everything; its exit code tells why
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            fail(`cannot run ${bin}: ${err.message}`);
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            const stdout = Buffer.concat(out).toString("utf8");
+            const stderr = clip(Buffer.concat(errOut).toString("utf8"));
+            if (timedOut) {
+                fail(`getdr did not finish within ${TIMEOUT_MS / 1000} s. Try again later or with fewer targets.`);
+                return;
+            }
+            if (code !== 0 && code !== 2) {
+                if (code === 3) {
+                    fail(stderr || `getdr: Ahrefs API key missing or rejected; see ${HOMEPAGE}#key`);
+                }
+                else {
+                    fail(`getdr exited with ${code ?? signal}${stderr ? `: ${stderr}` : ""}`);
+                }
+                return;
+            }
+            let records;
+            try {
+                records = stdout
+                    .split("\n")
+                    .filter((l) => l.trim() !== "")
+                    .map((l) => toRecord(JSON.parse(l)));
+            }
+            catch (err) {
+                fail(`getdr printed unexpected output: ${err.message}`);
+                return;
+            }
+            // Exit 2 without records is an error (bad flag, cache, no valid
+            // 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(asArgs ? "" : q.targets.join("\n") + "\n");
+    });
+}

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// getdr-mcp: an MCP server over stdio with one tool, get_dr. stdout carries
+// only protocol messages, one JSON object per line; diagnostics go to stderr.
+import { cancelledId, errorResponse, PARSE_ERROR, Server } from "./protocol.js";
+const server = new Server(process.env);
+const pending = new Set();
+// Requests in progress, and those the client cancelled: a cancelled request
+// gets no response (2026-07-28 basic/transports/stdio#cancellation).
+const inflight = new Set();
+const cancelled = new Set();
+let buffer = "";
+function send(msg) {
+    process.stdout.write(JSON.stringify(msg) + "\n");
+}
+function onLine(line) {
+    if (line.trim() === "")
+        return;
+    let msg;
+    try {
+        msg = JSON.parse(line);
+    }
+    catch {
+        send(errorResponse(null, PARSE_ERROR, "parse error: each line must be one JSON-RPC message"));
+        return;
+    }
+    const cancel = cancelledId(msg);
+    if (cancel !== undefined && inflight.has(cancel))
+        cancelled.add(cancel);
+    const id = msg?.id;
+    const tracked = typeof id === "string" || typeof id === "number" ? id : undefined;
+    if (tracked !== undefined)
+        inflight.add(tracked);
+    const p = server
+        .handle(msg)
+        .then((res) => {
+        if (tracked !== undefined) {
+            inflight.delete(tracked);
+            if (cancelled.delete(tracked))
+                return;
+        }
+        if (res)
+            send(res);
+    })
+        .catch((err) => {
+        process.stderr.write(`getdr-mcp: ${err?.stack ?? String(err)}\n`);
+    })
+        .finally(() => pending.delete(p));
+    pending.add(p);
+}
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf("\n")) >= 0) {
+        onLine(buffer.slice(0, nl));
+        buffer = buffer.slice(nl + 1);
+    }
+});
+// The client closed stdin: answer what is in flight, then exit.
+process.stdin.on("end", () => {
+    onLine(buffer);
+    buffer = "";
+    void Promise.allSettled([...pending]).then(() => process.exit(0));
+});
+// The client went away; nothing left to write to.
+process.stdout.on("error", () => process.exit(0));

package/dist/protocol.js

@@ -0,0 +1,195 @@
+// MCP over stdio is newline-delimited JSON-RPC 2.0. This module answers one
+// parsed message at a time; index.ts does the line framing.
+//
+// Two protocol eras are served side by side ("dual-era", 2026-07-28
+// basic/versioning#backward-compatibility-with-initialization-based-versions):
+// - legacy (2024-11-05 … 2025-11-25): an initialize handshake fixes the
+//   version for the process;
+// - modern (2026-07-28): no handshake, every request names its version and
+//   client capabilities in _meta, results carry resultType.
+import { callGetDr, toolDefinition } from "./tool.js";
+import { VERSION } from "./version.js";
+// Newest first. initialize answers with the requested legacy version when we
+// support it, else with the newest legacy one.
+export const LEGACY_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export const MODERN_VERSIONS = ["2026-07-28"];
+export const SUPPORTED_VERSIONS = [...MODERN_VERSIONS, ...LEGACY_VERSIONS];
+// structuredContent and outputSchema exist since 2025-06-18.
+const STRUCTURED_SINCE = "2025-06-18";
+// Per-request _meta keys (2026-07-28 basic/index#meta).
+const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+const META_CLIENT_CAPS = "io.modelcontextprotocol/clientCapabilities";
+const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+// The tool list only changes with a new release, which means a new process.
+// Cache hints are required on server/discover and tools/list
+// (2026-07-28 server/utilities/caching#cacheable-results).
+const CACHE_TTL_MS = 3_600_000;
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+export const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+const SERVER_INFO = { name: "getdr-mcp", title: "getdr", version: VERSION };
+const CAPABILITIES = { tools: { listChanged: false } };
+class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+export function errorResponse(id, code, message, data) {
+    const error = { code, message };
+    if (data !== undefined)
+        error.data = data;
+    return { jsonrpc: "2.0", id, error };
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+// The request id a notifications/cancelled message refers to, if it is one.
+export function cancelledId(msg) {
+    if (!isObject(msg) || msg.method !== "notifications/cancelled" || "id" in msg || !isObject(msg.params)) {
+        return undefined;
+    }
+    const id = msg.params.requestId;
+    return typeof id === "string" || typeof id === "number" ? id : undefined;
+}
+export class Server {
+    env;
+    // Legacy version agreed in initialize; null until then.
+    protocolVersion = null;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    // Returns the response to send, or null for notifications and for
+    // responses the client sends us (we never send requests, so we ignore them).
+    async handle(msg) {
+        if (Array.isArray(msg)) {
+            return errorResponse(null, INVALID_REQUEST, "JSON-RPC batches are not supported");
+        }
+        if (!isObject(msg) || msg.jsonrpc !== "2.0") {
+            const id = isObject(msg) ? validId(msg.id) : null;
+            return errorResponse(id, INVALID_REQUEST, 'invalid request: expected a JSON-RPC 2.0 object with "jsonrpc": "2.0"');
+        }
+        const hasId = "id" in msg;
+        if (typeof msg.method !== "string") {
+            if (!("result" in msg) && !("error" in msg)) {
+                return errorResponse(validId(msg.id), INVALID_REQUEST, "invalid request: missing method");
+            }
+            return null;
+        }
+        if (!hasId)
+            return null; // notification: notifications/initialized, notifications/cancelled, …
+        if (typeof msg.id !== "string" && typeof msg.id !== "number") {
+            return errorResponse(null, INVALID_REQUEST, "invalid request: id must be a string or a number");
+        }
+        const id = msg.id;
+        if (msg.params !== undefined && !isObject(msg.params)) {
+            return errorResponse(id, INVALID_PARAMS, "params must be an object");
+        }
+        const params = msg.params ?? {};
+        try {
+            const ctx = this.context(params);
+            const result = (await this.dispatch(msg.method, params, ctx));
+            if (ctx.modern) {
+                // 2026-07-28 basic/index#result-responses: resultType is required;
+                // serverInfo in every result's _meta is a SHOULD.
+                result.resultType = "complete";
+                result._meta = { [META_SERVER_INFO]: SERVER_INFO };
+            }
+            return { jsonrpc: "2.0", id, result };
+        }
+        catch (err) {
+            if (err instanceof RpcError)
+                return errorResponse(id, err.code, err.message, err.data);
+            return errorResponse(id, INTERNAL_ERROR, `internal error: ${err?.message ?? String(err)}`);
+        }
+    }
+    // A request that names its protocol version in _meta is served by that
+    // version alone (2026-07-28 basic/index#statelessness); one without it
+    // belongs to the legacy session.
+    context(params) {
+        const meta = isObject(params._meta) ? params._meta : undefined;
+        const requested = meta?.[META_VERSION];
+        if (requested === undefined) {
+            return { version: this.protocolVersion ?? LEGACY_VERSIONS[0], modern: false };
+        }
+        if (typeof requested !== "string") {
+            throw new RpcError(INVALID_PARAMS, `_meta["${META_VERSION}"] must be a string`);
+        }
+        if (!SUPPORTED_VERSIONS.includes(requested)) {
+            throw new RpcError(UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version", {
+                supported: SUPPORTED_VERSIONS,
+                requested,
+            });
+        }
+        const modern = MODERN_VERSIONS.includes(requested);
+        if (modern && !isObject(meta?.[META_CLIENT_CAPS])) {
+            throw new RpcError(INVALID_PARAMS, `missing _meta["${META_CLIENT_CAPS}"]`);
+        }
+        return { version: requested, modern };
+    }
+    async dispatch(method, params, ctx) {
+        const structured = ctx.version >= STRUCTURED_SINCE; // ISO dates compare as strings
+        switch (method) {
+            case "initialize":
+                return this.initialize(params);
+            case "server/discover":
+                if (!ctx.modern) {
+                    throw new RpcError(INVALID_PARAMS, `server/discover needs _meta["${META_VERSION}"]: "${MODERN_VERSIONS[0]}"`);
+                }
+                return {
+                    supportedVersions: SUPPORTED_VERSIONS,
+                    capabilities: CAPABILITIES,
+                    ttlMs: CACHE_TTL_MS,
+                    cacheScope: "public",
+                };
+            case "ping":
+                if (ctx.modern)
+                    break; // removed in 2026-07-28
+                return {};
+            case "tools/list": {
+                const result = { tools: [toolDefinition(structured)] };
+                if (ctx.modern)
+                    Object.assign(result, { ttlMs: CACHE_TTL_MS, cacheScope: "public" });
+                return result;
+            }
+            case "tools/call":
+                return this.callTool(params, structured);
+        }
+        throw new RpcError(METHOD_NOT_FOUND, `method not found: ${method}`);
+    }
+    initialize(params) {
+        const requested = params.protocolVersion;
+        if (typeof requested !== "string") {
+            throw new RpcError(INVALID_PARAMS, "initialize: protocolVersion must be a string", {
+                supported: LEGACY_VERSIONS,
+            });
+        }
+        this.protocolVersion = LEGACY_VERSIONS.includes(requested) ? requested : LEGACY_VERSIONS[0];
+        return {
+            protocolVersion: this.protocolVersion,
+            capabilities: CAPABILITIES,
+            serverInfo: SERVER_INFO,
+        };
+    }
+    async callTool(params, structured) {
+        if (typeof params.name !== "string") {
+            throw new RpcError(INVALID_PARAMS, "tools/call: name must be a string");
+        }
+        if (params.name !== "get_dr") {
+            throw new RpcError(INVALID_PARAMS, `unknown tool: ${params.name}`);
+        }
+        if (params.arguments !== undefined && !isObject(params.arguments)) {
+            throw new RpcError(INVALID_PARAMS, "tools/call: arguments must be an object");
+        }
+        return callGetDr(params.arguments ?? {}, { structured, env: this.env });
+    }
+}
+function validId(id) {
+    return typeof id === "string" || typeof id === "number" ? id : null;
+}

package/dist/tool.js

@@ -0,0 +1,125 @@
+// 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";
+const DESCRIPTION = "Ahrefs Domain Rating (0–100) for domains or URLs, via getdr by Index Pages";
+export function toolDefinition(structured) {
+    const tool = {
+        name: "get_dr",
+        title: "Ahrefs Domain Rating",
+        description: DESCRIPTION,
+        inputSchema: {
+            type: "object",
+            properties: {
+                targets: {
+                    type: "array",
+                    items: { type: "string" },
+                    minItems: 1,
+                    description: "Domains or URLs. URLs are reduced to the host, www. is dropped, duplicates are removed; results follow the input order.",
+                },
+                version: {
+                    type: "string",
+                    enum: ["dr3", "dr4"],
+                    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",
+                    description: "Ignore the cache and fetch again.",
+                },
+            },
+            required: ["targets"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    };
+    if (structured) {
+        tool.outputSchema = {
+            type: "object",
+            properties: {
+                results: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            target: { type: "string" },
+                            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 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"],
+                    },
+                },
+            },
+            required: ["results"],
+        };
+    }
+    return tool;
+}
+function toolError(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+export const NO_BACKEND = "getdr is not available. Either set GETDR_API to the URL of a getdr server (getdr serve), " +
+    "or install the getdr binary and put it on PATH: go install github.com/index-pages/getdr@latest, " +
+    "or download it from https://github.com/index-pages/getdr/releases. " +
+    `The binary needs a free Ahrefs API key in AHREFS_KEY; a getdr server brings its own. Setup: ${HOMEPAGE}`;
+// Returns the checked arguments or an error message for the model.
+function checkArgs(a) {
+    for (const k of Object.keys(a)) {
+        if (k !== "targets" && k !== "version" && k !== "fresh") {
+            return `unknown argument "${k}"; get_dr takes targets, version and fresh`;
+        }
+    }
+    const { targets, version, fresh } = a;
+    if (!Array.isArray(targets) || targets.length === 0) {
+        return "targets must be a non-empty array of domains or URLs, e.g. [\"example.com\"]";
+    }
+    for (const t of targets) {
+        if (typeof t !== "string")
+            return "every target must be a string";
+        if (/[\r\n]/.test(t))
+            return "a target must not contain line breaks";
+    }
+    if (version !== undefined && version !== "dr3" && version !== "dr4") {
+        return 'version must be "dr3" or "dr4"';
+    }
+    if (fresh !== undefined && typeof fresh !== "boolean") {
+        return "fresh must be true or false";
+    }
+    return { targets, version, fresh };
+}
+export async function callGetDr(raw, opts) {
+    const args = checkArgs(raw);
+    if (typeof args === "string")
+        return toolError(args);
+    let backend;
+    const api = opts.env.GETDR_API?.trim();
+    if (api) {
+        backend = (q) => viaApi(api, opts.env.GETDR_SERVE_TOKEN || undefined, q);
+    }
+    else {
+        const bin = findBinary(opts.env);
+        if (!bin)
+            return toolError(NO_BACKEND);
+        backend = (q) => viaBinary(bin, opts.env, q);
+    }
+    let records;
+    let detail = "";
+    try {
+        ({ records, detail } = await backend(args));
+    }
+    catch (err) {
+        if (err instanceof BackendError)
+            return toolError(err.message);
+        throw err;
+    }
+    // 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.");
+    }
+    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 };
+    return result;
+}

package/dist/version.js

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

package/humans.txt

@@ -0,0 +1,14 @@
+/* TEAM */
+Team: Index Pages
+Site: https://index-pages.com
+Project: https://index-pages.com/getdr
+
+/* THANKS */
+Domain Rating data: Ahrefs – https://ahrefs.com/
+
+/* SITE */
+Last update: 2026/10/28
+Language: English
+Standards: Model Context Protocol, JSON-RPC 2.0
+Components: none (no runtime dependencies)
+Software: Node.js, TypeScript

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "getdr-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server for Ahrefs Domain Rating via getdr by Index Pages",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ahrefs",
+    "domain-rating",
+    "seo",
+    "getdr"
+  ],
+  "author": "Index Pages",
+  "homepage": "https://index-pages.com/getdr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/index-pages/getdr-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/index-pages/getdr-mcp/issues"
+  },
+  "mcpName": "io.github.index-pages/getdr-mcp",
+  "type": "module",
+  "bin": {
+    "getdr-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "humans.txt"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "node --test test/*.test.mjs",
+    "check-release": "node scripts/check-release.mjs",
+    "release": "npm run build && npm test && npm run check-release && npm publish --access public"
+  },
+  "devDependencies": {
+    "@types/node": "18.19.130",
+    "typescript": "6.0.3"
+  }
+}