@cyanheads/mcp-ts-core 0.2.3 → 0.2.4

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.2.3
+**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.
@@ -267,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

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.2.3-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.2.3",
+  "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"

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/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.
@@ -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

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

@@ -284,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