drupal-mcp-connector 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-06-29
+
+### Added
+- **Audit command suite — 22 new read-only audit tools across four groups**, expanding
+  the connector from content reporting into link/404 integrity and configuration
+  posture. All follow the existing `drupal_report_*` / `drupal_audit_*` convention
+  (auto-classified read-only), degrade with a `gatedReport`/`gated` payload when a
+  required source is absent, and flag `approximate`/`truncated` when sampling-bounded.
+  - **Links & 404 integrity** (`reports-links.js`): `drupal_report_404_log`,
+    `drupal_report_redirect_health`, `drupal_report_broken_links`,
+    `drupal_report_alias_coverage`, `drupal_report_menu_integrity`,
+    `drupal_report_broken_embeds`.
+  - **Config & site-health** (`reports-config.js`): `drupal_report_config_drift`,
+    `drupal_audit_config_best_practices`, `drupal_report_module_audit`,
+    `drupal_report_permission_audit`, `drupal_report_status_report`,
+    `drupal_report_text_format_audit`, `drupal_report_cache_config`.
+  - **Content quality & governance** (`reports-content.js`):
+    `drupal_report_duplicate_content`, `drupal_report_workflow_bottlenecks`,
+    `drupal_report_translation_coverage`, `drupal_report_scheduled_content`,
+    `drupal_report_readability`, `drupal_report_orphan_pages`,
+    `drupal_report_pii_exposure`, `drupal_report_seo_meta_coverage`.
+  - **Composite** (`audit-composite.js`): `drupal_audit_site_health` — a scored
+    dashboard that runs a configurable battery of the above and rolls them into one
+    letter grade, with each section degrading independently.
+- **`drupal-full-audit` MCP prompt** — walks a client through running the composite
+  audit and turning the dashboard into a prioritized action plan.
+- **Opt-in live link checking.** `drupal_report_broken_links` performs no network
+  egress by default; with `checkLive: true` it verifies links via a bounded,
+  SSRF-guarded checker (`src/lib/link-checker.js`) that refuses
+  loopback/private/link-local/metadata addresses, requires a host allowlist for
+  external hosts, and caps concurrency, timeout, and link count. Configurable per site
+  via an optional `audit` block (`linkCheckAllowedHosts`, `linkCheckConcurrency`,
+  `linkCheckTimeoutMs`, `linkCheckMaxLinks`).
+- **Self-sufficient privileged audits.** Log/config/module/permission/requirements
+  audits read their data through the connector's own **drush bridge** (`watchdog:show`,
+  `config:status`/`config:get`, `pm:list`/`pm:security`, `role:list`,
+  `core:requirements`, and a read-only `sql:query` to enumerate `filter.format.*`), so
+  they work against stock Drupal with **no companion module required**. The
+  config-inspection audits additionally prefer the existing governed config server-tool
+  when a site has `serverTools` configured. Each returns a `gated`/`unavailable` payload
+  (never throws) when no source is configured.
+
+### Changed
+- `sshDrush` and `parseDrush` are now exported from `src/tools/drush.js`, and a
+  `toolResultData` helper is exported from `src/lib/server-tools.js`, so the audit tool
+  groups can reuse the hardened drush bridge and the existing governed config transport.
+
+### Security
+- The drush bridge no longer logs secret-bearing flag values (`--password`/`--token`/
+  `--secret`/`--api-key`) in clear text — they are redacted to `***` in the operational
+  stderr log line (`redactSecretArgs`). Clears a `js/clear-text-logging` finding.
+
 ## [1.5.1] - 2026-06-29
 
 ### Fixed

package/README.md

@@ -51,7 +51,7 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 
 ## Features
 
-### 93 Tools Across 21 Modules
+### 119 Tools Across 26 Modules
 
 | Module | Tools |
 |--------|-------|
@@ -76,6 +76,10 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 | **Redirects** | Create active URL redirects (301/302) + update/repoint existing redirects (Redirect module) |
 | **Search** | Best-effort content search (title match; Search API/Solr-ready) |
 | **Reports (extra)** | Orphaned references, unpublished content, missing-field audits |
+| **Reports — Links & 404** | 404-log → redirect candidates, redirect-table health (chains/loops/duplicates), body-link inventory with opt-in live checking, URL-alias coverage, menu-link integrity, embedded-entity scan |
+| **Reports — Config & Health** | Config drift, best-practice/security config linter, module audit (dev/debug + security updates), permission audit, Drupal status report, text-format safety, cache posture |
+| **Reports — Content Quality** | Duplicate content, workflow bottlenecks, translation coverage, scheduled content, readability (Flesch), orphan pages, PII exposure (masked), structured-meta SEO coverage |
+| **Audit (composite)** | `drupal_audit_site_health` — scored content/links/config dashboard with a roll-up grade |
 | **Config & Governance** | Governed config get/list/set via the server-tool bridge; `drupal_mcp_whoami` tier/capability report |
 
 **Preview writes with `dryRun`.** The node and entity create/update/delete tools accept an optional `dryRun: true` flag that validates the request and returns a preview of exactly what would be written — without committing anything to Drupal.
@@ -89,6 +93,7 @@ Browsable, always-fresh context the client can read without calling a tool:
 ### MCP Prompts
 Workflow templates usable as slash-commands from any MCP client:
 - `drupal-content-audit` — walk through a full site content audit
+- `drupal-full-audit` — run the composite content/links/config audit and turn the scored dashboard into a prioritized action plan
 - `drupal-create-article` — guided article creation with all fields
 - `drupal-seo-fix` — find and fix SEO gaps
 - `drupal-user-cleanup` — identify and handle inactive accounts
@@ -189,7 +194,7 @@ Governance keys off the authenticated account's role and OAuth scopes — not re
 | [OAuth client_credentials](docs/oauth-client-credentials.md) | Production OAuth deploy: scope→role mapping, JSON:API writes, config persistence, secret handling, troubleshooting |
 | [Architecture](docs/architecture.md) | Backend abstraction, canonical model, and how to extend it |
 | [GraphQL Setup](docs/graphql-local-setup.md) | GraphQL Compose backend + local TLS notes |
-| [Tools Reference](docs/tools-reference.md) | Full reference for all 93 tools |
+| [Tools Reference](docs/tools-reference.md) | Full reference for all 119 tools |
 | [Security Guide](docs/security.md) | Presets, entity access control, field redaction |
 | [Security Hardening](docs/security-hardening.md) | Optional transport, identity, and secrets controls |
 | [Threat Model](docs/threat-model.md) | Trust boundaries, threats & mitigations, residual risks, and the security-pass results |

package/config/config.example.json

@@ -78,6 +78,13 @@
         "port":            22,
         "allowedCommands": ["config:export", "config:status"]
       },
+      "audit": {
+        "_comment": "Optional. Controls drupal_report_broken_links live checking (off unless checkLive:true is passed). linkCheckAllowedHosts gates external hosts; same-origin links are always allowed when checking live.",
+        "linkCheckAllowedHosts": ["www.drupal.org", "wilkesliberty.com"],
+        "linkCheckConcurrency":  5,
+        "linkCheckTimeoutMs":    5000,
+        "linkCheckMaxLinks":     200
+      },
       "security": { "preset": "config-editor" }
     },
 
@@ -108,7 +115,11 @@
   },
 
   "_server_tools": {
-    "_comment": "serverTools.url is the JSON-RPC endpoint of the Drupal-side governed MCP tools (mcp_server_tool_bridge / mcp_sentinel), resolved against baseUrl. Required for drupal_config_get/list/set. Authenticated with the same OAuth bearer."
+    "_comment": "serverTools.url is the JSON-RPC endpoint of the Drupal-side governed MCP tools (mcp_server_tool_bridge / mcp_sentinel), resolved against baseUrl. Required for drupal_config_get/list/set. The config-inspection audits will also use it (governed path) when present, but fall back to the drush bridge, so it is optional for the audits. Authenticated with the same OAuth bearer."
+  },
+
+  "_audit_tools": {
+    "_comment": "The audit tool groups (drupal_report_* links/config/content, drupal_audit_site_health) are read-only. Privileged audits (404 log, config drift/best-practices, module/permission/status) are self-sufficient via the connector's own drush bridge (drushSsh) — no companion module required; the config-inspection audits additionally prefer the governed config server-tool when serverTools is configured. They report 'unavailable' when no source is configured for the site. drupal_report_broken_links does no outbound HTTP unless called with checkLive:true; see each site's optional 'audit' block for live-check limits."
   },
 
   "_mcp_client_registration": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -68,6 +68,10 @@ import * as structure    from "./tools/structure.js";
 import * as redirects    from "./tools/redirects.js";
 import * as search       from "./tools/search.js";
 import * as reportsExtra from "./tools/reports-extra.js";
+import * as reportsLinks   from "./tools/reports-links.js";
+import * as reportsConfig  from "./tools/reports-config.js";
+import * as reportsContent from "./tools/reports-content.js";
+import * as auditComposite from "./tools/audit-composite.js";
 import * as config       from "./tools/config.js";
 
 // ---------------------------------------------------------------------------
@@ -75,7 +79,8 @@ import * as config       from "./tools/config.js";
 // ---------------------------------------------------------------------------
 
 const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
-  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra, config];
+  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra,
+  reportsLinks, reportsConfig, reportsContent, auditComposite, config];
 
 // Flatten every module's tool definitions into one ListTools payload, and merge
 // their handler maps into a single closed dispatch table keyed by tool name.
@@ -247,6 +252,14 @@ const PROMPTS = [
     description: "Identify inactive, never-logged-in, or overly permissioned user accounts and take action.",
     arguments:   [{ name: "site", description: "Target site", required: false }],
   },
+  {
+    name:        "drupal-full-audit",
+    description: "Run a full site-health audit — content, link/404 integrity, and configuration posture — and turn the scored dashboard into a prioritized action plan.",
+    arguments:   [
+      { name: "site", description: "Named site to audit (omit for default)", required: false },
+      { name: "type", description: "Primary content type to audit",          required: false },
+    ],
+  },
 ];
 
 /**
@@ -310,6 +323,19 @@ function getPromptMessages(name, args) {
         "6. Ask for approval before making any changes."
       }},
     ],
+    "drupal-full-audit": [
+      { role: "user", content: { type: "text", text:
+        `Please run a full site-health audit ${site} and turn it into a prioritized action plan.\n\n` +
+        `1. Call drupal_audit_site_health (type: "${type}") for the scored dashboard and overall grade.\n` +
+        "2. For any section reporting high-severity findings, drill in with the matching tool for detail:\n" +
+        "   - links/404: drupal_report_404_log, drupal_report_redirect_health, drupal_report_broken_links (checkLive only with approval).\n" +
+        "   - config: drupal_audit_config_best_practices, drupal_report_module_audit, drupal_report_permission_audit.\n" +
+        "   - content: drupal_report_pii_exposure, drupal_report_duplicate_content, drupal_report_readability.\n" +
+        "3. For sections reported 'unavailable', note what (server-tool bridge or drush) would enable them — do not treat unavailable as 'passing'.\n" +
+        "4. Synthesize a prioritized plan: (a) high-severity/security fixes first, (b) content-quality improvements, (c) process recommendations.\n" +
+        "5. Present counts, severity, and specific node/config references; propose redirects for the top 404s. Ask before making any changes."
+      }},
+    ],
   };
 
   return new Map(Object.entries(prompts)).get(name) ?? [{ role: "user", content: { type: "text", text: `Run the ${name} workflow ${site}.` } }];

package/src/lib/audit-sources.js

@@ -0,0 +1,66 @@
+/**
+ * Privileged-source resolution for the audit tool groups.
+ *
+ * Single responsibility: run an audit that needs privileged log/config/module
+ * data through the best available source, in priority order — an optional
+ * governed server-tool first (when a callback is supplied), the connector's own
+ * drush SSH bridge otherwise — and report a clean "unavailable" outcome (never
+ * throw) when no source is configured or all fail. The drush bridge makes the
+ * audits self-sufficient against stock Drupal; no companion module is required.
+ */
+
+/**
+ * Whether the governed server-tool bridge is configured for a site.
+ * @param {object} site Resolved site config.
+ * @returns {boolean}
+ */
+export function serverToolsConfigured(site) {
+  return Boolean(site?.serverTools?.url);
+}
+
+/**
+ * Whether the drush SSH bridge is configured for a site.
+ * @param {object} site Resolved site config.
+ * @returns {boolean}
+ */
+export function drushConfigured(site) {
+  return Boolean(site?.drushSsh);
+}
+
+/**
+ * Run a privileged audit through the first source that succeeds.
+ *
+ * Tries the optional governed server-tool (when a `serverTool` callback is given
+ * and `serverTools` is configured), then the connector's own drush bridge (when a
+ * `drush` callback is given and `drushSsh` is configured). Either callback may be
+ * omitted when that source can't serve the audit. Failures are accumulated, not
+ * thrown, so the caller can surface them in a gated payload.
+ *
+ * @param {object} site Resolved site config.
+ * @param {object} sources
+ * @param {(() => Promise<*>)} [sources.serverTool] Server-tool attempt.
+ * @param {(() => Promise<*>)} [sources.drush] Drush attempt.
+ * @returns {Promise<{source: ("server-tool"|"drush"|null), data?: *, attempts: string[]}>}
+ *   On success, `source` names the winning path and `data` is its result. On
+ *   failure, `source` is null and `attempts` explains why each path was skipped
+ *   or failed.
+ */
+export async function runPrivileged(site, { serverTool, drush } = {}) {
+  const attempts = [];
+
+  if (serverTool && serverToolsConfigured(site)) {
+    try { return { source: "server-tool", data: await serverTool(), attempts }; }
+    catch (err) { attempts.push(`server-tool: ${err?.message || err}`); }
+  } else if (serverTool) {
+    attempts.push("server-tool: serverTools.url not configured for this site");
+  }
+
+  if (drush && drushConfigured(site)) {
+    try { return { source: "drush", data: await drush(), attempts }; }
+    catch (err) { attempts.push(`drush: ${err?.message || err}`); }
+  } else if (drush) {
+    attempts.push("drush: drushSsh not configured for this site");
+  }
+
+  return { source: null, attempts };
+}

package/src/lib/audit-support.js

@@ -0,0 +1,170 @@
+/**
+ * Shared helpers for the audit tool groups — HTML link/embed extraction and
+ * link classification, backend-neutral.
+ *
+ * Single responsibility: turn a node's rendered body HTML into structured link
+ * and embed records, and classify a URL as internal/external/other relative to
+ * a site's base URL. The link (`reports-links.js`) and content
+ * (`reports-content.js`) audits share this one parser so link handling stays
+ * consistent across the suite.
+ *
+ * Detection is regex-based on the stored body markup — a heuristic pass, not a
+ * full DOM parse — matching the existing seo/accessibility audits in reports.js.
+ */
+
+import { fieldValue } from "./reports-support.js";
+
+/**
+ * Read a node's body HTML from a canonical entity. Mirrors the body-extraction
+ * idiom in reports.js (the body field may be a `{value}` object or a scalar).
+ * @param {object} entity Canonical entity.
+ * @param {string[]} [candidates] Field names to try, in order.
+ * @returns {string} The body HTML, or "" when absent.
+ */
+export function bodyHtml(entity, candidates = ["body"]) {
+  const raw = fieldValue(entity, candidates);
+  const value = raw && typeof raw === "object" ? raw.value : raw;
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * Extract all `href` values from `<a>` tags in an HTML string.
+ * @param {string} html Body markup.
+ * @returns {string[]} Raw href values in document order (may include dups).
+ */
+export function extractAnchors(html) {
+  return matchAttr(html, /<a\b[^>]*?\bhref\s*=\s*["']([^"']+)["']/gi);
+}
+
+/**
+ * Extract all `src` values from `<img>` tags in an HTML string.
+ * @param {string} html Body markup.
+ * @returns {string[]} Raw src values in document order (may include dups).
+ */
+export function extractImages(html) {
+  return matchAttr(html, /<img\b[^>]*?\bsrc\s*=\s*["']([^"']+)["']/gi);
+}
+
+/**
+ * Extract entity embeds from body markup. Covers the CKEditor media/entity embed
+ * shapes Drupal emits — `<drupal-media>`, `<drupal-entity>`, and any element
+ * carrying `data-entity-type` + `data-entity-uuid` (entity_embed). Each embed is
+ * returned as a `{ entityType, uuid }` ref so callers can probe the target.
+ * @param {string} html Body markup.
+ * @returns {Array<{entityType: ?string, uuid: string}>} De-duped embed refs.
+ */
+export function extractEmbeds(html) {
+  const out = [];
+  const seen = new Set();
+  // Match any tag that carries a data-entity-uuid attribute; pull the optional
+  // sibling data-entity-type from the same tag.
+  const tagRe = /<([a-z-]+)\b([^>]*\bdata-entity-uuid\s*=\s*["'][^"']+["'][^>]*)>/gi;
+  for (const m of String(html || "").matchAll(tagRe)) {
+    const attrs = m[2];
+    const uuid = readAttr(attrs, /\bdata-entity-uuid\s*=\s*["']([^"']+)["']/i);
+    if (!uuid || seen.has(uuid)) continue;
+    seen.add(uuid);
+    out.push({ entityType: readAttr(attrs, /\bdata-entity-type\s*=\s*["']([^"']+)["']/i), uuid });
+  }
+  return out;
+}
+
+/**
+ * Classify a URL relative to a site base URL.
+ *
+ * @param {string} url Raw href/src value.
+ * @param {string} baseUrl The site's configured base URL (origin).
+ * @returns {{kind: "internal"|"external"|"fragment"|"mailto"|"tel"|"other",
+ *   url: string, path: ?string, host: ?string}} Classification. `path` is set
+ *   for internal links (origin-relative, no query/fragment); `host` for external.
+ */
+export function classifyLink(url, baseUrl) {
+  const raw = (url || "").trim();
+  if (!raw) return { kind: "other", url: raw, path: null, host: null };
+  if (raw.startsWith("#")) return { kind: "fragment", url: raw, path: null, host: null };
+
+  const lower = raw.toLowerCase();
+  if (lower.startsWith("mailto:")) return { kind: "mailto", url: raw, path: null, host: null };
+  if (lower.startsWith("tel:")) return { kind: "tel", url: raw, path: null, host: null };
+  if (/^(javascript|data):/i.test(lower)) return { kind: "other", url: raw, path: null, host: null };
+
+  const baseHost = hostOf(baseUrl);
+
+  // Root- or path-relative internal links.
+  if (raw.startsWith("/") && !raw.startsWith("//")) {
+    return { kind: "internal", url: raw, path: normalizePath(raw), host: baseHost };
+  }
+
+  // Protocol-relative or absolute URLs.
+  let parsed;
+  try {
+    parsed = new URL(raw, baseUrl || undefined);
+  } catch {
+    return { kind: "other", url: raw, path: null, host: null };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { kind: "other", url: raw, path: null, host: null };
+  }
+  if (baseHost && parsed.host.toLowerCase() === baseHost.toLowerCase()) {
+    return { kind: "internal", url: raw, path: normalizePath(parsed.pathname), host: parsed.host };
+  }
+  return { kind: "external", url: raw, path: null, host: parsed.host };
+}
+
+/**
+ * Normalize an internal path for comparison: decode, strip query/fragment, drop
+ * a trailing slash (except root), and ensure a leading slash.
+ * @param {string} path A pathname or root-relative URL.
+ * @returns {string} Normalized path beginning with "/".
+ */
+export function normalizePath(path) {
+  let p = String(path || "/");
+  const fragIdx = p.indexOf("#");
+  if (fragIdx !== -1) p = p.slice(0, fragIdx);
+  const queryIdx = p.indexOf("?");
+  if (queryIdx !== -1) p = p.slice(0, queryIdx);
+  try { p = decodeURI(p); } catch { /* leave as-is on malformed escapes */ }
+  if (!p.startsWith("/")) p = `/${p}`;
+  if (p.length > 1 && p.endsWith("/")) p = p.replace(/\/+$/, "");
+  return p || "/";
+}
+
+/**
+ * Pull the host (`host:port`) out of a base URL string, tolerating a bare host.
+ * @param {string} baseUrl A configured site base URL.
+ * @returns {?string} The host, or null when unparseable/absent.
+ */
+export function hostOf(baseUrl) {
+  if (!baseUrl) return null;
+  try { return new URL(baseUrl).host; }
+  catch {
+    try { return new URL(`https://${baseUrl}`).host; }
+    catch { return null; }
+  }
+}
+
+/**
+ * Run a global attribute-capturing regex over HTML and return capture group 1
+ * for every match.
+ * @param {string} html Source markup.
+ * @param {RegExp} re Global regex whose first group is the attribute value.
+ * @returns {string[]} Captured values in document order.
+ */
+function matchAttr(html, re) {
+  const out = [];
+  if (!html) return out;
+  for (const m of String(html).matchAll(re)) out.push(m[1]);
+  return out;
+}
+
+/**
+ * Read a single attribute value out of a tag's attribute string using a literal
+ * capturing regex.
+ * @param {string} attrs The raw attribute text inside a tag.
+ * @param {RegExp} re A regex whose first group captures the attribute value.
+ * @returns {?string} The value, or null when the attribute is absent.
+ */
+function readAttr(attrs, re) {
+  const m = String(attrs || "").match(re);
+  return m ? m[1] : null;
+}

package/src/lib/link-checker.js

@@ -0,0 +1,201 @@
+/**
+ * Guarded live link checker — opt-in outbound HTTP for the broken-links audit.
+ *
+ * Single responsibility: given a set of URLs, perform bounded liveness checks
+ * (HEAD, falling back to GET) and report each URL's status. Outbound HTTP is a
+ * privileged capability, so this module is the one place network egress is
+ * allowed during an audit, and only when the caller explicitly opts in.
+ *
+ * Safeguards (see checkLinks):
+ *   - SSRF guard: only http(s); refuse loopback/private/link-local/metadata
+ *     hosts and IP literals in private ranges.
+ *   - Allowlist: external hosts are skipped unless listed in
+ *     `allowedHosts`; same-origin (internal) hosts are always allowed.
+ *   - Caps: bounded concurrency, per-request timeout, and a hard ceiling on the
+ *     number of URLs checked (results flag `truncated` when the ceiling is hit).
+ */
+
+import nodeFetch from "node-fetch";
+
+/** Default per-request timeout (ms). */
+export const DEFAULT_TIMEOUT_MS = 5000;
+/** Default number of concurrent in-flight checks. */
+export const DEFAULT_CONCURRENCY = 5;
+/** Default hard ceiling on URLs checked in one call. */
+export const DEFAULT_MAX_LINKS = 200;
+
+/**
+ * Hostnames that must never be probed regardless of allowlist — loopback and
+ * cloud metadata endpoints.
+ */
+const BLOCKED_HOSTNAMES = new Set([
+  "localhost",
+  "metadata.google.internal",
+]);
+
+/**
+ * Decide whether a URL is safe to probe: http(s) only, and not pointed at a
+ * loopback, private, link-local, unique-local, or metadata address. Hostnames
+ * that are not IP literals are allowed past the IP-range check (DNS is not
+ * resolved here); the allowlist in checkLinks is the second gate for those.
+ *
+ * @param {string} url Absolute URL to validate.
+ * @returns {{safe: boolean, reason: ?string, host: ?string}} Verdict.
+ */
+export function isSafeUrl(url) {
+  let parsed;
+  try { parsed = new URL(url); }
+  catch { return { safe: false, reason: "unparseable URL", host: null }; }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { safe: false, reason: `unsupported protocol ${parsed.protocol}`, host: parsed.host };
+  }
+
+  // URL.hostname returns IPv6 literals wrapped in brackets; strip them so the
+  // range checks below see a bare address.
+  const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost")) {
+    return { safe: false, reason: "loopback host", host: parsed.host };
+  }
+  if (isPrivateIp(hostname)) {
+    return { safe: false, reason: "private or link-local address", host: parsed.host };
+  }
+  return { safe: true, reason: null, host: parsed.host };
+}
+
+/**
+ * Whether a hostname is an IP literal in a loopback/private/link-local/ULA range.
+ * Non-IP hostnames return false (resolution happens at fetch time, not here).
+ * @param {string} hostname Lowercased hostname from a URL.
+ * @returns {boolean} True when the literal IP is in a blocked range.
+ */
+function isPrivateIp(hostname) {
+  // IPv6 literals arrive bracket-stripped from URL.hostname.
+  if (hostname.includes(":")) {
+    if (hostname === "::1") return true;                 // loopback
+    if (hostname.startsWith("fe80")) return true;        // link-local
+    if (hostname.startsWith("fc") || hostname.startsWith("fd")) return true; // ULA
+    if (hostname.startsWith("::ffff:")) return isPrivateIp(hostname.slice(7)); // mapped v4
+    return false;
+  }
+  const m = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!m) return false;
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  if (a === 127) return true;                            // 127.0.0.0/8 loopback
+  if (a === 10) return true;                             // 10.0.0.0/8
+  if (a === 0) return true;                              // 0.0.0.0/8
+  if (a === 169 && b === 254) return true;               // 169.254.0.0/16 link-local + metadata
+  if (a === 172 && b >= 16 && b <= 31) return true;      // 172.16.0.0/12
+  if (a === 192 && b === 168) return true;               // 192.168.0.0/16
+  return false;
+}
+
+/**
+ * Check a list of URLs for liveness with bounded concurrency.
+ *
+ * @param {string[]} urls URLs to check (duplicates are de-duped).
+ * @param {object} [opts]
+ * @param {string[]} [opts.allowedHosts] Hosts allowed for external probes. A
+ *   same-origin host (see opts.internalHost) is always allowed.
+ * @param {?string} [opts.internalHost] The site's own host; never needs listing.
+ * @param {number} [opts.maxConcurrency] In-flight cap (default 5).
+ * @param {number} [opts.timeoutMs] Per-request timeout (default 5000).
+ * @param {number} [opts.maxLinks] Hard ceiling on URLs checked (default 200).
+ * @param {Function} [opts.fetchImpl] Injected fetch (for tests); defaults to node-fetch.
+ * @returns {Promise<{checked: number, truncated: boolean, results: Array<{
+ *   url: string, ok: boolean, status: ?number, skipped: boolean, reason: ?string}>}>}
+ */
+export async function checkLinks(urls, opts = {}) {
+  const {
+    allowedHosts = [],
+    internalHost = null,
+    maxConcurrency = DEFAULT_CONCURRENCY,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxLinks = DEFAULT_MAX_LINKS,
+    fetchImpl = nodeFetch,
+  } = opts;
+
+  const allow = new Set(allowedHosts.map((h) => String(h).toLowerCase()));
+  if (internalHost) allow.add(String(internalHost).toLowerCase());
+
+  const unique = [...new Set(urls)];
+  const truncated = unique.length > maxLinks;
+  const queue = unique.slice(0, maxLinks);
+
+  const results = [];
+  let cursor = 0;
+  /**
+   * Worker: pull URLs off the shared queue until drained.
+   * @returns {Promise<void>}
+   */
+  async function worker() {
+    while (cursor < queue.length) {
+      const url = queue[cursor++];
+      results.push(await checkOne(url, { allow, timeoutMs, fetchImpl }));
+    }
+  }
+  const workers = Array.from({ length: Math.max(1, Math.min(maxConcurrency, queue.length)) }, worker);
+  await Promise.all(workers);
+
+  return { checked: results.length, truncated, results };
+}
+
+/**
+ * Check a single URL, applying the SSRF guard and host allowlist before any
+ * network call. Safe failures (blocked/not-allowlisted) are returned as
+ * `skipped`, not errors.
+ * @param {string} url URL to check.
+ * @param {{allow: Set<string>, timeoutMs: number, fetchImpl: Function}} ctx Shared context.
+ * @returns {Promise<{url: string, ok: boolean, status: ?number, skipped: boolean, reason: ?string}>}
+ */
+async function checkOne(url, { allow, timeoutMs, fetchImpl }) {
+  const guard = isSafeUrl(url);
+  if (!guard.safe) {
+    return { url, ok: false, status: null, skipped: true, reason: guard.reason };
+  }
+  if (!allow.has(guard.host.toLowerCase())) {
+    return { url, ok: false, status: null, skipped: true, reason: "host not in allowlist" };
+  }
+
+  // HEAD first; some servers reject HEAD (405/501) so retry once with GET.
+  const head = await timedFetch(url, "HEAD", { timeoutMs, fetchImpl });
+  if (head.status && head.status !== 405 && head.status !== 501) {
+    return finalize(url, head);
+  }
+  const get = await timedFetch(url, "GET", { timeoutMs, fetchImpl });
+  return finalize(url, get);
+}
+
+/**
+ * Build the public result record from a fetch outcome. Treats 2xx/3xx as ok.
+ * @param {string} url URL checked.
+ * @param {{status: ?number, error: ?string}} res Fetch outcome.
+ * @returns {{url: string, ok: boolean, status: ?number, skipped: boolean, reason: ?string}}
+ */
+function finalize(url, res) {
+  if (res.error) return { url, ok: false, status: null, skipped: false, reason: res.error };
+  const ok = res.status >= 200 && res.status < 400;
+  return { url, ok, status: res.status, skipped: false, reason: ok ? null : `HTTP ${res.status}` };
+}
+
+/**
+ * Perform a single fetch with an abort-based timeout. Never throws — network and
+ * timeout failures are returned as `{ status: null, error }`.
+ * @param {string} url URL to fetch.
+ * @param {"HEAD"|"GET"} method HTTP method.
+ * @param {{timeoutMs: number, fetchImpl: Function}} ctx Timeout + fetch impl.
+ * @returns {Promise<{status: ?number, error: ?string}>}
+ */
+async function timedFetch(url, method, { timeoutMs, fetchImpl }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, { method, redirect: "follow", signal: controller.signal });
+    return { status: res.status, error: null };
+  } catch (err) {
+    const reason = err?.name === "AbortError" ? `timeout after ${timeoutMs}ms` : (err?.message || "request failed");
+    return { status: null, error: reason };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/lib/server-tools.js

@@ -309,6 +309,23 @@ export async function callServerTool(site, toolName, args = {}) {
   }
 }
 
+/**
+ * Extract the structured data a server tool returned, for callers (the audit
+ * tools) that need to inspect the payload rather than relay it. Prefers the MCP
+ * `structuredContent` field; otherwise parses the joined text content as JSON,
+ * falling back to the raw text when it isn't JSON.
+ * @param {object} result MCP tools/call result (as returned by callServerTool).
+ * @returns {*} Parsed structured data, raw text, or null when empty.
+ */
+export function toolResultData(result) {
+  if (!result) return null;
+  if (result.structuredContent !== undefined) return result.structuredContent;
+  const text = extractTextContent(result);
+  if (!text) return null;
+  try { return JSON.parse(text); }
+  catch { return text; }
+}
+
 /**
  * Pull the concatenated text from an MCP tool result's content array.
  * @param {object} result MCP tools/call result.