renovate-mcp 1.6.8 → 1.7.1

package/README.md

@@ -9,24 +9,15 @@ An MCP server for designing [Renovate](https://github.com/renovatebot/renovate)
 
 ## Quick start
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/tibuntu/renovate-mcp/main/install.sh | bash
-```
-
-Or add this entry manually to your client's `mcpServers` config:
+Needs Node.js ≥ 24.11 on Linux or macOS. With [Claude Code](https://docs.claude.com/en/docs/claude-code):
 
-```json
-{
-  "mcpServers": {
-    "renovate": {
-      "command": "npx",
-      "args": ["-y", "renovate-mcp"]
-    }
-  }
-}
+```bash
+npm install -g renovate-mcp
+claude mcp add renovate -s user -- renovate-mcp
+claude mcp list   # renovate should show as connected
 ```
 
-Restart your client and try the prompt: *"List the namespaces available under `renovate://presets`."* A response listing `config`, `docker`, `npm`, … confirms the server is reachable. Long-form install options are under [Install](#install) below.
+Then try the prompt: *"List the namespaces available under `renovate://presets`."* A response listing `config`, `docker`, `npm`, … confirms the server is reachable. No tokens are needed for the offline tools. Other clients, tokens and upgrades are under [Install](#install) below.
 
 ## What you can do
 
@@ -39,7 +30,7 @@ Restart your client and try the prompt: *"List the namespaces available under `r
 
 ## Tools & resources
 
-Seventeen tools, six resources, and three workflow prompts. Each tool name below links to its full reference in [`docs/tools.md`](docs/tools.md).
+Eighteen tools, seven resources, and four workflow prompts. Each tool name below links to its full reference in [`docs/tools.md`](docs/tools.md).
 
 | Tool | Purpose |
 | --- | --- |
@@ -47,10 +38,10 @@ Seventeen tools, six resources, and three workflow prompts. Each tool name below
 | [`get_version`](docs/tools.md#get_version) | Report the renovate-mcp server version and whether it's a released or local/dev build. |
 | [`read_config`](docs/tools.md#read_config) | Locate and parse a repo's Renovate config in Renovate's own discovery order. |
 | [`suggest_presets`](docs/tools.md#suggest_presets) | Search built-in (and optional local-repo) presets by natural-language intent; ranks matches and sketches an unvalidated draft config skeleton for multi-facet or weakly-covered intents. Offline. |
-| [`resolve_config`](docs/tools.md#resolve_config) | Expand every `extends` preset offline. Opt in to fetching `github>` / `gitlab>` presets over HTTPS. |
+| [`resolve_config`](docs/tools.md#resolve_config) | Expand every `extends` preset offline. Opt in to fetching `github>` / `gitlab>` / `gitea>` / `forgejo>` presets over HTTPS, or Bitbucket Cloud presets via `local>` + `platform`. |
 | [`explain_config`](docs/tools.md#explain_config) | Inverse of `resolve_config`: annotate every leaf field with the chain of presets that set it. |
 | [`resolve_config_diff`](docs/tools.md#resolve_config_diff) | Offline structural diff of two fully-resolved configs — changed fields plus an order-insensitive set diff of array keys (`packageRules`, `customManagers`, …). The refactor-friendly counterpart to `dry_run_diff`. |
-| [`test_package_rules`](docs/tools.md#test_package_rules) | Offline what-if: which `packageRules` match a hypothetical dependency, which matcher decided each, and what each contributes. Faithful (Renovate's real matchers in a worker); fields you don't supply are reported as unevaluatable, not non-matches. |
+| [`test_package_rules`](docs/tools.md#test_package_rules) | Offline what-if: which `packageRules` match a hypothetical dependency, which matcher decided each, and what each contributes — plus the `branchName` / `commitMessage` / `prTitle` the matched config would render for it. Faithful matching (Renovate's real matchers in a worker); fields you don't supply are reported as unevaluatable, not non-matches, and the rendered names list the post-lookup template variables they could not fill. |
 | [`preview_custom_manager`](docs/tools.md#preview_custom_manager) | Preview a `customManagers` entry (regex or JSONata) against a local repo. Offline. |
 | [`validate_config`](docs/tools.md#validate_config) | Run `renovate-config-validator` against a file or inline object. |
 | [`lint_config`](docs/tools.md#lint_config) | Semantic lint pass for Renovate-specific footguns the schema validator declares valid. Offline. |
@@ -58,6 +49,7 @@ Seventeen tools, six resources, and three workflow prompts. Each tool name below
 | [`dry_run_diff`](docs/tools.md#dry_run_diff) | Stateless semantic diff between two `dry_run` reports — added / removed / changed updates. |
 | [`annotate_dry_run`](docs/tools.md#annotate_dry_run) | Attribute each proposed update in a `dry_run` report to the `packageRules` that caused it; flags rules that never matched and report fields the matchers needed but the report lacked. Stateless + offline. |
 | [`explain_dependency`](docs/tools.md#explain_dependency) | Answer "why was/wasn't dependency X updated?" from a `dry_run` report: per-occurrence `skipReason`, proposed `updates`, `warnings`, a one-line verdict and remedy hints; optionally the `packageRules` that matched it. Stateless + offline. |
+| [`explain_schedule`](docs/tools.md#explain_schedule) | Answer "when will this `schedule` actually run?": active-now plus the next run windows in UTC and the config's `timezone`, computed with Renovate's own schedule matcher; invalid schedules return Renovate's message and the fact that it then runs at any time. Offline. |
 | [`migrate_config`](docs/tools.md#migrate_config) | Apply Renovate's built-in migrations and return the migrated config plus a unified diff. Does not write. |
 | [`write_config`](docs/tools.md#write_config) | Validate, then atomically write a config to disk. Preserves comments/key order on existing JSON-with-comments files; for `package.json` edits only the nested `renovate` key. |
 | [`renovate://presets`](docs/tools.md#renovatepresets) (resource) | Markdown index of all built-in presets grouped by namespace. |
@@ -66,21 +58,23 @@ Seventeen tools, six resources, and three workflow prompts. Each tool name below
 | [`renovate://options`](docs/tools.md#renovateoptions) (resource) | Markdown index of all Renovate config options, split into repository and global/self-hosted-only sections. |
 | [`renovate://option/{name}`](docs/tools.md#renovateoptionname) (resource) | Full definition of one config option as JSON. |
 | [`renovate://managers`](docs/tools.md#renovatemanagers) (resource) | Markdown list of all manager names, including custom managers. |
+| [`renovate://datasources`](docs/tools.md#renovatedatasources) (resource) | Markdown list of all built-in datasource ids. |
 
-**Prompts.** Three workflow prompts package the tool sequences above into ready-to-run starting points. Claude Code surfaces MCP prompts as slash commands (e.g. `/mcp__renovate__design-renovate-config`); other MCP clients expose them through their own prompt picker.
+**Prompts.** Four workflow prompts package the tool sequences above into ready-to-run starting points. Claude Code surfaces MCP prompts as slash commands (e.g. `/mcp__renovate__design-renovate-config`); other MCP clients expose them through their own prompt picker.
 
 | Prompt | Drives |
 | --- | --- |
 | [`design-renovate-config`](docs/tools.md#design-renovate-config) | `check_setup` → `read_config` → `suggest_presets` → `resolve_config`/`explain_config` → `validate_config`/`lint_config` → `dry_run` → `write_config` on confirmation. |
-| [`debug-package-rule`](docs/tools.md#debug-package-rule) | `check_setup` → `read_config` → `test_package_rules` → `dry_run` (with `reportOutputPath`) → `annotate_dry_run` → `explain_dependency` → a verdict naming rule indices and matchers. |
+| [`debug-package-rule`](docs/tools.md#debug-package-rule) | `check_setup` → `read_config` → `test_package_rules` (matches + rendered names) → `dry_run` (with `reportOutputPath`) → `annotate_dry_run` → `explain_dependency` → a verdict naming rule indices and matchers. |
 | [`author-custom-manager`](docs/tools.md#author-custom-manager) | Draft a `customManagers` entry → `preview_custom_manager` iteratively → `validate_config`/`lint_config` → `dry_run` → `write_config` on confirmation. |
+| [`onboard-repo`](docs/tools.md#onboard-repo) | For repos without a config: `check_setup` → `read_config` (expect none) → `dry_run` (extract mode) → `suggest_presets` → `lint_config`/`validate_config` → `write_config` on confirmation → full `dry_run`. |
 
 ## Requirements
 
 - **Linux or macOS.** Windows is not supported — `package.json` declares `"os": ["darwin", "linux"]`, so `npm i` surfaces an `EBADPLATFORM` warning on Windows and the server exits with a clear stderr message at startup. Use WSL2 or a Linux/macOS host instead.
 - **Node.js ≥ 24.11** (aligns with Renovate's own engine requirement).
 
-Renovate ships bundled — the `renovate` package is a runtime dependency, so `validate_config`, `dry_run`, and `write_config` work out of the box with no separate install. The offline tools (`read_config`, `suggest_presets`, `resolve_config`, `explain_config`, `resolve_config_diff`, `test_package_rules`, `preview_custom_manager`, `lint_config`, `dry_run_diff`, `annotate_dry_run`, `explain_dependency`, `migrate_config`) never spawn Renovate at all — nor do `check_setup` (by default it reads version metadata from the bundled install instead of spawning) or `get_version` (it only reports the renovate-mcp server's own version).
+Renovate ships bundled — the `renovate` package is a runtime dependency, so `validate_config`, `dry_run`, and `write_config` work out of the box with no separate install. The offline tools (`read_config`, `suggest_presets`, `resolve_config`, `explain_config`, `resolve_config_diff`, `test_package_rules`, `preview_custom_manager`, `lint_config`, `dry_run_diff`, `annotate_dry_run`, `explain_dependency`, `explain_schedule`, `migrate_config`) never spawn Renovate at all — nor do `check_setup` (by default it reads version metadata from the bundled install instead of spawning) or `get_version` (it only reports the renovate-mcp server's own version).
 
 **Optional env vars:**
 
@@ -93,30 +87,76 @@ Renovate ships bundled — the `renovate` package is a runtime dependency, so `v
 
 ## Install
 
-### Quick install
+### 1. Install the package
+
+```bash
+npm install -g renovate-mcp
+```
+
+Install before you register the server. The package bundles Renovate (about 670 packages, 350 MB), so a client that starts `npx -y renovate-mcp` against a cold npm cache downloads all of that during server startup and can time out.
+
+Upgrade with `npm install -g renovate-mcp@latest` and restart your client. With nvm or fnm, global packages belong to one Node version — reinstall after switching.
+
+### 2. Register it with your client
+
+**Claude Code:**
+
+```bash
+claude mcp add renovate -s user -- renovate-mcp
+```
+
+`-s user` makes the server available in every project. Leave it out to register it for the current project only, or use `-s project` to write a shared `.mcp.json`.
+
+**Claude Desktop and other GUI clients** don't load your shell's PATH, so with nvm, fnm or Homebrew they may find no Node or an older one. Use absolute paths:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/tibuntu/renovate-mcp/main/install.sh | bash
+which node                                        # → "command"
+echo "$(npm root -g)/renovate-mcp/dist/index.js"  # → "args"
 ```
 
-The script checks Node ≥ 24, asks whether you want `npx`-on-demand or a global install, runs an MCP `initialize` handshake to verify the binary works, and — when the Claude Code CLI is on PATH — auto-registers `renovate` in user scope via `claude mcp add`. Useful flags (pass after `bash -s --`): `--global`, `--npx`, `--no-mcp-add`, `--mcp-scope=user|project|local`, `--version=X.Y.Z`. The same flags are also accepted as env vars (`RENOVATE_MCP_GLOBAL=1`, `RENOVATE_MCP_NO_MCP_ADD=1`, `RENOVATE_MCP_VERSION=…`).
+Claude Desktop reads `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
-### Manual install
+```json
+{
+  "mcpServers": {
+    "renovate": {
+      "command": "/Users/you/.nvm/versions/node/v24.14.1/bin/node",
+      "args": ["/Users/you/.nvm/versions/node/v24.14.1/lib/node_modules/renovate-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Any other client that can launch a stdio MCP server works with the same command.
 
-`npx` fetches the [published package](https://www.npmjs.com/package/renovate-mcp) on demand — no manual install needed. For local development, clone and build first:
+### 3. Add tokens (optional)
+
+The offline tools need nothing. Add env vars only for what you use:
+
+| Use case | Env vars |
+| --- | --- |
+| Local `dry_run` on a repo with github.com dependencies | `GITHUB_COM_TOKEN` (read-only PAT, avoids anonymous rate limits) |
+| `dry_run` against GitHub, or private `github>` presets | `RENOVATE_PLATFORM=github` + `GITHUB_TOKEN` |
+| `dry_run` against GitLab, or private `gitlab>` presets | `RENOVATE_PLATFORM=gitlab` + `GITLAB_TOKEN` |
+
+Self-hosted GitLab and GitHub Enterprise also need `RENOVATE_ENDPOINT` — see [Platform setup](#platform-setup).
+
+In Claude Code, re-register with `-e`:
 
 ```bash
-npm install
-npm run build
+claude mcp remove renovate -s user
+claude mcp add renovate -s user -e GITHUB_COM_TOKEN=ghp_xxx -- renovate-mcp
 ```
 
-### Client config locations
+- `-e` stores the value in plain text in `~/.claude.json`. Keep tokens in `user` or `local` scope, never in a `project`-scope `.mcp.json` that gets committed.
+- `-e` accepts several values, so keep the `--` before `renovate-mcp`.
+- Other clients take the same variables in an `"env": { … }` block next to `"args"`.
 
-- **Claude Code** — `.mcp.json` (project) or `~/.claude.json` (user).
-- **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`.
-- **Other MCP clients** — any client that can launch a stdio MCP server works; point it at the same `npx -y renovate-mcp` command.
+### Alternatives
 
-For local development, swap to `"command": "node"` with `"args": ["/absolute/path/to/renovate-mcp/dist/index.js"]`.
+- **npx without a global install** — register `npx -y renovate-mcp` instead, after warming the npm cache once with `npm exec --yes --package=renovate-mcp -- node -e 0`.
+- **Installer script** — `curl -fsSL https://raw.githubusercontent.com/tibuntu/renovate-mcp/main/install.sh | bash` runs steps 1 and 2 interactively: it checks Node, asks for `npx` or global mode, verifies the server with an MCP `initialize` handshake, and registers it via `claude mcp add` when the Claude Code CLI is on PATH. Flags (after `bash -s --`): `--global`, `--npx`, `--no-mcp-add`, `--mcp-scope=user|project|local`, `--version=X.Y.Z`; also accepted as env vars (`RENOVATE_MCP_GLOBAL=1`, `RENOVATE_MCP_NO_MCP_ADD=1`, `RENOVATE_MCP_VERSION=…`).
+- **From source** — clone, run `npm install && npm run build`, and point your client at `node /absolute/path/to/renovate-mcp/dist/index.js`.
 
 ## Platform setup
 
@@ -128,6 +168,11 @@ For `dry_run` against a remote platform or `resolve_config` with `externalPreset
 | GitHub Enterprise | `github` | `https://github.example.com/api/v3/` | `RENOVATE_TOKEN` *or* `GITHUB_TOKEN` |
 | gitlab.com | `gitlab` | (omit) | `RENOVATE_TOKEN` *or* `GITLAB_TOKEN` |
 | Self-hosted GitLab | `gitlab` | `https://gitlab.example.com/api/v4/` | `RENOVATE_TOKEN` *or* `GITLAB_TOKEN` |
+| gitea.com / Forgejo (code.forgejo.org) | — | (omit) | `RENOVATE_TOKEN` *or* `GITEA_TOKEN` / `FORGEJO_TOKEN` |
+| Self-hosted Gitea / Forgejo | — | `https://forgejo.example.com/api/v1/` | `RENOVATE_TOKEN` *or* `GITEA_TOKEN` / `FORGEJO_TOKEN` |
+| Bitbucket Cloud | — | (omit) | `RENOVATE_TOKEN` *or* `BITBUCKET_TOKEN` |
+
+The Gitea / Forgejo / Bitbucket Cloud rows apply to the `resolve_config` family only: `dry_run` runs Renovate as `local` / `github` / `gitlab` and never reads those tokens. Pass `platform` (`gitea` / `forgejo` / `bitbucket`) and `endpoint` as tool inputs instead of `RENOVATE_PLATFORM` / `RENOVATE_ENDPOINT`.
 
 See [`docs/platform-setup.md`](docs/platform-setup.md) for a worked self-hosted GitLab example, `local>` preset handling, and private-registry credentials.
 
@@ -208,6 +253,7 @@ npm run generate:presets        # regenerate src/data/presets.generated.ts
 npm run generate:managers       # regenerate src/data/managers.generated.ts
 npm run generate:migrations     # regenerate src/data/migrations.generated.ts
 npm run generate:options        # regenerate src/data/options.generated.ts
+npm run generate:datasources    # regenerate src/data/datasources.generated.ts
 npm run sync:jsonata-pin        # sync package.json's jsonata pin to Renovate's own
 npm run check:snapshot-versions # fail if any src/data/*.generated.ts is stale vs installed renovate
 ```
@@ -228,4 +274,4 @@ See [`docs/development.md`](docs/development.md) for snapshot-file mechanics, CI
 - **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` merges faithfully.** Preset expansion runs offline against a committed snapshot, then folds with Renovate's real `mergeChildConfig` in a worker thread — `mergeQuality: "faithful"` (it falls back to an approximate in-process merge as `"preview"` only if the worker is unavailable). Template substitution still implements only positional `{{argN}}` placeholders — non-positional tokens and Handlebars helpers are flagged in `warnings` and pass through verbatim. For full config resolution (datasource lookups, etc.), run `dry_run`.
 - **`preview_custom_manager` is a subset of Renovate's custom managers.** It covers `customType: "regex"` (with `matchStringsStrategy` of `any` / `combination` / `recursive`) and `customType: "jsonata"` (with `fileFormat: "json" | "yaml" | "toml"`). File selection follows Renovate's `managerFilePatterns` semantics (globs or `/regex/`, entries unioned like Renovate's extract phase); the deprecated `fileMatch` is still accepted with a warning. Template substitution is `{{groupName}}` only — full Handlebars helpers/conditionals are not implemented. Other custom types (e.g. `html`) are out of scope. Use it for fast iteration; confirm with `dry_run`. Full coverage matrix in [`docs/tools.md#preview_custom_manager`](docs/tools.md#preview_custom_manager).
-- **`dry_run` still uses fake binaries in CI.** The bundled Renovate is available (it's a runtime dependency), and `validate_config` / `write_config` now have one real-validator integration test (`test/integration/realValidator.test.ts`) exercising the actual bundled `renovate-config-validator` — but `dry_run` itself still runs per-PR against fake binaries via `RENOVATE_BIN` / `RENOVATE_CONFIG_VALIDATOR_BIN` env overrides, for determinism and speed. A separate nightly workflow re-runs the full suite against `renovate@latest` end-to-end. Run `dry_run` locally against a real config to validate behaviour.
+- **`dry_run` still uses fake binaries in CI.** The bundled Renovate is available (it's a runtime dependency), and `validate_config` / `write_config` have real-validator integration tests (`test/integration/realValidator.test.ts`) exercising the actual bundled `renovate-config-validator` — but `dry_run` itself still runs per-PR against fake binaries via `RENOVATE_BIN` / `RENOVATE_CONFIG_VALIDATOR_BIN` env overrides, for determinism and speed. A separate nightly workflow re-runs the full suite against `renovate@latest` end-to-end. Run `dry_run` locally against a real config to validate behaviour.

package/dist/data/datasources.generated.js

@@ -0,0 +1,92 @@
+// AUTO-GENERATED by scripts/generate-datasources.mjs from renovate@44.181.5.
+// Do not edit by hand. Run `npm run generate:datasources` to refresh.
+export const RENOVATE_VERSION = "44.181.5";
+/**
+ * All built-in datasource ids accepted by Renovate's `matchDatasources` and
+ * `customManagers[].datasourceTemplate`. Custom datasources (`custom.<name>`)
+ * are not listed.
+ */
+export const DATASOURCES = Object.freeze([
+    "apk",
+    "artifactory",
+    "aws-eks-addon",
+    "aws-machine-image",
+    "aws-rds",
+    "azure-bicep-resource",
+    "azure-pipelines-tasks",
+    "azure-tags",
+    "bazel",
+    "bitbucket-server-tags",
+    "bitbucket-tags",
+    "bitrise",
+    "buildpacks-registry",
+    "cdnjs",
+    "clojure",
+    "conan",
+    "conda",
+    "cpan",
+    "crate",
+    "custom",
+    "dart",
+    "dart-version",
+    "deb",
+    "deno",
+    "devbox",
+    "docker",
+    "dotnet-version",
+    "elm-package",
+    "endoflife-date",
+    "flutter-version",
+    "forgejo-releases",
+    "forgejo-tags",
+    "galaxy",
+    "galaxy-collection",
+    "git-refs",
+    "git-tags",
+    "gitea-releases",
+    "gitea-tags",
+    "github-digest",
+    "github-release-attachments",
+    "github-releases",
+    "github-runners",
+    "github-tags",
+    "gitlab-packages",
+    "gitlab-releases",
+    "gitlab-tags",
+    "glasskube-packages",
+    "go",
+    "golang-version",
+    "gradle-version",
+    "hackage",
+    "helm",
+    "hermit",
+    "hex",
+    "hexpm-bob",
+    "java-version",
+    "jenkins-plugins",
+    "jsr",
+    "kubernetes-api",
+    "maven",
+    "nextcloud",
+    "node-version",
+    "npm",
+    "nuget",
+    "orb",
+    "packagist",
+    "pod",
+    "puppet-forge",
+    "pypi",
+    "python-version",
+    "repology",
+    "rpm",
+    "ruby-version",
+    "rubygems",
+    "rust-version",
+    "sbt-package",
+    "sbt-plugin",
+    "terraform-module",
+    "terraform-provider",
+    "typst",
+    "unity3d",
+    "unity3d-packages"
+]);

package/dist/index.js

@@ -15,6 +15,7 @@ import { registerDryRunDiff } from "./tools/dryRunDiff.js";
 import { registerTestPackageRules } from "./tools/testPackageRules.js";
 import { registerAnnotateDryRun } from "./tools/annotateDryRun.js";
 import { registerExplainDependency } from "./tools/explainDependency.js";
+import { registerExplainSchedule } from "./tools/explainSchedule.js";
 import { registerWriteConfig } from "./tools/writeConfig.js";
 import { registerMigrateConfig } from "./tools/migrateConfig.js";
 import { registerGetVersion } from "./tools/getVersion.js";
@@ -50,13 +51,14 @@ const BASE_INSTRUCTIONS = [
     " 11. dry_run_diff           — semantic diff between two dry_run reports (added/removed/changed updates)",
     " 12. annotate_dry_run       — attribute each proposed update in a dry_run report to the packageRules that caused it (and flag rules that never matched)",
     " 13. explain_dependency     — why was/wasn't a given dependency updated: skipReason, updates, warnings and matched rules, read from a dry_run report (offline)",
-    " 14. migrate_config         — apply Renovate's built-in migrations (deprecated keys → current schema) and return the migrated config",
-    " 15. write_config           — save the agreed-upon config (validates first)",
+    " 14. explain_schedule       — when will a `schedule` actually run: active-now plus the next windows in UTC and the config's timezone, or Renovate's own invalid-schedule message (offline)",
+    " 15. migrate_config         — apply Renovate's built-in migrations (deprecated keys → current schema) and return the migrated config",
+    " 16. write_config           — save the agreed-upon config (validates first)",
     "",
     "Before the first repo-touching tool call in a session (read_config, resolve_config, dry_run, write_config, …), call check_setup with the same repoPath. It surfaces token / endpoint / connectivity problems up front (e.g. \"set GITHUB_TOKEN or github-actions deps will be skipped\") instead of waiting for dry_run to fail. Skip if the user has already confirmed setup or is doing offline-only work that doesn't depend on git origin or registries.",
     "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).",
-    "Config option reference: renovate://options (index of all config options), renovate://option/{name} (one option's full definition). Manager names: renovate://managers.",
+    "Config option reference: renovate://options (index of all config options), renovate://option/{name} (one option's full definition). Manager names: renovate://managers. Datasource ids: renovate://datasources.",
 ].join("\n");
 if (process.platform === "win32") {
     process.stderr.write("renovate-mcp does not support Windows. Supported platforms are Linux and macOS — see the `os` field in package.json. Run on WSL2 or a Linux/macOS host instead.\n");
@@ -84,6 +86,7 @@ registerDryRunDiff(server);
 registerTestPackageRules(server);
 registerAnnotateDryRun(server);
 registerExplainDependency(server);
+registerExplainSchedule(server);
 registerMigrateConfig(server);
 registerWriteConfig(server);
 registerGetVersion(server);

package/dist/lib/configLinter.js

@@ -1,4 +1,5 @@
 import { ALL_MANAGERS, CUSTOM_MANAGERS } from "../data/managers.generated.js";
+import { DATASOURCES } from "../data/datasources.generated.js";
 import { DEPRECATED_KEYS, } from "../data/migrations.generated.js";
 import { isRecord } from "./util.js";
 const REGEX_AWARE_FIELDS = new Set([
@@ -12,23 +13,28 @@ const VALID_MANAGER_NAMES = new Set([
     ...ALL_MANAGERS,
     ...CUSTOM_MANAGERS.map((m) => `custom.${m}`),
 ]);
+const VALID_DATASOURCES = new Set(DATASOURCES);
 const DEPRECATED_KEY_LOOKUP = new Map(DEPRECATED_KEYS.map((e) => [e.oldKey, e]));
 // Hand-maintained snapshot of keys that count as "actions" on a packageRules entry
 // (i.e. keys whose presence means the rule actually *does* something to the matched
 // deps). Source of truth: `node_modules/renovate/dist/config/options/index.js` —
 // entries whose `parents` array includes `"packageRules"`, plus the broader set of
 // inheritable config options Renovate allows inside a packageRules entry
-// (groupName, automerge, labels, schedule, …). Reconciled against renovate@43.150.0.
-// Bumping the `renovate` devDep should prompt a manual re-check. We deliberately do
-// NOT generate this list at build time: per CLAUDE.md, the linter must stay
-// independent of the runtime `renovate` import, so this stays a curated snapshot
-// — analogous to the other allow-lists under `src/data/`.
+// (groupName, automerge, labels, schedule, …). We deliberately do NOT generate this
+// list at build time: per CLAUDE.md, the linter must stay independent of the runtime
+// `renovate` import, so this stays a curated snapshot — analogous to the other
+// allow-lists under `src/data/`. Drift guard: test/unit/allowListDrift.test.ts checks
+// every entry against the installed Renovate's option registry (real option, not
+// global-only, `scopes` allow packageRules) and that every packageRules-only option
+// is listed, so a `renovate` bump fails there instead of leaving this stale.
 //
 // Explicitly NOT in this set (kept here as documentation):
 //   - `description` (metadata)
 //   - every `match*` / `exclude*` key (selectors)
 //   - `paths` / `excludePaths` (path-scope selectors)
 //   - `matchJsonata`, `matchNewValue`, `matchCurrentAge` etc. (selectors)
+//   - `vulnerabilityAlerts`, `dependencyDashboardLabels` (Renovate's option `scopes`
+//     restrict them to the top level; its validator warns inside a packageRule)
 //   - `changelogUrl`, `sourceDirectory`, `sourceUrl` (metadata/locator overrides —
 //     treated as actions below since they actively override resolved fields)
 export const PACKAGE_RULE_ACTION_KEYS = new Set([
@@ -51,7 +57,6 @@ export const PACKAGE_RULE_ACTION_KEYS = new Set([
     "commitMessageSuffix",
     "commitMessageTopic",
     "dependencyDashboardApproval",
-    "dependencyDashboardLabels",
     "draftPR",
     "enabled",
     "extends",
@@ -102,7 +107,6 @@ export const PACKAGE_RULE_ACTION_KEYS = new Set([
     "sourceUrl",
     "stopUpdatingLabel",
     "versioning",
-    "vulnerabilityAlerts",
 ]);
 const DEPRECATED_KEY_CONTAINERS = ["packageRules", "hostRules", "customManagers"];
 // Schedule-validation heuristic. Behavioral source of truth:
@@ -121,6 +125,9 @@ const DEPRECATED_KEY_CONTAINERS = ["packageRules", "hostRules", "customManagers"
 // a deliberate bias toward false negatives over false positives: a non-later
 // string that happens to contain one of these anchor tokens gets a free pass,
 // but every plausible later-text input will contain at least one of them.
+// Drift guard: test/unit/allowListDrift.test.ts parses each token (in a minimal
+// phrase) with the `@breejs/later` Renovate ships, so a token the grammar does
+// not know can't sneak in or linger after a bump.
 // Special-cased sentinels meaning "no schedule". Renovate treats these as
 // always-on.
 const SCHEDULE_ANY_TIME = new Set(["", "at any time"]);
@@ -132,12 +139,10 @@ const SCHEDULE_MAPPING_LITERALS = new Set([
 ]);
 // Lowercase tokens. Presence of at least one (whole-word, case-insensitive)
 // makes a non-cron string plausibly-later-text. Curated from later's grammar.
-const LATER_TEXT_ANCHOR_TOKENS = new Set([
+export const LATER_TEXT_ANCHOR_TOKENS = new Set([
     // Time anchors
     "am",
     "pm",
-    "noon",
-    "midnight",
     "before",
     "after",
     "between",
@@ -181,10 +186,7 @@ const LATER_TEXT_ANCHOR_TOKENS = new Set([
     "feb",
     "mar",
     "apr",
-    "jun",
-    "jul",
     "aug",
-    "sep",
     "sept",
     "oct",
     "nov",
@@ -195,9 +197,7 @@ const LATER_TEXT_ANCHOR_TOKENS = new Set([
     "week",
     "weeks",
     "weekday",
-    "weekdays",
     "weekend",
-    "weekends",
     "month",
     "months",
     "year",
@@ -206,9 +206,6 @@ const LATER_TEXT_ANCHOR_TOKENS = new Set([
     "hours",
     "minute",
     "minutes",
-    "morning",
-    "evening",
-    "night",
 ]);
 // Cron-shape: 5 or 6 whitespace-separated fields, every char in `[0-9*/,\-]`,
 // FIRST field is exactly `*` (Renovate explicitly rejects non-`*` minutes).
@@ -241,6 +238,9 @@ export function lintConfig(config) {
     checkAutomergeIncludesMajor(config, findings);
     checkDuplicatePackageRuleMatchers(config, findings);
     checkHostRuleInlineSecret(config, findings);
+    checkDatasourceTemplates(config, findings);
+    checkScheduleWithoutTimezone(config, findings);
+    checkPackageRuleLabelsOverrides(config, findings);
     return findings;
 }
 function isSelectorKey(key) {
@@ -422,6 +422,76 @@ function checkDuplicatePackageRuleMatchers(config, findings) {
         }
     }
 }
+// First `schedule` entry (anywhere in the tree, same reach as `invalid-schedule`)
+// that actually restricts timing, as [path, value].
+function findRestrictingSchedule(node, pathStr) {
+    if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i++) {
+            const hit = findRestrictingSchedule(node[i], `${pathStr}[${i}]`);
+            if (hit)
+                return hit;
+        }
+        return null;
+    }
+    if (!isRecord(node))
+        return null;
+    for (const [key, value] of Object.entries(node)) {
+        const childPath = pathStr ? `${pathStr}.${key}` : key;
+        if (key === "schedule") {
+            if (typeof value === "string" && !SCHEDULE_ANY_TIME.has(value)) {
+                return [childPath, value];
+            }
+            if (Array.isArray(value)) {
+                const i = value.findIndex((v) => typeof v === "string" && !SCHEDULE_ANY_TIME.has(v));
+                if (i !== -1)
+                    return [`${childPath}[${i}]`, value[i]];
+            }
+            continue;
+        }
+        const hit = findRestrictingSchedule(value, childPath);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+function checkScheduleWithoutTimezone(config, findings) {
+    if (!isRecord(config) || config.timezone)
+        return;
+    const hit = findRestrictingSchedule(config, "");
+    if (!hit)
+        return;
+    const [path, value] = hit;
+    // One finding per config: the fix (a root `timezone`) is the same for all.
+    findings.push({
+        ruleId: "schedule-without-timezone",
+        severity: "warn",
+        path,
+        value,
+        message: `${path} sets a schedule but the root config has no \`timezone\`, so Renovate evaluates every schedule in UTC. ` +
+            "Ignore this if an extended preset sets the timezone.",
+        suggestion: 'Set a top-level "timezone" to an IANA name, e.g. "Europe/Berlin".',
+    });
+}
+function checkPackageRuleLabelsOverrides(config, findings) {
+    if (!isRecord(config))
+        return;
+    if (!Array.isArray(config.labels) || config.labels.length === 0)
+        return;
+    if (!Array.isArray(config.packageRules))
+        return;
+    config.packageRules.forEach((entry, i) => {
+        if (!isRecord(entry) || !("labels" in entry))
+            return;
+        findings.push({
+            ruleId: "package-rule-labels-overrides",
+            severity: "warn",
+            path: `packageRules[${i}].labels`,
+            value: JSON.stringify(entry.labels),
+            message: `packageRules[${i}].labels replaces the root labels (${JSON.stringify(config.labels)}) for matched deps instead of adding to them.`,
+            suggestion: `Use addLabels in packageRules[${i}] to append to the root labels.`,
+        });
+    });
+}
 const HOST_RULE_SECRET_FIELDS = ["token", "password"];
 function checkHostRuleInlineSecret(config, findings) {
     if (!isRecord(config))
@@ -537,6 +607,18 @@ function walk(node, pathStr, findings) {
                     });
                 }
             }
+            else if (key === "matchDatasources") {
+                if (Array.isArray(value)) {
+                    value.forEach((entry, i) => {
+                        if (typeof entry === "string") {
+                            checkDatasource(entry, `${childPath}[${i}]`, findings);
+                        }
+                    });
+                }
+                else if (typeof value === "string") {
+                    checkDatasource(value, childPath, findings);
+                }
+            }
             else if (MANAGER_FIELDS.has(key)) {
                 if (Array.isArray(value)) {
                     value.forEach((entry, i) => {
@@ -604,26 +686,73 @@ function checkSchedule(value, path, findings) {
             "preset such as `schedule:earlyMondays`.",
     });
 }
+// Renovate evaluates matchManagers and matchDatasources with
+// matchRegexOrGlobList: `/…/` (optionally `/…/i`) is a regex and anything with
+// glob metachars is a glob — neither is a literal id to check against a list.
+// Deliberately permissive: a typo that happens to contain a glob char (e.g.
+// `docker[`) is skipped rather than risk an error-severity finding on a valid glob.
+function isRegexOrGlobEntry(name) {
+    return /^\/.+\/i?$/.test(name) || /[*?[\]{}]/.test(name);
+}
 function checkManager(raw, path, findings) {
-    if (VALID_MANAGER_NAMES.has(raw))
+    // `!` is Renovate's negation prefix for every matchRegexOrGlobList field.
+    const name = raw.startsWith("!") ? raw.slice(1) : raw;
+    if (VALID_MANAGER_NAMES.has(name) || isRegexOrGlobEntry(name))
         return;
-    const suggestion = nearestManager(raw);
+    const suggestion = nearestName(name, VALID_MANAGER_NAMES);
     const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
     const finding = {
         ruleId: "matchManagers-unknown-name",
         severity: "error",
         path,
         value: raw,
-        message: `'${raw}' is not a known Renovate manager. Renovate will silently apply this rule to zero packages.${hint}`,
+        message: `'${name}' is not a known Renovate manager. Renovate will silently apply this rule to zero packages.${hint}`,
+    };
+    if (suggestion)
+        finding.suggestion = suggestion;
+    findings.push(finding);
+}
+function checkDatasourceTemplates(config, findings) {
+    if (!isRecord(config) || !Array.isArray(config.customManagers))
+        return;
+    config.customManagers.forEach((entry, i) => {
+        if (!isRecord(entry))
+            return;
+        const tpl = entry.datasourceTemplate;
+        // A templated value is resolved per match; only a literal id can be checked.
+        // A literal template is an id, never a pattern, so no `!` / regex / glob leniency.
+        if (typeof tpl !== "string" || tpl.includes("{{"))
+            return;
+        checkDatasource(tpl, `customManagers[${i}].datasourceTemplate`, findings, false);
+    });
+}
+function checkDatasource(raw, path, findings, isPattern = true) {
+    // Renovate matches `matchDatasources` via matchRegexOrGlobList: `!` negates,
+    // `/…/` is a regex and anything with glob metachars is a glob — none of those
+    // are literal ids. `custom.<name>` routes to the user's customDatasources.
+    const name = isPattern && raw.startsWith("!") ? raw.slice(1) : raw;
+    if (VALID_DATASOURCES.has(name) ||
+        name.startsWith("custom.") ||
+        (isPattern && isRegexOrGlobEntry(name))) {
+        return;
+    }
+    const suggestion = nearestName(name, VALID_DATASOURCES);
+    const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
+    const finding = {
+        ruleId: "matchDatasources-unknown-name",
+        severity: "error",
+        path,
+        value: raw,
+        message: `'${name}' is not a known Renovate datasource. Renovate does not validate datasource ids, so this silently matches (or looks up) nothing.${hint}`,
     };
     if (suggestion)
         finding.suggestion = suggestion;
     findings.push(finding);
 }
-function nearestManager(name) {
+function nearestName(name, candidates) {
     let best = null;
     let bestDistance = Infinity;
-    for (const candidate of VALID_MANAGER_NAMES) {
+    for (const candidate of candidates) {
         const d = damerauLevenshtein(name, candidate);
         if (d < bestDistance) {
             bestDistance = d;