renovate-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

MCP server that helps users design Renovate configurations interactively. TypeScript, Node ≥ 24 (aligns with Renovate's own engine requirement), built with @modelcontextprotocol/sdk 1.x, stdio transport.

Surface is intentionally small: sixteen tools (check_setup, read_config, suggest_presets, resolve_config, explain_config, resolve_config_diff, test_package_rules, preview_custom_manager, validate_config, lint_config, dry_run, dry_run_diff, annotate_dry_run, migrate_config, write_config, get_version) plus the renovate://presets resource family (namespace index, per-namespace listings, per-preset JSON). Don't grow this without a reason — the roadmap for expansion lives in the GitHub issues, not in ad-hoc additions.

Commands

npm install
npm run typecheck         # tsc --noEmit (covers src + test)
npm run build             # tsc -p tsconfig.build.json → dist/
npm run dev               # build watch mode
npm start                 # run built server over stdio
npm test                  # vitest run (auto-builds via pretest)
npm run test:watch        # vitest watch mode
npm run test:coverage     # vitest run --coverage (writes coverage/ report)
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

Run a single test file: npx vitest run test/unit/configLocations.test.ts. Filter by name: npx vitest run -t "renovate.json5".

Two tsconfigs: the root tsconfig.json includes both src/ and test/ and is used by typecheck; tsconfig.build.json narrows to src/ only and is what build uses so tests never leak into dist/.

Architecture — the non-obvious bits

Shell out to the Renovate CLI at runtime; never import renovate as a library in src/ from the main process. Every tool that needs Renovate goes through src/lib/renovateCli.ts, which resolves the binary name (overridable via RENOVATE_BIN / RENOVATE_CONFIG_VALIDATOR_BIN env vars) and spawns it as a child process. Importing renovate from the main server process is the wrong pattern — the whole runtime design hinges on staying decoupled from Renovate's API surface. Exceptions:

• Build-time scripts under scripts/ may import Renovate to generate committed snapshots — see the preset catalogue.
• Worker-thread isolation is an explicit carve-out for tools that need a Renovate library export with no CLI equivalent. migrate_config does this via src/lib/migrationWorker.ts + src/lib/migrationWorkerImpl.ts: the main process spawns a worker on demand; the worker imports renovate/dist/config/migration.js; the main process itself never imports renovate. See docs/adrs/0001-worker-isolated-renovate-migration.md for the rationale. resolve_config / explain_config use the same shape for their faithful config merge via src/lib/mergeWorker.ts + src/lib/mergeWorkerImpl.ts, which import renovate/dist/config/utils.js (mergeChildConfig) in the worker (ADR-0004). test_package_rules / annotate_dry_run are the third such carve-out: src/lib/packageRulesWorker.ts + src/lib/packageRulesWorkerImpl.ts import Renovate's real matcher registry (renovate/dist/util/package-rules/matchers.js) plus mergeChildConfig + compile and replicate applyPackageRules' loop in the worker to recover the per-rule / per-matcher provenance Renovate exposes nowhere — see docs/adrs/0006-worker-isolated-faithful-package-rules.md. Future tools wanting the same shape need their own ADR.