renovate-mcp 0.7.0 → 0.8.0

package/README.md

@@ -22,7 +22,7 @@ An MCP server for designing [Renovate](https://github.com/renovatebot/renovate)
 
 ## What it does
 
-Ten tools plus a preset reference:
+Eleven tools plus a preset reference:
 
 | Tool | Purpose |
 | --- | --- |
@@ -30,6 +30,7 @@ Ten tools plus a preset reference:
 | `get_version` | Report the renovate-mcp server version and whether it's a released build (running from `node_modules`) or a local/dev build (typically launched via `command: node` against a checkout). |
 | `read_config` | Locate and parse a repo's Renovate config (`renovate.json`, `renovate.json5`, `.renovaterc*`, `package.json#renovate`, …) in priority order. |
 | `resolve_config` | Expand every `extends` preset offline. Opt in to fetching `github>` / `gitlab>` presets over HTTPS with `externalPresets: true`. |
+| `explain_config` | Inverse of `resolve_config`: walk the same preset tree but annotate every leaf field with the chain of presets that touched it. Each leaf is `{ value, setBy }` where `setBy` lists every contribution in merge order — last entry wins for scalars; for arrays each entry adds its own slice. Same offline-by-default behaviour and same `externalPresets` / `endpoint` / `platform` opt-ins as `resolve_config`. |
 | `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 — malformed `/…/` regex patterns plus unknown manager names in `matchManagers` / `excludeManagers`. Offline. |
@@ -46,7 +47,7 @@ See [Design notes](#design-notes) for implementation details (timeouts, safety c
 
 - **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`.
+- **`preview_custom_manager` is a subset of Renovate's regex manager.** It covers `customType: "regex"`, `matchStringsStrategy` of `any` / `combination` / `recursive`, and `{{groupName}}` template substitution only — other custom types 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
@@ -162,6 +163,7 @@ Once the server is wired up, try prompts like these. They're written for Claude
 
 - "Read the Renovate config in this repo and summarize what it actually does — expand every preset so I can see the real effective behavior."
 - "Resolve my config and list anything that landed in `presetsUnresolved`, with the reason for each."
+- "Why is my `prCreation` set to `not-pending`? Use `explain_config` to trace which preset set it."
 
 **Browsing presets**
 
@@ -230,6 +232,8 @@ The preset catalogue at `src/data/presets.generated.ts` and the manager-name lis
 
 CI runs `typecheck`, `build`, and `test:coverage` on Node 24 for every PR and push to `main` (see `.github/workflows/ci.yml`). Coverage is uploaded as a per-run artifact; no threshold is enforced yet.
 
+`.github/workflows/claude.yml` is maintainer tooling: it lets the repo owner trigger [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) by mentioning `@claude` in an issue, issue comment, PR review, or PR review comment. It's gated on `sender.login == repository_owner`, so mentions from anyone else are ignored. The workflow needs the `CLAUDE_CODE_OAUTH_TOKEN` secret on the repo; outside contributors and forks do not need any Anthropic credentials to work on this project.
+
 ## Release flow
 
 Releases are automated via [release-please](https://github.com/googleapis/release-please) (see `.github/workflows/release.yaml`):
@@ -257,6 +261,7 @@ 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.
+- `explain_config` reuses the same expansion machinery as `resolve_config` (`parsePreset`, `loadPresetBody`, `applyArgs`, `recordTemplateWarnings`) so the two can't drift — if `resolve_config` resolves a preset, `explain_config` does too. The annotated layer threads each preset body's leaves through a parallel `mergeAnnotated` that preserves contributors instead of dropping them, then pins each contribution with the source name (literal `extends` entry, or `<own>` for the user's input config) and a `via` chain naming every parent preset traversed to reach it. Arrays accumulate every contribution in `setBy` and concat their `value`s; scalars list every contribution in merge order with the last as the winner. `merge_quality: "preview"` carries the same disclaimer as `resolve_config` — Renovate's rule-specific semantics for `hostRules`, `regexManagers`, and certain boolean flags aren't modelled.
 - `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. When the caller doesn't pass a `platform` input, the tool first falls back to `RENOVATE_PLATFORM` from the MCP server's env (if it's one of `local`/`github`/`gitlab`) before defaulting to `local` — without that fallback, the wrapper would unconditionally pass `--platform=local` and silently override an env var the user had set in their `mcp.json`. Passing `platform` + `endpoint` + `token` + `repository` (or relying on the `RENOVATE_PLATFORM` / `RENOVATE_ENDPOINT` env vars) 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. The repository is passed to Renovate as a positional argument because the CLI has no `--repository` flag. `endpoint` and `token` are also forwarded in the default `platform=local` mode so `gitlab>…` / `github>…` preset shortcuts (which are otherwise hardcoded to gitlab.com/github.com) can be redirected at a self-hosted host. 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`. The preflight is skipped for `dryRunMode=extract` so manifest-only extraction can still be attempted.
 - `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.

package/dist/data/presets.generated.d.ts

@@ -3,6 +3,6 @@ export interface GeneratedPreset {
     description: string | null;
     body: Record<string, unknown>;
 }
-export declare const RENOVATE_VERSION = "43.139.5";
+export declare const RENOVATE_VERSION = "43.141.5";
 export declare const PRESETS: Record<string, GeneratedPreset>;
 export declare const PRESET_NAMES: readonly string[];

package/dist/data/presets.generated.js

@@ -1,6 +1,6 @@
 // AUTO-GENERATED by scripts/generate-presets.mjs from renovate@43.139.5.
 // Do not edit by hand. Run `npm run generate:presets` to refresh.
-export const RENOVATE_VERSION = "43.139.5";
+export const RENOVATE_VERSION = "43.141.5";
 export const PRESETS = {
     "abandonments:recommended": {
         "namespace": "abandonments",

package/dist/index.js

@@ -6,6 +6,7 @@ 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 { registerExplainConfig } from "./tools/explainConfig.js";
 import { registerPreviewCustomManager } from "./tools/previewCustomManager.js";
 import { registerDryRun } from "./tools/dryRun.js";
 import { registerDryRunDiff } from "./tools/dryRunDiff.js";
@@ -20,12 +21,13 @@ const BASE_INSTRUCTIONS = [
     "Workflow:",
     "  1. read_config            — inspect the current config in a repo",
     "  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. 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. dry_run_diff           — semantic diff between two dry_run reports (added/removed/changed updates)",
-    "  8. write_config           — save the agreed-upon config (validates first)",
+    "  3. explain_config         — inverse of resolve_config: trace which preset set each field (offline)",
+    "  4. preview_custom_manager — iterate on a regex-based customManagers entry; shows file/line hits and extracted deps",
+    "  5. validate_config        — check a proposed config against Renovate's schema",
+    "  6. lint_config            — semantic lint pass: catches Renovate-specific footguns schema validation misses (e.g. malformed /…/ regex patterns)",
+    "  7. dry_run                — preview what Renovate would actually do (no PRs)",
+    "  8. dry_run_diff           — semantic diff between two dry_run reports (added/removed/changed updates)",
+    "  9. 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).",
@@ -41,6 +43,7 @@ const server = new McpServer({ name: "renovate-mcp", version: SERVER_VERSION },
 registerCheckSetup(server);
 registerReadConfig(server);
 registerResolveConfig(server);
+registerExplainConfig(server);
 registerPreviewCustomManager(server);
 registerValidateConfig(server);
 registerLintConfig(server);

package/dist/lib/configExplainer.d.ts

@@ -0,0 +1,64 @@
+import { type PresetWarning, type ResolveOptions, type UnresolvedPreset } from "./presetResolver.js";
+/**
+ * Sentinel used as the `source` of contributions that come from the user's own
+ * input config (i.e. the keys siblings of `extends`, not from any preset).
+ * Distinguishable from any real preset name because angle brackets cannot
+ * appear in a Renovate preset reference.
+ */
+export declare const OWN_SOURCE = "<own>";
+export interface Contribution {
+    /**
+     * Where the value came from. `<own>` for the user's input config; otherwise
+     * the preset reference exactly as it appeared in `extends` (e.g.
+     * `config:recommended`, `:automergeAll`, `github>acme/renovate-config`).
+     */
+    source: string;
+    /**
+     * Path of presets that brought this contribution in, outermost first. Empty
+     * when the value comes from `<own>` or from a top-level entry in the user's
+     * `extends`. For nested presets, lists every parent preset between the
+     * user's root and `source`.
+     */
+    via: string[];
+    /**
+     * The exact value `source` contributed at the point of the merge — for
+     * scalars this is the value `source` set, before any later preset/own
+     * override; for arrays this is just the slice `source` added.
+     */
+    value: unknown;
+}
+export type AnnotatedNode = AnnotatedLeaf | AnnotatedObject;
+export interface AnnotatedLeaf {
+    /**
+     * Final merged value of this field. Last `setBy` entry is the winner for
+     * scalars; for arrays, every contribution's `value` is concatenated into
+     * `value`.
+     */
+    value: unknown;
+    /**
+     * Contributions in merge order. The last entry is the winner for scalars;
+     * for arrays each entry adds its own slice to `value`.
+     */
+    setBy: Contribution[];
+}
+export type AnnotatedObject = {
+    [key: string]: AnnotatedNode;
+};
+export interface ExplainResult {
+    explanation: AnnotatedObject;
+    presetsResolved: string[];
+    presetsUnresolved: UnresolvedPreset[];
+    warnings: PresetWarning[];
+}
+/**
+ * Inverse of `resolveConfig`: walk the same preset tree but, instead of
+ * collapsing everything into a flat resolved object, annotate each leaf field
+ * with the chain of presets that touched it. The last entry in `setBy` is the
+ * winner; `value` is what `resolveConfig` would have returned.
+ *
+ * Sharing as much as possible with `presetResolver`'s expansion logic
+ * (`parsePreset`, `loadPresetBody`, `applyArgs`, `recordTemplateWarnings`) so
+ * the two tools stay consistent — if `resolve_config` resolves a preset,
+ * `explain_config` does too, by definition.
+ */
+export declare function explainConfig(config: Record<string, unknown>, options?: ResolveOptions): Promise<ExplainResult>;

package/dist/lib/configExplainer.js

@@ -0,0 +1,132 @@
+import { applyArgs, loadPresetBody, parsePreset, recordTemplateWarnings, } from "./presetResolver.js";
+/**
+ * Sentinel used as the `source` of contributions that come from the user's own
+ * input config (i.e. the keys siblings of `extends`, not from any preset).
+ * Distinguishable from any real preset name because angle brackets cannot
+ * appear in a Renovate preset reference.
+ */
+export const OWN_SOURCE = "<own>";
+/**
+ * Inverse of `resolveConfig`: walk the same preset tree but, instead of
+ * collapsing everything into a flat resolved object, annotate each leaf field
+ * with the chain of presets that touched it. The last entry in `setBy` is the
+ * winner; `value` is what `resolveConfig` would have returned.
+ *
+ * Sharing as much as possible with `presetResolver`'s expansion logic
+ * (`parsePreset`, `loadPresetBody`, `applyArgs`, `recordTemplateWarnings`) so
+ * the two tools stay consistent — if `resolve_config` resolves a preset,
+ * `explain_config` does too, by definition.
+ */
+export async function explainConfig(config, options = {}) {
+    const presetsResolved = [];
+    const presetsUnresolved = [];
+    const warnings = [];
+    const stack = [];
+    const ctx = {
+        fetchExternal: options.fetchExternal ?? false,
+        timeoutMs: options.timeoutMs,
+        endpoint: options.endpoint,
+        platform: options.platform,
+        cache: new Map(),
+    };
+    const annotated = await expandAnnotated(config, null, [], presetsResolved, presetsUnresolved, warnings, stack, ctx);
+    // The user's input is always a JSON object, so the root annotation is always
+    // an object, not a leaf. The cast is safe; falling back to `{}` is just
+    // defence in depth.
+    const explanation = isAnnotatedLeaf(annotated) ? {} : annotated;
+    return { explanation, presetsResolved, presetsUnresolved, warnings };
+}
+async function expandAnnotated(input, ownerName, viaChain, resolvedList, unresolvedList, warningsList, stack, ctx) {
+    let accumulated = {};
+    const rawExtends = input.extends;
+    if (Array.isArray(rawExtends) && rawExtends.length > 0) {
+        // Children of `input` are reached by going through `ownerName` (if any).
+        // The user's root has no name; for it `viaChain` and `childVia` are equal.
+        const childVia = ownerName === null ? viaChain : [...viaChain, ownerName];
+        for (const entry of rawExtends) {
+            if (typeof entry !== "string") {
+                unresolvedList.push({
+                    preset: String(entry),
+                    reason: "Preset entry must be a string.",
+                });
+                continue;
+            }
+            const parsed = parsePreset(entry);
+            if (stack.includes(parsed.key)) {
+                unresolvedList.push({
+                    preset: entry,
+                    reason: `Cycle detected: ${[...stack, parsed.key].join(" → ")}`,
+                });
+                continue;
+            }
+            const body = await loadPresetBody(parsed, ctx, unresolvedList);
+            if (!body)
+                continue;
+            const { value, missingArgs, unknownTemplates } = applyArgs(body, parsed.args);
+            recordTemplateWarnings(entry, parsed.args.length, missingArgs, unknownTemplates, warningsList);
+            stack.push(parsed.key);
+            const subNode = await expandAnnotated(value, entry, childVia, resolvedList, unresolvedList, warningsList, stack, ctx);
+            stack.pop();
+            accumulated = mergeAnnotated(accumulated, subNode);
+            resolvedList.push(entry);
+        }
+    }
+    const { extends: _drop, ...ownKeys } = input;
+    const source = ownerName ?? OWN_SOURCE;
+    const ownAnnotated = annotateValue(ownKeys, source, viaChain);
+    return mergeAnnotated(accumulated, ownAnnotated);
+}
+function annotateValue(value, source, via) {
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = annotateValue(v, source, via);
+        }
+        return out;
+    }
+    return { value, setBy: [{ source, via: [...via], value }] };
+}
+/**
+ * Mirrors `mergeConfig` in `presetResolver.ts`: arrays concat, plain objects
+ * recurse, everything else `b` wins. The annotated layer additionally keeps
+ * each contribution in `setBy` so callers can see the full chain that produced
+ * the final value.
+ */
+function mergeAnnotated(a, b) {
+    const aIsLeaf = isAnnotatedLeaf(a);
+    const bIsLeaf = isAnnotatedLeaf(b);
+    if (!aIsLeaf && !bIsLeaf) {
+        const out = { ...a };
+        for (const [k, bChild] of Object.entries(b)) {
+            const existing = out[k];
+            out[k] = existing ? mergeAnnotated(existing, bChild) : bChild;
+        }
+        return out;
+    }
+    if (aIsLeaf && bIsLeaf) {
+        if (Array.isArray(a.value) && Array.isArray(b.value)) {
+            return {
+                value: [...a.value, ...b.value],
+                setBy: [...a.setBy, ...b.setBy],
+            };
+        }
+        return {
+            value: b.value,
+            setBy: [...a.setBy, ...b.setBy],
+        };
+    }
+    // Mixed leaf / object — `b` wins entirely (matches `mergeConfig`'s "b wins
+    // unless both plain objects" rule). `a`'s contributions to the discarded
+    // shape are dropped, mirroring the resolved config losing them.
+    return b;
+}
+function isAnnotatedLeaf(node) {
+    if (typeof node !== "object" || node === null)
+        return false;
+    if (!("value" in node) || !("setBy" in node))
+        return false;
+    return Array.isArray(node.setBy);
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}

package/dist/lib/customManagerPreview.js

@@ -27,9 +27,7 @@ export async function previewCustomManager(repoPath, manager, options = {}) {
     const maxHitsPerFile = options.maxHitsPerFile ?? DEFAULT_MAX_HITS_PER_FILE;
     const matchTimeoutMs = options.matchTimeoutMs ?? DEFAULT_MATCH_TIMEOUT_MS;
     const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
-    if (manager.matchStringsStrategy && manager.matchStringsStrategy !== "any") {
-        warnings.push(`matchStringsStrategy='${manager.matchStringsStrategy}' is not yet supported by this preview tool; treating as 'any'. Run dry_run for full-fidelity behavior.`);
-    }
+    const strategy = resolveStrategy(manager.matchStringsStrategy, warnings);
     // Surface malformed user regexes eagerly, before we do any filesystem work.
     // The Worker path otherwise reports these as generic worker errors.
     for (const src of manager.fileMatch)
@@ -91,35 +89,162 @@ export async function previewCustomManager(repoPath, manager, options = {}) {
             warnings.push(`Could not read ${rel}: ${err.message}`);
             continue;
         }
-        let perFileHits = 0;
-        for (let i = 0; i < manager.matchStrings.length; i++) {
-            const source = manager.matchStrings[i];
-            const res = await runMatchAllInWorker(source, "gm", content, matchTimeoutMs);
-            if (res.timedOut) {
-                warnings.push(`${rel}: matchStrings[${i}] /${source}/ exceeded ${matchTimeoutMs}ms and was aborted; any matches in this file for this pattern were skipped. Simplify the regex (e.g. avoid nested quantifiers like (.*)*) or raise matchTimeoutMs.`);
-                continue;
-            }
-            for (const m of res.matches) {
-                if (perFileHits >= maxHitsPerFile) {
-                    warnings.push(`${rel}: capped at ${maxHitsPerFile} hits. Increase maxHitsPerFile to see more.`);
-                    break;
-                }
-                const line = lineNumberAt(content, m.index);
-                hits.push({
-                    file: rel,
-                    matchStringIndex: i,
-                    line,
-                    match: m.match,
-                    groups: m.groups,
-                });
-                extractedDeps.push(buildExtractedDep(rel, line, m.groups, manager));
-                perFileHits++;
-            }
-            if (perFileHits >= maxHitsPerFile)
+        const fileResult = await applyMatchStrings(rel, content, manager, strategy, matchTimeoutMs, maxHitsPerFile);
+        hits.push(...fileResult.hits);
+        extractedDeps.push(...fileResult.deps);
+        warnings.push(...fileResult.warnings);
+    }
+    return { filesWalked, filesMatched, hits, extractedDeps, warnings };
+}
+function resolveStrategy(raw, warnings) {
+    if (raw === undefined || raw === "any")
+        return "any";
+    if (raw === "combination" || raw === "recursive")
+        return raw;
+    warnings.push(`matchStringsStrategy='${raw}' is not supported by this preview tool; treating as 'any'. Run dry_run for full-fidelity behavior.`);
+    return "any";
+}
+async function applyMatchStrings(rel, content, manager, strategy, matchTimeoutMs, maxHitsPerFile) {
+    if (strategy === "combination") {
+        return applyCombination(rel, content, manager, matchTimeoutMs);
+    }
+    if (strategy === "recursive") {
+        return applyRecursive(rel, content, manager, matchTimeoutMs, maxHitsPerFile);
+    }
+    return applyAny(rel, content, manager, matchTimeoutMs, maxHitsPerFile);
+}
+async function applyAny(rel, content, manager, matchTimeoutMs, maxHitsPerFile) {
+    const hits = [];
+    const deps = [];
+    const warnings = [];
+    let perFileHits = 0;
+    for (let i = 0; i < manager.matchStrings.length; i++) {
+        const source = manager.matchStrings[i];
+        const res = await runMatchAllInWorker(source, "gm", content, matchTimeoutMs);
+        if (res.timedOut) {
+            warnings.push(`${rel}: matchStrings[${i}] /${source}/ exceeded ${matchTimeoutMs}ms and was aborted; any matches in this file for this pattern were skipped. Simplify the regex (e.g. avoid nested quantifiers like (.*)*) or raise matchTimeoutMs.`);
+            continue;
+        }
+        for (const m of res.matches) {
+            if (perFileHits >= maxHitsPerFile) {
+                warnings.push(`${rel}: capped at ${maxHitsPerFile} hits. Increase maxHitsPerFile to see more.`);
                 break;
+            }
+            const line = lineNumberAt(content, m.index);
+            hits.push({
+                file: rel,
+                matchStringIndex: i,
+                line,
+                match: m.match,
+                groups: m.groups,
+            });
+            deps.push(buildExtractedDep(rel, line, m.groups, manager));
+            perFileHits++;
         }
+        if (perFileHits >= maxHitsPerFile)
+            break;
+    }
+    return { hits, deps, warnings };
+}
+/**
+ * Mirrors Renovate's `handleCombination`: every matchString must hit at least
+ * once for the file to produce a dep; all matches' named groups are merged
+ * (later matches override earlier on key conflicts) into a single dep. We still
+ * surface every match as a `hit` so the user can see which lines contributed,
+ * but `extractedDeps` collapses to one entry per file.
+ */
+async function applyCombination(rel, content, manager, matchTimeoutMs) {
+    const hits = [];
+    const warnings = [];
+    const perStringMatches = [];
+    for (let i = 0; i < manager.matchStrings.length; i++) {
+        const source = manager.matchStrings[i];
+        const res = await runMatchAllInWorker(source, "gm", content, matchTimeoutMs);
+        if (res.timedOut) {
+            warnings.push(`${rel}: matchStrings[${i}] /${source}/ exceeded ${matchTimeoutMs}ms and was aborted; combination strategy could not produce a dep for this file. Simplify the regex or raise matchTimeoutMs.`);
+            return { hits: [], deps: [], warnings };
+        }
+        if (res.matches.length === 0) {
+            // Combination requires every matchString to hit at least once.
+            return { hits: [], deps: [], warnings };
+        }
+        perStringMatches.push(res.matches);
+        for (const m of res.matches) {
+            hits.push({
+                file: rel,
+                matchStringIndex: i,
+                line: lineNumberAt(content, m.index),
+                match: m.match,
+                groups: m.groups,
+            });
+        }
+    }
+    // Merge groups in match order across all matchStrings (later overrides earlier).
+    const mergedGroups = {};
+    for (const matches of perStringMatches) {
+        for (const m of matches)
+            Object.assign(mergedGroups, m.groups);
+    }
+    // Anchor the dep at the first match's line so the user can navigate to the file.
+    const firstHit = hits[0];
+    const deps = [buildExtractedDep(rel, firstHit.line, mergedGroups, manager)];
+    return { hits, deps, warnings };
+}
+/**
+ * Mirrors Renovate's `handleRecursive`: matchStrings[0] runs against the file,
+ * each match's text becomes the input for matchStrings[1], and so on. At the
+ * leaf level (after the last matchString), the merged groups from every level
+ * become a dep. Outer-level matches contribute groups but are not themselves
+ * deps; only the leaves are. `hits` reports the leaf-level matches with the
+ * merged groups, which matches the `any` strategy's "one hit per dep" shape.
+ */
+async function applyRecursive(rel, content, manager, matchTimeoutMs, maxHitsPerFile) {
+    const state = {
+        rel,
+        manager,
+        originalContent: content,
+        matchTimeoutMs,
+        maxHitsPerFile,
+        hits: [],
+        deps: [],
+        warnings: [],
+        capped: false,
+    };
+    await recurse(state, content, 0, 0, {});
+    return { hits: state.hits, deps: state.deps, warnings: state.warnings };
+}
+async function recurse(state, content, baseOffset, index, combinedGroups) {
+    if (state.capped)
+        return;
+    const { manager, rel } = state;
+    if (index === manager.matchStrings.length) {
+        if (state.deps.length >= state.maxHitsPerFile) {
+            state.warnings.push(`${rel}: capped at ${state.maxHitsPerFile} hits. Increase maxHitsPerFile to see more.`);
+            state.capped = true;
+            return;
+        }
+        const line = lineNumberAt(state.originalContent, baseOffset);
+        state.hits.push({
+            file: rel,
+            matchStringIndex: manager.matchStrings.length - 1,
+            line,
+            match: content,
+            groups: combinedGroups,
+        });
+        state.deps.push(buildExtractedDep(rel, line, combinedGroups, manager));
+        return;
+    }
+    const source = manager.matchStrings[index];
+    const res = await runMatchAllInWorker(source, "gm", content, state.matchTimeoutMs);
+    if (res.timedOut) {
+        state.warnings.push(`${rel}: matchStrings[${index}] /${source}/ exceeded ${state.matchTimeoutMs}ms and was aborted; any matches in this file for this pattern were skipped. Simplify the regex or raise matchTimeoutMs.`);
+        return;
+    }
+    for (const m of res.matches) {
+        if (state.capped)
+            return;
+        await recurse(state, m.match, baseOffset + m.index, index + 1, { ...combinedGroups, ...m.groups });
     }
-    return { filesWalked, filesMatched, hits, extractedDeps, warnings };
 }
 function buildExtractedDep(file, line, groups, manager) {
     const dep = { file, line };

package/dist/lib/presetResolver.d.ts

@@ -1,3 +1,4 @@
+import { type FetchResult } from "./externalPresetFetcher.js";
 export interface UnresolvedPreset {
     preset: string;
     reason: string;
@@ -76,6 +77,13 @@ export interface ParsedPreset {
      */
     unresolvableReason?: string;
 }
+export interface ExpandContext {
+    fetchExternal: boolean;
+    timeoutMs: number | undefined;
+    endpoint: string | undefined;
+    platform: FetchPlatform | undefined;
+    cache: Map<string, Promise<FetchResult>>;
+}
 /**
  * Resolve a Renovate config by expanding every preset in `extends`. Built-in
  * presets resolve offline against the committed catalogue; external presets
@@ -83,4 +91,14 @@ export interface ParsedPreset {
  * otherwise they land in `presetsUnresolved` with a network reason.
  */
 export declare function resolveConfig(config: Record<string, unknown>, options?: ResolveOptions): Promise<ResolveResult>;
+export declare function recordTemplateWarnings(entry: string, suppliedArgs: number, missingArgs: Set<number>, unknownTemplates: Set<string>, warningsList: PresetWarning[]): void;
+export declare function loadPresetBody(parsed: ParsedPreset, ctx: ExpandContext, unresolvedList: UnresolvedPreset[]): Promise<Record<string, unknown> | null>;
 export declare function parsePreset(raw: string): ParsedPreset;
+export interface ApplyArgsResult {
+    value: unknown;
+    /** Indices referenced by `{{argN}}` where N ≥ args.length. */
+    missingArgs: Set<number>;
+    /** Non-argN tokens (e.g. `{{packageRules}}`, block helpers) left verbatim. */
+    unknownTemplates: Set<string>;
+}
+export declare function applyArgs(value: unknown, args: string[]): ApplyArgsResult;

package/dist/lib/presetResolver.js

@@ -99,7 +99,7 @@ async function expand(input, resolvedList, unresolvedList, warningsList, stack,
     const { extends: _drop, ...ownKeys } = input;
     return mergeConfig(accumulated, ownKeys);
 }
-function recordTemplateWarnings(entry, suppliedArgs, missingArgs, unknownTemplates, warningsList) {
+export function recordTemplateWarnings(entry, suppliedArgs, missingArgs, unknownTemplates, warningsList) {
     for (const idx of [...missingArgs].sort((a, b) => a - b)) {
         warningsList.push({
             preset: entry,
@@ -117,7 +117,7 @@ function recordTemplateWarnings(entry, suppliedArgs, missingArgs, unknownTemplat
         });
     }
 }
-async function loadPresetBody(parsed, ctx, unresolvedList) {
+export async function loadPresetBody(parsed, ctx, unresolvedList) {
     if (parsed.unresolvableReason) {
         unresolvedList.push({ preset: parsed.original, reason: parsed.unresolvableReason });
         return null;
@@ -241,7 +241,7 @@ function parseExternal(rest, original, args, sourceRaw) {
         key += `#${ref}`;
     return { key, original, args, source, repoPath, presetName, subpath, ref };
 }
-function applyArgs(value, args) {
+export function applyArgs(value, args) {
     const missingArgs = new Set();
     const unknownTemplates = new Set();
     const out = applyArgsInner(value, args, missingArgs, unknownTemplates);

package/dist/lib/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SERVER_VERSION = "0.7.0";
+export declare const SERVER_VERSION = "0.8.0";
 export type BuildMode = "local" | "released";
 export interface VersionInfo {
     version: string;

package/dist/lib/version.js

@@ -1,5 +1,5 @@
 import { fileURLToPath } from "node:url";
-export const SERVER_VERSION = "0.7.0"; // x-release-please-version
+export const SERVER_VERSION = "0.8.0"; // x-release-please-version
 // "released" = the server is running from a `node_modules/` install (global
 // `npm i -g`, project-local `npm i`, or `npx renovate-mcp`). Anything else —
 // most commonly an MCP config of `{"command": "node", "args": [".../dist/index.js"]}`

package/dist/tools/explainConfig.d.ts

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

package/dist/tools/explainConfig.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { locateConfig } from "../lib/configLocations.js";
+import { explainConfig } from "../lib/configExplainer.js";
+const MERGE_QUALITY = "preview";
+const MERGE_DISCLAIMER = "Same simplified merge as resolve_config (arrays concat, objects merge, scalars overwrite). Renovate's rule-specific semantics for hostRules, regexManagers, and some boolean flags are not modelled — explanations of those keys are only as accurate as the merge.";
+export function registerExplainConfig(server) {
+    server.registerTool("explain_config", {
+        title: "Explain which preset set each field",
+        description: "Inverse of resolve_config: walk the same preset tree, but annotate every leaf field with the chain of presets that touched it. Each leaf in `explanation` carries `{ value, setBy }` where `setBy` lists every contribution in merge order — last entry wins for scalars; for arrays each entry adds its own slice. The `<own>` source means the value came from the user's input config (siblings of `extends`); other sources are preset references as written in `extends`. Use this to trace surprises like \"why is `prCreation` set to 'not-pending'?\". Pure analysis: same offline-by-default behaviour as resolve_config, plus the same `externalPresets` / `endpoint` / `platform` opt-ins. Pass `repoPath` (reads the repo's config) or `configContent` (an inline config). For full-fidelity output, run dry_run instead.",
+        inputSchema: {
+            repoPath: z
+                .string()
+                .optional()
+                .describe("Absolute path to the repository root. The tool will locate the repo's renovate config automatically."),
+            configContent: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Inline config object to explain — use instead of repoPath."),
+            externalPresets: z
+                .boolean()
+                .optional()
+                .describe("When true, fetch external presets (github>, gitlab>) over HTTPS — same credentials and behaviour as resolve_config. Default false."),
+            endpoint: z
+                .string()
+                .optional()
+                .describe("API base URL for github>/gitlab> fetches. Use for GitHub Enterprise or self-hosted GitLab — same semantics as resolve_config."),
+            platform: z
+                .enum(["github", "gitlab"])
+                .optional()
+                .describe("Platform flavour of `endpoint`. When set, `local>owner/repo` presets are routed through the same endpoint — same semantics as resolve_config."),
+        },
+    }, async ({ repoPath, configContent, externalPresets, endpoint, platform }) => {
+        if (!repoPath && !configContent) {
+            return {
+                isError: true,
+                content: [
+                    { type: "text", text: "Provide either repoPath or configContent." },
+                ],
+            };
+        }
+        let source;
+        let sourcePath;
+        if (configContent) {
+            source = configContent;
+        }
+        else {
+            const located = await locateConfig(repoPath);
+            if (!located) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No Renovate configuration found in ${repoPath}.`,
+                        },
+                    ],
+                };
+            }
+            source = located.config;
+            sourcePath = located.relPath;
+        }
+        const { explanation, presetsResolved, presetsUnresolved, warnings } = await explainConfig(source, {
+            fetchExternal: externalPresets ?? false,
+            endpoint,
+            platform,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ...(sourcePath ? { path: sourcePath } : {}),
+                        explanation,
+                        mergeQuality: MERGE_QUALITY,
+                        disclaimer: MERGE_DISCLAIMER,
+                        presetsResolved,
+                        presetsUnresolved,
+                        warnings,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "renovate-mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "MCP server for designing Renovate configurations interactively.",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "test:coverage": "vitest run --coverage",
     "generate:presets": "node scripts/generate-presets.mjs",
     "generate:managers": "node scripts/generate-managers.mjs",
-    "prepack": "npm run build && chmod +x dist/index.js"
+    "prepack": "npm run build && node -e \"if (!require('fs').readFileSync('dist/index.js','utf8').startsWith('#!')) { console.error('dist/index.js missing shebang'); process.exit(1); }\" && chmod +x dist/index.js"
   },
   "keywords": [
     "mcp",