Skip to main content
Glama
wrangler-config-doctor

wrangler-config-doctor

Wrangler Config Doctor

Find common Wrangler configuration mistakes before you deploy. An offline v0.1 beta with a CLI and one local MCP tool. Independent software by Valen Systems; not affiliated with Cloudflare.

Try it

Install Node.js 22.13 or newer, extract the ZIP, then run:

node wrangler-config-doctor.mjs --help
node wrangler-config-doctor.mjs check examples/wrangler.jsonc

For your own project, run from its directory:

node /path/to/wrangler-config-doctor.mjs check wrangler.jsonc
node /path/to/wrangler-config-doctor.mjs check wrangler.toml --env staging --strict

Paths are relative to the current directory. Select exactly wrangler.toml, wrangler.json, or wrangler.jsonc, optionally in a subdirectory. The tool reads only that file. It does not discover parent configurations, resolve $schema, load environment files, execute build commands, contact Cloudflare, or change files.

Related MCP server: MCP Preflight

What it checks

Code

Finding

WCD001

Missing/invalid compatibility date, or a date beyond the rule pack

WCD002

Both route and routes in the same configuration scope

WCD003

Duplicate names or malformed fields in supported bindings and vars

WCD004

Selected environment omits a top-level category that does not inherit

WCD005

Duplicate migration tags or conflicting operations in one migration

WCD006

Assets/site conflict or assets directory problem

WCD007

Invalid observability enabled/sampling configuration

WCD008

Possible credential keys in vars

WCD004 and WCD008 are warnings. A missing assets directory is also a warning because build plugins can supply it. Routes and triggers inherit; bindings and vars do not. Migration operations are compared within each migration, so creating a class in one migration and deleting it later is valid.

JSON output is deterministic. Diagnostics contain fixed messages and schema paths, with no config values, binding names, routes, or secret keys. The input path, selected environment, byte count, and input SHA-256 are included. Treat receipts as private if those identifiers are sensitive; the hash is an integrity check, not encryption.

Exit codes: 0 passes the selected policy; 2 has errors (or warnings with --strict); 64 is invalid input; 70 is an internal failure. Input failures produce a fixed error code on stderr and no receipt. Parse errors and duplicate keys fail before analysis.

Local MCP

{
  "mcpServers": {
    "wrangler-config-doctor": {
      "command": "node",
      "args": ["/path/to/wrangler-config-doctor.mjs", "mcp", "--root", "/path/to/project"]
    }
  }
}

The read-only wrangler_config_check tool accepts configPath, optional environment, and optional strict. Paths stay beneath the startup root. The root and config path must not be symlinks. Use a stable project directory; v0.1 is not a sandbox against another local process concurrently replacing directories.

Scope

These eight checks are advisory, not complete Wrangler schema validation or proof that a deployment will succeed. Unknown properties are ignored. Supported bindings: KV, R2, D1, Vectorize, Hyperdrive, services, Analytics Engine, mTLS, dispatch namespaces, Workflows, Pipelines, Secrets Store, AI, browser, images, version metadata, Durable Objects, queue producers, email, assets, and vars. Other binding categories are outside v0.1 coverage.

Input is capped at 1 MiB, 64 environments, nesting depth 64, 50,000 parsed values, and 256 inspected binding/migration entries. Exceeding a limit fails the analysis. The assets directory is checked for configuration shape, not opened or traversed. TOML date/time values are unsupported; write compatibility dates as quoted strings. Windows execution has not yet been tested.

Rule provenance is pinned in rule-pack.json: Wrangler 4.130.0, its upstream commit, and the configuration schema hash. Full schema coverage and broader platform testing can follow after feedback.

Build from source

npm ci --ignore-scripts
npm test
npm run build

Builds use Node, esbuild, and the host's zip command. The ZIP requires only Node at runtime, without a dependency install. Original code is MIT licensed; the distribution includes THIRD_PARTY_NOTICES.md and exact upstream license texts.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables any MCP client to detect Claude Code configuration that is silently ignored, such as agent files that fail to load, unknown frontmatter fields, parent-folder settings, conflicting MCP server entries and drift since a baseline. Exposes read-only tools that return findings with exact edits, the fix prompt, and explanations of each check, without modifying any files.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to statically review MCP configuration or captured tools/list JSON before running it, producing redacted JSON or SARIF reports and optionally exposing a stdio review tool.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents and MCP clients to run a read-only environment check against a project's declared requirements and receive structured results identifying exactly what needs fixing.
      240 PyPI
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables agents to diagnose environment-variable issues read-only without exposing values, including .env versus template comparison, undocumented or unused variables across source code, shape validation, secret-exposure checks, git-ignore and history checks, and safe .env.example proposals.
      6
      MIT