@cyanheads/mcp-ts-core 0.2.2 → 0.2.4

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.2.2
+**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.2.4
 **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.
@@ -159,16 +159,32 @@ export const myTool = tool('my_tool', {
   description: 'Does something useful.',
   annotations: { readOnlyHint: true },
   input: z.object({ query: z.string().describe('Search query') }),
-  output: z.object({ result: z.string().describe('Search result') }),
+  output: z.object({
+    items: z.array(z.object({
+      id: z.string().describe('Item ID'),
+      name: z.string().describe('Item name'),
+      status: z.string().describe('Current status'),
+      description: z.string().optional().describe('Item description'),
+    })).describe('Matching items'),
+    totalCount: z.number().describe('Total matches before pagination'),
+  }),
   auth: ['tool:my_tool:read'],
 
   async handler(input, ctx) {
     const data = await fetchFromApi(input.query);
-    ctx.log.info('Query resolved', { query: input.query, resultCount: data.length });
-    return { result: data.summary };
+    ctx.log.info('Query resolved', { query: input.query, resultCount: data.items.length });
+    return data;
   },
 
-  format: (result) => [{ type: 'text', text: result.result }],
+  format: (result) => {
+    const lines = [`**${result.totalCount} results**\n`];
+    for (const item of result.items) {
+      lines.push(`### ${item.name}`);
+      lines.push(`**ID:** ${item.id} | **Status:** ${item.status}`);
+      if (item.description) lines.push(item.description);
+    }
+    return [{ type: 'text', text: lines.join('\n') }];
+  },
 });
 ```
 
@@ -176,7 +192,7 @@ export const myTool = tool('my_tool', {
 
 **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`.
+**`format`**: Maps output to MCP `content[]` — the only field most LLM clients (Claude Code, VS Code Copilot, Cursor, Windsurf) forward to the model. `structuredContent` (from `output`) is for programmatic use and is not reliably shown to the LLM. **Make `format()` content-complete** — render all data the model needs to reason about the result, not just a count or title. Omit for JSON stringify fallback. 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.
 
@@ -251,6 +267,8 @@ export function getMyService(): MyService {
 
 Usage: `getMyService().doWork(input.query, ctx)`. Convention: `ctx.elicit`/`ctx.sample` only from tool handlers, not services.
 
+**API efficiency:** Prefer batch endpoints over N+1 individual requests. Use field selection to minimize payload. Cross-reference batch responses against requested IDs to detect missing items. See `add-service` skill for patterns.
+
 ---
 
 ## Context
@@ -448,6 +466,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 - **JSDoc:** `@fileoverview` + `@module` required on every file
 - **No fabricated signal:** Don't invent synthetic scores or arbitrary "confidence percentages." Surface real signal.
 - **Builders:** `tool()`/`resource()`/`prompt()` with correct fields (`handler`, `input`, `output`, `format`, `auth`, `args`)
+- **`format()` completeness:** `content[]` is the only field most LLM clients forward to the model — `format()` must render all data the LLM needs, not just a count or title
 - **Auth:** via `auth: ['scope']` on definitions (not HOF wrapper)
 - **Presence checks:** `ctx.elicit`/`ctx.sample` checked before use
 - **Task tools:** use `task: true` flag

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.2.2-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.28.0-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.2.4-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.28.0-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-^6.0.2-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/)
 

package/dist/core/index.d.ts

@@ -17,7 +17,7 @@ export { resource } from '../mcp-server/resources/utils/resourceDefinition.js';
 export type { AnyToolDef } from '../mcp-server/tools/tool-registration.js';
 export type { AnyToolDefinition, ToolAnnotations, ToolDefinition, } from '../mcp-server/tools/utils/toolDefinition.js';
 export { tool } from '../mcp-server/tools/utils/toolDefinition.js';
-export type { LintDiagnostic, LintInput, LintReport, LintSeverity } from '../linter/types.js';
+export type { LintDefinitionType, LintDiagnostic, LintInput, LintReport, LintSeverity, } from '../linter/types.js';
 export { validateDefinitions } from '../linter/validate.js';
 export type { CallToolResult, ContentBlock, CreateMessageResult, ElicitResult, ModelPreferences, PromptMessage, SamplingMessage, } from '@modelcontextprotocol/sdk/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,YAAY,EACV,WAAW,EACX,OAAO,EACP,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,mBAAmB,CAAC;AAM3B,YAAY,EACV,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,gDAAgD,CAAC;AACxE,YAAY,EACV,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,oDAAoD,CAAC;AAE5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oDAAoD,CAAC;AAC9E,sEAAsE;AACtE,YAAY,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAMlE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAM3D,YAAY,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,oCAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,YAAY,EACV,WAAW,EACX,OAAO,EACP,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,mBAAmB,CAAC;AAM3B,YAAY,EACV,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,gDAAgD,CAAC;AACxE,YAAY,EACV,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,oDAAoD,CAAC;AAE5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oDAAoD,CAAC;AAC9E,sEAAsE;AACtE,YAAY,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAMlE,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAM3D,YAAY,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,oCAAoC,CAAC"}

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,OAAO,EAAE,MAAM,EAAE,MAAM,gDAAgD,CAAC;AAMxE,OAAO,EAAE,QAAQ,EAAE,MAAM,oDAAoD,CAAC;AAQ9E,OAAO,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAOlE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,OAAO,EAAE,MAAM,EAAE,MAAM,gDAAgD,CAAC;AAMxE,OAAO,EAAE,QAAQ,EAAE,MAAM,oDAAoD,CAAC;AAQ9E,OAAO,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAalE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/linter/index.d.ts

@@ -3,6 +3,6 @@
  * Exports `validateDefinitions()` and all types needed to consume lint reports.
  * @module src/linter/index
  */
-export type { LintDiagnostic, LintInput, LintReport, LintSeverity } from './types.js';
+export type { LintDefinitionType, LintDiagnostic, LintInput, LintReport, LintSeverity, } from './types.js';
 export { validateDefinitions } from './validate.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/linter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/linter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/linter/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/linter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/linter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

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

@@ -6,5 +6,6 @@ export { checkDuplicateNames, checkNameRequired, checkToolNameFormat } from './n
 export { lintPromptDefinition } from './prompt-rules.js';
 export { lintResourceDefinition } from './resource-rules.js';
 export { checkFieldDescriptions, checkIsZodObject, checkSchemaSerializable, } from './schema-rules.js';
+export { lintServerJson } from './server-json-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,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,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,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/linter/rules/index.js

@@ -6,5 +6,6 @@ export { checkDuplicateNames, checkNameRequired, checkToolNameFormat } from './n
 export { lintPromptDefinition } from './prompt-rules.js';
 export { lintResourceDefinition } from './resource-rules.js';
 export { checkFieldDescriptions, checkIsZodObject, checkSchemaSerializable, } from './schema-rules.js';
+export { lintServerJson } from './server-json-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,EACL,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,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,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/linter/rules/server-json-rules.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Lint rules for server.json manifest validation.
+ * Validates server metadata against the MCP server manifest spec (2025-12-11).
+ * @module src/linter/rules/server-json-rules
+ */
+import type { LintDiagnostic } from '../types.js';
+/**
+ * Validates a parsed server.json manifest against the MCP server manifest spec.
+ * Accepts `unknown` to catch structural issues before type narrowing.
+ *
+ * @param serverJson - Parsed server.json content (or undefined to skip).
+ * @param crossCheck - Optional cross-validation data (e.g., package.json version).
+ * @returns Array of lint diagnostics (errors and warnings).
+ */
+export declare function lintServerJson(serverJson: unknown, crossCheck?: {
+    packageJsonVersion?: string;
+}): LintDiagnostic[];
+//# sourceMappingURL=server-json-rules.d.ts.map

package/dist/linter/rules/server-json-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-json-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/server-json-rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAiClD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,OAAO,EACnB,UAAU,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,cAAc,EAAE,CA2JlB"}

package/dist/linter/rules/server-json-rules.js

@@ -0,0 +1,290 @@
+/**
+ * @fileoverview Lint rules for server.json manifest validation.
+ * Validates server metadata against the MCP server manifest spec (2025-12-11).
+ * @module src/linter/rules/server-json-rules
+ */
+const DEF_TYPE = 'server-json';
+const DEF_NAME = 'server.json';
+/** Reverse-DNS name pattern from the spec. */
+const NAME_PATTERN = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
+/** Rejects version range specifiers. */
+const VERSION_RANGE_PATTERN = /[~^>=<*x]/;
+/** Loose semver check (major.minor.patch with optional pre-release/build). */
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/;
+/** Valid transport types per spec. */
+const TRANSPORT_TYPES = new Set(['stdio', 'streamable-http', 'sse']);
+/** Transports that require a url field. */
+const URL_TRANSPORTS = new Set(['streamable-http', 'sse']);
+/** URL pattern from the spec. */
+const URL_PATTERN = /^https?:\/\/[^\s]+$/;
+/** Valid argument types. */
+const ARGUMENT_TYPES = new Set(['positional', 'named']);
+/** Valid input format values. */
+const INPUT_FORMATS = new Set(['string', 'number', 'boolean', 'filepath']);
+function diag(rule, severity, message) {
+    return { definitionName: DEF_NAME, definitionType: DEF_TYPE, message, rule, severity };
+}
+/**
+ * Validates a parsed server.json manifest against the MCP server manifest spec.
+ * Accepts `unknown` to catch structural issues before type narrowing.
+ *
+ * @param serverJson - Parsed server.json content (or undefined to skip).
+ * @param crossCheck - Optional cross-validation data (e.g., package.json version).
+ * @returns Array of lint diagnostics (errors and warnings).
+ */
+export function lintServerJson(serverJson, crossCheck) {
+    if (serverJson == null)
+        return [];
+    const diagnostics = [];
+    if (typeof serverJson !== 'object' || Array.isArray(serverJson)) {
+        diagnostics.push(diag('server-json-type', 'error', 'server.json must be a JSON object.'));
+        return diagnostics;
+    }
+    const s = serverJson;
+    // ── Required fields ──────────────────────────────────────────────────
+    // name: required, 3-200 chars, reverse-DNS pattern
+    if (typeof s.name !== 'string' || s.name.length === 0) {
+        diagnostics.push(diag('server-json-name-required', 'error', 'name is required.'));
+    }
+    else {
+        if (s.name.length < 3 || s.name.length > 200) {
+            diagnostics.push(diag('server-json-name-length', 'error', `name must be 3–200 characters, got ${s.name.length}.`));
+        }
+        if (!NAME_PATTERN.test(s.name)) {
+            diagnostics.push(diag('server-json-name-format', 'error', `name '${s.name}' must match reverse-DNS format: owner/project (pattern: ${NAME_PATTERN.source}).`));
+        }
+    }
+    // description: required, 1-100 chars
+    if (typeof s.description !== 'string' || s.description.length === 0) {
+        diagnostics.push(diag('server-json-description-required', 'error', 'description is required.'));
+    }
+    else if (s.description.length > 100) {
+        diagnostics.push(diag('server-json-description-length', 'warning', `description exceeds 100 characters (${s.description.length}). Some registries may truncate.`));
+    }
+    // version: required, no ranges
+    if (typeof s.version !== 'string' || s.version.length === 0) {
+        diagnostics.push(diag('server-json-version-required', 'error', 'version is required.'));
+    }
+    else {
+        if (s.version.length > 255) {
+            diagnostics.push(diag('server-json-version-length', 'error', `version exceeds 255 characters (${s.version.length}).`));
+        }
+        if (VERSION_RANGE_PATTERN.test(s.version)) {
+            diagnostics.push(diag('server-json-version-no-range', 'error', `version '${s.version}' looks like a range. Must be a specific version.`));
+        }
+        if (!SEMVER_PATTERN.test(s.version)) {
+            diagnostics.push(diag('server-json-version-semver', 'warning', `version '${s.version}' is not valid semver. Semver is recommended.`));
+        }
+    }
+    // ── Optional fields with structure constraints ───────────────────────
+    // repository
+    if (s.repository != null) {
+        if (typeof s.repository !== 'object' || Array.isArray(s.repository)) {
+            diagnostics.push(diag('server-json-repository-type', 'error', 'repository must be an object.'));
+        }
+        else {
+            const repo = s.repository;
+            if (typeof repo.url !== 'string' || repo.url.length === 0) {
+                diagnostics.push(diag('server-json-repository-url', 'error', 'repository.url is required when repository is present.'));
+            }
+            if (typeof repo.source !== 'string' || repo.source.length === 0) {
+                diagnostics.push(diag('server-json-repository-source', 'error', 'repository.source is required when repository is present.'));
+            }
+        }
+    }
+    // packages
+    if (s.packages != null) {
+        if (!Array.isArray(s.packages)) {
+            diagnostics.push(diag('server-json-packages-type', 'error', 'packages must be an array.'));
+        }
+        else {
+            for (let i = 0; i < s.packages.length; i++) {
+                diagnostics.push(...lintPackageEntry(s.packages[i], i, s.version));
+            }
+        }
+    }
+    // remotes
+    if (s.remotes != null) {
+        if (!Array.isArray(s.remotes)) {
+            diagnostics.push(diag('server-json-remotes-type', 'error', 'remotes must be an array.'));
+        }
+        else {
+            for (let i = 0; i < s.remotes.length; i++) {
+                diagnostics.push(...lintRemoteEntry(s.remotes[i], i));
+            }
+        }
+    }
+    // ── Cross-validation ─────────────────────────────────────────────────
+    if (crossCheck?.packageJsonVersion &&
+        typeof s.version === 'string' &&
+        s.version.length > 0 &&
+        s.version !== crossCheck.packageJsonVersion) {
+        diagnostics.push(diag('server-json-version-sync', 'warning', `version '${s.version}' does not match package.json version '${crossCheck.packageJsonVersion}'.`));
+    }
+    return diagnostics;
+}
+/** Validates a single entry in the packages array. */
+function lintPackageEntry(pkg, index, rootVersion) {
+    const diagnostics = [];
+    const prefix = `packages[${index}]`;
+    if (typeof pkg !== 'object' || pkg == null || Array.isArray(pkg)) {
+        diagnostics.push(diag('server-json-package-type', 'error', `${prefix} must be an object.`));
+        return diagnostics;
+    }
+    const p = pkg;
+    // registryType: required
+    if (typeof p.registryType !== 'string' || p.registryType.length === 0) {
+        diagnostics.push(diag('server-json-package-registry', 'error', `${prefix}.registryType is required.`));
+    }
+    // identifier: required
+    if (typeof p.identifier !== 'string' || p.identifier.length === 0) {
+        diagnostics.push(diag('server-json-package-identifier', 'error', `${prefix}.identifier is required.`));
+    }
+    // transport: required
+    if (p.transport == null) {
+        diagnostics.push(diag('server-json-package-transport', 'error', `${prefix}.transport is required.`));
+    }
+    else {
+        diagnostics.push(...lintTransport(p.transport, `${prefix}.transport`));
+    }
+    // version: must not be "latest", should match root
+    if (typeof p.version === 'string') {
+        if (p.version === 'latest') {
+            diagnostics.push(diag('server-json-package-no-latest', 'error', `${prefix}.version must be a specific version, not "latest".`));
+        }
+        if (rootVersion &&
+            p.version.length > 0 &&
+            p.version !== 'latest' &&
+            p.version !== rootVersion) {
+            diagnostics.push(diag('server-json-package-version-sync', 'warning', `${prefix}.version '${p.version}' does not match root version '${rootVersion}'.`));
+        }
+    }
+    // packageArguments
+    if (p.packageArguments != null) {
+        if (!Array.isArray(p.packageArguments)) {
+            diagnostics.push(diag('server-json-package-args-type', 'error', `${prefix}.packageArguments must be an array.`));
+        }
+        else {
+            for (let j = 0; j < p.packageArguments.length; j++) {
+                diagnostics.push(...lintArgument(p.packageArguments[j], `${prefix}.packageArguments[${j}]`));
+            }
+        }
+    }
+    // runtimeArguments
+    if (p.runtimeArguments != null) {
+        if (!Array.isArray(p.runtimeArguments)) {
+            diagnostics.push(diag('server-json-runtime-args-type', 'error', `${prefix}.runtimeArguments must be an array.`));
+        }
+        else {
+            for (let j = 0; j < p.runtimeArguments.length; j++) {
+                diagnostics.push(...lintArgument(p.runtimeArguments[j], `${prefix}.runtimeArguments[${j}]`));
+            }
+        }
+    }
+    // environmentVariables
+    if (p.environmentVariables != null) {
+        if (!Array.isArray(p.environmentVariables)) {
+            diagnostics.push(diag('server-json-env-vars-type', 'error', `${prefix}.environmentVariables must be an array.`));
+        }
+        else {
+            for (let j = 0; j < p.environmentVariables.length; j++) {
+                diagnostics.push(...lintEnvVar(p.environmentVariables[j], `${prefix}.environmentVariables[${j}]`));
+            }
+        }
+    }
+    return diagnostics;
+}
+/** Validates a single entry in the remotes array. */
+function lintRemoteEntry(remote, index) {
+    const diagnostics = [];
+    const prefix = `remotes[${index}]`;
+    if (typeof remote !== 'object' || remote == null || Array.isArray(remote)) {
+        diagnostics.push(diag('server-json-remote-type', 'error', `${prefix} must be an object.`));
+        return diagnostics;
+    }
+    const r = remote;
+    // Remote transports must be streamable-http or sse (no stdio)
+    if (r.type == null) {
+        diagnostics.push(diag('server-json-remote-transport-type', 'error', `${prefix}.type is required.`));
+    }
+    else if (r.type === 'stdio') {
+        diagnostics.push(diag('server-json-remote-no-stdio', 'error', `${prefix}.type is 'stdio' but remotes only support 'streamable-http' or 'sse'.`));
+    }
+    else {
+        diagnostics.push(...lintTransport(r, prefix));
+    }
+    return diagnostics;
+}
+/** Validates a transport object. */
+function lintTransport(transport, path) {
+    const diagnostics = [];
+    if (typeof transport !== 'object' || transport == null || Array.isArray(transport)) {
+        diagnostics.push(diag('server-json-transport-type', 'error', `${path} must be an object.`));
+        return diagnostics;
+    }
+    const t = transport;
+    if (typeof t.type !== 'string' || !TRANSPORT_TYPES.has(t.type)) {
+        diagnostics.push(diag('server-json-transport-type-value', 'error', `${path}.type must be one of: ${[...TRANSPORT_TYPES].join(', ')}. Got '${String(t.type)}'.`));
+        return diagnostics;
+    }
+    if (URL_TRANSPORTS.has(t.type)) {
+        if (typeof t.url !== 'string' || t.url.length === 0) {
+            diagnostics.push(diag('server-json-transport-url-required', 'error', `${path}.url is required for transport type '${t.type}'.`));
+        }
+        else if (!URL_PATTERN.test(t.url)) {
+            diagnostics.push(diag('server-json-transport-url-format', 'warning', `${path}.url '${t.url}' should match pattern: ${URL_PATTERN.source}.`));
+        }
+    }
+    return diagnostics;
+}
+/** Validates a single argument entry (positional or named). */
+function lintArgument(arg, path) {
+    const diagnostics = [];
+    if (typeof arg !== 'object' || arg == null || Array.isArray(arg)) {
+        diagnostics.push(diag('server-json-argument-type', 'error', `${path} must be an object.`));
+        return diagnostics;
+    }
+    const a = arg;
+    if (typeof a.type !== 'string' || !ARGUMENT_TYPES.has(a.type)) {
+        diagnostics.push(diag('server-json-argument-type-value', 'error', `${path}.type must be 'positional' or 'named'. Got '${String(a.type)}'.`));
+        return diagnostics;
+    }
+    if (a.type === 'named') {
+        if (typeof a.name !== 'string' || a.name.length === 0) {
+            diagnostics.push(diag('server-json-argument-name', 'error', `${path}.name is required for named arguments.`));
+        }
+    }
+    // Positional args need either value or valueHint
+    if (a.type === 'positional') {
+        const hasValue = typeof a.value === 'string' && a.value.length > 0;
+        const hasHint = typeof a.valueHint === 'string' && a.valueHint.length > 0;
+        if (!hasValue && !hasHint) {
+            diagnostics.push(diag('server-json-argument-value', 'error', `${path} (positional) requires either 'value' or 'valueHint'.`));
+        }
+    }
+    // format validation if present
+    if (a.format != null && (typeof a.format !== 'string' || !INPUT_FORMATS.has(a.format))) {
+        diagnostics.push(diag('server-json-input-format', 'warning', `${path}.format should be one of: ${[...INPUT_FORMATS].join(', ')}. Got '${String(a.format)}'.`));
+    }
+    return diagnostics;
+}
+/** Validates a single environment variable entry. */
+function lintEnvVar(envVar, path) {
+    const diagnostics = [];
+    if (typeof envVar !== 'object' || envVar == null || Array.isArray(envVar)) {
+        diagnostics.push(diag('server-json-env-var-type', 'error', `${path} must be an object.`));
+        return diagnostics;
+    }
+    const e = envVar;
+    if (typeof e.name !== 'string' || e.name.length === 0) {
+        diagnostics.push(diag('server-json-env-var-name', 'error', `${path}.name is required.`));
+    }
+    if (e.description == null || (typeof e.description === 'string' && e.description.length === 0)) {
+        diagnostics.push(diag('server-json-env-var-description', 'warning', `${path} '${typeof e.name === 'string' ? e.name : '?'}' has no description.`));
+    }
+    if (e.format != null && (typeof e.format !== 'string' || !INPUT_FORMATS.has(e.format))) {
+        diagnostics.push(diag('server-json-input-format', 'warning', `${path}.format should be one of: ${[...INPUT_FORMATS].join(', ')}. Got '${String(e.format)}'.`));
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=server-json-rules.js.map

package/dist/linter/rules/server-json-rules.js.map

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

package/dist/linter/types.d.ts

@@ -6,16 +6,18 @@
  */
 /** Severity of a lint diagnostic. */
 export type LintSeverity = 'error' | 'warning';
+/** Definition type that produced a lint diagnostic. */
+export type LintDefinitionType = 'tool' | 'resource' | 'prompt' | 'server-json';
 /**
  * A single lint diagnostic produced by a validation rule.
  * Errors represent spec violations that will cause runtime failures.
  * Warnings represent SHOULD-level or quality issues.
  */
 export interface LintDiagnostic {
-    /** Name of the specific definition (tool/resource/prompt name). */
+    /** Name of the specific definition (tool/resource/prompt name, or 'server.json'). */
     definitionName: string;
     /** Which definition type produced this diagnostic. */
-    definitionType: 'tool' | 'resource' | 'prompt';
+    definitionType: LintDefinitionType;
     /** Human-readable message describing the issue. */
     message: string;
     /** Rule identifier (e.g., 'name-format', 'describe-on-fields'). */
@@ -36,11 +38,17 @@ export interface LintReport {
 }
 /**
  * Input to `validateDefinitions()`.
- * Mirrors the definition arrays from `CreateAppOptions`.
+ * Mirrors the definition arrays from `CreateAppOptions`, plus optional server.json.
  */
 export interface LintInput {
+    /** Parsed package.json — used for cross-validation (version sync). */
+    packageJson?: {
+        version?: string;
+    };
     prompts?: unknown[];
     resources?: unknown[];
+    /** Parsed server.json content. When provided, validated against the MCP server manifest spec. */
+    serverJson?: unknown;
     tools?: unknown[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/linter/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/linter/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qCAAqC;AACrC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,cAAc,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC/C,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/linter/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qCAAqC;AACrC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/C,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEhF;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,cAAc,EAAE,kBAAkB,CAAC;IACnC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,WAAW,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IACtB,iGAAiG;IACjG,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB"}

package/dist/linter/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/linter/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAkB,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CA+ChE"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/linter/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAkB,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CA0DhE"}

package/dist/linter/validate.js

@@ -7,6 +7,7 @@
 import { checkDuplicateNames } from './rules/name-rules.js';
 import { lintPromptDefinition } from './rules/prompt-rules.js';
 import { lintResourceDefinition } from './rules/resource-rules.js';
+import { lintServerJson } from './rules/server-json-rules.js';
 import { lintToolDefinition } from './rules/tool-rules.js';
 /**
  * Validates MCP tool, resource, and prompt definitions against the MCP spec
@@ -46,6 +47,11 @@ export function validateDefinitions(input) {
     for (const def of prompts) {
         diagnostics.push(...lintPromptDefinition(def));
     }
+    // server.json manifest validation
+    if (input.serverJson != null) {
+        const pkgVersion = input.packageJson?.version;
+        diagnostics.push(...lintServerJson(input.serverJson, pkgVersion ? { packageJsonVersion: pkgVersion } : undefined));
+    }
     // Cross-definition duplicate checks
     const extractNames = (defs) => defs
         .map((d) => d?.name)

package/dist/linter/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/linter/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,MAAM,WAAW,GAAqB,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;IAChC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;IAEpC,4BAA4B;IAC5B,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,WAAW,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,WAAW,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,WAAW,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,oCAAoC;IACpC,MAAM,YAAY,GAAG,CAAC,IAAe,EAAE,EAAE,CACvC,IAAI;SACD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAA6B,EAAE,IAAI,CAAC;SAChD,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEvE,WAAW,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAEtE,MAAM,aAAa,GAAG,SAAS;SAC5B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,MAAM,CAAC,GAAG,CAA4B,CAAC;QACvC,OAAO,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ;YAChC,CAAC,CAAC,CAAC,CAAC,IAAI;YACR,CAAC,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,QAAQ;gBAClC,CAAC,CAAC,CAAC,CAAC,WAAW;gBACf,CAAC,CAAC,EAAE,CAAC;IACX,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,WAAW,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;IAEpE,WAAW,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE1E,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC;IAErE,OAAO;QACL,MAAM;QACN,QAAQ;QACR,MAAM,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;KAC5B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/linter/validate.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/utils/toolDefinition.d.ts

@@ -55,8 +55,16 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
     /** LLM-facing description. */
     description: string;
     /**
-     * Optional formatter mapping output to ContentBlock[].
-     * If omitted, the handler factory JSON-stringifies the output.
+     * Optional formatter mapping output to MCP `content[]` — the field LLM clients
+     * inject into the model's context. `structuredContent` (from `output`) is for
+     * programmatic/machine use and is NOT reliably forwarded to the model by most
+     * clients (Claude Code, VS Code Copilot, Cursor, Windsurf all read `content[]`).
+     *
+     * **Make `format()` content-complete.** If the LLM needs data to reason about
+     * the result, it must appear here — not just in the output schema. A thin
+     * one-liner (e.g., a count or title) leaves the model blind to the actual data.
+     *
+     * If omitted, the handler factory JSON-stringifies the output as a fallback.
      */
     format?: (result: z.infer<TOutput>) => ContentBlock[];
     /**
@@ -85,13 +93,25 @@ export type AnyToolDefinition = ToolDefinition<ZodObject<ZodRawShape>, ZodObject
  * const myTool = tool('my_tool', {
  *   description: 'Does something useful.',
  *   input: z.object({ query: z.string().describe('Search query') }),
- *   output: z.object({ result: z.string().describe('Search result') }),
+ *   output: z.object({
+ *     items: z.array(z.object({
+ *       id: z.string().describe('Item ID'),
+ *       name: z.string().describe('Item name'),
+ *       status: z.string().describe('Current status'),
+ *     })).describe('Matching items'),
+ *   }),
  *   auth: ['tool:my_tool:read'],
  *   annotations: { readOnlyHint: true },
  *   async handler(input, ctx) {
  *     ctx.log.info('Processing', { query: input.query });
- *     return { result: `Found: ${input.query}` };
+ *     return { items: await search(input.query) };
  *   },
+ *   // format() populates content[] — the only field most LLM clients read.
+ *   // Render all data the model needs; structuredContent is not forwarded.
+ *   format: (result) => [{
+ *     type: 'text',
+ *     text: result.items.map(i => `**${i.id}**: ${i.name} (${i.status})`).join('\n'),
+ *   }],
  * });
  * ```
  */

package/dist/mcp-server/tools/utils/toolDefinition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAC9D,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC;IAE/D,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qCAAqC;IACrC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,YAAY,EAAE,CAAC;IACtD;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChG,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;AAM/F;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,EAAE,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,EAChG,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,GACrD,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjC"}
+{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAC9D,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC;IAE/D,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qCAAqC;IACrC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,YAAY,EAAE,CAAC;IACtD;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChG,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;AAM/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,EAAE,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,EAChG,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,GACrD,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjC"}

package/dist/mcp-server/tools/utils/toolDefinition.js

@@ -15,13 +15,25 @@
  * const myTool = tool('my_tool', {
  *   description: 'Does something useful.',
  *   input: z.object({ query: z.string().describe('Search query') }),
- *   output: z.object({ result: z.string().describe('Search result') }),
+ *   output: z.object({
+ *     items: z.array(z.object({
+ *       id: z.string().describe('Item ID'),
+ *       name: z.string().describe('Item name'),
+ *       status: z.string().describe('Current status'),
+ *     })).describe('Matching items'),
+ *   }),
  *   auth: ['tool:my_tool:read'],
  *   annotations: { readOnlyHint: true },
  *   async handler(input, ctx) {
  *     ctx.log.info('Processing', { query: input.query });
- *     return { result: `Found: ${input.query}` };
+ *     return { items: await search(input.query) };
  *   },
+ *   // format() populates content[] — the only field most LLM clients read.
+ *   // Render all data the model needs; structuredContent is not forwarded.
+ *   format: (result) => [{
+ *     type: 'text',
+ *     text: result.items.map(i => `**${i.id}**: ${i.name} (${i.status})`).join('\n'),
+ *   }],
  * });
  * ```
  */

package/dist/mcp-server/tools/utils/toolDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmFH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,IAAI,CAClB,IAAY,EACZ,OAAsD;IAEtD,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2FH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,IAAI,CAClB,IAAY,EACZ,OAAsD;IAEtD,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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",
@@ -145,8 +145,11 @@
     "chrono-node": "2.9.0",
     "diff": "8.0.4",
     "dotenv": "17.3.1",
+    "brace-expansion": "1.1.13",
     "flatted": "3.4.2",
+    "handlebars": "4.7.9",
     "hono": "4.12.9",
+    "path-to-regexp": "8.4.0",
     "picomatch": "2.3.2",
     "yaml": "1.10.3",
     "zod": "4.3.6"
@@ -250,7 +253,7 @@
   "dependencies": {
     "@hono/mcp": "^0.2.4",
     "@hono/node-server": "^1.19.11",
-    "@modelcontextprotocol/ext-apps": "^1.3.1",
+    "@modelcontextprotocol/ext-apps": "^1.3.2",
     "@modelcontextprotocol/sdk": "^1.28.0",
     "@opentelemetry/api": "^1.9.1",
     "dotenv": "^17.3.1",

package/scripts/lint-mcp.ts

@@ -16,7 +16,7 @@
  *
  * @module scripts/lint-mcp
  */
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
 // ---------------------------------------------------------------------------
@@ -102,11 +102,26 @@ function discoverFiles(): string[] {
 // Main
 // ---------------------------------------------------------------------------
 
+/** Try to read and parse a JSON file. Returns undefined on failure. */
+function tryReadJson(path: string): unknown {
+  try {
+    if (!existsSync(path)) return;
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (err) {
+    console.warn(`Warning: Failed to parse ${path}: ${err instanceof Error ? err.message : err}`);
+    return;
+  }
+}
+
 async function main(): Promise<void> {
   const files = discoverFiles();
 
-  if (files.length === 0) {
-    console.log('No MCP definition files found. Skipping lint.');
+  // Discover server.json and package.json at project root
+  const serverJson = tryReadJson(resolve('server.json'));
+  const packageJson = tryReadJson(resolve('package.json')) as { version?: string } | undefined;
+
+  if (files.length === 0 && serverJson == null) {
+    console.log('No MCP definition files or server.json found. Skipping lint.');
     process.exit(0);
   }
 
@@ -129,17 +144,28 @@ async function main(): Promise<void> {
     }
   }
 
-  const total = tools.length + resources.length + prompts.length;
-  if (total === 0) {
+  const defTotal = tools.length + resources.length + prompts.length;
+  if (defTotal === 0 && serverJson == null) {
     console.log(`Scanned ${files.length} files but found no definitions. Skipping lint.`);
     process.exit(0);
   }
 
-  console.log(
-    `Linting ${tools.length} tool(s), ${resources.length} resource(s), ${prompts.length} prompt(s) from ${files.length} file(s)...`,
-  );
-
-  const report = validateDefinitions({ tools, resources, prompts });
+  const parts: string[] = [];
+  if (defTotal > 0) {
+    parts.push(
+      `${tools.length} tool(s), ${resources.length} resource(s), ${prompts.length} prompt(s) from ${files.length} file(s)`,
+    );
+  }
+  if (serverJson != null) parts.push('server.json');
+  console.log(`Linting ${parts.join(' + ')}...`);
+
+  const report = validateDefinitions({
+    tools,
+    resources,
+    prompts,
+    serverJson,
+    packageJson,
+  });
 
   for (const w of report.warnings) {
     console.warn(`  ⚠ [${w.rule}] ${w.message}`);

package/skills/add-service/SKILL.md

@@ -150,6 +150,40 @@ parseResponse<T>(text: string): T {
 }
 ```
 
+## API Efficiency
+
+When a service wraps an external API, design methods to minimize upstream calls. These patterns compound — a tool calling 3 service methods that each make N requests is 3N calls; batching drops it to 3.
+
+### Batch over N+1
+
+If the API supports filter-by-IDs, bulk GET, or batch query endpoints, expose a batch method instead of (or alongside) the single-item method. One request for 20 items beats 20 sequential requests — it eliminates serial latency, avoids rate-limit accumulation, and simplifies error handling.
+
+```typescript
+/** Fetch multiple studies in a single request via filter.ids. */
+async getStudiesBatch(nctIds: string[], ctx: Context): Promise<Study[]> {
+  const response = await this.searchStudies({
+    filterIds: nctIds,
+    fields: ['NCTId', 'BriefTitle', 'HasResults', 'ResultsSection'],
+    pageSize: nctIds.length,
+  }, ctx);
+  return response.studies;
+}
+```
+
+Cross-reference the response against the requested IDs to detect missing items — don't assume the API returns everything you asked for.
+
+### Field selection
+
+If the API supports `fields`, `select`, or `include` parameters, request only what the caller needs. A full record might be 70KB; four fields might be 5KB. Expose field selection as a parameter on the service method, or use sensible defaults per method.
+
+### Pagination awareness
+
+If a batch request might exceed the API's page size limit, either:
+- Paginate internally (loop until all pages consumed), or
+- Assert/throw when the response indicates truncation (e.g., `nextPageToken` present)
+
+Silent truncation is a data integrity bug — the caller thinks it has all results when it doesn't.
+
 ## Checklist
 
 - [ ] Directory created at `src/services/{{domain}}/`
@@ -159,4 +193,5 @@ parseResponse<T>(text: string): T {
 - [ ] `init` function registered in `setup()` callback in `src/index.ts`
 - [ ] Accessor throws `Error` if not initialized
 - [ ] If wrapping external API: retry covers full pipeline (fetch + parse), backoff calibrated
+- [ ] If wrapping external API: batch endpoints used where available, field selection applied, pagination handled
 - [ ] `bun run devcheck` passes

package/skills/add-tool/SKILL.md

@@ -55,7 +55,20 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
     return { /* output */ };
   },
 
-  format: (result) => [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  // format() populates MCP content[] — the only field most LLM clients forward
+  // to the model. structuredContent (from output) is for programmatic use only.
+  // Render ALL data the LLM needs to reason about the result.
+  format: (result) => {
+    const lines: string[] = [];
+    // Render each item with all relevant fields — not just a count or title.
+    // A thin one-liner (e.g., "Found 5 items") leaves the model blind to the data.
+    for (const item of result.items) {
+      lines.push(`## ${item.name}`);
+      lines.push(`**ID:** ${item.id} | **Status:** ${item.status}`);
+      if (item.description) lines.push(item.description);
+    }
+    return [{ type: 'text', text: lines.join('\n') }];
+  },
 });
 ```
 
@@ -192,6 +205,7 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 - [ ] 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
+- [ ] `format()` renders all data the LLM needs (not just a count or title) — `content[]` is the only field most clients forward to the model
 - [ ] `auth` scopes declared if the tool needs authorization
 - [ ] `task: true` added if the tool is long-running
 - [ ] Registered in `definitions/index.ts` barrel and `allToolDefinitions`

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

@@ -33,7 +33,7 @@ If the domain has a public API, read its docs before designing. Don't design fro
 
 ### 1. Research External Dependencies
 
-Before designing, verify the APIs and services the server will wrap.
+Before designing, verify the APIs and services the server will wrap. Read the docs, then **hit the API** — real requests reveal what docs omit.
 
 If the Agent tool is available, spawn background agents to research in parallel while you proceed with domain mapping:
 
@@ -43,6 +43,16 @@ If the Agent tool is available, spawn background agents to research in parallel
 
 If the Agent tool is not available, do this research inline — fetch docs, read SDK readmes, confirm assumptions before committing them to the design.
 
+**Live API probing.** After reading docs, make real requests against the API to verify assumptions:
+
+- **Response shapes** — confirm actual field names, nesting, and types. Docs frequently lag or omit fields.
+- **Batch/filter endpoints** — look for `filter.ids`, bulk GET, or query-by-multiple-IDs patterns. A single batch request replaces N individual fetches and eliminates serial-request bottlenecks and rate-limit accumulation.
+- **Field selection** — check if the API supports `fields` or `select` parameters to request only the data you need. This reduces payload size dramatically for large objects.
+- **Pagination behavior** — verify token format, page size limits, and what happens when results exceed one page.
+- **Error shapes** — trigger real 400/404/429 responses to see the actual error format, not just what docs claim.
+
+This step prevents building a service layer against assumed response shapes that don't match reality.
+
 ### 2. Map the Domain
 
 List the concrete operations the underlying system supports. Group by domain noun.
@@ -193,7 +203,7 @@ output: z.object({
 ```
 
 - **Truncate large output with counts.** When a list exceeds a reasonable display size, show the top N and append "...and X more". Don't silently drop results.
-- **Use the `format` function for readable summaries** while keeping the full structured data in the output object for programmatic use.
+- **`format()` is the model-facing output — make it content-complete.** MCP `content[]` (populated by `format()`) is the only field most LLM clients forward to the model. `structuredContent` (from `output`) is for programmatic/machine use and is not reliably shown to the LLM. A thin `format()` that returns only a count or title leaves the model blind to the actual data. Render all fields the LLM needs to reason about or act on the result. Use structured markdown (headers, bold labels, lists) for readability.
 
 #### Convenience shortcuts for complex inputs
 
@@ -279,6 +289,15 @@ For services wrapping external APIs, plan the resilience layer. See `docs/servic
 | **Parse failure classification** | Response handler detects HTML error pages and throws transient errors, not `SerializationError`. |
 | **Exhausted retry messaging** | `withRetry` enriches the final error with attempt count automatically. |
 
+For API efficiency, design the service methods to minimize upstream calls:
+
+| Concern | Decision |
+|:--------|:---------|
+| **Batch over N+1** | If the API supports filter-by-IDs or bulk-GET endpoints, use a single batch request instead of N individual fetches. Cross-reference the response against requested IDs to detect missing items. |
+| **Field selection** | If the API supports `fields`/`select` parameters, request only the fields the tool needs. A full study record might be 70KB; selecting 4 fields might be 5KB. |
+| **Request consolidation** | When a tool needs data from multiple related endpoints, check if a single endpoint with broader field selection can serve the same data in one round trip. |
+| **Pagination awareness** | If a batch request might exceed the API's page size, either paginate internally or assert/throw when results are truncated so callers aren't silently missing data. |
+
 **Config** — list env vars (API keys, base URLs). Goes in `src/config/server-config.ts` as a separate Zod schema.
 
 ### 8. Write the Design Doc
@@ -364,6 +383,7 @@ Execute the plan using the scaffolding skills:
 - [ ] Parameter `.describe()` text explains what the value is, what it affects, and tradeoffs
 - [ ] Input schemas use constrained types (enums, literals, regex) over free strings
 - [ ] Output schemas designed for LLM's next action — chaining IDs, post-write state, filtering communicated
+- [ ] `format()` renders all data the LLM needs — `content[]` is the only field most clients forward to the model (not just a count or title)
 - [ ] Error messages guide recovery — name what went wrong and what to do next
 - [ ] Annotations set correctly (`readOnlyHint`, `destructiveHint`, etc.)
 - [ ] Resource URIs use `{param}` templates, pagination planned for large lists

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

@@ -242,6 +242,7 @@ Table of environment variables. Include framework vars only if the server uses n
 | `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
 | `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
+| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |
 | `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |
 ```

package/templates/AGENTS.md

@@ -75,7 +75,12 @@ export const searchItems = tool('search_items', {
     return { items };
   },
 
-  format: (result) => [{ type: 'text', text: `Found ${result.items.length} items` }],
+  // format() populates content[] — the only field most LLM clients forward to
+  // the model. Render all data the LLM needs, not just a count or title.
+  format: (result) => [{
+    type: 'text',
+    text: result.items.map(i => `**${i.id}**: ${i.name}`).join('\n'),
+  }],
 });
 ```
 
@@ -279,6 +284,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] 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
+- [ ] `format()` renders all data the LLM needs — `content[]` is the only field most clients forward to the model
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
 - [ ] `npm run devcheck` passes

package/templates/CLAUDE.md

@@ -75,7 +75,12 @@ export const searchItems = tool('search_items', {
     return { items };
   },
 
-  format: (result) => [{ type: 'text', text: `Found ${result.items.length} items` }],
+  // format() populates content[] — the only field most LLM clients forward to
+  // the model. Render all data the LLM needs, not just a count or title.
+  format: (result) => [{
+    type: 'text',
+    text: result.items.map(i => `**${i.id}**: ${i.name}`).join('\n'),
+  }],
 });
 ```
 
@@ -279,6 +284,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] 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
+- [ ] `format()` renders all data the LLM needs — `content[]` is the only field most clients forward to the model
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
 - [ ] `npm run devcheck` passes

package/templates/src/mcp-server/tools/definitions/echo.tool.ts

@@ -21,5 +21,8 @@ export const echoTool = tool('template_echo_message', {
     return { message: input.message };
   },
 
+  // format() populates MCP content[] — the only field most LLM clients forward to
+  // the model. Render ALL data the LLM needs here, not just a summary or count.
+  // This echo tool is trivial; real tools should render every relevant field.
   format: (result) => [{ type: 'text', text: result.message }],
 });