@dnsdoctor/mcp 1.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,169 @@
+# DNS Doctor — Claude Code plugin
+
+Diagnose and fix a domain's email authentication (SPF, DMARC, DKIM, MX, blacklist,
+domain/SSL expiry) from inside Claude. This plugin bundles the DNS Doctor **skill**
+(the scan → diagnose → fix workflow) and an **MCP server config** pointing at the
+hosted DNS Doctor tools.
+
+The moat: every fix record you get back is generated and validated by a
+deterministic engine — RFC grammar plus the SPF 10-lookup counter — **never an LLM
+guess**. Your agent hands the human a record that already parses correctly, not a
+plausible-looking string that silently fails.
+
+## What's inside
+
+```
+claude-plugin/
+├── .claude-plugin/plugin.json   # plugin manifest
+├── .mcp.json                    # MCP server: https://dnsdoctor.dev/mcp (HTTP)
+├── skills/dns-doctor/SKILL.md   # the scan → diagnose → fix workflow
+├── src/                         # @dnsdoctor/mcp — the local stdio MCP server
+├── tools.json                   # the 11 tool definitions (generated, never hand-edited)
+├── instructions.txt             # the server's own `initialize` guidance (generated)
+├── tests/                       # vitest suite for the stdio server
+├── package.json  tsconfig.json  # npm package + build
+├── LICENSE                      # Apache-2.0
+└── README.md
+```
+
+## Tools it adds
+
+| Tool | Does |
+|---|---|
+| `scan_domain` | Fresh scan of a domain; full report. |
+| `get_report` | Persisted report (scans once if none exists). |
+| `build_dmarc_upgrade` | A validated DMARC enforcement record — `p=reject` only when the server-derived alignment gate passes. |
+| `count_spf_lookups` | The SPF DNS-lookup count against the RFC limit of 10. |
+| `validate_dmarc_record` | Parse and validate a DMARC record, tag by tag. |
+| `generate_dmarc_record` | Build a DMARC record from a policy + reporting address. |
+| `check_dkim_selector` | Look up one DKIM selector and check the key. |
+| `parse_dmarc_report` | Parse an aggregate (RUA) report file into rows. |
+| `check_record` | Read any DNS record type for a name. |
+| `check_reverse_dns` | PTR / forward-confirmed reverse DNS for an IP. |
+| `start_monitoring_signup` | A sign-up link to hand to the human who owns the domain. Sends no email and creates nothing — they open it, sign in on our page themselves (a social provider or an emailed link, whichever that deployment offers), and the domain is carried over to their dashboard already filled in; monitoring starts once they verify it with a TXT record. |
+
+Over the hosted HTTP transport the `dnsdoctor://domains` resource (your
+monitored domains) is always listed; reading it needs an API token and is
+refused without one. The local stdio server registers the tools only — no
+resource. Anonymous access is enough for a one-off diagnosis either way.
+
+## Install
+
+### Claude Code
+
+Add the marketplace/repo and enable the plugin:
+
+```bash
+/plugin marketplace add dnsdoctor/claude-plugin
+/plugin install dns-doctor
+```
+
+> Public home: [github.com/dnsdoctor/claude-plugin](https://github.com/dnsdoctor/claude-plugin)
+> (org `dnsdoctor`, domain-verified). The plugin is developed in the DNS Doctor
+> monorepo and published here as clean release snapshots.
+
+Or point Claude Code at a local checkout of this directory during development.
+Once enabled, the skill auto-loads and the `dns-doctor` MCP server connects to
+`https://dnsdoctor.dev/mcp`.
+
+### claude.ai (MCP connector)
+
+Add a custom connector with:
+
+- **URL:** `https://dnsdoctor.dev/mcp`
+- **Transport:** Streamable HTTP
+- **Auth:** none (anonymous) — or a Bearer token (below)
+
+## Optional: API token for monitored domains
+
+Anonymous access covers scanning and fixes. A per-account API token unlocks the
+`dnsdoctor://domains` resource (your continuously-monitored domains and their
+latest per-check statuses).
+
+1. Sign in at <https://dnsdoctor.dev> → **Settings → API tokens** → create a token.
+   The plaintext (`dnsd_…`) is shown once; copy it.
+2. Add the `Authorization` header to the server in `.mcp.json`:
+
+   ```json
+   {
+     "mcpServers": {
+       "dns-doctor": {
+         "type": "http",
+         "url": "https://dnsdoctor.dev/mcp",
+         "headers": { "Authorization": "Bearer ${DNSDOCTOR_API_TOKEN}" }
+       }
+     }
+   }
+   ```
+
+   Then export `DNSDOCTOR_API_TOKEN=dnsd_YOUR_TOKEN` in your environment. Never
+   commit the token.
+
+### Transport
+
+Two supported public transports, same 11 tools:
+
+- **Hosted streamable HTTP** — `https://dnsdoctor.dev/mcp`, wired in this
+  plugin's `.mcp.json`. No install, no keys.
+- **Local stdio** — `npx -y @dnsdoctor/mcp`. A thin server that runs on your
+  machine and calls the public DNS Doctor REST API; it holds no diagnosis logic
+  of its own and relays every record string verbatim.
+
+```json
+{
+  "mcpServers": {
+    "dns-doctor": {
+      "command": "npx",
+      "args": ["-y", "@dnsdoctor/mcp"],
+      "env": { "DNSDOCTOR_API_TOKEN": "dnsd_YOUR_TOKEN" }
+    }
+  }
+}
+```
+
+`DNSDOCTOR_API_TOKEN` is optional (anonymous access covers scanning and fixes).
+`DNSDOCTOR_API_BASE` overrides the origin — it must be an origin that serves the
+`/api/…` paths, i.e. the public site rather than a bare backend port.
+
+### Build the stdio server from source
+
+```bash
+npm ci
+npm test
+npm run build      # -> dist/index.js, the package's bin entrypoint
+```
+
+`tools.json` and `instructions.txt` are **generated from the hosted server** and
+pinned by a backend test — never hand-edit them, and never add a tool
+description to `src/`. Both files ship in the npm tarball; without them the
+client has no tools and none of its safety guidance.
+
+## Worked example
+
+> **You:** Our invoices keep landing in customers' spam. Domain is `example.com`.
+>
+> **Claude** (`scan_domain` → `example.com`): DMARC is at `p=none`, so nothing
+> enforces alignment — receivers can't tell your mail from a spoof. SPF passes with
+> 7 of 10 lookups used. DKIM: a selector was found and is valid. Not blacklisted.
+> Domain expires in 240 days.
+>
+> **Claude** (`build_dmarc_upgrade` → `example.com`): SPF is aligned and DKIM is
+> present, so enforcement to `p=reject` is safe. Publish this exact TXT record at
+> `_dmarc.example.com` — **paste it verbatim, don't edit it**:
+>
+> ```
+> v=DMARC1; p=reject; rua=mailto:dmarc@example.com; adkim=r; aspf=r
+> ```
+>
+> Apply it in your DNS host once you've confirmed it's approved, then ask me to
+> re-scan to verify. Want the domain watched continuously with aggregate-report
+> alerts? I can send a setup link to your email.
+
+## Learn more
+
+- **Methodology** (how the verdicts are computed): <https://dnsdoctor.dev/methodology>
+- **REST API / OpenAPI schema:** <https://dnsdoctor.dev/api/v1/openapi.json>
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/api.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The ONE HTTP layer of the thin client.
+ *
+ * Every tool handler goes through here, and nothing else in `src/` may hold a
+ * base URL or invent an error message. Two rules are load-bearing:
+ *
+ * 1. **Relay, never compose.** Response bodies are returned untouched — the
+ *    records and signup URLs in them are authored server-side by the fixengine
+ *    and are the product's trust moat. This file never edits a payload.
+ * 2. **A transport failure is never a verdict.** 429/5xx/network faults map to
+ *    explicitly transient errors that tell the agent to retry rather than
+ *    report a diagnosis, mirroring the backend's `temperror` discipline.
+ *
+ * A 422 relays the API's `detail` **verbatim** — those strings are a wire
+ * contract shared with the hosted MCP server; rewording them here would let the
+ * two surfaces disagree about the same malformed input.
+ */
+export declare const DEFAULT_API_BASE = "https://dnsdoctor.dev";
+/** Shared tail of every transient message — one string, so all of them agree. */
+export declare const TRANSIENT_SUFFIX = "retry; never report this as a verdict";
+export declare const RATE_LIMITED_MESSAGE = "rate limited \u2014 slow down and retry";
+/** Error raised for any non-2xx response or transport fault. */
+export declare class ApiError extends Error {
+    readonly status: number | null;
+    readonly transient: boolean;
+    constructor(message: string, status: number | null, transient: boolean);
+}
+/** Base URL for the DNS Doctor API; `DNSDOCTOR_API_BASE` overrides for local runs. */
+export declare function apiBase(): string;
+/** This package's version — also what the server reports in `initialize`. */
+export declare function packageVersion(): string;
+/**
+ * The UA every call carries — this client's only attribution.
+ *
+ * `api/agents.py::agent_family` is an ALLOWLIST: an unrecognized UA is not
+ * counted at all, so without this marker the npm channel would be invisible in
+ * `dnsdoctor_agent_requests_total`, which is the number the agent channel's
+ * kill criterion reads. The matching entry lives in that module's `_FAMILIES`.
+ */
+export declare function userAgent(): string;
+/** GET a JSON resource. `path` is API-root-relative and already encoded. */
+export declare function getJson(path: string): Promise<unknown>;
+/** POST a JSON body and return the parsed response, untouched. */
+export declare function postJson(path: string, body: unknown): Promise<unknown>;
+/**
+ * Decode base64, rejecting input Node would silently mangle.
+ *
+ * Not transient: the caller sent bad bytes, so retrying the same call changes
+ * nothing — the agent must re-encode instead of reporting a verdict.
+ */
+export declare function decodeBase64(value: string): Buffer;
+/**
+ * POST one file as `multipart/form-data` — the shape `/api/tools/dmarc-report-parse`
+ * expects. The tool takes the report as base64, so the bytes are decoded here and
+ * uploaded as a file part rather than re-encoded into JSON.
+ */
+export declare function postFile(path: string, field: string, filename: string, contentBase64: string): Promise<unknown>;

package/dist/api.js

@@ -0,0 +1,178 @@
+/**
+ * The ONE HTTP layer of the thin client.
+ *
+ * Every tool handler goes through here, and nothing else in `src/` may hold a
+ * base URL or invent an error message. Two rules are load-bearing:
+ *
+ * 1. **Relay, never compose.** Response bodies are returned untouched — the
+ *    records and signup URLs in them are authored server-side by the fixengine
+ *    and are the product's trust moat. This file never edits a payload.
+ * 2. **A transport failure is never a verdict.** 429/5xx/network faults map to
+ *    explicitly transient errors that tell the agent to retry rather than
+ *    report a diagnosis, mirroring the backend's `temperror` discipline.
+ *
+ * A 422 relays the API's `detail` **verbatim** — those strings are a wire
+ * contract shared with the hosted MCP server; rewording them here would let the
+ * two surfaces disagree about the same malformed input.
+ */
+import { readFileSync } from "node:fs";
+export const DEFAULT_API_BASE = "https://dnsdoctor.dev";
+/** Shared tail of every transient message — one string, so all of them agree. */
+export const TRANSIENT_SUFFIX = "retry; never report this as a verdict";
+export const RATE_LIMITED_MESSAGE = "rate limited — slow down and retry";
+/** Error raised for any non-2xx response or transport fault. */
+export class ApiError extends Error {
+    status;
+    transient;
+    constructor(message, status, transient) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.transient = transient;
+    }
+}
+/** Base URL for the DNS Doctor API; `DNSDOCTOR_API_BASE` overrides for local runs. */
+export function apiBase() {
+    const raw = process.env.DNSDOCTOR_API_BASE?.trim();
+    const base = raw ? raw : DEFAULT_API_BASE;
+    return base.replace(/\/+$/, "");
+}
+/** Optional bearer token — anonymous access works, a token only raises the budget. */
+function authHeaders() {
+    const token = process.env.DNSDOCTOR_API_TOKEN?.trim();
+    return token ? { Authorization: `Bearer ${token}` } : {};
+}
+/** This package's version — also what the server reports in `initialize`. */
+export function packageVersion() {
+    try {
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+        const version = JSON.parse(raw).version;
+        return typeof version === "string" ? version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * The UA every call carries — this client's only attribution.
+ *
+ * `api/agents.py::agent_family` is an ALLOWLIST: an unrecognized UA is not
+ * counted at all, so without this marker the npm channel would be invisible in
+ * `dnsdoctor_agent_requests_total`, which is the number the agent channel's
+ * kill criterion reads. The matching entry lives in that module's `_FAMILIES`.
+ */
+export function userAgent() {
+    return `dnsdoctor-mcp/${packageVersion()} (+https://dnsdoctor.dev)`;
+}
+/** Pull the API's `detail` out of an error body, preserving its exact text. */
+function detailOf(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const detail = body.detail;
+    if (typeof detail === "string")
+        return detail;
+    if (detail === undefined || detail === null)
+        return null;
+    return JSON.stringify(detail);
+}
+async function readBody(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+async function toApiError(response) {
+    const detail = detailOf(await readBody(response));
+    const status = response.status;
+    if (status === 429) {
+        // The constant leads, so the agent always reads the same instruction; the
+        // API's own detail (which domain, which budget) rides along verbatim.
+        const message = detail ? `${RATE_LIMITED_MESSAGE} (${detail})` : RATE_LIMITED_MESSAGE;
+        return new ApiError(message, status, true);
+    }
+    if (status === 503) {
+        return new ApiError(`DNS Doctor could not complete the lookup (transient) — ${TRANSIENT_SUFFIX}`, status, true);
+    }
+    if (status >= 500) {
+        return new ApiError(`DNS Doctor returned a server error (HTTP ${status}) — ${TRANSIENT_SUFFIX}`, status, true);
+    }
+    // 4xx — the API's own `detail` is the answer (422 malformed input, opaque 404,
+    // 413 oversize report). Verbatim, always.
+    return new ApiError(detail ?? `DNS Doctor request failed (HTTP ${status})`, status, false);
+}
+async function send(path, init) {
+    const url = `${apiBase()}${path}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            ...init,
+            headers: {
+                Accept: "application/json",
+                "User-Agent": userAgent(),
+                ...authHeaders(),
+                ...(init.headers ?? {}),
+            },
+        });
+    }
+    catch (error) {
+        const cause = error instanceof Error ? error.message : String(error);
+        throw new ApiError(`Could not reach the DNS Doctor API (${cause}) — ${TRANSIENT_SUFFIX}`, null, true);
+    }
+    if (!response.ok)
+        throw await toApiError(response);
+    const body = await readBody(response);
+    if (body === null) {
+        throw new ApiError(`DNS Doctor returned an unreadable response (HTTP ${response.status}) — ${TRANSIENT_SUFFIX}`, response.status, true);
+    }
+    return body;
+}
+/** GET a JSON resource. `path` is API-root-relative and already encoded. */
+export function getJson(path) {
+    return send(path, { method: "GET" });
+}
+/** POST a JSON body and return the parsed response, untouched. */
+export function postJson(path, body) {
+    return send(path, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
+/**
+ * Decode base64, rejecting input Node would silently mangle.
+ *
+ * Not transient: the caller sent bad bytes, so retrying the same call changes
+ * nothing — the agent must re-encode instead of reporting a verdict.
+ */
+export function decodeBase64(value) {
+    // Whitespace (MIME line breaks) and the base64url alphabet are both accepted
+    // — Node decodes them and so should we; the round-trip below is what rejects
+    // input that is not base64 at all.
+    const compact = value.replace(/\s+/g, "").replace(/-/g, "+").replace(/_/g, "/");
+    const bytes = Buffer.from(compact, "base64");
+    if (bytes.toString("base64").replace(/=+$/, "") !== compact.replace(/=+$/, "")) {
+        throw new ApiError("'content_base64' is not valid base64 — re-encode the report file and try again", null, false);
+    }
+    return bytes;
+}
+/**
+ * POST one file as `multipart/form-data` — the shape `/api/tools/dmarc-report-parse`
+ * expects. The tool takes the report as base64, so the bytes are decoded here and
+ * uploaded as a file part rather than re-encoded into JSON.
+ */
+// `async`, so a decode rejection reaches callers the same way a transport one
+// does — a synchronous throw from a Promise-returning function is a trap.
+export async function postFile(path, field, filename, contentBase64) {
+    // Validated, not try/caught: `Buffer.from(s, "base64")` never throws — it
+    // silently DISCARDS characters outside the alphabet. Uploading those bytes
+    // would earn a 422 "not a DMARC report file", telling the agent its report is
+    // invalid when the real fault is the encoding it sent us.
+    const bytes = decodeBase64(contentBase64);
+    const form = new FormData();
+    form.append(field, new Blob([bytes], { type: "application/octet-stream" }), filename);
+    // No Content-Type header: fetch sets it with the multipart boundary.
+    return send(path, { method: "POST", body: form });
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * `@dnsdoctor/mcp` — a thin stdio MCP server in front of the public DNS Doctor
+ * REST API.
+ *
+ * It holds no diagnosis logic of its own. Every tool is one HTTP call whose
+ * response is relayed **verbatim**: the record strings, signup URLs and verdicts
+ * in those payloads are authored server-side by the fixengine, and rewriting one
+ * here would break the product's central invariant (an LLM — or a client — never
+ * composes an authoritative record). The tool definitions come from `tools.json`
+ * (see `tools.ts`), so the only thing this file decides is which endpoint each
+ * tool calls.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+type ToolArgs = Record<string, unknown>;
+/** Run one tool and return the API's parsed body, untouched. */
+export declare function callTool(name: string, args?: ToolArgs): Promise<unknown>;
+/** Build the MCP server with the fixture's tools and instructions registered. */
+export declare function createServer(): Server;
+/** Every fixture tool has a route — a missing one would 'unknown tool' at runtime. */
+export declare function unroutedTools(): string[];
+export declare function main(): Promise<void>;
+/**
+ * True when this module is the process entrypoint — false when a test imports it.
+ *
+ * Both sides are resolved through `realpathSync` because npm installs `bin`
+ * entries as **symlinks**: launched as `dnsdoctor-mcp` (or via `npx`),
+ * `process.argv[1]` is `node_modules/.bin/dnsdoctor-mcp` while
+ * `import.meta.url` is already the symlink's target, so a raw string compare is
+ * false for every installed user and the server silently never starts. That is
+ * invisible to `node dist/index.js` and shows up only in the `npm pack` smoke.
+ */
+export declare function isEntrypoint(): boolean;
+export {};

package/dist/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * `@dnsdoctor/mcp` — a thin stdio MCP server in front of the public DNS Doctor
+ * REST API.
+ *
+ * It holds no diagnosis logic of its own. Every tool is one HTTP call whose
+ * response is relayed **verbatim**: the record strings, signup URLs and verdicts
+ * in those payloads are authored server-side by the fixengine, and rewriting one
+ * here would break the product's central invariant (an LLM — or a client — never
+ * composes an authoritative record). The tool definitions come from `tools.json`
+ * (see `tools.ts`), so the only thing this file decides is which endpoint each
+ * tool calls.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { ApiError, getJson, packageVersion, postFile, postJson } from "./api.js";
+import { instructions, listTools, toolNames } from "./tools.js";
+const ROUTES = {
+    scan_domain: { kind: "json", path: "/api/v1/scan" },
+    get_report: { kind: "report" },
+    build_dmarc_upgrade: { kind: "json", path: "/api/v1/dmarc-upgrade" },
+    start_monitoring_signup: { kind: "json", path: "/api/v1/signup-url" },
+    count_spf_lookups: { kind: "json", path: "/api/tools/spf-count" },
+    validate_dmarc_record: { kind: "json", path: "/api/tools/dmarc-validate" },
+    generate_dmarc_record: { kind: "json", path: "/api/tools/dmarc-generate" },
+    check_dkim_selector: { kind: "json", path: "/api/tools/dkim-check" },
+    parse_dmarc_report: {
+        kind: "upload",
+        path: "/api/tools/dmarc-report-parse",
+        field: "file",
+    },
+    check_record: { kind: "json", path: "/api/tools/check-record" },
+    check_reverse_dns: { kind: "json", path: "/api/tools/reverse-dns-check" },
+};
+/** Default upload name when the caller supplies none — the API only reads bytes. */
+const DEFAULT_REPORT_FILENAME = "report.xml";
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ApiError(`'${key}' is required and must be a non-empty string`, null, false);
+    }
+    return value;
+}
+/** Run one tool and return the API's parsed body, untouched. */
+export async function callTool(name, args = {}) {
+    const route = ROUTES[name];
+    if (route === undefined) {
+        throw new ApiError(`unknown tool '${name}'`, null, false);
+    }
+    if (route.kind === "report") {
+        const domain = requireString(args, "domain");
+        return getJson(`/api/v1/report/${encodeURIComponent(domain)}`);
+    }
+    if (route.kind === "upload") {
+        const content = requireString(args, "content_base64");
+        const filename = args["filename"];
+        return postFile(route.path, route.field, typeof filename === "string" && filename.trim() !== "" ? filename : DEFAULT_REPORT_FILENAME, content);
+    }
+    return postJson(route.path, args);
+}
+function okResult(body) {
+    return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+}
+function errorResult(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/** Build the MCP server with the fixture's tools and instructions registered. */
+export function createServer() {
+    const server = new Server({ name: "dns-doctor", version: packageVersion() }, 
+    // `instructions` is the hosted server's own preamble, shipped in the pinned
+    // fixture: without it a host other than Claude Code (which reads the bundled
+    // SKILL.md) gets the tools with none of the safety contract around them.
+    { capabilities: { tools: {} }, instructions: instructions() });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listTools() }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            return okResult(await callTool(name, args ?? {}));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    return server;
+}
+/** Every fixture tool has a route — a missing one would 'unknown tool' at runtime. */
+export function unroutedTools() {
+    return toolNames().filter((name) => ROUTES[name] === undefined);
+}
+export async function main() {
+    await createServer().connect(new StdioServerTransport());
+}
+/**
+ * True when this module is the process entrypoint — false when a test imports it.
+ *
+ * Both sides are resolved through `realpathSync` because npm installs `bin`
+ * entries as **symlinks**: launched as `dnsdoctor-mcp` (or via `npx`),
+ * `process.argv[1]` is `node_modules/.bin/dnsdoctor-mcp` while
+ * `import.meta.url` is already the symlink's target, so a raw string compare is
+ * false for every installed user and the server silently never starts. That is
+ * invisible to `node dist/index.js` and shows up only in the `npm pack` smoke.
+ */
+export function isEntrypoint() {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined)
+        return false;
+    const resolve = (path) => {
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return path;
+        }
+    };
+    return resolve(argv1) === resolve(fileURLToPath(import.meta.url));
+}
+if (isEntrypoint()) {
+    main().catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The tool definitions and the `initialize` preamble — read from the fixtures,
+ * never authored here.
+ *
+ * `tools.json` and `instructions.txt` are generated from the hosted server's own
+ * `list_tools()` and instructions, and pinned byte-for-byte by
+ * `backend/tests/mcp_server/test_tools_fixture.py`. That is the whole point: a
+ * name, description, schema or instruction sentence edited on the server fails a
+ * backend test until the fixtures are regenerated, so this client cannot drift
+ * from the surface it claims to mirror. Consequently **no description string,
+ * schema, tool name or guidance sentence is written in `src/`** — everything
+ * comes from the files.
+ */
+/** One entry of `tools.json`; the shape the MCP `tools/list` result expects. */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+}
+/** Every tool the hosted server exposes, in the fixture's own (sorted) order. */
+export declare function listTools(): ToolDefinition[];
+/** The tool names, for the dispatch table's coverage check. */
+export declare function toolNames(): string[];
+export declare function instructions(): string;

package/dist/tools.js

@@ -0,0 +1,52 @@
+/**
+ * The tool definitions and the `initialize` preamble — read from the fixtures,
+ * never authored here.
+ *
+ * `tools.json` and `instructions.txt` are generated from the hosted server's own
+ * `list_tools()` and instructions, and pinned byte-for-byte by
+ * `backend/tests/mcp_server/test_tools_fixture.py`. That is the whole point: a
+ * name, description, schema or instruction sentence edited on the server fails a
+ * backend test until the fixtures are regenerated, so this client cannot drift
+ * from the surface it claims to mirror. Consequently **no description string,
+ * schema, tool name or guidance sentence is written in `src/`** — everything
+ * comes from the files.
+ */
+import { readFileSync } from "node:fs";
+/**
+ * `tools.json` sits at the package root — one level up from both `src/` (tests,
+ * run from source) and `dist/` (the published `bin`), so the same relative URL
+ * resolves in either. It ships in `package.json#files`; without it the client
+ * has no tools at all, which is why a missing file throws rather than degrading
+ * to an empty list.
+ */
+const FIXTURE_URL = new URL("../tools.json", import.meta.url);
+function readFixture() {
+    const parsed = JSON.parse(readFileSync(FIXTURE_URL, "utf8"));
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error("tools.json is not a non-empty array of tool definitions");
+    }
+    return parsed;
+}
+const TOOLS = readFixture();
+/** Every tool the hosted server exposes, in the fixture's own (sorted) order. */
+export function listTools() {
+    return TOOLS;
+}
+/** The tool names, for the dispatch table's coverage check. */
+export function toolNames() {
+    return TOOLS.map((tool) => tool.name);
+}
+/**
+ * The in-band guidance the hosted server sends in `initialize`, shipped verbatim.
+ *
+ * Claude Code users read the same rules from the bundled SKILL.md; every OTHER
+ * host running `npx -y @dnsdoctor/mcp` reads them only here. Dropping them would
+ * leave an agent with no `temperror`-is-not-a-failure rule, no
+ * `not_registered`-is-not-health rule, no records-verbatim rule and no
+ * SPF-is-diagnose-only rule — the product's safety contract, not decoration.
+ */
+const INSTRUCTIONS = readFileSync(new URL("../instructions.txt", import.meta.url), "utf8").trim();
+export function instructions() {
+    return INSTRUCTIONS;
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAUvC;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE9D,SAAS,WAAW;IAClB,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IACtE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,MAA0B,CAAC;AACpC,CAAC;AAED,MAAM,KAAK,GAAqB,WAAW,EAAE,CAAC;AAE9C,iFAAiF;AACjF,MAAM,UAAU,SAAS;IACvB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,SAAS;IACvB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,YAAY,GAAW,YAAY,CACvC,IAAI,GAAG,CAAC,qBAAqB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAC/C,MAAM,CACP,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/instructions.txt

@@ -0,0 +1 @@
+DNS Doctor scans a domain's email-authentication posture (SPF, DMARC, DKIM, MX, DNS, blacklist, expiry) and returns deterministic verdicts plus copy-paste fix records generated by a validating engine — never a guessed record. Workflow: call scan_domain (or get_report), read the verdicts failing-first (a 'temperror' status is transient, NOT a failure), then call build_dmarc_upgrade for a DMARC enforcement record. ONE EXCEPTION TO READING FAILING-FIRST: when a report carries not_registered: true the domain has no DNS records at all, so no check ran and every status is an 'info' placeholder — zero failing checks there does NOT mean the domain is healthy. Report that the domain does not resolve (usually a typo), propose no records for it, and do not offer monitoring until it resolves. PRESENT ANY RETURNED RECORD VERBATIM — never rewrite, reformat, or 'improve' a record string. build_dmarc_upgrade may return record: null (the domain does not exist; the DMARC lookup itself hit NXDOMAIN while the existence probe did not resolve; the DMARC lookup temp-failed; or the domain already applies a policy at least as strong as the one this scan justifies) — relay its 'rationale' as the answer and NEVER compose a record yourself to fill the gap. 'policy' describes the returned record and is null whenever record is; the domain's observed policy is in 'current_policy'. A human must approve every DNS change; nothing is applied automatically. SPF is diagnose-only: relay the report's SPF findings, but never propose SPF record edits of your own (e.g. tightening ~all to -all) — an SPF change can silently de-authorize a real sender, which is why the engine emits no SPF fix record. Scan responses end with a next_steps block: relay it — safe DMARC enforcement needs ~30 days of aggregate-report (RUA) evidence that no chat session can watch, so when a domain lacks reporting, call start_monitoring_signup and give the human the signup_url it returns. That tool sends no email and creates nothing: the human opens the link, signs in themselves, and adds the domain themselves. Never ask a human for their email address to pass to us, and never invent one — hand over the link and let them sign in on our page. Also share the report_url and monitor_url links from next_steps.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dnsdoctor/mcp",
+  "version": "1.2.0",
+  "description": "Thin stdio MCP server for DNS Doctor — diagnoses SPF, DMARC, DKIM, MX, DNS, blacklist and expiry over the public DNS Doctor REST API.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "DNS Doctor",
+    "url": "https://dnsdoctor.dev"
+  },
+  "homepage": "https://dnsdoctor.dev/methodology",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dnsdoctor/claude-plugin.git"
+  },
+  "keywords": [
+    "mcp",
+    "dns",
+    "email",
+    "spf",
+    "dmarc",
+    "dkim",
+    "deliverability"
+  ],
+  "type": "module",
+  "bin": {
+    "dnsdoctor-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "tools.json",
+    "instructions.txt"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/tools.json

@@ -0,0 +1,354 @@
+[
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true,
+      "readOnlyHint": false
+    },
+    "description": "Return a validated DMARC enforcement-upgrade record for a domain. The alignment gate (whether p=reject is safe) is derived server-side from a scan \u2014 a caller can never assert alignment. `record` is null when there is no honest upgrade to offer (the domain does not exist; the DMARC lookup itself hit NXDOMAIN while the existence probe did not resolve; the DMARC lookup temp-failed; or the domain already applies a policy at least as strong as this scan justifies): relay `rationale` and never compose a record to fill the gap. Present a returned record verbatim; a human must approve before publishing.",
+    "inputSchema": {
+      "properties": {
+        "domain": {
+          "title": "Domain",
+          "type": "string"
+        }
+      },
+      "required": [
+        "domain"
+      ],
+      "title": "build_dmarc_upgradeArguments",
+      "type": "object"
+    },
+    "name": "build_dmarc_upgrade"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true,
+      "readOnlyHint": true
+    },
+    "description": "Check ONE specific DKIM selector on a domain \u2014 the exact selector the sending platform uses (e.g. `google`, `s1`), which a full scan's common-selector sweep may miss. Returns the verdict, its explanation, and the published key record when one resolves. No fix record is returned: a DKIM key is generated by the sending platform, so the fix is always to publish what that platform gives the owner.",
+    "inputSchema": {
+      "properties": {
+        "domain": {
+          "title": "Domain",
+          "type": "string"
+        },
+        "selector": {
+          "title": "Selector",
+          "type": "string"
+        }
+      },
+      "required": [
+        "domain",
+        "selector"
+      ],
+      "title": "check_dkim_selectorArguments",
+      "type": "object"
+    },
+    "name": "check_dkim_selector"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true,
+      "readOnlyHint": true
+    },
+    "description": "Check whether a DNS change has landed: reads the record from the domain's OWN nameservers (cache-free) and from two public caching resolvers, and reports whether they agree. `kind` is one of spf|dmarc|txt|mx|cname|a|aaaa \u2014 pass the kind, not a query name: `dmarc` reads TXT at _dmarc.<domain> and `spf` reads apex TXT, each filtered to the matching record. `host` prepends a label (txt, cname, a and aaaa only). Empty values mean the record is genuinely absent. When in_sync is false, max_wait_seconds is the largest remaining cached TTL \u2014 the wait before those resolvers refresh. This samples two resolvers, so never describe it as worldwide or as propagation coverage.",
+    "inputSchema": {
+      "properties": {
+        "domain": {
+          "title": "Domain",
+          "type": "string"
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Host"
+        },
+        "kind": {
+          "enum": [
+            "spf",
+            "dmarc",
+            "txt",
+            "mx",
+            "cname",
+            "a",
+            "aaaa"
+          ],
+          "title": "Kind",
+          "type": "string"
+        }
+      },
+      "required": [
+        "domain",
+        "kind"
+      ],
+      "title": "check_recordArguments",
+      "type": "object"
+    },
+    "name": "check_record"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true,
+      "readOnlyHint": true
+    },
+    "description": "Check one sending IP's forward-confirmed reverse DNS (FCrDNS): reads the IP's PTR record, then resolves that hostname back and reports whether it returns to the same IP. `verdict` is confirmed (the pair agrees \u2014 what receivers want to see), ptr_missing (the IP publishes no reverse record), or mismatch (a PTR that does not resolve back). A PTR on its own proves nothing, because the IP's operator writes its own reverse zone \u2014 only the forward confirmation is evidence, so never report a bare PTR as verified. The fix is always made by whoever controls the IP (the hosting or mail provider), never in the sending domain's own DNS. Pass a public IPv4 or IPv6 address.",
+    "inputSchema": {
+      "properties": {
+        "ip": {
+          "title": "Ip",
+          "type": "string"
+        }
+      },
+      "required": [
+        "ip"
+      ],
+      "title": "check_reverse_dnsArguments",
+      "type": "object"
+    },
+    "name": "check_reverse_dns"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true,
+      "readOnlyHint": true
+    },
+    "description": "Validate an SPF record and count what it costs. Returns `record_valid` (the record parses as RFC 7208 SPF), `findings` (per-term diagnostics), `has_pass_all` (a `+all` that authorizes the whole internet to send as this domain), `multiple_all` (more than one `all`, which makes everything after the first unreachable), the parsed `terms`, and the lookup count against the limit of 10 with `over_limit`/`near_limit` and the `offending_mechanisms` that push it over. Pass EXACTLY ONE of `domain` (resolves the published record and counts recursively through nested includes) or `record` (parses a pasted record, its own terms only). This is the SPF validator \u2014 there is no separate one. Diagnose-only: no SPF fix record is ever returned, because removing a mechanism can silently de-authorize a real sender \u2014 relay the findings and let the domain's owner decide what to drop.",
+    "inputSchema": {
+      "properties": {
+        "domain": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Domain"
+        },
+        "record": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Record"
+        }
+      },
+      "title": "count_spf_lookupsArguments",
+      "type": "object"
+    },
+    "name": "count_spf_lookups"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false,
+      "readOnlyHint": true
+    },
+    "description": "Build a DMARC record from scratch for a domain that has none, using a validating engine \u2014 never compose one yourself. `policy` is none|quarantine|reject; optional `rua_email` (aggregate-report destination), `subdomain_policy`, and `strict_alignment`. The generated record is re-validated before it is returned. Present it verbatim; a human must approve before publishing.",
+    "inputSchema": {
+      "properties": {
+        "policy": {
+          "enum": [
+            "none",
+            "quarantine",
+            "reject"
+          ],
+          "title": "Policy",
+          "type": "string"
+        },
+        "rua_email": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Rua Email"
+        },
+        "strict_alignment": {
+          "default": false,
+          "title": "Strict Alignment",
+          "type": "boolean"
+        },
+        "subdomain_policy": {
+          "anyOf": [
+            {
+              "enum": [
+                "none",
+                "quarantine",
+                "reject"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Subdomain Policy"
+        }
+      },
+      "required": [
+        "policy"
+      ],
+      "title": "generate_dmarc_recordArguments",
+      "type": "object"
+    },
+    "name": "generate_dmarc_record"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true,
+      "readOnlyHint": false
+    },
+    "description": "Return the stored report for a domain, scanning once only if none exists yet \u2014 the cheap read, and the right default for a first look. Returns the same seven-check report as scan_domain (SPF, DKIM, DMARC, MX, DNS hardening, domain/TLS expiry, blacklist; each with a status, the observed record and any fixengine fix_record), including `scanned_at` so you can judge staleness yourself. Prefer scan_domain when you specifically need state re-read right now \u2014 for example after a DNS change.",
+    "inputSchema": {
+      "properties": {
+        "domain": {
+          "title": "Domain",
+          "type": "string"
+        }
+      },
+      "required": [
+        "domain"
+      ],
+      "title": "get_reportArguments",
+      "type": "object"
+    },
+    "name": "get_report"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false,
+      "readOnlyHint": true
+    },
+    "description": "Parse ONE DMARC aggregate (RUA) report into readable per-source aggregates: who sent mail as the domain, how much, and what share was SPF/DKIM aligned. Pass the file's bytes base64-encoded in `content_base64` (XML, .gz or .zip; up to 2 MiB decoded) with an optional `filename`. Nothing is stored \u2014 the report is parsed and discarded.",
+    "inputSchema": {
+      "properties": {
+        "content_base64": {
+          "title": "Content Base64",
+          "type": "string"
+        },
+        "filename": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Filename"
+        }
+      },
+      "required": [
+        "content_base64"
+      ],
+      "title": "parse_dmarc_reportArguments",
+      "type": "object"
+    },
+    "name": "parse_dmarc_report"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true,
+      "readOnlyHint": false
+    },
+    "description": "Force a fresh scan of a domain and return its full report: seven deterministic checks \u2014 SPF, DKIM, DMARC, MX, DNS hardening, domain/TLS expiry and blacklist listing \u2014 each with a status (pass/warn/fail/info/temperror), the observed record, and a fixengine-generated fix_record where one exists. Explanations are cache-first. A repeat scan of the same domain within a minute reuses the stored report. Use this when you need current state; use get_report when a recent cached answer will do.",
+    "inputSchema": {
+      "properties": {
+        "domain": {
+          "title": "Domain",
+          "type": "string"
+        }
+      },
+      "required": [
+        "domain"
+      ],
+      "title": "scan_domainArguments",
+      "type": "object"
+    },
+    "name": "scan_domain"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false,
+      "readOnlyHint": true
+    },
+    "description": "Return a sign-up link to give to the HUMAN who owns a domain, so they can start monitoring it themselves. Nothing is created and no email is sent by this call: the returned signup_url opens a page that explains monitoring and asks them to sign in with their own email address; the domain is carried over to their dashboard, already filled in, only after that, and monitoring itself starts once they prove ownership with a TXT record. Hand them the URL and relay `message` \u2014 never sign in on their behalf.",
+    "inputSchema": {
+      "properties": {
+        "domain": {
+          "title": "Domain",
+          "type": "string"
+        }
+      },
+      "required": [
+        "domain"
+      ],
+      "title": "start_monitoring_signupArguments",
+      "type": "object"
+    },
+    "name": "start_monitoring_signup"
+  },
+  {
+    "annotations": {
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false,
+      "readOnlyHint": true
+    },
+    "description": "Validate a pasted DMARC record: parsed tags, level'd findings, and whether it is valid. No DNS lookup \u2014 pass the record string itself. `upgrade_record` previews a stronger policy and is capped at p=quarantine: a pasted record carries no alignment evidence, so p=reject needs a full scan (use build_dmarc_upgrade). Present any returned record verbatim.",
+    "inputSchema": {
+      "properties": {
+        "record": {
+          "title": "Record",
+          "type": "string"
+        }
+      },
+      "required": [
+        "record"
+      ],
+      "title": "validate_dmarc_recordArguments",
+      "type": "object"
+    },
+    "name": "validate_dmarc_record"
+  }
+]