renovate-mcp 0.5.0 → 0.6.0

package/README.md

@@ -31,7 +31,7 @@ Eight tools plus a preset reference:
 | `preview_custom_manager` | Preview a `customManagers` (regex) entry against a local repo — shows file/line hits and extracted dep info. Offline. |
 | `validate_config` | Run `renovate-config-validator` against a file or inline object. |
 | `lint_config` | Semantic lint for Renovate-specific footguns schema validation misses (mostly malformed `/…/` regex patterns). Offline. |
-| `dry_run` | Run Renovate with `--platform=local --dry-run` and return the structured JSON report. No PRs, no pushes. Emits MCP progress notifications during the run when the caller supplies a `progressToken`. |
+| `dry_run` | Run Renovate with `--dry-run` and return the structured JSON report. Defaults to `--platform=local` against `repoPath`; pass `platform` + `endpoint` + `token` + `repository` to run as a real GitHub/GitLab client (needed when the config extends `local>` presets on a private host). No PRs, no pushes. Emits MCP progress notifications during the run when the caller supplies a `progressToken`. |
 | `write_config` | Validate, then atomically write a config to disk. Refuses to save invalid configs unless `force: true`. |
 | `renovate://presets` (resource) | Markdown index of all 1000+ built-in presets grouped by namespace. |
 | `renovate://presets/{namespace}` (resource template) | Markdown listing for a single namespace (e.g. `renovate://presets/config`) — cheaper than the full index. |
@@ -125,6 +125,7 @@ Once the server is wired up, try prompts like these. They're written for Claude
 
 - "Resolve my config with external presets enabled, fetching `gitlab>platform/renovate-presets` from our self-hosted GitLab at `https://gitlab.example.com/api/v4`. Route `local>` presets through the same host."
 - "Expand `github>acme/renovate-config//base` from our GitHub Enterprise at `https://github.acme.corp/api/v3`."
+- "Dry-run `devops/gitops` against our self-hosted GitLab at `https://gitlab.example.com/api/v4` — use `platform=gitlab` with my token so Renovate can fetch the `local>` presets the config extends."
 
 (Reminder: auth tokens must be set on the MCP server process — via the `env` key in `.mcp.json` / `claude_desktop_config.json`, not your shell.)
 
@@ -209,6 +210,8 @@ Scope and non-goals are summarized in [What this is NOT](#what-this-is-not); thi
 - `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.
 - `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.
+- `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 the `RENOVATE_CONFIG_FILE` env var (the CLI has no `--config-file` flag), and deleted in a `finally` block. Token/password values — including the platform `token` input — are scrubbed from the detected `problems` list and the `logTail` fallback before returning.
+- `dry_run` defaults to `--platform=local` so no host token is required, but that mode can't resolve `local>` presets (they have no platform context to expand against) and silently hides non-default-host GitHub/GitLab setups. Passing `platform` + `endpoint` + `token` + `repository` switches the run to a real platform client so the preset-fetch path works end-to-end; `--dry-run` is still set, so no PRs are opened. As a guard against the silent-failure mode, `dry_run` preflight-checks the repo's config: if it extends any `local>…` preset while the effective platform is `local`, the tool fails fast with specific remediation rather than spawning a Renovate run that would opaquely report `config-validation`.
+- `dry_run` returns a top-level `ok` boolean that is `false` whenever the CLI exited non-zero OR the structured report contains a validation/error-level problem (`level >= 40`, `message === "config-validation"`, or a non-empty `validationError` field). Renovate frequently writes exit-code 0 alongside report-level failures — trusting the exit code alone hides runs that did nothing.
 - `dry_run` emits MCP progress notifications only when the caller's `tools/call` includes `_meta.progressToken` — no-op otherwise, so legacy clients see zero overhead. A 5-second heartbeat ticks while the child runs; each tick's message is best-effort enriched with the latest Renovate JSON-log `msg` seen on stdout. Notifications are also emitted at start and completion. We deliberately don't couple to Renovate's log schema beyond reading `msg`, since that schema isn't a stable API.
 - `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

@@ -33,7 +33,7 @@ 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.5.0"; // x-release-please-version
+const SERVER_VERSION = "0.6.0"; // x-release-please-version
 const server = new McpServer({ name: "renovate-mcp", version: SERVER_VERSION }, { instructions });
 registerCheckSetup(server);
 registerReadConfig(server);

package/dist/lib/hostRulesConfig.d.ts

@@ -5,8 +5,10 @@ export type HostRule = Record<string, unknown>;
  * 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
+ * The caller points Renovate at this file via the `RENOVATE_CONFIG_FILE` env
+ * var (not a CLI flag — `--config-file` is not a real Renovate option).
+ * Renovate merges its rules with any repo-level `hostRules` via 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>;

package/dist/lib/hostRulesConfig.js

@@ -8,8 +8,10 @@ import { randomUUID } from "node:crypto";
  * 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
+ * The caller points Renovate at this file via the `RENOVATE_CONFIG_FILE` env
+ * var (not a CLI flag — `--config-file` is not a real Renovate option).
+ * Renovate merges its rules with any repo-level `hostRules` via 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) {

package/dist/tools/dryRun.js

@@ -4,18 +4,94 @@ 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 { locateConfig } from "../lib/configLocations.js";
 import { detectLookupProblems } from "../lib/lookupProblems.js";
 import { collectSecrets, scrubSecrets, writeHostRulesConfig, } from "../lib/hostRulesConfig.js";
 import { extractRenovateLogMsg, buildDryRunHeartbeatMessage, } from "../lib/dryRunProgress.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.");
+/**
+ * Walk Renovate's JSON report looking for `problems` arrays and collect the
+ * ones that represent failed runs — not informational notices. Criteria:
+ *   - `level >= 40` (Renovate's bunyan-derived ERROR/FATAL bands), or
+ *   - `message === "config-validation"` (Renovate's canonical config-failure
+ *     marker — it can appear with lower levels but still means the run was
+ *     effectively a no-op), or
+ *   - the problem object has a `validationError` field (preset/extends
+ *     resolution failures carry their explanation here).
+ *
+ * The report shape isn't a stable Renovate API, so we walk defensively: any
+ * nested `problems` array anywhere in the tree is inspected.
+ */
+function collectReportErrors(report) {
+    const out = [];
+    const seen = new Set();
+    const visit = (node) => {
+        if (node === null || typeof node !== "object")
+            return;
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (const entry of node)
+                visit(entry);
+            return;
+        }
+        const obj = node;
+        const problems = obj.problems;
+        if (Array.isArray(problems)) {
+            for (const raw of problems) {
+                if (!raw || typeof raw !== "object")
+                    continue;
+                const p = raw;
+                const level = typeof p.level === "number" ? p.level : 0;
+                const isErrorLevel = level >= 40;
+                const isConfigValidation = p.message === "config-validation";
+                const hasValidationError = typeof p.validationError === "string" && p.validationError.length > 0;
+                if (isErrorLevel || isConfigValidation || hasValidationError) {
+                    out.push(p);
+                }
+            }
+        }
+        for (const value of Object.values(obj))
+            visit(value);
+    };
+    visit(report);
+    return out;
+}
+/**
+ * Scan the repo's Renovate config for `extends` entries of the form
+ * `local>owner/repo[:preset]` and return them along with the config-file path
+ * they were found in. Returns `null` if no config is found (Renovate will
+ * handle that case itself with its usual error). Silently returns `null` on
+ * parse errors too — we don't want preflight to be stricter than Renovate's
+ * own config loader; any real problems will surface when Renovate runs.
+ */
+async function detectUnresolvableLocalPresets(repoPath) {
+    let located;
+    try {
+        located = await locateConfig(repoPath);
+    }
+    catch {
+        return null;
+    }
+    if (!located)
+        return null;
+    const extendsRaw = located.config.extends;
+    if (!Array.isArray(extendsRaw))
+        return null;
+    const presets = extendsRaw.filter((entry) => typeof entry === "string" && entry.startsWith("local>"));
+    return { relPath: located.relPath, presets };
+}
 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.\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.",
+        description: "Run Renovate in dry-run mode to preview what it would do — no PRs opened, no git pushes. Returns a structured JSON report plus a top-level `ok` boolean (false when the CLI failed OR the report records a validation/error-level problem, even if the exit code was 0).\n\nDefault mode runs `--platform=local` against the filesystem at `repoPath`. If your config extends `local>…` presets (or any preset hosted on a non-default GitHub/GitLab), pass `platform` (`github` or `gitlab`), `endpoint` (API base URL), `token`, and `repository` (`owner/repo`) to run as a real platform client that can actually fetch those presets — Renovate still runs with `--dry-run`, so no PRs are opened. The tool preflight-checks for `local>` presets under `--platform=local` and fails fast with remediation guidance rather than spawning a Renovate run that would fail opaquely with `config-validation`.\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 — including the platform `token` input — 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"),
+            repoPath: z
+                .string()
+                .describe("Absolute path to the repository root. Required for the default `platform=local` mode. When `platform` is overridden (e.g. `gitlab` / `github`), Renovate runs against the remote `repository` instead — `repoPath` is still used as the child's working directory but its manifest files are ignored."),
             dryRunMode: z
                 .enum(["extract", "lookup", "full"])
                 .default("full")
@@ -28,17 +104,72 @@ export function registerDryRun(server) {
                 .max(15 * 60_000)
                 .default(5 * 60_000)
                 .describe("Max wait time in ms (default 5 minutes, capped at 15)"),
+            platform: z
+                .enum(["local", "github", "gitlab"])
+                .optional()
+                .describe("Renovate platform to run as. Default `local` runs against the filesystem at `repoPath`. Set `github` or `gitlab` (with `endpoint` + `token` + `repository`) to run a full remote dry-run — this is what you need when your config extends `local>` presets that live on a private GitHub Enterprise / self-hosted GitLab. Still no PRs opened because `--dry-run` is always set."),
+            endpoint: z
+                .string()
+                .optional()
+                .describe("API base URL for the chosen platform (e.g. `https://gitlab.example.com/api/v4/` or `https://ghe.example.com/api/v3/`). Required with non-default GitHub/GitLab hosts. Ignored when `platform=local`."),
+            token: z
+                .string()
+                .optional()
+                .describe("Platform auth token. Scrubbed from any log output this tool returns. Ignored when `platform=local`."),
+            repository: z
+                .string()
+                .optional()
+                .describe("`owner/repo` identifier of the repository Renovate should operate on. Required when `platform` is not `local`. Ignored when `platform=local`."),
             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."),
+                .describe("Optional per-invocation Renovate hostRules for private registry auth. Written to a mode-0600 temp file that is passed via the RENOVATE_CONFIG_FILE env var 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, hostRules }, extra) => {
+    }, async ({ repoPath, dryRunMode, logLevel, timeoutMs, platform, endpoint, token, repository, hostRules }, extra) => {
         const reportPath = path.join(tmpdir(), `renovate-mcp-report-${randomUUID()}.json`);
         const bin = resolveRenovateTool("renovate");
         const ruleList = hostRules ?? [];
+        const effectivePlatform = platform ?? "local";
+        const isRemotePlatform = effectivePlatform !== "local";
         const secrets = collectSecrets(ruleList);
+        if (token)
+            secrets.push(token);
         let hostRulesConfigPath;
+        if (isRemotePlatform && !repository) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `\`repository\` is required when \`platform\` is \`${effectivePlatform}\`. Pass the target repo as \`owner/repo\`, or unset \`platform\` to run against the local filesystem at \`repoPath\`.`,
+                    },
+                ],
+            };
+        }
+        // Preflight: if the repo's config extends any `local>…` preset and we're
+        // about to run with `--platform=local`, Renovate will fail opaquely with
+        // a generic "config-validation" error, because `local>` has no platform
+        // context to resolve against in local mode. Detect this up front and
+        // return an actionable message instead of spawning Renovate.
+        if (!isRemotePlatform) {
+            const unresolvable = await detectUnresolvableLocalPresets(repoPath);
+            if (unresolvable && unresolvable.presets.length > 0) {
+                const sample = unresolvable.presets.slice(0, 3).join(", ");
+                const more = unresolvable.presets.length > 3
+                    ? ` (+${unresolvable.presets.length - 3} more)`
+                    : "";
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: `\`${unresolvable.relPath}\` extends \`local>\` presets (${sample}${more}) that cannot be resolved under \`--platform=local\` — Renovate has no platform context to expand them against, so the run would fail with an opaque \`config-validation\` error.\n\n` +
+                                `To fix: pass \`platform\` (e.g. \`gitlab\` or \`github\`), \`endpoint\`, \`token\`, and \`repository\` so Renovate runs as a real platform client and can fetch the preset. Alternatively, rewrite the \`extends\` entries from \`local>…\` to \`gitlab>…\` / \`github>…\` in your config.`,
+                        },
+                    ],
+                };
+            }
+        }
         // Hybrid progress reporter: a heartbeat tick every HEARTBEAT_MS keeps
         // MCP clients informed during long runs, and each tick enriches its
         // message with the latest Renovate JSON-log `msg` we saw (best-effort —
@@ -67,14 +198,28 @@ export function registerDryRun(server) {
         };
         try {
             const args = [
-                "--platform=local",
+                `--platform=${effectivePlatform}`,
                 `--dry-run=${dryRunMode}`,
                 "--report-type=file",
                 `--report-path=${reportPath}`,
             ];
+            const childEnv = {
+                LOG_LEVEL: logLevel,
+                LOG_FORMAT: "json",
+            };
+            if (isRemotePlatform) {
+                if (endpoint)
+                    args.push(`--endpoint=${endpoint}`);
+                args.push(`--repository=${repository}`);
+                if (token)
+                    childEnv.RENOVATE_TOKEN = token;
+            }
             if (ruleList.length > 0) {
                 hostRulesConfigPath = await writeHostRulesConfig(ruleList);
-                args.push(`--config-file=${hostRulesConfigPath}`);
+                // Renovate reads this config file via the RENOVATE_CONFIG_FILE env
+                // var, not a CLI flag — `--config-file` is not a real Renovate flag
+                // and passing it crashes the CLI with "unknown option".
+                childEnv.RENOVATE_CONFIG_FILE = hostRulesConfigPath;
             }
             if (progressEnabled) {
                 emit(`Starting Renovate dry-run (${dryRunMode})`);
@@ -82,7 +227,7 @@ export function registerDryRun(server) {
             }
             const result = await run(bin, args, {
                 cwd: repoPath,
-                env: { LOG_LEVEL: logLevel, LOG_FORMAT: "json" },
+                env: childEnv,
                 timeoutMs,
                 onStdoutLine: progressEnabled
                     ? (line) => {
@@ -104,7 +249,15 @@ export function registerDryRun(server) {
             catch {
                 // no report produced (e.g., renovate errored before writing)
             }
+            const reportErrors = collectReportErrors(report);
             const summary = {
+                // `ok` collapses the three failure modes (spawn error, non-zero
+                // exit, in-report validation/error-level problems) into a single
+                // field so callers don't need to know which one fired. Renovate
+                // frequently writes a report with exitCode=0 while its `problems`
+                // array records a validation/config failure — judging only by
+                // exitCode hides those runs.
+                ok: result.exitCode === 0 && reportErrors.length === 0,
                 exitCode: result.exitCode,
                 hasReport: report !== null,
                 report,
@@ -115,6 +268,9 @@ export function registerDryRun(server) {
             if (problems.length > 0) {
                 summary.problems = problems;
             }
+            if (reportErrors.length > 0) {
+                summary.reportErrors = reportErrors;
+            }
             // 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) {
@@ -137,7 +293,7 @@ export function registerDryRun(server) {
                         text: JSON.stringify(summary, null, 2),
                     },
                 ],
-                isError: result.exitCode !== 0,
+                isError: !summary.ok,
             };
         }
         catch (err) {

package/package.json

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