MCP `tools/list` fails with `Cannot read properties of undefined (reading '_zod')` on zod >= 4

[Ohmdahar]

Summary

The plugin's MCP server starts and handshakes successfully but errors on tools/list, preventing Claude Code (and any other MCP client doing standard discovery) from seeing any of the kg_* tools. Pinning zod to v3 fixes it.

Environment

OS	Windows 11
Node	v22.x
Plugin commit	1d2481e (current main HEAD)
@modelcontextprotocol/sdk	1.27.1
zod	4.3.6 (within SDK peer range ^3.25 || ^4.0)

Reproduction

Per https://modelcontextprotocol.io/docs/tools/debugging — drive the server with raw JSON-RPC over stdio:

cd knowledge-graph
KG_VAULT_PATH=/path/to/vault npx tsx src/mcp/index.ts

Send three messages on stdin:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"v","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

Expected: tools/list returns the 14 registered tools.

Actual:

{"jsonrpc":"2.0","id":2,"error":{"code":-32603,"message":"Cannot read properties of undefined (reading '_zod')"}}

initialize succeeds (serverInfo: knowledge-graph 0.1.0), so the failure is specifically in the SDK's schema-introspection path when building the tools/list response from the z.object({...}) arg schemas in src/mcp/index.ts.

Impact

Claude Code's plugin loader calls tools/list as part of discovery. The MCP server connects but is then marked as failed and none of the kg_* tools surface. The plugin is effectively unusable from inside Claude Code on a fresh install.

Workaround

Force zod v3 via npm overrides in package.json:

"overrides": { "zod": "^3.25" }

Then rm -rf node_modules package-lock.json && npm install. After this, tools/list returns all 14 tools and the plugin works inside Claude Code.

Suggested fix

Either pin zod to ^3.25 in dependencies until the SDK's zod-v4 introspection path is stable, or upgrade @modelcontextprotocol/sdk to a version that handles zod v4 schemas correctly (worth checking the SDK's own issue tracker first).

[m3talux]

Confirming on macOS (Darwin 24.6, Node 25.2.1, @modelcontextprotocol/sdk@1.27.1, zod@4.3.6). Same Cannot read properties of undefined (reading '_zod') on tools/list. initialize succeeds and the binary works fine for direct invocation (e.g. UserPromptSubmit hook vault context still resolves), so the failure is isolated to MCP schema introspection.

Root cause is z.record(z.unknown()) at src/mcp/index.ts:242 — zod v4 requires z.record(keySchema, valueSchema), so the single-arg form produces a schema with _zod.def.valueType === undefined, which zod/v4-mini's toJSONSchema() dereferences and crashes on.

Fix:

- frontmatter: z.record(z.unknown()).optional().describe(...)
+ frontmatter: z.record(z.string(), z.unknown()).optional().describe(...)

Happy to send a PR — also closes #2.

[m3talux]

Correction on the PR offer — #4 already does this (open since 2026-04-03, mergeable, no reviews yet). It uses z.record(z.string(), z.any()) plus a regression test. Worth nudging that one along rather than opening a duplicate.