@cyanheads/mcp-ts-core 0.3.3 → 0.3.5

package/skills/api-workers/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Cloudflare Workers deployment using `createWorkerHandler` from `@cyanheads/mcp-ts-core/worker`. Covers the full handler signature, binding types, CloudflareBindings extensibility, runtime compatibility guards, and wrangler.toml requirements.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: reference
 ---
@@ -19,15 +19,15 @@ metadata:
 
 ```ts
 import { createWorkerHandler } from '@cyanheads/mcp-ts-core/worker';
-import { allToolDefinitions } from './mcp-server/tools/index.js';
-import { allResourceDefinitions } from './mcp-server/resources/index.js';
-import { allPromptDefinitions } from './mcp-server/prompts/index.js';
+import { echoTool } from './mcp-server/tools/definitions/echo.tool.js';
+import { echoResource } from './mcp-server/resources/definitions/echo.resource.js';
+import { echoPrompt } from './mcp-server/prompts/definitions/echo.prompt.js';
 import { initMyService } from './services/my-domain/my-service.js';
 
 export default createWorkerHandler({
-  tools: allToolDefinitions,
-  resources: allResourceDefinitions,
-  prompts: allPromptDefinitions,
+  tools: [echoTool],
+  resources: [echoResource],
+  prompts: [echoPrompt],
   setup(core) {
     initMyService(core.config, core.storage);
   },
@@ -39,6 +39,8 @@ export default createWorkerHandler({
 });
 ```
 
+Fresh scaffolds register definitions directly in the entry point as shown above. If your project later adds barrel files for definitions, importing arrays from those barrels is also fine.
+
 ### Options
 
 | Option | Type | Purpose |

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

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.1"
+  version: "2.2"
   audience: external
   type: workflow
 ---
@@ -117,9 +117,7 @@ const gitBranch = tool('git_branch', {
 ```ts
 // Workflow tool — search + local filter pipeline, not a raw API proxy
 const findEligibleStudies = tool('clinicaltrials_find_eligible_studies', {
-  description: 'Matches patient demographics and medical profile to eligible clinical trials. '
-    + 'Filters by age, sex, conditions, location, and healthy volunteer status. '
-    + 'Returns ranked list of matching studies with eligibility explanations.',
+  description: 'Matches patient demographics and medical profile to eligible clinical trials. Filters by age, sex, conditions, location, and healthy volunteer status. Returns ranked list of matching studies with eligibility explanations.',
   // handler: listStudies() → filter by eligibility → rank by location proximity → slice
 });
 ```
@@ -142,21 +140,20 @@ The description is the LLM's primary signal for tool selection. It must answer:
 
 - **Be concrete about capability.** "Search for clinical trial studies using queries and filters" beats "Interact with studies."
 - **Include operational guidance when it matters.** If the tool has prerequisites, constraints, or gotchas the LLM needs to know, say so in the description. Don't add boilerplate workflow hints when the tool is self-explanatory.
+- **Don't leak implementation details.** Descriptions are for the consumer, not the author. Internal endpoint paths, API call counts, internal parameter name mappings, and routing logic don't belong — describe what the tool does and when to use it, not how it's wired up.
 
 ```ts
 // Good — describes a prerequisite the LLM must know
-description: 'Set the session working directory for all git operations. '
-  + 'This allows subsequent git commands to omit the path parameter.'
+description: 'Set the session working directory for all git operations. This allows subsequent git commands to omit the path parameter.'
 
 // Good — self-explanatory, no workflow hints needed
 description: 'Show the working tree status including staged, unstaged, and untracked files.'
 
 // Good — warns about constraints
-description: 'Fetches trial results data for completed studies. '
-  + 'Only available for studies where hasResults is true.'
+description: 'Fetches trial results data for completed studies. Only available for studies where hasResults is true.'
 ```
 
-Context-dependent: a simple read-only tool needs a one-line description. A tool with prerequisites, modes, or non-obvious behavior needs more. Match depth of description to complexity of tool.
+Descriptions should be as long as needed — concise but complete. Don't artificially truncate, and don't pad with filler.
 
 #### Parameter descriptions
 
@@ -171,14 +168,11 @@ Every `.describe()` is prompt text the LLM reads. Parameters should convey: what
 ```ts
 // Good — explains cost, recommends action, names the alternative
 fields: z.array(z.string()).optional()
-  .describe('Specific fields to return (reduces payload size). '
-    + 'STRONGLY RECOMMENDED — without this, the full study record (~70KB each) is returned. '
-    + 'Use full data only when you need detailed eligibility criteria, locations, or results.'),
+  .describe('Specific fields to return (reduces payload size). Without this, the full study record (~70KB each) is returned. Use full data only when you need detailed eligibility criteria, locations, or results.'),
 
 // Good — explains what the flag does AND how to override
 autoExclude: z.boolean().default(true)
-  .describe('Automatically exclude lock files and generated files from diff output '
-    + 'to reduce context bloat. Set to false if you need to inspect these files.'),
+  .describe('Automatically exclude lock files and generated files from diff output to reduce context bloat. Set to false if you need to inspect these files.'),
 
 // Good — names the format and gives one example
 nctIds: z.union([z.string(), z.array(z.string()).max(5)])
@@ -201,8 +195,7 @@ The output schema and `format` function control what the LLM reads back. Design
 output: z.object({
   diff: z.string().describe('Unified diff output.'),
   excludedFiles: z.array(z.string()).optional()
-    .describe('Files automatically excluded from the diff (e.g., lock files). '
-      + 'Call again with autoExclude=false to include them.'),
+    .describe('Files automatically excluded from the diff (e.g., lock files). Call again with autoExclude=false to include them.'),
 }),
 ```
 
@@ -244,9 +237,7 @@ When a tool wraps a complex query language or filter system, provide a simple sh
 ```ts
 // text_search handles the common case; query handles everything else
 text_search: z.string().optional()
-  .describe('Convenience shortcut: full-text search across title and abstract. '
-    + 'Equivalent to {"_or":[{"_text_any":{"title":"..."}},{"_text_any":{"abstract":"..."}}]}. '
-    + 'For more control, use the query parameter directly.'),
+  .describe('Convenience shortcut: full-text search across title and abstract. For structured filters or field-specific matching, use the query parameter instead.'),
 query: z.record(z.unknown()).optional()
   .describe('Full query object for structured filters. Supports operators: _eq, _gt, _and, _or, ...'),
 ```

package/skills/devcheck/SKILL.md

@@ -4,37 +4,51 @@ description: >
   Lint, format, typecheck, and verify the project is clean. Use after making changes, before committing, or when the user asks to verify quality.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: workflow
 ---
 
 ## What It Runs
 
-`bun run devcheck` runs lint and typecheck:
+`bun run devcheck` runs a broader check suite than just lint + types. By default it includes local hygiene checks, MCP definition linting, Biome, TypeScript, and slow dependency/security checks unless `--fast` is passed. Tests are opt-in via `--test`.
 
 | Check | Tool | Notes |
 |:------|:-----|:------|
+| TODOs / FIXMEs | `git grep` | Fails on tracked TODO/FIXME markers outside excluded files |
+| Tracked secrets | `git ls-files` | Flags tracked `.env`, keys, credentials, and similar sensitive files |
+| MCP definitions | `bun run scripts/lint-mcp.ts` | Validates tool/resource/prompt definitions against framework rules |
 | Biome | `biome check` | Unified lint + format — read-only by default |
 | TypeScript | `tsc --noEmit` | Full project type check |
+| Unused dependencies | `depcheck` | Runs by default; network-free but slower on large repos |
+| Security audit | `bun audit` | Runs by default unless `--fast` or `--no-audit` |
+| Outdated dependencies | `bun outdated` | Runs by default unless `--fast` or `--no-deps` |
+| Tests | `vitest run` | Off by default; enable with `bun run devcheck --test` |
 
-To auto-fix lint/format issues, run `bun run format` (which runs `biome check --fix .`).
+To auto-fix lint/format issues, run `bun run format`.
 
 ## Steps
 
 1. Run `bun run devcheck`
-2. Read the output — both checks run sequentially
-3. Fix any lint or type errors in source files
+2. Read the failing checks in the summary and per-check output
+3. Fix the reported issues
 4. Re-run `bun run devcheck` until clean
-5. Do not consider this skill complete until the command exits successfully with no errors
+5. If the change touches runtime behavior, also run `bun run devcheck --test` or `bun run test`
+6. Do not consider this skill complete until the required commands exit successfully with no errors
 
 ## Common Issues
 
 | Check | Error Type | Typical Fix |
 |:------|:-----------|:------------|
+| TODOs / FIXMEs | Tracked work markers | Resolve or remove the marker before committing |
+| Tracked secrets | Sensitive files in git | Add to `.gitignore` and remove from the index |
+| MCP definitions | Definition lint errors | Fix schema/name/annotation issues reported by `lint-mcp` |
 | Biome | Lint/format errors | Run `bun run format` to auto-fix, or address the flagged rule manually |
 | TypeScript | Type errors | Fix type mismatches, missing properties, incorrect generics |
+| Security audit | Vulnerabilities in direct deps | Update or replace the affected dependency |
+| Outdated deps | Stale package versions | Run `bun update` or allowlist intentionally pinned packages |
 
 ## Checklist
 
 - [ ] `bun run devcheck` exits with no errors
+- [ ] Tests run when needed (`bun run devcheck --test` or `bun run test`)

package/skills/field-test/SKILL.md

@@ -4,14 +4,14 @@ description: >
   Exercise tools, resources, and prompts with real-world inputs to verify behavior end-to-end. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface. Calls each definition with realistic and adversarial inputs and produces a report of issues, pain points, and recommendations.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: debug
 ---
 
 ## Context
 
-Unit tests (`add-test` skill) verify handler logic with mocked context. Field testing verifies the full picture: real server, real transport, real inputs, real outputs. It catches issues that unit tests miss — bad descriptions, awkward input shapes, unhelpful error messages, missing format functions, schema mismatches, and surprising edge-case behavior.
+Unit tests (`add-test` skill) verify handler logic with mocked context. Field testing verifies the full picture: real server, real transport, real inputs, real outputs. It catches issues that unit tests miss — bad descriptions, awkward input shapes, unhelpful error messages, missing format functions, schema mismatches, silent divergence between `structuredContent` and model-visible `content[]`, and surprising edge-case behavior.
 
 **Actively use** the tools — don't just read their code.
 
@@ -36,12 +36,17 @@ For every tool, resource, and prompt, run through these categories:
 | Category | What to test |
 |:---------|:-------------|
 | **Happy path** | Realistic input that should succeed. Verify output shape matches the output schema. Verify format function produces sensible content blocks. |
+| **`structuredContent` parity** | Compare the raw handler return, the data captured in `structuredContent`, and what `format()` renders into `content[]`. Flag fields or records that exist in the handler result or `structuredContent` but are absent from `content[]` unless the omission is explicit and acceptable for the tool's purpose. Most LLM clients only see `content[]`, so silent formatter drops are real bugs. |
 | **Variations** | Different valid input combinations — optional fields omitted, optional fields included, different enum values, min/max boundaries. |
+| **Field selection / projection** | For tools with `fields`, `include`, `expand`, `view`, or similar parameters, call the tool with non-default selections. Verify the handler returns the requested fields and `format()` renders each requested field rather than a hardcoded summary subset. |
 | **Edge cases** | Empty strings, zero values, very long inputs, special characters, Unicode. |
 | **Error paths** | Missing required fields, wrong types, nonexistent IDs, inputs that should trigger domain errors. Verify errors are clear and actionable — they should name what went wrong, why, and what to do next. |
 | **Empty results** | Inputs that match nothing. Verify the response explains *why* (echoes criteria, suggests broadening) rather than returning a bare empty array. |
 | **Partial success** | For tools that operate on multiple items, test cases where some succeed and some fail. Verify both outcomes are reported — not just the successes. |
+| **Annotations** | Review tool `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) against actual behavior. If a tool is marked read-only, verify it does not mutate state. If it is marked idempotent, verify retries with the same input are safe. If it is marked open-world false, verify it is not silently depending on live external systems. |
+| **Workflow chaining** | For servers with multi-step workflows, execute 1-2 representative chains end-to-end. Example: search → detail → follow-up action. Verify each step returns the IDs, cursors, URIs, tokens, or state needed for the next step without guessing. |
 | **Response quality** | Inspect successful responses for: (1) chaining IDs needed for follow-up calls, (2) operational metadata (counts, applied filters, truncation notices), (3) filtering transparency (if anything was excluded, does the response say what and how to include it?), (4) reasonable response size (not dumping unbounded data into context). See the `add-tool` skill's **Tool Response Design** section for the full set of patterns. |
+| **Resilience** | For tools backed by external APIs or slow subsystems, test or explicitly note rate-limit, timeout, and transient-failure behavior. Verify retries/backoff happen where intended, or at minimum that the error message clearly tells the user whether to retry, wait, or change input. |
 | **Descriptions** | Read every field's `.describe()` — would a user/LLM understand what to provide? Flag vague or missing descriptions. |
 
 #### Resources
@@ -91,10 +96,15 @@ Cross-cutting observations that aren't tied to a single definition:
 
 - Inconsistent error message patterns across tools
 - Missing format functions (raw JSON returned to user)
+- `structuredContent` contains data that `content[]` silently drops
+- Requested projected fields are returned programmatically but not rendered for the model
 - Description quality issues (vague, missing, or misleading)
 - Schema design issues (required fields that should be optional, missing defaults, overly broad types, non-JSON-Schema-serializable types like `z.custom()` or `z.date()`)
+- Annotation hints that do not match real behavior (`readOnlyHint`, `idempotentHint`, `openWorldHint`)
 - Response quality issues (empty results with no context, silent filtering, missing chaining IDs, oversized payloads, no operational metadata)
+- Multi-step workflows that cannot be completed because intermediate outputs omit required IDs, cursors, or URIs
 - Error messages that don't guide recovery (generic "not found" instead of naming alternatives)
+- Resilience issues (rate limits, timeouts, transient upstream failures handled poorly or explained poorly)
 - Performance observations (unexpectedly slow responses)
 
 ---
@@ -106,7 +116,12 @@ Cross-cutting observations that aren't tied to a single definition:
 - [ ] All registered prompts tested (happy path + defaults)
 - [ ] Error messages reviewed for clarity and recovery guidance
 - [ ] Empty-result responses reviewed for context (criteria echo, suggestions)
+- [ ] `structuredContent` and `content[]` reviewed for parity
+- [ ] Field-selection / projection behavior reviewed where applicable
 - [ ] Response quality reviewed (chaining IDs, metadata, filtering transparency, payload size)
+- [ ] Tool annotations reviewed against actual behavior
+- [ ] Representative multi-step workflows exercised where applicable
+- [ ] External API resilience reviewed where applicable (rate limits, timeouts, transient failures)
 - [ ] Descriptions reviewed for completeness and accuracy
 - [ ] Format functions verified (or absence noted)
 - [ ] Summary report presented to user

package/skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Sync skills and dependencies after package updates. Use after running `bun update @cyanheads/mcp-ts-core` to ensure project skills are up to date, or periodically to check for drift.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: workflow
 ---
@@ -35,7 +35,8 @@ After `bun update @cyanheads/mcp-ts-core`, the package may have newer skills tha
 2. For any major version bumps, review changelogs before proceeding
 3. Run `bun update` to apply updates
 4. Run `bun audit` to check for vulnerabilities introduced by the update
-5. Run `bun run devcheck` to confirm lint, types, security, and tests still pass
+5. Run `bun run devcheck` to confirm lint, definitions, types, and dependency/security checks still pass
+6. Run `bun run test` to confirm runtime behavior still passes
 
 ## Checklist
 
@@ -44,3 +45,4 @@ After `bun update @cyanheads/mcp-ts-core`, the package may have newer skills tha
 - [ ] Dependencies updated (`bun update`)
 - [ ] `bun audit` passes (no new vulnerabilities)
 - [ ] `bun run devcheck` passes
+- [ ] `bun run test` passes

package/skills/migrate-mcp-ts-template/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Migrate an existing mcp-ts-template fork to use @cyanheads/mcp-ts-core as a package dependency. Use when a project was cloned/forked from github.com/cyanheads/mcp-ts-template and carries framework source code in its own src/ — this skill rewrites those internal imports to package subpath imports and removes the bundled framework files.
 metadata:
   author: cyanheads
-  version: "2.1"
+  version: "2.2"
   audience: external
   type: workflow
 ---
@@ -23,7 +23,7 @@ For the full exports catalog, see `CLAUDE.md` → Exports Reference.
 2. **Search for all `@/` imports** across `src/` that reference framework internals
 3. **Rewrite each import** using the mapping table below
 4. **Identify framework source files** now provided by the package (see candidates below) — review each for server-specific additions before cleaning up
-5. **Update entry point** (`src/index.ts`) to use `createApp()` from the package
+5. **Update entry point** (`src/index.ts`) to use `createApp()` from the package and the project's chosen registration pattern (fresh scaffold default: direct imports in `src/index.ts`)
 6. **Update build configs**:
    - `tsconfig.json` extends `@cyanheads/mcp-ts-core/tsconfig.base.json`
    - `biome.json` extends `@cyanheads/mcp-ts-core/biome`
@@ -113,19 +113,19 @@ Framework files within directories that contain server code:
 
 ## Entry point rewrite
 
-Replace the fork's `src/index.ts` with:
+Replace the fork's `src/index.ts` with the scaffold-default direct-registration pattern:
 
 ```ts
 #!/usr/bin/env node
 import { createApp } from '@cyanheads/mcp-ts-core';
-import { allToolDefinitions } from './mcp-server/tools/definitions/index.js';
-import { allResourceDefinitions } from './mcp-server/resources/definitions/index.js';
-import { allPromptDefinitions } from './mcp-server/prompts/definitions/index.js';
+import { echoTool } from './mcp-server/tools/definitions/echo.tool.js';
+import { echoResource } from './mcp-server/resources/definitions/echo.resource.js';
+import { echoPrompt } from './mcp-server/prompts/definitions/echo.prompt.js';
 
 await createApp({
-  tools: allToolDefinitions,
-  resources: allResourceDefinitions,
-  prompts: allPromptDefinitions,
+  tools: [echoTool],
+  resources: [echoResource],
+  prompts: [echoPrompt],
 });
 ```
 
@@ -133,15 +133,17 @@ Add `setup()` if the server initializes services:
 
 ```ts
 await createApp({
-  tools: allToolDefinitions,
-  resources: allResourceDefinitions,
-  prompts: allPromptDefinitions,
+  tools: [echoTool],
+  resources: [echoResource],
+  prompts: [echoPrompt],
   setup(core) {
     initMyService(core.config, core.storage);
   },
 });
 ```
 
+If the migrated project already has `definitions/index.ts` barrels and you want to keep them, that is fine. The important part is removing imports from framework internals and registering definitions consistently.
+
 ## Checklist
 
 - [ ] `@cyanheads/mcp-ts-core` installed as a dependency

package/skills/polish-docs-meta/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: workflow
 ---
@@ -23,7 +23,7 @@ Prefer running after implementation is complete, but safe to re-run at any point
 
 - [ ] All tools/resources/prompts implemented and registered
 - [ ] `bun run devcheck` passes
-- [ ] Tests pass (`npm test`)
+- [ ] Tests pass (`bun run test`)
 
 If these aren't met, address them first.
 
@@ -166,7 +166,7 @@ Run the full check suite one last time:
 
 ```bash
 bun run devcheck
-npm test
+bun run test
 ```
 
 Both must pass clean.
@@ -186,4 +186,4 @@ Both must pass clean.
 - [ ] `Dockerfile` OCI labels and runtime config accurate (if present)
 - [ ] `docs/tree.md` regenerated
 - [ ] `bun run devcheck` passes
-- [ ] `npm test` passes
+- [ ] `bun run test` passes

package/skills/setup/SKILL.md

@@ -4,23 +4,23 @@ description: >
   Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: workflow
 ---
 
 ## Context
 
-This skill assumes `@cyanheads/mcp-ts-core init` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` (identical content), copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
+This skill assumes `@cyanheads/mcp-ts-core init` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
 
 ## Agent Protocol File
 
-The init CLI generates both `CLAUDE.md` and `AGENTS.md` with identical content. Keep the one your agent uses, discard the other:
+The init CLI generates both `CLAUDE.md` and `AGENTS.md` with the same purpose. Keep one authoritative file for the agent you actually use:
 
 - **Claude Code** — keep `CLAUDE.md`, discard `AGENTS.md`
 - **All other agents** (Codex, Cursor, Windsurf, etc.) — keep `AGENTS.md`, discard `CLAUDE.md`
 
-Both files serve the same purpose: project-specific agent instructions. Only one should exist in the committed project.
+Both files serve the same purpose: project-specific agent instructions. Prefer committing one authoritative copy rather than trying to keep both in sync by hand.
 
 For the full framework API, read:
 
@@ -34,7 +34,7 @@ What `init` actually creates:
 
 ```text
 CLAUDE.md                                       # Agent protocol (project-specific)
-AGENTS.md                                       # Same content — discard whichever you don't use
+AGENTS.md                                       # Alternate agent protocol file — keep the one your agent uses
 .github/ISSUE_TEMPLATE/                         # GitHub issue templates (bug report, feature request)
 skills/                                         # Project skills (source of truth)
 src/
@@ -95,19 +95,19 @@ After the initial copy, use the `maintenance` skill to keep them in sync after p
 
 ## Project Scaffolding
 
-After installing dependencies (`npm install`, or `bun install` if using Bun), complete these one-time setup tasks:
+After installing dependencies (prefer `bun install`; `npm install` also works), complete these one-time setup tasks:
 
-1. **Update dependencies to latest** — `npx npm-check-updates -u && npm install` (or `bun update --latest` if using Bun). The scaffolded `package.json` pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.
+1. **Update dependencies to latest** — `bun update --latest` (or `npx npm-check-updates -u && npm install` if using npm). The scaffolded `package.json` pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.
 2. **Initialize git** — `git init && git add -A && git commit -m "chore: scaffold from @cyanheads/mcp-ts-core"`
 3. **Verify agent protocol placeholders** — if the `init` CLI was run without a `[name]` argument, `{{PACKAGE_NAME}}` may remain as a literal in `CLAUDE.md`/`AGENTS.md` and `package.json`. Replace it with the actual server name.
 
 ## Checklist
 
-- [ ] Agent protocol file selected — keep `CLAUDE.md` or `AGENTS.md`, discard the other
+- [ ] Agent protocol file selected — keep one authoritative file (`CLAUDE.md` or `AGENTS.md`)
 - [ ] `{{PACKAGE_NAME}}` placeholders replaced in agent protocol file (if not auto-substituted by init)
 - [ ] Core framework CLAUDE.md read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`)
 - [ ] Unused echo definitions cleaned up (and unregistered from `src/index.ts`)
 - [ ] Skills copied to agent directory (`cp -R skills/* .claude/skills/` or equivalent)
 - [ ] Project structure understood (definitions directories, entry point)
-- [ ] `npm run devcheck` passes
+- [ ] `bun run devcheck` passes
 - [ ] If new server: proceed to `design-mcp-server` skill to plan the tool surface

package/templates/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** {{PACKAGE_NAME}}
-**Version:** 0.1.0
+**Version:** 0.1.1
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -224,6 +224,7 @@ Available skills:
 | `setup` | Post-init project orientation |
 | `design-mcp-server` | Design tool surface, resources, and services for a new server |
 | `add-tool` | Scaffold a new tool definition |
+| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
 | `add-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
 | `add-service` | Scaffold a new service integration |
@@ -281,10 +282,14 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 ## Checklist
 
 - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, etc.)
+- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
 - [ ] 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
+- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
+- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
+- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] 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

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** {{PACKAGE_NAME}}
-**Version:** 0.1.0
+**Version:** 0.1.1
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -25,7 +25,7 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
 
 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
-3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-resource`, `add-prompt` skills
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
 4. **Add services** — scaffold domain service integrations using the `add-service` skill
 5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
@@ -224,6 +224,7 @@ Available skills:
 | `setup` | Post-init project orientation |
 | `design-mcp-server` | Design tool surface, resources, and services for a new server |
 | `add-tool` | Scaffold a new tool definition |
+| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
 | `add-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
 | `add-service` | Scaffold a new service integration |
@@ -286,6 +287,9 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] `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
+- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
+- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
+- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] 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/resources/definitions/echo-app-ui.app-resource.ts

@@ -62,7 +62,12 @@ const APP_HTML = `<!DOCTYPE html>
   </div>
 
   <script type="module">
-    import { App } from "https://unpkg.com/@modelcontextprotocol/ext-apps@1/app-with-deps";
+    import {
+      App,
+      applyDocumentTheme,
+      applyHostFonts,
+      applyHostStyleVariables,
+    } from "https://unpkg.com/@modelcontextprotocol/ext-apps@1/app-with-deps";
 
     const app = new App({ name: "Echo App", version: "1.0.0" });
     const messageEl = document.getElementById("message");
@@ -70,6 +75,18 @@ const APP_HTML = `<!DOCTYPE html>
     const inputEl = document.getElementById("input");
     const sendBtn = document.getElementById("send");
 
+    function applyHostContext(hostContext) {
+      if (hostContext?.theme) {
+        applyDocumentTheme(hostContext.theme);
+      }
+      if (hostContext?.styles?.variables) {
+        applyHostStyleVariables(hostContext.styles.variables);
+      }
+      if (hostContext?.styles?.css?.fonts) {
+        applyHostFonts(hostContext.styles.css.fonts);
+      }
+    }
+
     function render(content) {
       const text = content?.find(c => c.type === "text")?.text;
       if (!text) return;
@@ -82,6 +99,7 @@ const APP_HTML = `<!DOCTYPE html>
 
     // Receive initial tool result pushed by the host
     app.ontoolresult = (result) => render(result.content);
+    app.onhostcontextchanged = applyHostContext;
 
     // Send new echo from the UI
     sendBtn.addEventListener("click", async () => {
@@ -106,7 +124,10 @@ const APP_HTML = `<!DOCTYPE html>
       if (e.key === "Enter") sendBtn.click();
     });
 
-    await app.connect();
+    app.connect().then(() => {
+      const hostContext = app.getHostContext();
+      if (hostContext) applyHostContext(hostContext);
+    });
   </script>
 </body>
 </html>`;
@@ -119,13 +140,13 @@ export const echoAppUiResource = appResource('ui://template-echo-app/app.html',
   description:
     'Interactive HTML app for the echo app tool. Displayed as a sandboxed iframe ' +
     'by MCP Apps-capable hosts.',
+  params: ParamsSchema,
+  auth: ['resource:echo-app-ui:read'],
   _meta: {
     ui: {
       csp: { resourceDomains: ['https://unpkg.com'] },
     },
   },
-  params: ParamsSchema,
-  auth: ['resource:echo-app-ui:read'],
 
   handler(_params, ctx) {
     ctx.log.debug('Serving echo app UI.', { resourceUri: ctx.uri?.href });