@cyanheads/mcp-ts-core 0.1.20 → 0.1.22

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.1.20
+**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.1.22
 **npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) · **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
 
 > **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never edit a file before reading it.
@@ -173,6 +173,8 @@ export const myTool = tool('my_tool', {
 
 **Steps:** Create `src/mcp-server/tools/definitions/[name].tool.ts` (kebab-case) → use `tool('snake_case', {...})` with Zod `.describe()` on all fields → implement `handler(input, ctx)` (pure, throws on failure) → add `auth`/`format` if needed → register in `definitions/index.ts` → `bun run devcheck` → smoke-test with `dev:stdio`/`dev:http`.
 
+**Schema constraint:** Input/output schemas must use JSON-Schema-serializable Zod types only. The MCP SDK converts schemas to JSON Schema for `tools/list` — non-serializable types (`z.custom()`, `z.date()`, `z.transform()`, etc.) cause a hard runtime failure. Use structural equivalents instead (e.g., `z.string()` with `.describe('ISO 8601 date')` instead of `z.date()`). The linter validates this at startup.
+
 **`format`**: Maps output to `ContentBlock[]`. Omit for JSON stringify default. Additional formatters: `markdown()` (builder), `diffFormatter` (async), `tableFormatter`, `treeFormatter` from `/utils`.
 
 **Task tools:** Add `task: true` for long-running async operations. Framework manages lifecycle: creates task → returns ID immediately → runs handler in background with `ctx.progress` → stores result/error → `ctx.signal` for cancellation. See `add-tool` skill for full example.
@@ -418,7 +420,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 
 ## Code Style & Checklist
 
-- **Validation:** Zod schemas, all fields need `.describe()`
+- **Validation:** Zod schemas, all fields need `.describe()`. Schemas must be JSON-Schema-serializable — avoid `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()` (the linter catches these at startup)
 - **Logging:** Framework auto-instruments all handler calls. `ctx.log` for domain-specific logging in handlers, global `logger` for lifecycle/background
 - **Errors:** handlers throw — error factories (`notFound()`, `validationError()`, etc.) when the code matters, plain `Error` for don't-care cases. Framework catches and classifies. `ErrorHandler.tryCatch` for services only.
 - **Secrets:** server config only — no hardcoded credentials

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.20-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
+[![Version](https://img.shields.io/badge/Version-0.1.22-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -39,7 +39,7 @@ That's a complete MCP server. Every tool call is automatically logged with durat
 - **Unified Context** — handlers receive a single `ctx` object with `ctx.log` (request-scoped logging), `ctx.state` (tenant-scoped storage), `ctx.elicit` (user prompting), `ctx.sample` (LLM completion), and `ctx.signal` (cancellation).
 - **Inline auth** — `auth: ['scope']` on definitions. No wrapper functions. Framework checks scopes before calling your handler.
 - **Task tools** — `task: true` flag for long-running operations. Framework manages the full lifecycle (create, poll, progress, complete/fail/cancel).
-- **Definition linter** — `validateDefinitions()` checks tools, resources, and prompts against MCP spec at startup. Name format, schema structure, `.describe()` presence, URI template validity. Also available as a standalone CLI (`lint:mcp`) and devcheck step.
+- **Definition linter** — `validateDefinitions()` checks tools, resources, and prompts against MCP spec at startup. Name format, schema structure, `.describe()` presence, JSON Schema serializability, auth scope validity, annotation coherence, and URI template–params alignment. Also available as a standalone CLI (`lint:mcp`) and devcheck step.
 - **Structured error handling** — Handlers throw freely; the framework catches, classifies, and formats. Error factories (`notFound()`, `validationError()`, `serviceUnavailable()`, etc.) for precise control when the code matters. Auto-classification from plain `Error` messages when it doesn't.
 - **Multi-backend storage** — `in-memory`, `filesystem`, `Supabase`, `Cloudflare D1/KV/R2`. Swap providers via env var without changing tool logic. Cursor pagination, batch ops, TTL, tenant isolation.
 - **Pluggable auth** — `none`, `jwt`, or `oauth` modes. JWT with local secret or OAuth with JWKS verification.

package/dist/linter/rules/index.d.ts

@@ -5,6 +5,6 @@
 export { checkDuplicateNames, checkNameRequired, checkToolNameFormat } from './name-rules.js';
 export { lintPromptDefinition } from './prompt-rules.js';
 export { lintResourceDefinition } from './resource-rules.js';
-export { checkFieldDescriptions, checkIsZodObject } from './schema-rules.js';
-export { lintToolDefinition } from './tool-rules.js';
+export { checkFieldDescriptions, checkIsZodObject, checkSchemaSerializable, } from './schema-rules.js';
+export { lintAuthScopes, lintToolDefinition } from './tool-rules.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/linter/rules/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/linter/rules/index.js

@@ -5,6 +5,6 @@
 export { checkDuplicateNames, checkNameRequired, checkToolNameFormat } from './name-rules.js';
 export { lintPromptDefinition } from './prompt-rules.js';
 export { lintResourceDefinition } from './resource-rules.js';
-export { checkFieldDescriptions, checkIsZodObject } from './schema-rules.js';
-export { lintToolDefinition } from './tool-rules.js';
+export { checkFieldDescriptions, checkIsZodObject, checkSchemaSerializable, } from './schema-rules.js';
+export { lintAuthScopes, lintToolDefinition } from './tool-rules.js';
 //# sourceMappingURL=index.js.map

package/dist/linter/rules/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/linter/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/linter/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/linter/rules/name-rules.js

@@ -29,9 +29,9 @@ export function checkToolNameFormat(name) {
     if (!TOOL_NAME_RE.test(name)) {
         return {
             rule: 'name-format',
-            severity: 'warning',
+            severity: 'error',
             message: `Tool name '${name}' does not match MCP spec format [A-Za-z0-9._-]{1,128}. ` +
-                'This may cause issues with some MCP clients.',
+                'The spec requires (MUST) this format. Non-conforming names may break clients.',
             definitionType: 'tool',
             definitionName: name,
         };

package/dist/linter/rules/name-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"name-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/name-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,6EAA6E;AAC7E,MAAM,YAAY,GAAG,yBAAyB,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAa,EACb,cAAgD,EAChD,cAAsB;IAEtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO;YACL,IAAI,EAAE,eAAe;YACrB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,GAAG,cAAc,mDAAmD;YAC7E,cAAc;YACd,cAAc,EAAE,cAAc,IAAI,WAAW;SAC9C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,cAAc,IAAI,0DAA0D;gBAC5E,8CAA8C;YAChD,cAAc,EAAE,MAAM;YACtB,cAAc,EAAE,IAAI;SACrB,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAe,EACf,cAAgD;IAEhD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,MAAM,WAAW,GAAqB,EAAE,CAAC;IAEzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,aAAa;gBACnB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,aAAa,cAAc,UAAU,IAAI,WAAW,cAAc,2BAA2B;gBACtG,cAAc;gBACd,cAAc,EAAE,IAAI;aACrB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}
+{"version":3,"file":"name-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/name-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,6EAA6E;AAC7E,MAAM,YAAY,GAAG,yBAAyB,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAa,EACb,cAAgD,EAChD,cAAsB;IAEtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO;YACL,IAAI,EAAE,eAAe;YACrB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,GAAG,cAAc,mDAAmD;YAC7E,cAAc;YACd,cAAc,EAAE,cAAc,IAAI,WAAW;SAC9C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,QAAQ,EAAE,OAAO;YACjB,OAAO,EACL,cAAc,IAAI,0DAA0D;gBAC5E,+EAA+E;YACjF,cAAc,EAAE,MAAM;YACtB,cAAc,EAAE,IAAI;SACrB,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAe,EACf,cAAgD;IAEhD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,MAAM,WAAW,GAAqB,EAAE,CAAC;IAEzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,aAAa;gBACnB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,aAAa,cAAc,UAAU,IAAI,WAAW,cAAc,2BAA2B;gBACtG,cAAc;gBACd,cAAc,EAAE,IAAI;aACrB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/linter/rules/prompt-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/prompt-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CA2CnE"}
+{"version":3,"file":"prompt-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/prompt-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CA6CnE"}

package/dist/linter/rules/prompt-rules.js

@@ -4,7 +4,7 @@
  * @module src/linter/rules/prompt-rules
  */
 import { checkNameRequired } from './name-rules.js';
-import { checkFieldDescriptions, checkIsZodObject } from './schema-rules.js';
+import { checkFieldDescriptions, checkIsZodObject, checkSchemaSerializable, } from './schema-rules.js';
 /**
  * Runs all lint rules against a single prompt definition.
  */
@@ -45,6 +45,9 @@ export function lintPromptDefinition(def) {
         }
         else {
             diagnostics.push(...checkFieldDescriptions(d.args, 'args', 'prompt', displayName));
+            const argsSerial = checkSchemaSerializable(d.args, 'args', 'prompt', displayName);
+            if (argsSerial)
+                diagnostics.push(argsSerial);
         }
     }
     return diagnostics;

package/dist/linter/rules/prompt-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/prompt-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE7E;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,MAAM,WAAW,GAAG,IAAI,IAAI,WAAW,CAAC;IAExC,kBAAkB;IAClB,MAAM,OAAO,GAAG,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3D,IAAI,OAAO;QAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEvC,cAAc;IACd,IAAI,OAAO,CAAC,EAAE,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrE,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,sBAAsB;YAC5B,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,WAAW,WAAW,uBAAuB;YACtD,cAAc,EAAE,QAAQ;YACxB,cAAc,EAAE,WAAW;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,oBAAoB;IACpB,IAAI,OAAO,CAAC,EAAE,QAAQ,KAAK,UAAU,EAAE,CAAC;QACtC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,WAAW,WAAW,mCAAmC;YAClE,cAAc,EAAE,QAAQ;YACxB,cAAc,EAAE,WAAW;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,6DAA6D;IAC7D,IAAI,CAAC,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC1E,IAAI,SAAS,EAAE,CAAC;YACd,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}
+{"version":3,"file":"prompt-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/prompt-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,MAAM,WAAW,GAAG,IAAI,IAAI,WAAW,CAAC;IAExC,kBAAkB;IAClB,MAAM,OAAO,GAAG,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3D,IAAI,OAAO;QAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEvC,cAAc;IACd,IAAI,OAAO,CAAC,EAAE,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrE,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,sBAAsB;YAC5B,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,WAAW,WAAW,uBAAuB;YACtD,cAAc,EAAE,QAAQ;YACxB,cAAc,EAAE,WAAW;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,oBAAoB;IACpB,IAAI,OAAO,CAAC,EAAE,QAAQ,KAAK,UAAU,EAAE,CAAC;QACtC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,WAAW,WAAW,mCAAmC;YAClE,cAAc,EAAE,QAAQ;YACxB,cAAc,EAAE,WAAW;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,6DAA6D;IAC7D,IAAI,CAAC,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC1E,IAAI,SAAS,EAAE,CAAC;YACd,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;YACnF,MAAM,UAAU,GAAG,uBAAuB,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;YAClF,IAAI,UAAU;gBAAE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/linter/rules/resource-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/resource-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CAgFrE"}
+{"version":3,"file":"resource-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/resource-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AASlD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CAiGrE"}

package/dist/linter/rules/resource-rules.js

@@ -4,7 +4,8 @@
  * @module src/linter/rules/resource-rules
  */
 import { checkNameRequired } from './name-rules.js';
-import { checkFieldDescriptions, checkIsZodObject } from './schema-rules.js';
+import { checkFieldDescriptions, checkIsZodObject, checkSchemaSerializable, } from './schema-rules.js';
+import { lintAuthScopes } from './tool-rules.js';
 /**
  * Runs all lint rules against a single resource definition.
  */
@@ -75,13 +76,70 @@ export function lintResourceDefinition(def) {
         }
         else {
             diagnostics.push(...checkFieldDescriptions(d.params, 'params', 'resource', displayName));
+            const paramsSerial = checkSchemaSerializable(d.params, 'params', 'resource', displayName);
+            if (paramsSerial)
+                diagnostics.push(paramsSerial);
+            // Cross-reference: template variables must match params schema keys
+            if (uriTemplate) {
+                diagnostics.push(...checkTemplateParamsAlignment(uriTemplate, d.params, displayName));
+            }
         }
     }
+    // Auth scopes validation
+    if (d?.auth !== undefined) {
+        diagnostics.push(...lintAuthScopes(d.auth, 'resource', displayName));
+    }
     // Output schema (optional, but must be ZodObject when present)
     if (d?.output !== undefined) {
         const outputCheck = checkIsZodObject(d.output, 'output', 'resource', displayName);
-        if (outputCheck)
+        if (outputCheck) {
             diagnostics.push(outputCheck);
+        }
+        else {
+            const outputSerial = checkSchemaSerializable(d.output, 'output', 'resource', displayName);
+            if (outputSerial)
+                diagnostics.push(outputSerial);
+        }
+    }
+    return diagnostics;
+}
+/** Extracts variable names from an RFC 6570 URI template (strips operators like +, #, ?, &, etc.). */
+function extractTemplateVariables(template) {
+    const vars = [];
+    for (const match of template.matchAll(/\{(?:[+#./;?&]?)([^}]+)\}/g)) {
+        // match[1] contains comma-separated variable names, each optionally with :maxLength or *
+        const varList = match[1] ?? '';
+        for (const part of varList.split(',')) {
+            const name = part.replace(/:[0-9]+$|\*$/g, '').trim();
+            if (name)
+                vars.push(name);
+        }
+    }
+    return vars;
+}
+/**
+ * Checks that URI template variables align with params schema keys.
+ * A mismatch causes hard failures: the SDK extracts variables from the URI
+ * and passes them to the params schema for validation.
+ */
+function checkTemplateParamsAlignment(template, params, resourceName) {
+    const templateVars = extractTemplateVariables(template);
+    if (templateVars.length === 0)
+        return [];
+    const shape = params.shape;
+    const schemaKeys = new Set(Object.keys(shape));
+    const diagnostics = [];
+    for (const varName of templateVars) {
+        if (!schemaKeys.has(varName)) {
+            diagnostics.push({
+                rule: 'template-params-align',
+                severity: 'error',
+                message: `Resource '${resourceName}' URI template variable '{${varName}}' has no matching key in params schema. ` +
+                    `Params schema has: [${[...schemaKeys].join(', ')}]. This will cause every resource read to fail.`,
+                definitionType: 'resource',
+                definitionName: resourceName,
+            });
+        }
     }
     return diagnostics;
 }

package/dist/linter/rules/resource-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/resource-rules.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/resource-rules.ts"],"names":[],"mappings":"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"}

package/dist/linter/rules/schema-rules.d.ts

@@ -1,5 +1,6 @@
 /**
- * @fileoverview Lint rules for Zod schema validation: type checking, `.describe()` presence.
+ * @fileoverview Lint rules for Zod schema validation: type checking, `.describe()` presence,
+ * and JSON Schema serializability.
  * Covers MCP spec rules T3-T5 and framework convention for field descriptions.
  * @module src/linter/rules/schema-rules
  */
@@ -14,4 +15,11 @@ export declare function checkIsZodObject(schema: unknown, fieldName: string, def
  * Framework convention: all fields need `.describe()` for LLM discoverability.
  */
 export declare function checkFieldDescriptions(schema: unknown, fieldName: string, definitionType: LintDiagnostic['definitionType'], definitionName: string): LintDiagnostic[];
+/**
+ * Checks that a Zod schema can be converted to JSON Schema.
+ * The MCP SDK serializes schemas via `toJSONSchema()` when handling `tools/list`.
+ * Types like `z.custom()`, `z.date()`, `z.transform()`, etc. throw at serialization
+ * time, causing a hard runtime failure for any client that enumerates tools.
+ */
+export declare function checkSchemaSerializable(schema: unknown, fieldName: string, definitionType: LintDiagnostic['definitionType'], definitionName: string): LintDiagnostic | null;
 //# sourceMappingURL=schema-rules.d.ts.map

package/dist/linter/rules/schema-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/schema-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAChD,cAAc,EAAE,MAAM,GACrB,cAAc,GAAG,IAAI,CAavB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAChD,cAAc,EAAE,MAAM,GACrB,cAAc,EAAE,CAwBlB"}
+{"version":3,"file":"schema-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/schema-rules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAChD,cAAc,EAAE,MAAM,GACrB,cAAc,GAAG,IAAI,CAavB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAChD,cAAc,EAAE,MAAM,GACrB,cAAc,EAAE,CAwBlB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAChD,cAAc,EAAE,MAAM,GACrB,cAAc,GAAG,IAAI,CAkBvB"}

package/dist/linter/rules/schema-rules.js

@@ -1,8 +1,10 @@
 /**
- * @fileoverview Lint rules for Zod schema validation: type checking, `.describe()` presence.
+ * @fileoverview Lint rules for Zod schema validation: type checking, `.describe()` presence,
+ * and JSON Schema serializability.
  * Covers MCP spec rules T3-T5 and framework convention for field descriptions.
  * @module src/linter/rules/schema-rules
  */
+import { toJSONSchema } from 'zod/v4/core';
 /**
  * Checks that a schema is a ZodObject (required for tool inputSchema).
  * Spec: T3-T4 — inputSchema MUST be a JSON Schema object with type: "object".
@@ -45,6 +47,31 @@ export function checkFieldDescriptions(schema, fieldName, definitionType, defini
     }
     return diagnostics;
 }
+/**
+ * Checks that a Zod schema can be converted to JSON Schema.
+ * The MCP SDK serializes schemas via `toJSONSchema()` when handling `tools/list`.
+ * Types like `z.custom()`, `z.date()`, `z.transform()`, etc. throw at serialization
+ * time, causing a hard runtime failure for any client that enumerates tools.
+ */
+export function checkSchemaSerializable(schema, fieldName, definitionType, definitionName) {
+    if (!isZodObject(schema))
+        return null;
+    try {
+        toJSONSchema(schema);
+        return null;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Schema contains non-serializable types';
+        return {
+            rule: 'schema-serializable',
+            severity: 'error',
+            message: `${definitionType} '${definitionName}' ${fieldName} cannot be converted to JSON Schema: ${message}. ` +
+                'Replace non-serializable types (z.custom(), z.date(), z.transform(), z.bigint(), etc.) with structural Zod types.',
+            definitionType,
+            definitionName,
+        };
+    }
+}
 /** Runtime check for ZodObject via Zod 4's `_zod.def.type`. */
 function isZodObject(value) {
     if (!value || typeof value !== 'object')

package/dist/linter/rules/schema-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/schema-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAe,EACf,SAAiB,EACjB,cAAgD,EAChD,cAAsB;IAEtB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,kBAAkB;YACxB,QAAQ,EAAE,OAAO;YACjB,OAAO,EACL,GAAG,cAAc,KAAK,cAAc,KAAK,SAAS,yBAAyB;gBAC3E,uDAAuD;YACzD,cAAc;YACd,cAAc;SACf,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAe,EACf,SAAiB,EACjB,cAAgD,EAChD,cAAsB;IAEtB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,MAAM,KAAK,GAAI,MAAiC,CAAC,KAAK,CAAC;IAEvD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,QAAQ,GAAG,KAAqE,CAAC;QAEvF,gFAAgF;QAChF,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,oBAAoB;gBAC1B,QAAQ,EAAE,SAAS;gBACnB,OAAO,EACL,GAAG,cAAc,KAAK,cAAc,KAAK,SAAS,IAAI,GAAG,2BAA2B;oBACpF,kDAAkD;gBACpD,cAAc;gBACd,cAAc;aACf,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,+DAA+D;AAC/D,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,GAAG,GAAI,KAAiC,CAAC,IAA+C,CAAC;IAC/F,OAAO,GAAG,EAAE,GAAG,EAAE,IAAI,KAAK,QAAQ,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAA2E,CAAC;IAEtF,oCAAoC;IACpC,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/E,4DAA4D;IAC5D,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC;IACrC,IAAI,KAAK;QAAE,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC;IAExC,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"schema-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/schema-rules.ts"],"names":[],"mappings":"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"}

package/dist/linter/rules/tool-rules.d.ts

@@ -9,4 +9,6 @@ import type { LintDiagnostic } from '../types.js';
  * Accepts `unknown` to catch structural issues before type narrowing.
  */
 export declare function lintToolDefinition(def: unknown): LintDiagnostic[];
+/** Validates that auth scopes are well-formed (array of non-empty strings). */
+export declare function lintAuthScopes(auth: unknown, definitionType: LintDiagnostic['definitionType'], definitionName: string): LintDiagnostic[];
 //# sourceMappingURL=tool-rules.d.ts.map

package/dist/linter/rules/tool-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/tool-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CA2DjE"}
+{"version":3,"file":"tool-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/tool-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CAoEjE;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAChD,cAAc,EAAE,MAAM,GACrB,cAAc,EAAE,CA8BlB"}

package/dist/linter/rules/tool-rules.js

@@ -4,7 +4,7 @@
  * @module src/linter/rules/tool-rules
  */
 import { checkNameRequired, checkToolNameFormat } from './name-rules.js';
-import { checkFieldDescriptions, checkIsZodObject } from './schema-rules.js';
+import { checkFieldDescriptions, checkIsZodObject, checkSchemaSerializable, } from './schema-rules.js';
 /**
  * Runs all lint rules against a single tool definition.
  * Accepts `unknown` to catch structural issues before type narrowing.
@@ -43,21 +43,31 @@ export function lintToolDefinition(def) {
             definitionName: displayName,
         });
     }
-    // Input schema: must be ZodObject
+    // Input schema: must be ZodObject, serializable to JSON Schema
     const inputCheck = checkIsZodObject(d?.input, 'input', 'tool', displayName);
     if (inputCheck) {
         diagnostics.push(inputCheck);
     }
     else {
         diagnostics.push(...checkFieldDescriptions(d?.input, 'input', 'tool', displayName));
+        const inputSerial = checkSchemaSerializable(d?.input, 'input', 'tool', displayName);
+        if (inputSerial)
+            diagnostics.push(inputSerial);
     }
-    // Output schema: must be ZodObject
+    // Output schema: must be ZodObject, serializable to JSON Schema
     const outputCheck = checkIsZodObject(d?.output, 'output', 'tool', displayName);
     if (outputCheck) {
         diagnostics.push(outputCheck);
     }
     else {
         diagnostics.push(...checkFieldDescriptions(d?.output, 'output', 'tool', displayName));
+        const outputSerial = checkSchemaSerializable(d?.output, 'output', 'tool', displayName);
+        if (outputSerial)
+            diagnostics.push(outputSerial);
+    }
+    // Auth scopes validation
+    if (d?.auth !== undefined) {
+        diagnostics.push(...lintAuthScopes(d.auth, 'tool', displayName));
     }
     // Annotations validation
     if (d?.annotations && typeof d.annotations === 'object') {
@@ -65,6 +75,34 @@ export function lintToolDefinition(def) {
     }
     return diagnostics;
 }
+/** Validates that auth scopes are well-formed (array of non-empty strings). */
+export function lintAuthScopes(auth, definitionType, definitionName) {
+    const diagnostics = [];
+    if (!Array.isArray(auth)) {
+        diagnostics.push({
+            rule: 'auth-type',
+            severity: 'error',
+            message: `${definitionType} '${definitionName}' auth must be an array of scope strings.`,
+            definitionType,
+            definitionName,
+        });
+        return diagnostics;
+    }
+    for (let i = 0; i < auth.length; i++) {
+        const scope = auth[i];
+        if (typeof scope !== 'string' || scope.trim().length === 0) {
+            diagnostics.push({
+                rule: 'auth-scope-format',
+                severity: 'error',
+                message: `${definitionType} '${definitionName}' auth[${i}] must be a non-empty string, ` +
+                    `got ${typeof scope === 'string' ? 'empty string' : typeof scope}.`,
+                definitionType,
+                definitionName,
+            });
+        }
+    }
+    return diagnostics;
+}
 /** Validates that annotation hint values are booleans where expected. */
 function lintToolAnnotations(annotations, toolName) {
     const diagnostics = [];
@@ -85,6 +123,29 @@ function lintToolAnnotations(annotations, toolName) {
             });
         }
     }
+    // Semantic coherence: destructiveHint and idempotentHint are meaningless when readOnlyHint is true
+    if (annotations.readOnlyHint === true) {
+        if ('destructiveHint' in annotations) {
+            diagnostics.push({
+                rule: 'annotation-coherence',
+                severity: 'warning',
+                message: `Tool '${toolName}' sets destructiveHint while readOnlyHint is true. ` +
+                    'destructiveHint is meaningless for read-only tools.',
+                definitionType: 'tool',
+                definitionName: toolName,
+            });
+        }
+        if ('idempotentHint' in annotations) {
+            diagnostics.push({
+                rule: 'annotation-coherence',
+                severity: 'warning',
+                message: `Tool '${toolName}' sets idempotentHint while readOnlyHint is true. ` +
+                    'Read-only tools are inherently idempotent — this hint is redundant.',
+                definitionType: 'tool',
+                definitionName: toolName,
+            });
+        }
+    }
     return diagnostics;
 }
 //# sourceMappingURL=tool-rules.js.map

package/dist/linter/rules/tool-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/tool-rules.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-rules.js","sourceRoot":"","sources":["../../../src/linter/rules/tool-rules.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Build tools, not infrastructure. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Node.js and Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -175,6 +175,7 @@
     "depcheck": "^1.4.7",
     "execa": "^9.6.1",
     "fast-check": "^4.6.0",
+    "js-yaml": "^4.1.0",
     "ignore": "^7.0.5",
     "msw": "^2.12.14",
     "node-cron": "^4.2.1",
@@ -268,7 +269,7 @@
     "chrono-node": "^2.9.0",
     "diff": "^8.0.3",
     "fast-xml-parser": "^5.5.8",
-    "js-yaml": "^3.14.2",
+    "js-yaml": "^4.1.0",
     "node-cron": "^4.2.1",
     "openai": "^6.32.0",
     "papaparse": "^5.5.3",

package/scripts/lint-mcp.ts

@@ -42,7 +42,9 @@ try {
 function isToolLike(v: unknown): boolean {
   if (!v || typeof v !== 'object') return false;
   const o = v as Record<string, unknown>;
-  return typeof o.handler === 'function' && o.input != null && o.output != null;
+  const hasHandler = typeof o.handler === 'function';
+  const hasTaskHandlers = o.taskHandlers != null && typeof o.taskHandlers === 'object';
+  return (hasHandler || hasTaskHandlers) && o.input != null && o.output != null;
 }
 
 function isResourceLike(v: unknown): boolean {

package/skills/add-tool/SKILL.md

@@ -42,10 +42,10 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
   description: '{{TOOL_DESCRIPTION}}',
   annotations: { readOnlyHint: true },
   input: z.object({
-    // All fields need .describe()
+    // All fields need .describe(). Only JSON-Schema-serializable Zod types allowed.
   }),
   output: z.object({
-    // All fields need .describe()
+    // All fields need .describe(). Only JSON-Schema-serializable Zod types allowed.
   }),
   // auth: ['tool:{{tool_name}}:read'],
 
@@ -100,6 +100,7 @@ export const allToolDefinitions = [
 
 - [ ] File created at `src/mcp-server/tools/definitions/{{tool-name}}.tool.ts`
 - [ ] All Zod schema fields have `.describe()` annotations
+- [ ] Schemas use only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`)
 - [ ] JSDoc `@fileoverview` and `@module` header present
 - [ ] `handler(input, ctx)` is pure — throws on failure, no try/catch
 - [ ] `auth` scopes declared if the tool needs authorization

package/skills/design-mcp-server/SKILL.md

@@ -147,6 +147,7 @@ Context-dependent: a simple read-only tool needs a one-line description. A tool
 Every `.describe()` is prompt text the LLM reads. Parameters should convey: what the value is, what it affects, and (where non-obvious) how to use it well.
 
 - **Constrain the type.** Enums and literals over free strings. Regex validation for formatted IDs. Ranges for numeric bounds.
+- **Use JSON-Schema-serializable types only.** The MCP SDK serializes schemas to JSON Schema for `tools/list`. Types like `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()` throw at runtime. Use structural equivalents (e.g., `z.string().describe('ISO 8601 date')` instead of `z.date()`).
 - **Explain costs and tradeoffs** when a parameter choice has meaningful consequences.
 - **Name alternative approaches** when a simpler path exists.
 - **Include format patterns** for structured values, but don't pad descriptions with redundant examples.

package/skills/field-test/SKILL.md

@@ -89,7 +89,7 @@ Cross-cutting observations that aren't tied to a single definition:
 - Inconsistent error message patterns across tools
 - Missing format functions (raw JSON returned to user)
 - Description quality issues (vague, missing, or misleading)
-- Schema design issues (required fields that should be optional, missing defaults, overly broad types)
+- Schema design issues (required fields that should be optional, missing defaults, overly broad types, non-JSON-Schema-serializable types like `z.custom()` or `z.date()`)
 - Performance observations (unexpectedly slow responses)
 
 ---

package/skills/polish-docs-meta/references/readme.md

@@ -27,17 +27,18 @@ Badges row                             ← npm, Docker, Version, MCP Spec, SDK,
 
 ### Title Block
 
-Centered HTML. The `<h1>` is the server name (package name). The `<p>` is a bold one-liner: what the server wraps, key capabilities, transport/deployment options. Follow with a badge row.
+Centered HTML. The `<h1>` is the server name — use the scoped package name if published under a scope (e.g., `@cyanheads/my-mcp-server`). The `<p>` is a bold one-liner: what the server wraps, key capabilities, transport/deployment options. Follow with a count line summarizing the MCP surface (tools, resources, prompts) separated by ` · `, then a badge row.
 
 ```html
 <div align="center">
-  <h1>my-mcp-server</h1>
-  <p><b>MCP server for the Acme API. Search projects, manage tasks, track teams. Runs over stdio or HTTP.</b></p>
+  <h1>@cyanheads/my-mcp-server</h1>
+  <p><b>MCP server for the Acme API. Search projects, manage tasks, track teams. STDIO & Streamable HTTP</b></p>
+  <p><b>7 Tools · 2 Resources · 1 Prompt</b></p>
 </div>
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/my-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/my-mcp-server) [![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![npm](https://img.shields.io/npm/v/my-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/my-mcp-server) [![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/)
 
 </div>
 ```
@@ -49,6 +50,7 @@ Centered HTML. The `<h1>` is the server name (package name). The `<p>` is a bold
 | npm | Published to npm |
 | Docker | Published to ghcr.io or Docker Hub |
 | Version | Always — link to CHANGELOG.md |
+| Framework | Always — links to `@cyanheads/mcp-ts-core` on npm |
 | MCP Spec | Always — link to the spec version implemented |
 | MCP SDK | Always — show the `@modelcontextprotocol/sdk` version |
 | License | Always |

package/templates/AGENTS.md

@@ -273,7 +273,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 
 ## Checklist
 
-- [ ] Zod schemas: all fields have `.describe()`
+- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, etc.)
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage
 - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch

package/templates/CLAUDE.md

@@ -273,7 +273,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 
 ## Checklist
 
-- [ ] Zod schemas: all fields have `.describe()`
+- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, etc.)
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage
 - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch

package/templates/_.dockerignore

@@ -0,0 +1,197 @@
+# =============================================================================
+# OPERATING SYSTEM FILES
+# =============================================================================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# =============================================================================
+# VERSION CONTROL
+# =============================================================================
+.git/
+
+# =============================================================================
+# IDE AND EDITOR FILES
+# =============================================================================
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+*.sublime-workspace
+*.sublime-project
+.history/
+
+# =============================================================================
+# NODE.JS & PACKAGE MANAGERS
+# =============================================================================
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+.npm
+.pnp.js
+.pnp.cjs
+.pnp.mjs
+.pnp.json
+.pnp.ts
+
+# =============================================================================
+# TYPESCRIPT & JAVASCRIPT
+# =============================================================================
+*.tsbuildinfo
+.tscache/
+*.js.map
+*.mjs.map
+*.cjs.map
+*.d.ts.map
+*.d.ts
+!*.d.ts.template
+*.tgz
+.eslintcache
+.rollup.cache
+
+# =============================================================================
+# PYTHON
+# =============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+develop-eggs/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.venv
+venv/
+ENV/
+
+# =============================================================================
+# JAVA
+# =============================================================================
+*.class
+*.jar
+*.war
+*.nar
+*.ear
+hs_err_pid*
+target/
+.gradle/
+
+# =============================================================================
+# RUBY
+# =============================================================================
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+.byebug_history
+
+# =============================================================================
+# BUILD & DISTRIBUTION
+# =============================================================================
+build/
+dist/
+out/
+
+# =============================================================================
+# COMPILED FILES
+# =============================================================================
+*.com
+*.dll
+*.exe
+*.o
+
+# =============================================================================
+# PACKAGE & ARCHIVE FILES
+# =============================================================================
+*.7z
+*.dmg
+*.gz
+*.iso
+*.rar
+*.tar
+*.tar.gz
+*.zip
+
+# =============================================================================
+# LOGS & DATABASES
+# =============================================================================
+*.log
+*.sql
+*.sqlite
+*.sqlite3
+logs/
+
+# =============================================================================
+# TESTING & COVERAGE
+# =============================================================================
+coverage/
+.nyc_output/
+
+# =============================================================================
+# CACHE & TEMPORARY FILES
+# =============================================================================
+.cache/
+.parcel-cache/
+*.bak
+
+# =============================================================================
+# ENVIRONMENT & CONFIGURATION
+# =============================================================================
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.sample-env
+sample.*
+!sample.template.*
+mcp-servers.json
+mcp-config.json
+
+# =============================================================================
+# DEMO & EXAMPLE DIRECTORIES
+# =============================================================================
+demo/
+demos/
+example/
+examples/
+samples/
+
+# =============================================================================
+# GENERATED DOCUMENTATION
+# =============================================================================
+docs/api/
+
+# =============================================================================
+# APPLICATION SPECIFIC
+# =============================================================================
+repomix-output*
+duckdata/
+.claude

package/templates/package.json

@@ -26,9 +26,9 @@
     "format": "biome check --write --unsafe .",
     "lint:mcp": "tsx scripts/lint-mcp.ts",
     "test": "vitest run",
-    "dev:stdio": "tsx --watch src/index.ts",
+    "dev:stdio": "MCP_TRANSPORT_TYPE=stdio tsx --watch src/index.ts",
     "dev:http": "MCP_TRANSPORT_TYPE=http tsx --watch src/index.ts",
-    "start:stdio": "node dist/index.js",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
     "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
   },
   "keywords": [

package/templates/tests/prompts/echo.prompt.test.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Tests for the echo prompt.
+ * @module tests/prompts/echo.prompt.test
+ */
+
+import { describe, expect, it } from 'vitest';
+import { echoPrompt } from '@/mcp-server/prompts/definitions/echo.prompt.js';
+
+describe('echoPrompt', () => {
+  it('generates a user message with the echoed text', () => {
+    const args = echoPrompt.args.parse({ message: 'hello world' });
+    const messages = echoPrompt.generate(args);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]).toMatchObject({
+      role: 'user',
+      content: { type: 'text', text: 'Echo: hello world' },
+    });
+  });
+});

package/templates/tests/resources/echo.resource.test.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Tests for the echo resource.
+ * @module tests/resources/echo.resource.test
+ */
+
+import { describe, expect, it } from 'vitest';
+import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { echoResource } from '@/mcp-server/resources/definitions/echo.resource.js';
+
+describe('echoResource', () => {
+  it('echoes the message from params', async () => {
+    const ctx = createMockContext();
+    const params = echoResource.params.parse({ message: 'hello world' });
+    const result = await echoResource.handler(params, ctx);
+    expect(result).toEqual({ message: 'hello world' });
+  });
+
+  it('lists available resources', () => {
+    const listing = echoResource.list!();
+    expect(listing.resources).toHaveLength(1);
+    expect(listing.resources[0]).toMatchObject({
+      uri: 'echo://hello',
+      name: 'Echo Hello',
+    });
+  });
+});

package/templates/tests/tools/echo.tool.test.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Tests for the echo tool.
+ * @module tests/tools/echo.tool.test
+ */
+
+import { describe, expect, it } from 'vitest';
+import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { echoTool } from '@/mcp-server/tools/definitions/echo.tool.js';
+
+describe('echoTool', () => {
+  it('echoes the message back', async () => {
+    const ctx = createMockContext();
+    const input = echoTool.input.parse({ message: 'hello world' });
+    const result = await echoTool.handler(input, ctx);
+    expect(result).toEqual({ message: 'hello world' });
+  });
+
+  it('formats output as text content', () => {
+    const blocks = echoTool.format!({ message: 'hello world' });
+    expect(blocks).toEqual([{ type: 'text', text: 'hello world' }]);
+  });
+});