renovate-mcp 0.3.0 → 0.4.0

package/README.md

@@ -4,27 +4,38 @@ An MCP server for designing [Renovate](https://github.com/renovatebot/renovate)
 
 ## What it does
 
-Seven tools plus a preset reference:
+Eight tools plus a preset reference:
 
 | Tool | What it does |
 | --- | --- |
 | `check_setup` | Report Renovate CLI + validator availability, versions, env overrides, and install hints. Also runs at server startup and embeds the result in the server's `instructions` when anything's missing. |
 | `read_config` | Locate and parse `renovate.json` / `renovate.json5` / `.renovaterc*` / `.github/renovate.json` / `.gitlab/renovate.json` / `package.json#renovate` in a repo — in Renovate's priority order. |
-| `resolve_config` | Expand every `extends` preset against the committed catalogue and return the fully resolved config (offline; no `renovate` invocation). Flags unresolvable entries with a reason. Opt in to fetching `github>` / `gitlab>` presets over HTTPS with `externalPresets: true` (auth via `GITHUB_TOKEN` / `GITLAB_TOKEN` / `RENOVATE_TOKEN`). For GitHub Enterprise or self-hosted GitLab, pass `endpoint` (API base URL) — and `platform` in addition to route `local>` presets through the same host. `bitbucket>`, `gitea>`, and npm presets remain in `presetsUnresolved` regardless. |
+| `resolve_config` | Expand every `extends` preset against the committed catalogue and return the fully resolved config (offline; no `renovate` invocation). Flags unresolvable entries with a reason. Opt in to fetching `github>` / `gitlab>` presets over HTTPS with `externalPresets: true` (auth via `RENOVATE_TOKEN`, or `GITHUB_TOKEN` / `GITLAB_TOKEN` as platform-specific fallbacks). For GitHub Enterprise or self-hosted GitLab, pass `endpoint` (API base URL) — and `platform` in addition to route `local>` presets through the same host. `bitbucket>`, `gitea>`, and npm presets remain in `presetsUnresolved` regardless. |
 | `preview_custom_manager` | Preview a `customManagers` (regex) entry against a local repo — offline, no `renovate` invocation. Shows which files match `fileMatch`, which lines match each `matchStrings` regex with named capture groups, and what dep info the template fields produce. Intended for fast regex iteration; run `dry_run` afterwards for full-fidelity confirmation. |
 | `validate_config` | Run `renovate-config-validator` against a file or inline object. |
-| `dry_run` | Run Renovate with `--platform=local --dry-run`, return the structured JSON report (no PRs, no pushes). |
+| `lint_config` | Semantic lint pass for Renovate-specific footguns schema validation misses — primarily malformed `/…/` regex patterns in `matchPackageNames` / `matchDepNames` / `matchSourceUrls` / `matchCurrentVersion`. Offline; does not shell out. Returns findings with JSON path, offending value, and a stable `ruleId` (`dead-regex-missing-slash`, `unwrapped-regex`) for suppression. Complements `validate_config`. |
+| `dry_run` | Run Renovate with `--platform=local --dry-run`, return the structured JSON report (no PRs, no pushes). Scans Renovate's logs for registry-auth failures (401/403/unauthorized/etc.) and surfaces them under `problems` so an empty-updates result isn't mistaken for "no updates available" when credentials were actually missing. Accepts an optional `hostRules` input for per-invocation private-registry credentials so callers don't have to restart the MCP server with new env vars (written to a mode-0600 temp file, passed via `--config-file`, cleaned up after the run; token/password values are scrubbed from any log output). |
 | `write_config` | Validate, then write a config to disk (temp-file → validate → atomic rename). Refuses to save invalid configs unless `force: true`. |
 | `renovate://presets` (resource) | Thin markdown index of every namespace (with preset counts) covering all 1000+ built-in presets. Snapshot from the installed `renovate` devDep. |
 | `renovate://presets/{namespace}` (resource template) | Markdown listing of every preset in a single namespace (e.g. `renovate://presets/config`). Fetch this instead of the full index when the LLM only cares about one namespace — cuts token cost by roughly 1/N where N is the number of namespaces. |
 | `renovate://preset/{name}` (resource template) | Expanded JSON body (description, extends, packageRules, …) for any single built-in preset. E.g. `renovate://preset/config:recommended`. |
 
+## What this is NOT
+
+- **Not a Renovate replacement.** This server doesn't open PRs, run scheduled updates, or execute in CI — it's a design-time companion for a local `renovate.json`. Use the real Renovate for the actual dependency-update pipeline.
+- **`resolve_config` is preview-quality.** Preset expansion runs against a committed snapshot, and template substitution implements only positional `{{argN}}` placeholders — non-positional tokens and Handlebars helpers are flagged in `warnings` and pass through verbatim. For authoritative output, run `dry_run`.
+- **`preview_custom_manager` is a subset of Renovate's regex manager.** It covers `customType: "regex"`, `matchStringsStrategy: "any"`, and `{{groupName}}` template substitution only — other custom types, other strategies, and full Handlebars (helpers, conditionals) are not implemented. Use it for fast regex iteration; confirm with `dry_run`.
+- **`validate_config` / `dry_run` aren't exercised in CI.** CI deliberately doesn't install Renovate, so tools that shell out to it are only covered by unit/integration tests that don't require the binary. Run them locally against the Renovate install you intend to deploy with.
+
 ## Requirements
 
 - Node.js ≥ 24 (aligns with Renovate's own engine requirement).
-- Renovate available on your `PATH` — either a global install (`npm i -g renovate`) or a project-local install that exposes `renovate` and `renovate-config-validator` via `npm exec`. Only needed for `validate_config`, `dry_run`, and `write_config`; the offline tools (`read_config`, `resolve_config`, `preview_custom_manager`) work without it.
+- Renovate available on your `PATH` — either a global install (`npm i -g renovate`) or a project-local install that exposes `renovate` and `renovate-config-validator` via `npm exec`. Only needed for `validate_config`, `dry_run`, and `write_config`; the offline tools (`read_config`, `resolve_config`, `preview_custom_manager`, `lint_config`) work without it.
 - Override binary locations with env vars if needed: `RENOVATE_BIN`, `RENOVATE_CONFIG_VALIDATOR_BIN`.
-- Optional for `resolve_config` with `externalPresets: true`: `GITHUB_TOKEN` / `GITLAB_TOKEN` (or `RENOVATE_TOKEN` as a fallback) for fetching presets from private repos or to avoid rate limits. For GitHub Enterprise / self-hosted GitLab, pass the `endpoint` tool input (and `platform` if you also want `local>` presets routed there); `RENOVATE_ENDPOINT` is **not** read. Any env vars the tool does read must be set on the MCP server process itself — via the `env` key in `claude_desktop_config.json` / `.mcp.json`, not your shell, since the MCP server runs as a child of Claude and does not inherit shell env.
+- `RENOVATE_MCP_REQUIRE_CLI=false` suppresses the startup "partial availability" notice. Set this if you only intend to use the offline tools (`read_config`, `resolve_config`, `preview_custom_manager`) and don't want the missing-CLI notice in the server's MCP instructions.
+- Optional for `resolve_config` with `externalPresets: true`: `RENOVATE_TOKEN` (preferred — matches Renovate's own convention, where `RENOVATE_TOKEN` is the explicit Renovate-specific override), or `GITHUB_TOKEN` / `GITLAB_TOKEN` as platform-specific fallbacks, for fetching presets from private repos or to avoid rate limits. When both `RENOVATE_TOKEN` and a platform token are set, `RENOVATE_TOKEN` wins. For GitHub Enterprise / self-hosted GitLab, pass the `endpoint` tool input (and `platform` if you also want `local>` presets routed there); `RENOVATE_ENDPOINT` is **not** read.
+- Optional for `dry_run` against private package registries: whatever credentials Renovate itself would need at lookup time — e.g. `COMPOSER_AUTH` for private Packagist / Satis proxies, `NPM_TOKEN` or `.npmrc` for private npm, Docker registry credentials, or a `RENOVATE_HOST_RULES` JSON blob covering multiple hosts. Alternatively, encode these as `hostRules` directly in the Renovate config, or pass them per-call via the `hostRules` input on `dry_run` (no MCP server restart needed — useful while debugging an empty-updates result). Per-call `hostRules` are appended to any the repo's own config already declares. Values reach Renovate through the MCP tool-call transport as JSON, so the calling LLM sees them in its context; if that matters for a given token, use the env route instead. Without any of these Renovate's lookup step often returns 0 updates silently; `dry_run` will scan its logs for auth failures and surface them under `problems` in the output.
+- Any env vars the tools read (tokens, `COMPOSER_AUTH`, `RENOVATE_HOST_RULES`, binary overrides, …) must be set on the MCP server process itself — via the `env` key in `claude_desktop_config.json` / `.mcp.json`, not your shell, since the MCP server runs as a child of Claude and does not inherit shell env.
 
 ## Install
 
@@ -111,6 +122,32 @@ Once the server is wired up, try prompts like these. They're written for Claude
 - "Do a dry run and show me which PRs Renovate would open — no pushes."
 - "Add `:semanticCommits` to my `extends`, validate it, and save back to `renovate.json`."
 
+## Example session
+
+A transcript-style walkthrough: design a Dockerfile custom manager from scratch, validate it, dry-run, and save. Turns are abbreviated — your client will show the actual tool-call JSON.
+
+> **You:** I've got `# renovate: datasource=docker depName=<image>` comments above `FROM` lines in my Dockerfiles. Draft a `customManagers` entry and preview it against this repo.
+>
+> **Claude** calls `preview_custom_manager` with a first-draft `fileMatch` + `matchStrings`.
+> → 4 Dockerfiles matched `fileMatch`, 0 lines matched `matchStrings`. The regex anchored on `ARG`, but the Dockerfiles use `FROM`.
+>
+> **You:** Rewrite `matchStrings` to anchor on the renovate comment, then `FROM <image>:<version>` on the next line.
+>
+> **Claude** calls `preview_custom_manager` again with the fixed regex.
+> → 4 files, 4 line hits. Extracted: `postgres:15.3-alpine`, `redis:7.2`, `nginx:1.25`, `node:20.11`. Named groups `depName` and `currentValue` populated on every hit.
+>
+> **You:** Good. Validate the full config inline, with this `customManagers` entry alongside my existing `extends`.
+>
+> **Claude** calls `validate_config` with the inline config. → valid.
+>
+> **You:** Now dry-run so I can see what Renovate would actually open.
+>
+> **Claude** calls `dry_run`. → 2 updates: `postgres` 15.3-alpine → 15.5-alpine, `redis` 7.2 → 7.4. No entries in `problems`.
+>
+> **You:** Save it.
+>
+> **Claude** calls `write_config` on `renovate.json`. → validated, written atomically.
+
 ## Development
 
 ```bash
@@ -142,9 +179,14 @@ Secrets required on the repo: `RELEASE_PLEASE_TOKEN` (a PAT for release-please).
 
 ## Design notes
 
+Scope and non-goals are summarized in [What this is NOT](#what-this-is-not); this section covers implementation decisions behind the scope that *is* supported.
+
 - `validate_config`, `dry_run`, and `write_config` shell out to the Renovate CLI rather than importing Renovate as a library — this decouples our Node version from Renovate's (currently Node 24).
-- `resolve_config` and `preview_custom_manager` are fully in-process and never invoke the Renovate CLI, so they work without a Renovate install.
+- `resolve_config`, `preview_custom_manager`, and `lint_config` are fully in-process and never invoke the Renovate CLI, so they work without a Renovate install.
+- `lint_config` is a semantic lint pass that sits alongside `validate_config` rather than replacing it: schema validation catches structural bugs, the linter catches Renovate-specific footguns that schema validation declares valid — most commonly a pattern like `"matchPackageNames": ["/devops\\/pipelines\\/.+"]` where a trailing `/` is missing and Renovate silently degrades the value to an exact-string match that never hits. The ruleset is intentionally small (two rules: `dead-regex-missing-slash`, `unwrapped-regex`), scoped to the four regex-aware fields named in the proposal, and tuned to avoid false positives on benign exact strings containing a `.`. Rule IDs are stable so findings can be suppressed by callers.
 - `preview_custom_manager` honors `.gitignore` (including nested `.gitignore`s and `.git/info/exclude`) when walking the repo, so generated/vendored directories like `dist/`, `.next/`, `target/`, `__pycache__/` don't crowd out real hits against the `maxFilesScanned` cap. `node_modules/` and `.git/` are always skipped as a safety net even when no `.gitignore` is present.
 - `resolve_config` expands `extends` against a committed snapshot of Renovate's built-in presets (`src/data/presets.generated.ts`). External `github>` / `gitlab>` fetching is opt-in, uses each platform's contents API with a 10 s timeout, and caches results per call. The `endpoint` input swaps in a custom API base for GHE / self-hosted GitLab; `platform` additionally rewrites `local>` presets to be fetched against that endpoint.
-- `dry_run` uses `--report-type=file` so we get a structured JSON report instead of scraping stdout.
+- `resolve_config` merges preset bodies with a close approximation of Renovate's own `mergeChildConfig` — arrays concat, objects recursively merge, scalars overwrite — not a bit-identical port. Rule-specific semantics for `hostRules`, `regexManagers` / `customManagers`, and certain boolean flags aren't modeled here. Every response carries `mergeQuality: "preview"` plus a human-readable `disclaimer` so callers can't miss the limitation; run `dry_run` for authoritative output.
+- When `resolve_config` encounters template tokens outside its supported subset, it records a structured entry in `warnings`: under-argument cases (`{{arg2}}` referenced when only one arg was passed) substitute an empty string, while non-positional tokens (`{{packageRules}}`, Handlebars helpers like `{{#if …}}`) pass through verbatim.
+- `dry_run` uses `--report-type=file` so we get a structured JSON report instead of scraping stdout. When a `hostRules` input is passed it's written to a mode-0600 temp file in `os.tmpdir()`, handed to Renovate via `--config-file=`, and deleted in a `finally` block. Token/password values are scrubbed from both the detected `problems` list and the `logTail` fallback before returning.
 - `write_config` writes to a temp file, validates, then atomically renames — so a failed validation never leaves a broken config on disk.

package/dist/index.js

@@ -4,12 +4,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { registerCheckSetup } from "./tools/checkSetup.js";
 import { registerReadConfig } from "./tools/readConfig.js";
 import { registerValidateConfig } from "./tools/validateConfig.js";
+import { registerLintConfig } from "./tools/lintConfig.js";
 import { registerResolveConfig } from "./tools/resolveConfig.js";
 import { registerPreviewCustomManager } from "./tools/previewCustomManager.js";
 import { registerDryRun } from "./tools/dryRun.js";
 import { registerWriteConfig } from "./tools/writeConfig.js";
 import { registerPresetResources } from "./resources/presets.js";
-import { checkSetup, describeSetup } from "./lib/setupCheck.js";
+import { checkSetup, startupBanner } from "./lib/setupCheck.js";
 const BASE_INSTRUCTIONS = [
     "Design and debug Renovate configurations interactively.",
     "",
@@ -18,23 +19,28 @@ const BASE_INSTRUCTIONS = [
     "  2. resolve_config         — expand built-in presets to see what a config actually becomes (offline)",
     "  3. preview_custom_manager — iterate on a regex-based customManagers entry; shows file/line hits and extracted deps",
     "  4. validate_config        — check a proposed config against Renovate's schema",
-    "  5. dry_run                — preview what Renovate would actually do (no PRs)",
-    "  6. write_config           — save the agreed-upon config (validates first)",
+    "  5. lint_config            — semantic lint pass: catches Renovate-specific footguns schema validation misses (e.g. malformed /…/ regex patterns)",
+    "  6. dry_run                — preview what Renovate would actually do (no PRs)",
+    "  7. write_config           — save the agreed-upon config (validates first)",
     "",
     "If any tool fails unexpectedly, call check_setup to diagnose CLI availability.",
     "Built-in preset reference: renovate://presets (namespace index), renovate://presets/{namespace} (one namespace), renovate://preset/{name} (one preset's expanded JSON).",
 ].join("\n");
 const setup = await checkSetup();
-const instructions = setup.ok
-    ? BASE_INSTRUCTIONS
-    : [BASE_INSTRUCTIONS, "", "Startup setup check:", describeSetup(setup)].join("\n");
-const SERVER_VERSION = "0.3.0"; // x-release-please-version
+// `RENOVATE_MCP_REQUIRE_CLI=false` is the opt-out for users who have
+// consciously chosen the offline subset and don't want the startup notice.
+const requireCliRaw = process.env.RENOVATE_MCP_REQUIRE_CLI?.trim().toLowerCase();
+const suppressBanner = requireCliRaw === "false" || requireCliRaw === "0";
+const banner = suppressBanner ? null : startupBanner(setup);
+const instructions = banner ? [BASE_INSTRUCTIONS, "", banner].join("\n") : BASE_INSTRUCTIONS;
+const SERVER_VERSION = "0.4.0"; // x-release-please-version
 const server = new McpServer({ name: "renovate-mcp", version: SERVER_VERSION }, { instructions });
 registerCheckSetup(server);
 registerReadConfig(server);
 registerResolveConfig(server);
 registerPreviewCustomManager(server);
 registerValidateConfig(server);
+registerLintConfig(server);
 registerDryRun(server);
 registerWriteConfig(server);
 registerPresetResources(server);

package/dist/lib/configLinter.d.ts

@@ -0,0 +1,8 @@
+export type LintRuleId = "dead-regex-missing-slash" | "unwrapped-regex";
+export interface LintFinding {
+    ruleId: LintRuleId;
+    path: string;
+    value: string;
+    message: string;
+}
+export declare function lintConfig(config: unknown): LintFinding[];

package/dist/lib/configLinter.js

@@ -0,0 +1,74 @@
+const REGEX_AWARE_FIELDS = new Set([
+    "matchPackageNames",
+    "matchDepNames",
+    "matchSourceUrls",
+    "matchCurrentVersion",
+]);
+export function lintConfig(config) {
+    const findings = [];
+    walk(config, "", findings);
+    return findings;
+}
+function walk(node, pathStr, findings) {
+    if (Array.isArray(node)) {
+        node.forEach((item, i) => walk(item, `${pathStr}[${i}]`, findings));
+        return;
+    }
+    if (node && typeof node === "object") {
+        for (const [key, value] of Object.entries(node)) {
+            const childPath = pathStr ? `${pathStr}.${key}` : key;
+            if (REGEX_AWARE_FIELDS.has(key)) {
+                if (Array.isArray(value)) {
+                    value.forEach((entry, i) => {
+                        if (typeof entry === "string") {
+                            checkPattern(entry, `${childPath}[${i}]`, findings);
+                        }
+                    });
+                }
+                else if (typeof value === "string") {
+                    checkPattern(value, childPath, findings);
+                }
+            }
+            else {
+                walk(value, childPath, findings);
+            }
+        }
+    }
+}
+function checkPattern(raw, path, findings) {
+    // `!` is Renovate's exclusion prefix; strip it before checking regex wrapping.
+    const stripped = raw.startsWith("!") ? raw.slice(1) : raw;
+    // Too short to meaningfully be a /…/ regex or trigger a metachar rule.
+    if (stripped.length < 2)
+        return;
+    const startsSlash = stripped.startsWith("/");
+    const endsSlash = stripped.endsWith("/");
+    if (startsSlash !== endsSlash) {
+        findings.push({
+            ruleId: "dead-regex-missing-slash",
+            path,
+            value: raw,
+            message: startsSlash
+                ? "Value starts with '/' but does not end with '/'. Renovate will treat this as an exact-match string, not a regex. Add the trailing '/' if a regex match was intended, otherwise remove the leading '/'."
+                : "Value ends with '/' but does not start with '/'. Renovate will treat this as an exact-match string, not a regex. Add the leading '/' if a regex match was intended, otherwise remove the trailing '/'.",
+        });
+        return;
+    }
+    if (startsSlash && endsSlash)
+        return;
+    if (hasStrongRegexSignal(stripped)) {
+        findings.push({
+            ruleId: "unwrapped-regex",
+            path,
+            value: raw,
+            message: `Value contains regex metacharacters but is not wrapped in '/…/'. Renovate will treat it as an exact-match string. Wrap it as '/${stripped}/' (or '!/${stripped}/' to negate) if a regex match was intended.`,
+        });
+    }
+}
+function hasStrongRegexSignal(s) {
+    return (/\\[dwsbDWSB]/.test(s) ||
+        /\.[+*?]/.test(s) ||
+        /\\\./.test(s) ||
+        /\(\?[:!=<]/.test(s) ||
+        /\[[^\]]+\]/.test(s));
+}

package/dist/lib/externalPresetFetcher.js

@@ -46,14 +46,14 @@ async function fetchGitHub(parsed, timeoutMs, fetchImpl, endpoint) {
     const ref = parsed.ref ?? "HEAD";
     const apiBase = endpoint ?? DEFAULT_GITHUB_API_BASE;
     const url = `${apiBase}/repos/${parsed.repoPath}/contents/${encodeFilePath(file)}?ref=${encodeURIComponent(ref)}`;
-    const token = process.env.GITHUB_TOKEN || process.env.RENOVATE_TOKEN;
+    const credential = resolveCredential(["RENOVATE_TOKEN", "GITHUB_TOKEN"]);
     const headers = {
         Accept: "application/vnd.github.raw",
         "User-Agent": "renovate-mcp",
     };
-    if (token)
-        headers.Authorization = `Bearer ${token}`;
-    return fetchJson(url, headers, timeoutMs, parsed.original, fetchImpl);
+    if (credential.token)
+        headers.Authorization = `Bearer ${credential.token}`;
+    return fetchJson(url, headers, timeoutMs, parsed.original, fetchImpl, "github", credential);
 }
 async function fetchGitLab(parsed, timeoutMs, fetchImpl, endpoint) {
     if (!parsed.repoPath) {
@@ -63,11 +63,19 @@ async function fetchGitLab(parsed, timeoutMs, fetchImpl, endpoint) {
     const ref = parsed.ref ?? "HEAD";
     const apiBase = endpoint ?? DEFAULT_GITLAB_API_BASE;
     const url = `${apiBase}/projects/${encodeURIComponent(parsed.repoPath)}/repository/files/${encodeURIComponent(file)}/raw?ref=${encodeURIComponent(ref)}`;
-    const token = process.env.GITLAB_TOKEN || process.env.RENOVATE_TOKEN;
+    const credential = resolveCredential(["RENOVATE_TOKEN", "GITLAB_TOKEN"]);
     const headers = { "User-Agent": "renovate-mcp" };
-    if (token)
-        headers["PRIVATE-TOKEN"] = token;
-    return fetchJson(url, headers, timeoutMs, parsed.original, fetchImpl);
+    if (credential.token)
+        headers["PRIVATE-TOKEN"] = credential.token;
+    return fetchJson(url, headers, timeoutMs, parsed.original, fetchImpl, "gitlab", credential);
+}
+function resolveCredential(vars) {
+    for (const envVar of vars) {
+        const value = process.env[envVar];
+        if (value)
+            return { envVar, token: value, triedVars: vars };
+    }
+    return { envVar: null, token: undefined, triedVars: vars };
 }
 function presetFileName(parsed) {
     if (parsed.subpath)
@@ -82,12 +90,48 @@ function ensureJson(name) {
 function encodeFilePath(file) {
     return file.split("/").map(encodeURIComponent).join("/");
 }
-async function fetchJson(url, headers, timeoutMs, presetName, fetchImpl) {
+function detectRateLimit(res, platform, presetName) {
+    if (platform === "github" && res.status === 403) {
+        if (res.headers.get("x-ratelimit-remaining") !== "0")
+            return undefined;
+        const resetIso = parseEpochHeader(res.headers.get("x-ratelimit-reset"));
+        const resetClause = resetIso ? ` (resets at ${resetIso})` : "";
+        return `GitHub API rate limit exceeded${resetClause} when fetching ${presetName}. Set GITHUB_TOKEN for an authenticated limit, or wait for reset.`;
+    }
+    if (platform === "gitlab" && res.status === 429) {
+        const resetIso = parseEpochHeader(res.headers.get("ratelimit-reset"));
+        const resetClause = resetIso ? ` (resets at ${resetIso})` : "";
+        return `GitLab API rate limit exceeded${resetClause} when fetching ${presetName}. Set GITLAB_TOKEN for an authenticated limit, or wait for reset.`;
+    }
+    return undefined;
+}
+function parseEpochHeader(raw) {
+    if (!raw)
+        return undefined;
+    const seconds = Number.parseInt(raw, 10);
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    const date = new Date(seconds * 1000);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return date.toISOString();
+}
+async function fetchJson(url, headers, timeoutMs, presetName, fetchImpl, platform, credential) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const res = await fetchImpl(url, { headers, signal: controller.signal });
         if (!res.ok) {
+            const rateLimit = detectRateLimit(res, platform, presetName);
+            if (rateLimit)
+                return { ok: false, reason: rateLimit };
+            if (res.status === 401 || res.status === 403) {
+                const body = await safeReadText(res);
+                return {
+                    ok: false,
+                    reason: formatAuthFailure(res.status, presetName, url, credential, body),
+                };
+            }
             return {
                 ok: false,
                 reason: `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ""} when fetching ${presetName}`,
@@ -128,3 +172,30 @@ async function fetchJson(url, headers, timeoutMs, presetName, fetchImpl) {
         clearTimeout(timer);
     }
 }
+const AUTH_BODY_MAX = 500;
+async function safeReadText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return "";
+    }
+}
+function formatAuthFailure(status, presetName, url, credential, body) {
+    const lines = [`HTTP ${status} when fetching ${presetName}`];
+    lines.push(`  URL:         ${url}`);
+    lines.push(`  Credential:  ${formatCredential(credential)}`);
+    const trimmed = body.trim();
+    if (trimmed) {
+        const snippet = trimmed.length > AUTH_BODY_MAX
+            ? `${trimmed.slice(0, AUTH_BODY_MAX)}… [truncated]`
+            : trimmed;
+        lines.push(`  Response:    ${snippet}`);
+    }
+    return lines.join("\n");
+}
+function formatCredential(credential) {
+    if (credential.envVar)
+        return `${credential.envVar} (present)`;
+    return `none (tried ${credential.triedVars.join(", ")})`;
+}

package/dist/lib/hostRulesConfig.d.ts

@@ -0,0 +1,24 @@
+export type HostRule = Record<string, unknown>;
+/**
+ * Write a throwaway Renovate config containing just `{ hostRules: [...] }` to
+ * `os.tmpdir()` with mode 0600, and return the absolute path. The caller is
+ * responsible for unlinking the file (in a `finally` block) once Renovate has
+ * consumed it — we do not keep a reference here.
+ *
+ * Renovate merges CLI `--config-file` rules with any repo-level `hostRules`
+ * (array concatenation, most-specific match wins), so callers can combine
+ * per-invocation credentials with whatever the repo itself already declares.
+ */
+export declare function writeHostRulesConfig(hostRules: HostRule[]): Promise<string>;
+/**
+ * Pull the token/password values out of the provided hostRules so callers can
+ * scrub them from log output. Usernames are intentionally not treated as
+ * secrets — Renovate echoes them in diagnostics and they are not typically
+ * sensitive on their own.
+ */
+export declare function collectSecrets(hostRules: HostRule[]): string[];
+/**
+ * Replace every literal occurrence of any secret in `text` with `[REDACTED]`.
+ * No-op when `secrets` is empty.
+ */
+export declare function scrubSecrets(text: string, secrets: string[]): string;

package/dist/lib/hostRulesConfig.js

@@ -0,0 +1,56 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+/**
+ * Write a throwaway Renovate config containing just `{ hostRules: [...] }` to
+ * `os.tmpdir()` with mode 0600, and return the absolute path. The caller is
+ * responsible for unlinking the file (in a `finally` block) once Renovate has
+ * consumed it — we do not keep a reference here.
+ *
+ * Renovate merges CLI `--config-file` rules with any repo-level `hostRules`
+ * (array concatenation, most-specific match wins), so callers can combine
+ * per-invocation credentials with whatever the repo itself already declares.
+ */
+export async function writeHostRulesConfig(hostRules) {
+    const tmpPath = path.join(tmpdir(), `renovate-mcp-hostrules-${randomUUID()}.json`);
+    const body = JSON.stringify({ hostRules }, null, 2);
+    await fs.writeFile(tmpPath, body, { mode: 0o600 });
+    return tmpPath;
+}
+const SECRET_KEYS = ["token", "password"];
+/**
+ * Pull the token/password values out of the provided hostRules so callers can
+ * scrub them from log output. Usernames are intentionally not treated as
+ * secrets — Renovate echoes them in diagnostics and they are not typically
+ * sensitive on their own.
+ */
+export function collectSecrets(hostRules) {
+    const out = new Set();
+    for (const rule of hostRules) {
+        if (!rule || typeof rule !== "object")
+            continue;
+        for (const key of SECRET_KEYS) {
+            const value = rule[key];
+            if (typeof value === "string" && value.length > 0) {
+                out.add(value);
+            }
+        }
+    }
+    return [...out];
+}
+/**
+ * Replace every literal occurrence of any secret in `text` with `[REDACTED]`.
+ * No-op when `secrets` is empty.
+ */
+export function scrubSecrets(text, secrets) {
+    if (!secrets.length)
+        return text;
+    let result = text;
+    for (const secret of secrets) {
+        if (!secret)
+            continue;
+        result = result.split(secret).join("[REDACTED]");
+    }
+    return result;
+}

package/dist/lib/lookupProblems.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Scan Renovate's log output for signals that a lookup silently failed due to
+ * registry auth. Renovate does not always fail loudly when a private registry
+ * rejects a request — managers are detected, but the `updates` array comes
+ * back empty with no warning on the structured report. This heuristic catches
+ * the common cases so the caller can distinguish "no updates available" from
+ * "couldn't auth to the registry."
+ *
+ * We try to parse each line as a Renovate JSON log entry (emitted when
+ * LOG_FORMAT=json) and also fall back to plain-text scanning, since some
+ * errors surface as uncaught messages on stderr before the JSON logger takes
+ * over. Output is deduplicated and capped so this never blows up the caller's
+ * context.
+ */
+export interface LookupProblem {
+    message: string;
+    context?: string;
+}
+export declare function detectLookupProblems(log: string): LookupProblem[];

package/dist/lib/lookupProblems.js

@@ -0,0 +1,92 @@
+/**
+ * Scan Renovate's log output for signals that a lookup silently failed due to
+ * registry auth. Renovate does not always fail loudly when a private registry
+ * rejects a request — managers are detected, but the `updates` array comes
+ * back empty with no warning on the structured report. This heuristic catches
+ * the common cases so the caller can distinguish "no updates available" from
+ * "couldn't auth to the registry."
+ *
+ * We try to parse each line as a Renovate JSON log entry (emitted when
+ * LOG_FORMAT=json) and also fall back to plain-text scanning, since some
+ * errors surface as uncaught messages on stderr before the JSON logger takes
+ * over. Output is deduplicated and capped so this never blows up the caller's
+ * context.
+ */
+const AUTH_PATTERNS = [
+    /(?:^|[^\d])(401|403)(?:[^\d]|$)/,
+    /\bunauthori[sz]ed\b/i,
+    /\bauthentication (?:required|failed)\b/i,
+    /\brequires authentication\b/i,
+    /\binvalid credentials\b/i,
+    /\bcould not authenticate\b/i,
+    /\baccess denied\b/i,
+];
+const MAX_MESSAGE_LENGTH = 300;
+const MAX_PROBLEMS = 10;
+function matchesAuthPattern(text) {
+    return AUTH_PATTERNS.some((re) => re.test(text));
+}
+function truncate(s) {
+    if (s.length <= MAX_MESSAGE_LENGTH)
+        return s;
+    return `${s.slice(0, MAX_MESSAGE_LENGTH - 1)}…`;
+}
+function extractContext(parsed) {
+    const parts = [];
+    const datasource = parsed.datasource;
+    const packageName = parsed.packageName ?? parsed.depName;
+    const hostname = parsed.hostname ?? parsed.host ?? parsed.url;
+    if (typeof datasource === "string")
+        parts.push(`datasource=${datasource}`);
+    if (typeof packageName === "string")
+        parts.push(`package=${packageName}`);
+    if (typeof hostname === "string")
+        parts.push(`host=${hostname}`);
+    return parts.length ? parts.join(" ") : undefined;
+}
+export function detectLookupProblems(log) {
+    const problems = [];
+    const seen = new Set();
+    for (const rawLine of log.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (problems.length >= MAX_PROBLEMS)
+            break;
+        let parsed = null;
+        if (line.startsWith("{")) {
+            try {
+                const obj = JSON.parse(line);
+                if (obj && typeof obj === "object") {
+                    parsed = obj;
+                }
+            }
+            catch {
+                // Fall through to plain-text handling.
+            }
+        }
+        let message;
+        let context;
+        if (parsed) {
+            const msg = typeof parsed.msg === "string" ? parsed.msg : "";
+            const err = parsed.err;
+            const errMsg = err && typeof err.message === "string" ? err.message : "";
+            const combined = [msg, errMsg].filter(Boolean).join(" — ");
+            if (!combined || !matchesAuthPattern(combined))
+                continue;
+            message = truncate(combined);
+            context = extractContext(parsed);
+        }
+        else {
+            if (!matchesAuthPattern(line))
+                continue;
+            message = truncate(line);
+        }
+        const dedupeKey = context ? `${context}::${message}` : message;
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        problems.push(context ? { message, context } : { message });
+    }
+    return problems;
+}

package/dist/lib/presetResolver.d.ts

@@ -2,10 +2,15 @@ export interface UnresolvedPreset {
     preset: string;
     reason: string;
 }
+export interface PresetWarning {
+    preset: string;
+    message: string;
+}
 export interface ResolveResult {
     resolved: Record<string, unknown>;
     presetsResolved: string[];
     presetsUnresolved: UnresolvedPreset[];
+    warnings: PresetWarning[];
 }
 export type FetchPlatform = "github" | "gitlab";
 export interface ResolveOptions {

package/dist/lib/presetResolver.js

@@ -49,6 +49,7 @@ export function classifyExternalSource(source) {
 export async function resolveConfig(config, options = {}) {
     const presetsResolved = [];
     const presetsUnresolved = [];
+    const warnings = [];
     const stack = [];
     const ctx = {
         fetchExternal: options.fetchExternal ?? false,
@@ -57,10 +58,10 @@ export async function resolveConfig(config, options = {}) {
         platform: options.platform,
         cache: new Map(),
     };
-    const resolved = await expand(config, presetsResolved, presetsUnresolved, stack, ctx);
-    return { resolved, presetsResolved, presetsUnresolved };
+    const resolved = await expand(config, presetsResolved, presetsUnresolved, warnings, stack, ctx);
+    return { resolved, presetsResolved, presetsUnresolved, warnings };
 }
-async function expand(input, resolvedList, unresolvedList, stack, ctx) {
+async function expand(input, resolvedList, unresolvedList, warningsList, stack, ctx) {
     const rawExtends = input.extends;
     if (!Array.isArray(rawExtends) || rawExtends.length === 0) {
         const { extends: _drop, ...rest } = input;
@@ -86,9 +87,11 @@ async function expand(input, resolvedList, unresolvedList, stack, ctx) {
         const body = await loadPresetBody(parsed, ctx, unresolvedList);
         if (!body)
             continue;
-        const substituted = applyArgs(body, parsed.args);
+        const { value, missingArgs, unknownTemplates } = applyArgs(body, parsed.args);
+        recordTemplateWarnings(entry, parsed.args.length, missingArgs, unknownTemplates, warningsList);
+        const substituted = value;
         stack.push(parsed.key);
-        const subResolved = await expand(substituted, resolvedList, unresolvedList, stack, ctx);
+        const subResolved = await expand(substituted, resolvedList, unresolvedList, warningsList, stack, ctx);
         stack.pop();
         accumulated = mergeConfig(accumulated, subResolved);
         resolvedList.push(entry);
@@ -96,6 +99,24 @@ async function expand(input, resolvedList, unresolvedList, stack, ctx) {
     const { extends: _drop, ...ownKeys } = input;
     return mergeConfig(accumulated, ownKeys);
 }
+function recordTemplateWarnings(entry, suppliedArgs, missingArgs, unknownTemplates, warningsList) {
+    for (const idx of [...missingArgs].sort((a, b) => a - b)) {
+        warningsList.push({
+            preset: entry,
+            message: `Preset references {{arg${idx}}} but only ${suppliedArgs} argument(s) were supplied; ` +
+                `the placeholder was substituted with an empty string. Pass more arguments, ` +
+                `e.g. "${entry.replace(/\([^)]*\)\s*$/, "")}(arg0, arg1, ...)".`,
+        });
+    }
+    for (const token of [...unknownTemplates].sort()) {
+        warningsList.push({
+            preset: entry,
+            message: `Preset uses template "{{${token}}}" which resolve_config does not expand ` +
+                `(only positional {{argN}} is supported). The token was left verbatim; ` +
+                `run dry_run for full-fidelity expansion via the Renovate CLI.`,
+        });
+    }
+}
 async function loadPresetBody(parsed, ctx, unresolvedList) {
     if (!parsed.source) {
         const preset = PRESETS[parsed.key];
@@ -211,19 +232,35 @@ function parseExternal(rest, original, args, sourceRaw) {
     return { key, original, args, source, repoPath, presetName, subpath, ref };
 }
 function applyArgs(value, args) {
+    const missingArgs = new Set();
+    const unknownTemplates = new Set();
+    const out = applyArgsInner(value, args, missingArgs, unknownTemplates);
+    return { value: out, missingArgs, unknownTemplates };
+}
+const TEMPLATE_TOKEN_RE = /\{\{\s*([^{}]+?)\s*\}\}/g;
+const ARG_TOKEN_RE = /^arg(\d+)$/;
+function applyArgsInner(value, args, missingArgs, unknownTemplates) {
     if (typeof value === "string") {
-        return value.replace(/\{\{\s*arg(\d+)\s*\}\}/g, (_, idx) => {
-            const i = Number(idx);
-            return i < args.length ? args[i] : "";
+        return value.replace(TEMPLATE_TOKEN_RE, (match, inner) => {
+            const argMatch = ARG_TOKEN_RE.exec(inner);
+            if (argMatch) {
+                const i = Number(argMatch[1]);
+                if (i < args.length)
+                    return args[i];
+                missingArgs.add(i);
+                return "";
+            }
+            unknownTemplates.add(inner);
+            return match;
         });
     }
     if (Array.isArray(value)) {
-        return value.map((v) => applyArgs(v, args));
+        return value.map((v) => applyArgsInner(v, args, missingArgs, unknownTemplates));
     }
     if (value && typeof value === "object") {
         const out = {};
         for (const [k, v] of Object.entries(value)) {
-            out[k] = applyArgs(v, args);
+            out[k] = applyArgsInner(v, args, missingArgs, unknownTemplates);
         }
         return out;
     }

package/dist/lib/setupCheck.d.ts

@@ -15,4 +15,12 @@ export interface SetupStatus {
     hints: string[];
 }
 export declare function checkSetup(): Promise<SetupStatus>;
+export declare const OFFLINE_TOOLS: readonly ["read_config", "resolve_config", "preview_custom_manager"];
+export declare function unavailableTools(status: SetupStatus): string[];
+/**
+ * Concise startup banner appended to the server's MCP `instructions` so the
+ * LLM is primed to treat CLI-missing as a partial-availability signal rather
+ * than a setup error. Returns `null` when every tool is available.
+ */
+export declare function startupBanner(status: SetupStatus): string | null;
 export declare function describeSetup(status: SetupStatus): string;

package/dist/lib/setupCheck.js

@@ -56,6 +56,39 @@ export async function checkSetup() {
         hints,
     };
 }
+// Tools that do not depend on the Renovate CLI and are always callable.
+export const OFFLINE_TOOLS = ["read_config", "resolve_config", "preview_custom_manager"];
+// Returns the tool names that cannot currently run because their backing
+// binary is missing. Order is workflow-ordered (validate → dry_run → write).
+export function unavailableTools(status) {
+    const names = [];
+    if (!status.renovateConfigValidator.found)
+        names.push("validate_config");
+    if (!status.renovate.found)
+        names.push("dry_run");
+    if (!status.renovateConfigValidator.found)
+        names.push("write_config");
+    return names;
+}
+/**
+ * Concise startup banner appended to the server's MCP `instructions` so the
+ * LLM is primed to treat CLI-missing as a partial-availability signal rather
+ * than a setup error. Returns `null` when every tool is available.
+ */
+export function startupBanner(status) {
+    const unavailable = unavailableTools(status);
+    if (unavailable.length === 0)
+        return null;
+    const unavailList = unavailable.map((n) => `\`${n}\``).join(", ");
+    const offlineList = OFFLINE_TOOLS.map((n) => `\`${n}\``).join(", ");
+    return [
+        "Partial availability:",
+        `  Renovate CLI not found — only blocks: ${unavailList}.`,
+        `  Offline tools (${offlineList}) still work; do not flag this as a setup problem when the task only needs those.`,
+        "  Install Renovate (`npm i -g renovate`) before calling the blocked tools, or call `check_setup` for a full diagnostic.",
+        "  Set `RENOVATE_MCP_REQUIRE_CLI=false` to suppress this notice if you have consciously chosen the offline subset.",
+    ].join("\n");
+}
 export function describeSetup(status) {
     const lines = [];
     lines.push(`Node: ${status.node}`);

package/dist/tools/dryRun.js

@@ -4,10 +4,15 @@ import { promises as fs } from "node:fs";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { run, resolveRenovateTool, formatMissingBinaryError } from "../lib/renovateCli.js";
+import { detectLookupProblems } from "../lib/lookupProblems.js";
+import { collectSecrets, scrubSecrets, writeHostRulesConfig, } from "../lib/hostRulesConfig.js";
+const hostRuleSchema = z
+    .record(z.string(), z.unknown())
+    .describe("A single Renovate hostRule (matchHost, hostType, username, password, token, …). Structure is not validated here — Renovate's own config loader checks it when the temp file is read.");
 export function registerDryRun(server) {
     server.registerTool("dry_run", {
         title: "Dry-run Renovate",
-        description: "Run Renovate in dry-run mode against a local repository to preview what it would do — no PRs opened, no git pushes. Uses --platform=local so no host token is required. Emits a structured JSON report of the updates Renovate would create.",
+        description: "Run Renovate in dry-run mode against a local repository to preview what it would do — no PRs opened, no git pushes. Uses --platform=local so no host token is required. Emits a structured JSON report of the updates Renovate would create.\n\nCredentials for private registries (e.g. `COMPOSER_AUTH` for Packagist/Satis proxies, `NPM_TOKEN` / `.npmrc` for npm, Docker registry creds, `RENOVATE_HOST_RULES` for anything else) must be set on the MCP server process itself — via the `env` key in `claude_desktop_config.json` / `.mcp.json`, not your shell, since the MCP server runs as a child of Claude and does not inherit shell env. Alternatively, encode credentials as `hostRules` in the Renovate config, or pass them per-call via the `hostRules` input on this tool (written to a mode-0600 temp file that is cleaned up after the run; token/password values are scrubbed from `logTail` and `problems`). Per-call `hostRules` are appended to any the repo's own config already declares. If a lookup can't auth to a registry, Renovate often reports 0 updates without a loud error; when that happens this tool surfaces detected auth failures under `problems` in the output so callers can distinguish a genuine \"no updates\" from a silent registry-auth failure.",
         inputSchema: {
             repoPath: z.string().describe("Absolute path to the repository root"),
             dryRunMode: z
@@ -22,17 +27,29 @@ export function registerDryRun(server) {
                 .max(15 * 60_000)
                 .default(5 * 60_000)
                 .describe("Max wait time in ms (default 5 minutes, capped at 15)"),
+            hostRules: z
+                .array(hostRuleSchema)
+                .optional()
+                .describe("Optional per-invocation Renovate hostRules for private registry auth. Written to a mode-0600 temp file that is passed via --config-file and deleted after the run. Token/password values are scrubbed from any log output this tool returns. Appended to (not replacing) any hostRules declared in the repo's own config."),
         },
-    }, async ({ repoPath, dryRunMode, logLevel, timeoutMs }) => {
+    }, async ({ repoPath, dryRunMode, logLevel, timeoutMs, hostRules }) => {
         const reportPath = path.join(tmpdir(), `renovate-mcp-report-${randomUUID()}.json`);
         const bin = resolveRenovateTool("renovate");
+        const ruleList = hostRules ?? [];
+        const secrets = collectSecrets(ruleList);
+        let hostRulesConfigPath;
         try {
-            const result = await run(bin, [
+            const args = [
                 "--platform=local",
                 `--dry-run=${dryRunMode}`,
                 "--report-type=file",
                 `--report-path=${reportPath}`,
-            ], {
+            ];
+            if (ruleList.length > 0) {
+                hostRulesConfigPath = await writeHostRulesConfig(ruleList);
+                args.push(`--config-file=${hostRulesConfigPath}`);
+            }
+            const result = await run(bin, args, {
                 cwd: repoPath,
                 env: { LOG_LEVEL: logLevel, LOG_FORMAT: "json" },
                 timeoutMs,
@@ -50,10 +67,16 @@ export function registerDryRun(server) {
                 hasReport: report !== null,
                 report,
             };
+            const scrubbedStdout = scrubSecrets(result.stdout, secrets);
+            const scrubbedStderr = scrubSecrets(result.stderr, secrets);
+            const problems = detectLookupProblems(`${scrubbedStderr}\n${scrubbedStdout}`);
+            if (problems.length > 0) {
+                summary.problems = problems;
+            }
             // If no structured report, surface the last bit of stderr so Claude can
             // debug without blowing up the context with Renovate's verbose logs.
             if (!report) {
-                const tail = (result.stderr || result.stdout)
+                const tail = (scrubbedStderr || scrubbedStdout)
                     .split(/\r?\n/)
                     .filter(Boolean)
                     .slice(-40)
@@ -76,13 +99,16 @@ export function registerDryRun(server) {
                 content: [
                     {
                         type: "text",
-                        text: formatMissingBinaryError("renovate", err),
+                        text: scrubSecrets(formatMissingBinaryError("renovate", err), secrets),
                     },
                 ],
             };
         }
         finally {
             await fs.unlink(reportPath).catch(() => undefined);
+            if (hostRulesConfigPath) {
+                await fs.unlink(hostRulesConfigPath).catch(() => undefined);
+            }
         }
     });
 }

package/dist/tools/lintConfig.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerLintConfig(server: McpServer): void;

package/dist/tools/lintConfig.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import JSON5 from "json5";
+import { lintConfig } from "../lib/configLinter.js";
+export function registerLintConfig(server) {
+    server.registerTool("lint_config", {
+        title: "Lint Renovate config for semantic footguns",
+        description: "Run a semantic lint pass over a Renovate config. Complements validate_config: schema validation catches structural bugs, this catches Renovate-specific footguns schema validation misses — primarily malformed '/…/' regex patterns in fields like matchPackageNames, matchDepNames, matchSourceUrls, matchCurrentVersion. Offline; does not shell out. Pass either configPath (file on disk, JSON or JSON5) or configContent (inline object).",
+        inputSchema: {
+            configPath: z
+                .string()
+                .optional()
+                .describe("Absolute path to a config file to lint (JSON or JSON5)"),
+            configContent: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Inline config object to lint"),
+        },
+    }, async ({ configPath, configContent }) => {
+        if (!configPath && !configContent) {
+            return {
+                isError: true,
+                content: [
+                    { type: "text", text: "Provide either configPath or configContent." },
+                ],
+            };
+        }
+        let config;
+        if (configContent) {
+            config = configContent;
+        }
+        else {
+            try {
+                const raw = await fs.readFile(configPath, "utf8");
+                config = path.extname(configPath).toLowerCase() === ".json5"
+                    ? JSON5.parse(raw)
+                    : JSON.parse(raw);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to read or parse config at ${configPath}: ${err.message}`,
+                        },
+                    ],
+                };
+            }
+        }
+        const findings = lintConfig(config);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        clean: findings.length === 0,
+                        findings,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/resolveConfig.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
 import { locateConfig } from "../lib/configLocations.js";
 import { resolveConfig } from "../lib/presetResolver.js";
+const MERGE_QUALITY = "preview";
+const MERGE_DISCLAIMER = "Preset expansion uses a simplified merge (arrays concat, objects merge, scalars overwrite). Run dry_run for authoritative output — hostRules, regexManagers, and some boolean flags merge with rule-specific semantics that are not modeled here.";
 export function registerResolveConfig(server) {
     server.registerTool("resolve_config", {
         title: "Resolve Renovate config (expand presets)",
-        description: "Expand every preset referenced by `extends` and return the fully resolved config. Built-in presets resolve offline against the committed catalogue. Pass `externalPresets: true` to fetch `github>` and `gitlab>` presets over HTTPS (with optional `GITHUB_TOKEN` / `GITLAB_TOKEN` / `RENOVATE_TOKEN` for private repos). For GitHub Enterprise or self-hosted GitLab, pass `endpoint` (API base URL, e.g. `https://ghe.example.com/api/v3` or `https://gitlab.example.com/api/v4`); pass `platform` in addition to route `local>` presets through the same endpoint. `bitbucket>`, `gitea>`, and npm presets are structurally unsupported and remain in `presetsUnresolved` regardless. Endpoint and platform are **tool inputs only** — env vars like `RENOVATE_ENDPOINT` are not read, since the MCP server runs under Claude rather than in your shell. Pass either `repoPath` (reads the repo's config) or `configContent` (an inline config object).",
+        description: "Expand every preset referenced by `extends` and return the fully resolved config. Built-in presets resolve offline against the committed catalogue. Pass `externalPresets: true` to fetch `github>` and `gitlab>` presets over HTTPS (with optional `RENOVATE_TOKEN` — or `GITHUB_TOKEN` / `GITLAB_TOKEN` as platform-specific fallbacks — for private repos). For GitHub Enterprise or self-hosted GitLab, pass `endpoint` (API base URL, e.g. `https://ghe.example.com/api/v3` or `https://gitlab.example.com/api/v4`); pass `platform` in addition to route `local>` presets through the same endpoint. `bitbucket>`, `gitea>`, and npm presets are structurally unsupported and remain in `presetsUnresolved` regardless. Endpoint and platform are **tool inputs only** — env vars like `RENOVATE_ENDPOINT` are not read, since the MCP server runs under Claude rather than in your shell. Pass either `repoPath` (reads the repo's config) or `configContent` (an inline config object). The response includes `mergeQuality: \"preview\"` plus a `disclaimer` and a `warnings` array — preset merging here is a close approximation of Renovate's rules rather than bit-identical, and Handlebars expressions other than `{{argN}}` are left verbatim; run `dry_run` for authoritative output.",
         inputSchema: {
             repoPath: z
                 .string()
@@ -17,7 +19,7 @@ export function registerResolveConfig(server) {
             externalPresets: z
                 .boolean()
                 .optional()
-                .describe("When true, fetch external presets (github>, gitlab>) over HTTPS. Credentials come from GITHUB_TOKEN / GITLAB_TOKEN / RENOVATE_TOKEN env vars set on the MCP server process — via the `env` key in claude_desktop_config.json / .mcp.json, not your shell, since the MCP server runs as a child of Claude and does not inherit shell env. Default false."),
+                .describe("When true, fetch external presets (github>, gitlab>) over HTTPS. Credentials come from RENOVATE_TOKEN (preferred, matches Renovate's own convention) or GITHUB_TOKEN / GITLAB_TOKEN as platform-specific fallbacks, set on the MCP server process — via the `env` key in claude_desktop_config.json / .mcp.json, not your shell, since the MCP server runs as a child of Claude and does not inherit shell env. Default false."),
             endpoint: z
                 .string()
                 .optional()
@@ -56,7 +58,7 @@ export function registerResolveConfig(server) {
             source = located.config;
             sourcePath = located.relPath;
         }
-        const { resolved, presetsResolved, presetsUnresolved } = await resolveConfig(source, {
+        const { resolved, presetsResolved, presetsUnresolved, warnings } = await resolveConfig(source, {
             fetchExternal: externalPresets ?? false,
             endpoint,
             platform,
@@ -68,8 +70,11 @@ export function registerResolveConfig(server) {
                     text: JSON.stringify({
                         ...(sourcePath ? { path: sourcePath } : {}),
                         resolved,
+                        mergeQuality: MERGE_QUALITY,
+                        disclaimer: MERGE_DISCLAIMER,
                         presetsResolved,
                         presetsUnresolved,
+                        warnings,
                     }, null, 2),
                 },
             ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "renovate-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for designing Renovate configurations interactively.",
   "type": "module",
   "bin": {