@cyanheads/mcp-ts-core 0.9.7 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -18,7 +18,6 @@
     "scripts/lint-mcp.ts",
     "scripts/lint-packaging.ts",
     "scripts/list-skills.ts",
-    "scripts/split-changelog.ts",
     "scripts/tree.ts",
     "skills/",
     "templates/",
@@ -170,7 +169,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
     "@cloudflare/vitest-pool-workers": "^0.16.9",
-    "@cloudflare/workers-types": "^4.20260523.1",
+    "@cloudflare/workers-types": "^4.20260524.1",
     "@duckdb/node-api": "^1.5.3-r.1",
     "@hono/otel": "^1.1.2",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
@@ -198,7 +197,6 @@
     "depcheck": "^1.4.7",
     "diff": "^9.0.0",
     "execa": "^9.6.1",
-    "fast-check": "^4.8.0",
     "fast-xml-parser": "^5.8.0",
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.1",
@@ -228,7 +226,6 @@
     "cloudflare-workers",
     "declarative",
     "framework",
-    "llm",
     "mcp",
     "mcp-server",
     "mcp-framework",
@@ -270,7 +267,7 @@
   },
   "dependencies": {
     "@hono/mcp": "^0.3.0",
-    "@hono/node-server": "^2.0.3",
+    "@hono/node-server": "^2.0.4",
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/api": "^1.9.1",
@@ -296,6 +293,7 @@
     "chrono-node": "^2.9.0",
     "defuddle": "^0.18.1",
     "diff": "latest",
+    "fast-check": "^4.8.0",
     "fast-xml-parser": "^5.8.0",
     "js-yaml": "^4.1.1",
     "linkedom": "^0.18.12",
@@ -355,6 +353,9 @@
     "diff": {
       "optional": true
     },
+    "fast-check": {
+      "optional": true
+    },
     "fast-xml-parser": {
       "optional": true
     },

package/scripts/check-framework-antipatterns.ts

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 /**
- * @fileoverview Guards framework source against three SDK-coupling antipatterns
- * tempting to reach for when fixing tool input-validation error shape (#66) or
- * similar SDK-adjacent bugs. Each rule is narrow and mechanical — the goal is to
- * pin an architectural decision so it does not have to be re-litigated per PR.
+ * @fileoverview Guards against three SDK-coupling antipatterns. Scans `src/`
+ * via `git grep` — all rules target framework-internal paths. Shipped to
+ * consumers via `package.json` `files:` because `devcheck` invokes it; in
+ * consumer projects the scanned paths (`src/mcp-server/tools/`,
+ * `src/mcp-server/transports/`) either don't exist or contain consumer code
+ * that follows different conventions, so the script exits cleanly with 0
+ * findings. Defense-in-depth: harmless when nothing matches, catches real
+ * regressions in the framework.
  *
  * Rules:
  *   1. Framework must not downgrade the Zod `inputSchema` passed to

package/skills/add-app-tool/SKILL.md

@@ -30,11 +30,11 @@ MCP Apps extend the standard tool pattern with an interactive HTML UI rendered i
 
 Both builders are exported from `@cyanheads/mcp-ts-core`. They handle `_meta.ui.resourceUri`, the compat key (`ui/resourceUri`), and the correct MIME type (`text/html;profile=mcp-app`) automatically.
 
-For the full API, Context interface, and error codes, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
+For the full API, Context interface, and error codes, read the framework's `CLAUDE.md` (loaded at session start).
 
 ## Steps
 
-1. **Ask the user** for the tool's name, purpose, input/output shape, and what the UI should display
+1. **Confirm the three conditions** in "When to Use" apply — if any is uncertain, default to `add-tool` instead. Then **gather** the tool's name, purpose, input/output shape, and what the UI should display from the user's request — ask only if genuinely absent
 2. **Choose a URI** — convention: `ui://{{tool-name}}/app.html`
 3. **Create the app tool** at `src/mcp-server/tools/definitions/{{tool-name}}.app-tool.ts`
 4. **Create the app resource** at `src/mcp-server/resources/definitions/{{tool-name}}-ui.app-resource.ts`
@@ -233,10 +233,12 @@ If the repo already uses `definitions/index.ts` barrels, update those instead of
 - [ ] App resource created at `src/mcp-server/resources/definitions/{{tool-name}}-ui.app-resource.ts` using `appResource()`
 - [ ] `resourceUri` matches between tool and resource (`ui://{{tool-name}}/app.html`)
 - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types
-- [ ] `format()` renders JSON first block (for UI) + human-readable, content-complete fallback blocks (for non-app hosts and LLMs)
-- [ ] App resource `_meta.ui.csp` covers any external iframe dependencies, or a custom `format()` adds equivalent per-read metadata
+- [ ] `format()` first block is `JSON.stringify(result)` — the full output object for the UI to parse via `app.ontoolresult`. Subsequent blocks are human-readable, content-complete fallback for non-app hosts and LLMs
+- [ ] App resource `_meta.ui.csp.resourceDomains` lists every external domain loaded by the UI
 - [ ] UI bundles or inlines the client SDK for the shipped HTML, and handles `app.ontoolresult`
 - [ ] UI applies host context updates via `app.onhostcontextchanged`
+- [ ] App resource has a `list` callback returning at least one URI so resource-aware clients can discover it
 - [ ] Both registered in the project's existing `createApp()` arrays (directly or via barrels)
+- [ ] Handler tested directly via `createMockContext()`, or `add-test` skill run to scaffold the test file
 - [ ] `bun run devcheck` passes (linter validates `_meta.ui` and tool/resource pairing)
 - [ ] Smoke-tested with `bun run rebuild && bun run start:stdio` (or `start:http`)

package/skills/add-export/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 Subpath exports are defined in `package.json` under the `exports` field. Each subpath maps to a source entry point that gets compiled to `dist/`. The exports catalog in `CLAUDE.md` must stay in sync with `package.json`.
 
-The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src` and `include: ["src/**/*"]`. This means every source file at `src/foo/bar.ts` compiles to `dist/foo/bar.js` — the `dist/` paths in `exports` must mirror the source tree exactly, not flatten it.
+The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src` and `include: ["src/**/*"]`. This means every source file at `src/foo/bar.ts` compiles to `dist/foo/bar.js` — the `dist/` path in each export entry must match wherever `tsc` produces the compiled output for the named source file. Choose your source file location to produce the `dist/` path you want in the export entry.
 
 ## Steps
 
@@ -28,16 +28,16 @@ The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src`
    }
    ```
 
-3. **Update the exports catalog** in `CLAUDE.md` — add a row to the table
+3. **Update the exports catalog** in both `CLAUDE.md` and `AGENTS.md` — add a row to the table. These files must stay byte-identical; the simplest approach is `cp CLAUDE.md AGENTS.md` after editing
 4. **Build** with `bun run build` to generate `dist/` output
-5. **Verify the export** by inspecting the compiled output directly:
+5. **Verify the export** resolves through the package's `exports` map:
 
    ```bash
    # Confirm the compiled file exists at the expected dist path
    ls dist/utils/new-util.js
 
-   # Confirm the declared exports resolve to real files
-   bun -e "import('./dist/utils/new-util.js').then(m => console.log(Object.keys(m)))"
+   # Confirm the subpath export resolves correctly (tests the exports map, not just the dist file)
+   bun -e "import('@cyanheads/mcp-ts-core/newutil').then(m => console.log(Object.keys(m)))"
    ```
 
 6. **Run `bun run devcheck`** to verify
@@ -46,7 +46,7 @@ The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src`
 
 | Convention | Rule |
 |:-----------|:-----|
-| Subpath | lowercase, no underscores (e.g., `utils/errorHandler`) |
+| Subpath | all-lowercase, no underscores (e.g., `utils`, `storage/types`, `testing/fuzz`) |
 | Source file | kebab-case (e.g., `error-handler.ts`) |
 | Export name | camelCase for values, PascalCase for types |
 
@@ -54,7 +54,9 @@ The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src`
 
 - [ ] Source entry point file created with JSDoc header
 - [ ] Subpath added to `package.json` `exports` with `types` and `import` conditions
-- [ ] Exports catalog in `CLAUDE.md` updated with new row
+- [ ] Exports catalog updated in both `CLAUDE.md` and `AGENTS.md` (must be byte-identical)
+- [ ] If the new export has optional peer dependencies: entries added to both `peerDependencies` and `peerDependenciesMeta` in `package.json`
 - [ ] `bun run build` succeeds
-- [ ] Compiled file exists at expected `dist/` path and exports the expected symbols
+- [ ] Compiled file exists at expected `dist/` path and subpath import resolves correctly
+- [ ] Integration test at `tests/integration/package-consumer.int.test.ts` updated: new subpath added to the import spec list and `toHaveLength` count incremented
 - [ ] `bun run devcheck` passes

package/skills/add-prompt/SKILL.md

@@ -11,15 +11,13 @@ metadata:
 
 ## Context
 
-Prompts use the `prompt()` builder from `@cyanheads/mcp-ts-core`. Each prompt lives in `src/mcp-server/prompts/definitions/` with a `.prompt.ts` suffix and is registered into `createApp()` in `src/index.ts`. Some repos later add `definitions/index.ts` barrels; match the project's current pattern.
+Prompts use the `prompt()` builder from `@cyanheads/mcp-ts-core`. Each prompt lives in `src/mcp-server/prompts/definitions/` with a `.prompt.ts` suffix. The standard registration pattern uses a `definitions/index.ts` barrel that collects all prompts into an `allPromptDefinitions` array for `createApp()`. Fresh scaffolds start with direct imports in `src/index.ts` — the barrel is introduced as definitions grow. Match the pattern already used by the project you're editing.
 
-Prompts are pure message templates — no `Context`, no auth, no side effects.
-
-For the full `prompt()` API, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
+Prompts are pure message templates — no `Context`, no auth, no side effects. `generate` can be sync or async (returns `PromptMessage[] | Promise<PromptMessage[]>`).
 
 ## Steps
 
-1. **Ask the user** for the prompt's name, purpose, and arguments
+1. **Gather** the prompt's name, purpose, and arguments from the user's request — ask only if genuinely absent
 2. **Create the file** at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
 3. **Register** the prompt in the project's existing `createApp()` prompt list (directly in `src/index.ts` for fresh scaffolds, or via a barrel if the repo already has one)
 4. **Run `bun run devcheck`** to verify
@@ -36,6 +34,8 @@ import { prompt, z } from '@cyanheads/mcp-ts-core';
 
 export const {{PROMPT_EXPORT}} = prompt('{{prompt_name}}', {
   description: '{{PROMPT_DESCRIPTION}}',
+  // args is optional — omit entirely for prompts with no parameters.
+  // When present, all fields need .describe(). Only JSON-Schema-serializable types allowed.
   args: z.object({
     // All fields need .describe()
   }),
@@ -86,14 +86,21 @@ await createApp({
 });
 ```
 
-If the repo already uses `src/mcp-server/prompts/definitions/index.ts`, update that barrel instead.
+If the repo already uses `src/mcp-server/prompts/definitions/index.ts`, add the export to that barrel instead:
+
+```typescript
+export { {{PROMPT_EXPORT}} } from './{{prompt-name}}.prompt.js';
+```
 
 ## Checklist
 
 - [ ] File created at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
-- [ ] All Zod `args` fields have `.describe()` annotations
+- [ ] Prompt name passed to `prompt()` uses snake_case
+- [ ] `description` field set (lint warns if absent, but `devcheck` won't hard-fail — verify it's present)
+- [ ] All Zod `args` fields have `.describe()` annotations — or `args` omitted entirely for no-parameter prompts
+- [ ] `args` fields use only JSON-Schema-serializable Zod types (no `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.custom()`, etc.)
 - [ ] JSDoc `@fileoverview` and `@module` header present
-- [ ] `generate` function returns valid message array
+- [ ] `generate` function present and returns at least one `{ role, content: { type: 'text', text } }` message
 - [ ] No side effects — prompts are pure templates
 - [ ] Registered in the project's existing `createApp()` prompt list (directly or via barrel)
 - [ ] `bun run devcheck` passes

package/skills/add-provider/SKILL.md

@@ -15,6 +15,10 @@ Providers implement interfaces defined in core. They are selected at runtime via
 (e.g., `STORAGE_PROVIDER_TYPE`). Tier 3 providers lazy-load their dependencies to keep the
 core bundle small.
 
+Providers live inside the package source tree — import the interface via relative path
+(e.g., `import type { IStorageProvider } from '../core/IStorageProvider.js'`), not via the
+package subpath exports (those are for consumers).
+
 ## Provider interfaces
 
 | Domain  | Interface file                                    |
@@ -32,9 +36,11 @@ these flags drive routing in `SpeechService`.
 
 Provider file location and naming differ by domain:
 
-- **Storage** — nested subdirectory, PascalCase file:
-  `src/storage/providers/{{provider-name}}/{{provider-name}}Provider.ts`
-  (e.g., `src/storage/providers/inMemory/inMemoryProvider.ts`)
+- **Storage** — nested subdirectory, camelCase directory name, PascalCase-suffixed provider file.
+  Each provider gets its own subdirectory for the provider file plus any co-located types:
+  `src/storage/providers/{{providerName}}/{{providerName}}Provider.ts`
+  (e.g., `src/storage/providers/inMemory/inMemoryProvider.ts`,
+  `src/storage/providers/supabase/supabaseProvider.ts` + `supabase.types.ts`)
 
 - **LLM / Speech** — flat directory, kebab-case with `.provider.ts` suffix:
   `src/services/llm/providers/{{provider-name}}.provider.ts`
@@ -63,8 +69,11 @@ Provider file location and naming differ by domain:
 
 5. **Register the provider** — the registration point differs by domain:
 
-   - **Storage** — add a `case` to the `switch` in `src/storage/core/storageFactory.ts`
-     inside `createStorageProvider()`. Import the new provider class at the top of that file.
+   - **Storage** — two changes required:
+     1. Add the new provider string to the `z.enum` for `STORAGE_PROVIDER_TYPE` in
+        `src/config/index.ts` — without this, the config schema rejects the env var at runtime.
+     2. Add a `case` to the `switch` in `src/storage/core/storageFactory.ts`
+        inside `createStorageProvider()`. Import the new provider class at the top of that file.
 
    - **Speech** — two changes required:
      1. Add the new provider string literal to the `provider` union in
@@ -75,8 +84,10 @@ Provider file location and naming differ by domain:
 
    - **LLM** — currently only one provider exists (`OpenRouterProvider`); it is
      instantiated directly in `src/core/app.ts` rather than through a factory switch.
-     Add a factory function or extend `app.ts` as needed, then update `ILlmProvider`
-     consumers accordingly.
+     There is no factory pattern yet — adding a second provider requires introducing
+     one (a selector env var, a factory function, and a conditional in `app.ts`).
+     Read `src/core/app.ts` to understand the current instantiation site before
+     designing the wiring.
 
 6. **Update the Worker-compatible provider list** if the new storage provider runs in
    Cloudflare Workers. The list is an inline array in `storageFactory.ts` at the
@@ -90,8 +101,11 @@ Provider file location and naming differ by domain:
    Add the new provider string to this array. Non-storage providers have no equivalent
    gate.
 
-7. **Add the dependency** as an optional peer dependency in `package.json` if Tier 3.
-8. **Run `bun run devcheck`** to verify.
+7. **Add the dependency** if Tier 3: add to both `peerDependencies` and
+   `peerDependenciesMeta` (with `{ "optional": true }`) in `package.json`.
+   Without the `peerDependenciesMeta` entry, the dep appears required rather than optional.
+8. **Run `bun run rebuild`** — since this is package source, verify the build output compiles.
+9. **Run `bun run devcheck`** to verify.
 
 ## Checklist
 
@@ -99,8 +113,11 @@ Provider file location and naming differ by domain:
 - [ ] Interface fully implemented (including `name`, `supportsTTS`/`supportsSTT` for speech)
 - [ ] Tier 3 dependencies lazy-loaded (not top-level imports)
 - [ ] Registered in the correct factory for the domain (see Step 5)
-- [ ] Speech: `provider` literal added to `SpeechProviderConfig` union in `types.ts`
+- [ ] Storage: provider string added to `z.enum` in `src/config/index.ts`
 - [ ] Storage: Worker-compatible array in `storageFactory.ts` updated if applicable
-- [ ] Optional peer dependency added to `package.json` if Tier 3
+- [ ] Speech: `provider` literal added to `SpeechProviderConfig` union in `types.ts`
+- [ ] LLM: `src/core/app.ts` instantiation logic updated if adding a second LLM provider
+- [ ] Optional peer dependency added to both `peerDependencies` and `peerDependenciesMeta` in `package.json` if Tier 3
+- [ ] `bun run rebuild` succeeds
 - [ ] `bun run devcheck` passes
-- [ ] Integration tested with the target backend
+- [ ] Test file created at `src/storage/providers/{{name}}/{{name}}Provider.test.ts` (or equivalent path for the domain) and `bun run test` passes

package/skills/add-resource/SKILL.md

@@ -11,15 +11,13 @@ metadata:
 
 ## Context
 
-Resources use the `resource()` builder from `@cyanheads/mcp-ts-core`. Each resource lives in `src/mcp-server/resources/definitions/` with a `.resource.ts` suffix and is registered into `createApp()` in `src/index.ts`. Some repos later add `definitions/index.ts` barrels; follow the pattern already used by the project.
+Resources use the `resource()` builder from `@cyanheads/mcp-ts-core`. Each resource lives in `src/mcp-server/resources/definitions/` with a `.resource.ts` suffix. The standard registration pattern uses a `definitions/index.ts` barrel that collects all resources into an `allResourceDefinitions` array for `createApp()`. Fresh scaffolds start with direct imports in `src/index.ts` — the barrel is introduced as definitions grow. Match the pattern already used by the project you're editing.
 
 **Tool coverage.** Not all MCP clients expose resources — many are tool-only (Claude Code, Cursor, most chat UIs). Before adding a resource, verify the same data is reachable via the tool surface — either through a dedicated tool, included in another tool's output, or bundled into a broader tool. A resource whose data has no tool path is invisible to a large share of agents.
 
-For the full `resource()` API, pagination utilities, and `Context` interface, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
-
 ## Steps
 
-1. **Ask the user** for the resource's URI template, purpose, and data shape
+1. **Gather** the resource's URI template, purpose, and data shape from the user's request — ask only if genuinely absent
 2. **Design the URI** — use `{paramName}` for path parameters (e.g., `myscheme://{itemId}/data`)
 3. **Create the file** at `src/mcp-server/resources/definitions/{{resource-name}}.resource.ts`
 4. **Register** the resource in the project's existing `createApp()` resource list (directly in `src/index.ts` for fresh scaffolds, or via a barrel if the repo already has one)
@@ -105,7 +103,11 @@ await createApp({
 });
 ```
 
-If the repo already uses `src/mcp-server/resources/definitions/index.ts`, update that barrel instead of changing the registration style.
+If the repo already uses `src/mcp-server/resources/definitions/index.ts`, add the export to that barrel instead:
+
+```typescript
+export { {{RESOURCE_EXPORT}} } from './{{resource-name}}.resource.js';
+```
 
 ### Optional: declarative `errors[]` contract
 
@@ -118,11 +120,14 @@ export const articleResource = resource('article://{pmid}', {
   description: 'Read an article by PMID.',
   errors: [
     { reason: 'no_pmid_match', code: JsonRpcErrorCode.NotFound,
-      when: 'PMID not found in the index.' },
+      when: 'PMID not found in the index.',
+      recovery: 'Use pubmed_search_articles to discover valid PMIDs first.' },
     { reason: 'withdrawn', code: JsonRpcErrorCode.NotFound,
-      when: 'Article was withdrawn upstream.' },
+      when: 'Article was withdrawn upstream.',
+      recovery: 'Check PubMed directly for retraction or withdrawal notices.' },
     { reason: 'upstream_throttled', code: JsonRpcErrorCode.RateLimited,
-      when: 'Upstream PubMed quota hit.', retryable: true },
+      when: 'Upstream PubMed quota hit.', retryable: true,
+      recovery: 'Wait a few seconds and retry the request.' },
   ],
   params: z.object({ pmid: z.string().describe('PubMed ID') }),
   async handler(params, ctx) {
@@ -142,21 +147,25 @@ Beyond `description`, `params`, `handler`, and `list`, the builder also supports
 
 | Field | Purpose |
 |:------|:--------|
+| `name` | Short human-readable name for `resources/list`. Defaults to a slug derived from the URI template if omitted. |
 | `output` | Optional Zod schema for runtime validation of the handler return value (parity with `tool()`'s `output`). |
 | `format` | Optional formatter mapping the handler's return to the `ReadResourceResult.contents[]` shape. Default: string passthrough; objects serialized to JSON. Override when you need to attach permissions, custom encodings, or split into multiple content items. |
 | `annotations` | Resource annotations (e.g., `audience`, `priority`) — see `ResourceAnnotations`. |
 | `title` | Human-readable display title (defaults to `name`). |
+| `examples` | Array of `{ name, uri }` example entries surfaced in `resources/list` for discoverability. |
 
 ## Checklist
 
 - [ ] File created at `src/mcp-server/resources/definitions/{{resource-name}}.resource.ts`
-- [ ] URI template uses `{paramName}` syntax for path parameters
+- [ ] Resource name passed to `resource()` uses a valid URI template with `{paramName}` syntax
 - [ ] All Zod `params` fields have `.describe()` annotations
+- [ ] `output` schema added if the handler returns structured data that benefits from runtime validation
 - [ ] JSDoc `@fileoverview` and `@module` header present
 - [ ] `handler(params, ctx)` is pure — throws on failure, no try/catch
-- [ ] Data is reachable via the tool surface (dedicated tool, another tool's output, or not needed for tool-only agents)
+- [ ] If `errors[]` contract declared: every entry has a `recovery` field (≥5 words, lint-enforced)
+- [ ] Data is reachable via the tool surface — confirm by checking `src/mcp-server/tools/definitions/` for a tool that exposes this data, or document why this resource is resources-only
 - [ ] `list()` function provided if the resource is discoverable
-- [ ] Pagination used for large result sets (`extractCursor`/`paginateArray`)
+- [ ] Pagination used for large result sets (`extractCursor`/`paginateArray`) — applies to both `handler` data and `list()` catalogs with many entries
 - [ ] Registered in the project's existing `createApp()` resource list (directly or via barrel)
 - [ ] `bun run devcheck` passes
 - [ ] Smoke-tested with `bun run rebuild && bun run start:stdio` (or `start:http`)

package/skills/add-service/SKILL.md

@@ -15,11 +15,11 @@ Services use the init/accessor pattern: initialized once in `createApp`'s `setup
 
 Service methods receive `Context` for correlated logging (`ctx.log`) and tenant-scoped storage (`ctx.state`). Convention: `ctx.elicit` and `ctx.sample` should only be called from tool handlers, not from services.
 
-For the full service pattern, `CoreServices`, and `Context` interface, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
+For the full service pattern, `CoreServices`, and `Context` interface, read the framework's `CLAUDE.md` (loaded at session start).
 
 ## Steps
 
-1. **Ask the user** for the service domain name and what it integrates with
+1. **Gather** the service domain name and what it integrates with from the user's request — ask only if genuinely absent
 2. **Create the directory** at `src/services/{{domain}}/`
 3. **Create the service file** at `src/services/{{domain}}/{{domain}}-service.ts`
 4. **Create types** at `src/services/{{domain}}/types.ts` if needed
@@ -71,19 +71,16 @@ export function get{{ServiceName}}(): {{ServiceName}} {
 
 ### Entry point registration
 
+Add the `setup()` callback and import to the existing `createApp()` call — preserve the existing tool/resource/prompt arrays:
+
 ```typescript
-// src/index.ts
-import { createApp } from '@cyanheads/mcp-ts-core';
+// In src/index.ts (or src/worker.ts for Worker-only servers)
 import { init{{ServiceName}} } from './services/{{domain}}/{{domain}}-service.js';
 
-await createApp({
-  tools: [/* existing tools */],
-  resources: [/* existing resources */],
-  prompts: [/* existing prompts */],
-  setup(core) {
-    init{{ServiceName}}(core.config, core.storage);
-  },
-});
+// Add setup() alongside existing options:
+setup(core) {
+  init{{ServiceName}}(core.config, core.storage);
+},
 ```
 
 ### Usage in tool handlers
@@ -133,13 +130,13 @@ async fetchItem(id: string, ctx: Context): Promise<Item> {
 ### Key principles
 
 1. **Calibrate backoff to the upstream.** 200–500ms for ephemeral failures, 1–2s for rate-limited APIs, 2–5s for service degradation. The default `baseDelayMs: 1000` suits most APIs.
-2. **Check HTTP status before parsing.** `fetchWithTimeout` already throws `ServiceUnavailable` on non-OK responses — this prevents feeding HTML error pages into XML/JSON parsers.
+2. **Check HTTP status before parsing.** `fetchWithTimeout` already throws on non-OK responses with granular status mapping (401→`Unauthorized`, 403→`Forbidden`, 404→`NotFound`, 408/425→`Timeout`, 422→`ValidationError`, 429→`RateLimited`, 5xx→`ServiceUnavailable`/`InternalError`) — this prevents feeding HTML error pages into XML/JSON parsers.
 3. **Classify parse failures by content.** If the upstream returns HTTP 200 with an HTML error page, detect it and throw `ServiceUnavailable` (transient) instead of `SerializationError` (non-transient).
 4. **Exhausted retries say so.** `withRetry` automatically enriches the final error with attempt count — callers know retries were already attempted.
 
 ### When you need finer-grained HTTP error classification
 
-`fetchWithTimeout` collapses every non-2xx into `ServiceUnavailable`. That's the safe default but it isn't always right — a `401` should be `Unauthorized`, a `429` should be `RateLimited` (and is retryable), a `408` should be `Timeout` (and is retryable). When you need the nuance, drop down to raw `fetch` + `httpErrorFromResponse`:
+`fetchWithTimeout` already maps status codes to appropriate error codes (see key principle 2 above). Use `httpErrorFromResponse` instead when you need `Retry-After` header capture, request body passthrough in error data, or custom `service`/`data` fields on the thrown error:
 
 ```typescript
 import { httpErrorFromResponse, withRetry } from '@cyanheads/mcp-ts-core/utils';
@@ -289,11 +286,12 @@ Silent truncation is a data integrity bug — the caller thinks it has all resul
 ## Checklist
 
 - [ ] Directory created at `src/services/{{domain}}/`
-- [ ] Service file created with init/accessor pattern
+- [ ] Service file created — `init` function accepts `(config: AppConfig, storage: StorageService)` and stores the instance
+- [ ] Accessor function exported — throws `Error` if not initialized
 - [ ] JSDoc `@fileoverview` and `@module` header present
+- [ ] No `console` calls — use `ctx.log` for service-level logging
 - [ ] Service methods accept `Context` for logging and storage
-- [ ] `init` function registered in `setup()` callback in `src/index.ts`
-- [ ] Accessor throws `Error` if not initialized
+- [ ] `init` function registered in `setup()` callback in the server's entry point (`src/index.ts` or `src/worker.ts`)
 - [ ] If wrapping external API: retry covers full pipeline (fetch + parse), backoff calibrated
 - [ ] If wrapping external API: raw/domain types reflect real upstream sparsity; missing values are preserved as unknown, not fabricated into concrete facts
 - [ ] If wrapping external API: batch endpoints used where available, field selection applied, pagination handled

package/skills/add-test/SKILL.md

@@ -21,10 +21,10 @@ For the full `createMockContext` API and testing patterns, read:
 
 1. **Identify the target** — which tool, resource, or service needs tests
 2. **Read the source file** — understand the handler's logic, input/output schemas, error paths, and which `ctx` features it uses
-3. **Create the test file** in the repo's existing test layout
+3. **Create the test file** in the repo's existing test layout — search for existing `*.test.ts` files to confirm whether tests are colocated with source or under a root `tests/` directory
 4. **Write test cases** covering happy path, error paths, and edge cases
 5. **Run `bun run test`** to verify
-6. **Run `bun run devcheck`** to verify types
+6. **Run `bun run devcheck`** to verify lint, types, and MCP definitions
 
 ## Determining What to Test
 
@@ -41,6 +41,7 @@ Read the handler and identify:
 | **`ctx.fail` (typed contract)** | Definitions with `errors[]` need `fail` attached to the mock ctx — `createMockContext({ errors: myTool.errors })` does it for you. Assert on `data.reason` (stable per-contract entry), not just `code`. |
 | **`format` function** | Test separately if defined — it's pure, no ctx needed. Verify it renders the IDs and fields the model needs, not just a count or title. For projection-style tools, test non-default field selections. |
 | **Sparse upstream payloads** | For third-party API integrations, build a fixture with omitted fields. Assert normalized output still validates and `format()` preserves unknown values instead of inventing facts. |
+| **Form-client payloads** | If handler has optional fields: test with empty-string inner values (form clients send `""` instead of `undefined`). Assert handler doesn't break or produce invalid output. |
 | **Auth scopes** | Not tested at handler level (framework enforces) — skip |
 
 ## Templates
@@ -134,6 +135,8 @@ describe('{{RESOURCE_EXPORT}}', () => {
   //   expect(err.code).toBe(JsonRpcErrorCode.NotFound);
   //   expect(err.data.reason).toBe('no_match');
 
+  // Include this block only when the resource definition exports a `list` function.
+  // Check the source — `list` is optional on resource definitions.
   it('lists available resources', async () => {
     const listing = await {{RESOURCE_EXPORT}}.list!();
     expect(listing.resources).toBeInstanceOf(Array);
@@ -156,14 +159,16 @@ describe('{{RESOURCE_EXPORT}}', () => {
 
 import { beforeEach, describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { StorageService } from '@cyanheads/mcp-ts-core/storage';
 import { get{{ServiceClass}}, init{{ServiceClass}} } from '@/services/{{domain}}/{{domain}}-service.js';
 
-import { createInMemoryStorage } from '@cyanheads/mcp-ts-core/testing';
+// Derive the minimal mock config from src/config/server-config.ts — read
+// the server's Zod schema to see which fields init{{ServiceClass}}() needs.
+const mockConfig = { /* fields from server config schema */ } as AppConfig;
 
 describe('{{ServiceClass}}', () => {
-  beforeEach(() => {
-    // Re-initialize with fresh config/storage for each test
-    const mockStorage = createInMemoryStorage();
+  beforeEach(async () => {
+    const mockStorage = await StorageService.create({ type: 'in-memory' });
     init{{ServiceClass}}(mockConfig, mockStorage);
   });
 
@@ -206,8 +211,42 @@ it('respects cancellation', async () => {
   setTimeout(() => controller.abort(), 50);
   const result = await {{TOOL_EXPORT}}.handler(input, ctx);
 
-  // Should have stopped early
-  expect(result.finalCount).toBeGreaterThan(0);
+  // Should have returned a partial result rather than throwing on cancellation.
+  // Assert on a field from the tool's actual output schema.
+  expect(result).toBeDefined();
+});
+```
+
+### Prompt test
+
+```typescript
+/**
+ * @fileoverview Tests for {{PROMPT_NAME}} prompt.
+ * @module tests/prompts/{{PROMPT_NAME}}.prompt.test
+ */
+
+import { describe, expect, it } from 'vitest';
+import { {{PROMPT_EXPORT}} } from '@/mcp-server/prompts/definitions/{{prompt-name}}.prompt.js';
+
+describe('{{PROMPT_EXPORT}}', () => {
+  it('generates valid messages for valid args', () => {
+    const args = {{PROMPT_EXPORT}}.args!.parse({
+      // valid args matching the Zod schema
+    });
+    const messages = {{PROMPT_EXPORT}}.generate(args);
+    expect(messages).toBeInstanceOf(Array);
+    expect(messages.length).toBeGreaterThan(0);
+    for (const msg of messages) {
+      expect(msg).toHaveProperty('role');
+      expect(msg).toHaveProperty('content');
+    }
+  });
+
+  // Include only when the prompt has no required args (args is optional or all fields optional).
+  it('generates messages with no args', () => {
+    const messages = {{PROMPT_EXPORT}}.generate({});
+    expect(messages.length).toBeGreaterThan(0);
+  });
 });
 ```
 
@@ -249,6 +288,8 @@ When scaffolding tests for an existing handler, use the Zod schemas to generate
 - [ ] `format` function tested if defined
 - [ ] `createMockContext` options match handler's ctx usage (`tenantId`, `progress`, `elicit`, `sample`)
 - [ ] Service re-initialized in `beforeEach` if handler depends on a service singleton
-- [ ] If wrapping external API: sparse-payload case tested (omitted upstream fields still validate; `format()` does not invent facts)
+- [ ] If handler has optional fields: tested with empty-string inner values (form-client simulation)
+- [ ] If wrapping external API: sparse-payload case tested — fixture omits at least one optional upstream field; output still validates and `format()` renders uncertainty honestly instead of inventing values
+- [ ] If target is a prompt: `generate()` tested with valid args and (when applicable) no args
 - [ ] `bun run test` passes
 - [ ] `bun run devcheck` passes

package/skills/add-tool/SKILL.md

@@ -11,18 +11,16 @@ metadata:
 
 ## Context
 
-Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in `src/mcp-server/tools/definitions/` with a `.tool.ts` suffix and is registered into `createApp()` in `src/index.ts`. Some larger repos later add `definitions/index.ts` barrels; match the pattern already used by the project you're editing.
-
-For the full `tool()` API, `Context` interface, and error codes, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
+Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in `src/mcp-server/tools/definitions/` with a `.tool.ts` suffix. The standard registration pattern uses a `definitions/index.ts` barrel that collects all tools into an `allToolDefinitions` array for `createApp()`. Fresh scaffolds from `init` start with direct imports in `src/index.ts` — the barrel is introduced as definitions grow. Match the pattern already used by the project you're editing.
 
 ## Steps
 
-1. **Ask the user** for the tool's name, purpose, and input/output shape
+1. **Gather** the tool's name, purpose, and input/output shape from the user's request — ask only if genuinely absent
 2. **Determine if long-running** — if the tool involves streaming, polling, or
    multi-step async work, it should use `task: true`
 3. **Create the file** at `src/mcp-server/tools/definitions/{{tool-name}}.tool.ts`
 4. **Register** the tool in the project's existing `createApp()` tool list (directly in `src/index.ts` for fresh scaffolds, or via a barrel if the repo already has one)
-5. **Run `bun run devcheck`** to verify
+5. **Run `bun run devcheck`** to verify — if Biome reports formatting issues, run `bun run format` to auto-fix, then re-run devcheck
 6. **Smoke-test** with `bun run rebuild && bun run start:stdio` (or `start:http`)
 
 ## Naming
@@ -136,6 +134,7 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
   output: z.object({ /* ... */ }),
 
   async handler(input, ctx) {
+    // ctx.progress is guaranteed non-null when task: true — the ! assertion is safe here.
     await ctx.progress!.setTotal(totalSteps);
     for (const step of steps) {
       if (ctx.signal.aborted) break;
@@ -528,18 +527,26 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 ## Checklist
 
 - [ ] File created at `src/mcp-server/tools/definitions/{{tool-name}}.tool.ts`
+- [ ] Tool name passed to `tool()` uses snake_case
+- [ ] `title` field set
+- [ ] `annotations` set correctly — `readOnlyHint: false` for write tools, `destructiveHint: true` for delete/overwrite tools
 - [ ] All Zod schema fields have `.describe()` annotations
 - [ ] Numeric `output` fields carry units in the field name (`sizeInBytes`, `durationInMs`, `priceInCents`, `latencyInMs`) — `.describe()` may be summarized away or truncated, but the field name persists into the JSON the agent reads. Exempt: dimensionless counts (`totalCount`, `itemCount`), indices (`index`, `position`)
 - [ ] 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
 - [ ] Optional nested objects guarded for empty inner values from form-based clients (check `?.field` truthiness, not just object presence)
-- [ ] `handler(input, ctx)` is pure — throws on failure, no try/catch
+- [ ] No `console` calls — use `ctx.log` for handler logging
+- [ ] `handler(input, ctx)` is pure — throws on failure, no try/catch (exception: batch tools with per-item isolation use try/catch inside the loop — that's intentional, don't remove it)
 - [ ] `format()` renders every field in the output schema — enforced at lint time via sentinel injection, startup fails with `format-parity` errors otherwise. Different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data. Primary fix: render the missing field in `format()` (use `z.discriminatedUnion` for list/detail variants). Escape hatch: if the output schema was over-typed for a genuinely dynamic upstream API, relax it (`z.object({}).passthrough()`) rather than maintaining aspirational typing
 - [ ] If wrapping external API: output schema and `format()` preserve uncertainty from sparse upstream payloads instead of inventing concrete values
 - [ ] `auth` scopes declared if the tool needs authorization
 - [ ] `errors: [...]` contract declared for the tool's domain-specific failure modes — or block deleted if no domain failures apply (baseline codes bubble freely)
 - [ ] Error contract declared inline on this tool — not imported from a shared module, even when other tools have near-identical entries
 - [ ] `task: true` added if the tool is long-running
+- [ ] If `task: true`: handler checks `ctx.signal.aborted` in its loop for cancellation support
+- [ ] If tool returns unbounded arrays: pagination with total count, or `spillover()` / DataCanvas for tabular working sets
+- [ ] If tool is feature-gated: evaluated whether `disabledTool()` wrapper is appropriate (present in manifest but uncallable)
 - [ ] Registered in the project's existing `createApp()` tool list (directly or via barrel)
+- [ ] Test file created via `add-test` skill, or handler tested directly with `createMockContext()`
 - [ ] `bun run devcheck` passes
 - [ ] Smoke-tested with `bun run rebuild && bun run start:stdio` (or `start:http`)