@cyanheads/mcp-ts-core 0.3.3 → 0.3.5

package/skills/add-prompt/SKILL.md

@@ -4,14 +4,14 @@ description: >
   Scaffold a new MCP prompt template. Use when the user asks to add a prompt, create a reusable message template, or define a prompt for LLM interactions.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: reference
 ---
 
 ## 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 in the barrel `index.ts`.
+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 are pure message templates — no `Context`, no auth, no side effects.
 
@@ -23,7 +23,7 @@ For the full `prompt()` API, read:
 
 1. **Ask the user** for the prompt's name, purpose, and arguments
 2. **Create the file** at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
-3. **Register** the prompt in `src/mcp-server/prompts/definitions/index.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
 
 ## Template
@@ -74,17 +74,22 @@ generate: (args) => [
 ],
 ```
 
-### Barrel registration
+### Registration
 
 ```typescript
-// src/mcp-server/prompts/definitions/index.ts
-import { {{PROMPT_EXPORT}} } from './{{prompt-name}}.prompt.js';
-export const allPromptDefinitions = [
-  // ... existing prompts
-  {{PROMPT_EXPORT}},
-];
+// src/index.ts (fresh scaffold default)
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { {{PROMPT_EXPORT}} } from './mcp-server/prompts/definitions/{{prompt-name}}.prompt.js';
+
+await createApp({
+  tools: [/* existing tools */],
+  resources: [/* existing resources */],
+  prompts: [{{PROMPT_EXPORT}}],
+});
 ```
 
+If the repo already uses `src/mcp-server/prompts/definitions/index.ts`, update that barrel instead.
+
 ## Checklist
 
 - [ ] File created at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
@@ -92,5 +97,5 @@ export const allPromptDefinitions = [
 - [ ] JSDoc `@fileoverview` and `@module` header present
 - [ ] `generate` function returns valid message array
 - [ ] No side effects — prompts are pure templates
-- [ ] Registered in `definitions/index.ts` barrel and `allPromptDefinitions`
+- [ ] Registered in the project's existing `createApp()` prompt list (directly or via barrel)
 - [ ] `bun run devcheck` passes

package/skills/add-resource/SKILL.md

@@ -4,14 +4,14 @@ description: >
   Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
 
 ## 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 in the barrel `index.ts`.
+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.
 
 **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.
 
@@ -24,7 +24,7 @@ For the full `resource()` API, pagination utilities, and `Context` interface, re
 1. **Ask the user** for the resource's URI template, purpose, and data shape
 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 `src/mcp-server/resources/definitions/index.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)
 5. **Run `bun run devcheck`** to verify
 6. **Smoke-test** with `bun run dev:stdio` or `dev:http`
 
@@ -93,17 +93,22 @@ async handler(params, ctx) {
 },
 ```
 
-### Barrel registration
+### Registration
 
 ```typescript
-// src/mcp-server/resources/definitions/index.ts
-import { {{RESOURCE_EXPORT}} } from './{{resource-name}}.resource.js';
-export const allResourceDefinitions = [
-  // ... existing resources
-  {{RESOURCE_EXPORT}},
-];
+// src/index.ts (fresh scaffold default)
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { {{RESOURCE_EXPORT}} } from './mcp-server/resources/definitions/{{resource-name}}.resource.js';
+
+await createApp({
+  tools: [/* existing tools */],
+  resources: [{{RESOURCE_EXPORT}}],
+  prompts: [/* existing prompts */],
+});
 ```
 
+If the repo already uses `src/mcp-server/resources/definitions/index.ts`, update that barrel instead of changing the registration style.
+
 ## Checklist
 
 - [ ] File created at `src/mcp-server/resources/definitions/{{resource-name}}.resource.ts`
@@ -114,6 +119,6 @@ export const allResourceDefinitions = [
 - [ ] Data is reachable via the tool surface (dedicated tool, another tool's output, or not needed for tool-only agents)
 - [ ] `list()` function provided if the resource is discoverable
 - [ ] Pagination used for large result sets (`extractCursor`/`paginateArray`)
-- [ ] Registered in `definitions/index.ts` barrel and `allResourceDefinitions`
+- [ ] Registered in the project's existing `createApp()` resource list (directly or via barrel)
 - [ ] `bun run devcheck` passes
 - [ ] Smoke-tested with `bun run dev:stdio` or `dev:http`

package/skills/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -25,7 +25,7 @@ For the full service pattern, `CoreServices`, and `Context` interface, read:
 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
-5. **Register in `setup()`** in the server's entry point (`src/index.ts`)
+5. **Register in `setup()`** in the server's entry point (`src/index.ts`, or `src/worker.ts` for Worker-only servers)
 6. **Run `bun run devcheck`** to verify
 
 ## Template
@@ -79,9 +79,9 @@ import { createApp } from '@cyanheads/mcp-ts-core';
 import { init{{ServiceName}} } from './services/{{domain}}/{{domain}}-service.js';
 
 await createApp({
-  tools: allToolDefinitions,
-  resources: allResourceDefinitions,
-  prompts: allPromptDefinitions,
+  tools: [/* existing tools */],
+  resources: [/* existing resources */],
+  prompts: [/* existing prompts */],
   setup(core) {
     init{{ServiceName}}(core.config, core.storage);
   },
@@ -100,7 +100,7 @@ handler: async (input, ctx) => {
 
 ## Resilience (External API Services)
 
-When a service wraps an external API, apply these patterns. See `docs/service-resilience.md` for full rationale.
+When a service wraps an external API, apply these patterns. For the framework retry contract, see `skills/api-utils/SKILL.md`.
 
 ### Retry wraps the full pipeline
 
@@ -150,6 +150,46 @@ parseResponse<T>(text: string): T {
 }
 ```
 
+### Sparse upstream payloads
+
+Third-party APIs often omit fields entirely instead of returning `null`. If your raw response types, normalized domain types, or tool output schemas are stricter than the real upstream payloads, you'll either fail validation or silently invent facts.
+
+**Guidance:**
+
+1. **Raw upstream types default to optional unless presence is guaranteed.** Trust the docs only after you've verified real payloads.
+2. **Preserve absence when it means "unknown".** Missing data is different from `false`, `0`, `''`, or an empty array.
+3. **Don't fabricate defaults during normalization** unless the upstream contract or your own tool semantics explicitly define them.
+4. **With `exactOptionalPropertyTypes`, omit absent fields instead of returning `undefined`.** Conditional spreads keep the normalized object honest.
+
+```typescript
+type RawRepo = {
+  id: string;
+  name: string;
+  archived?: boolean;
+  star_count?: number;
+  description?: string | null;
+};
+
+type Repo = {
+  id: string;
+  name: string;
+  archived?: boolean;
+  starCount?: number;
+  description?: string;
+};
+
+function normalizeRepo(raw: RawRepo): Repo {
+  const description = raw.description?.trim();
+  return {
+    id: raw.id,
+    name: raw.name,
+    ...(typeof raw.archived === 'boolean' && { archived: raw.archived }),
+    ...(typeof raw.star_count === 'number' && { starCount: raw.star_count }),
+    ...(description ? { description } : {}),
+  };
+}
+```
+
 ## 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.
@@ -193,5 +233,6 @@ Silent truncation is a data integrity bug — the caller thinks it has all resul
 - [ ] `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: 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
 - [ ] `bun run devcheck` passes

package/skills/add-test/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: add-test
 description: >
-  Scaffold a test file for an existing tool, resource, or service. Use when the user asks to add tests, improve coverage, or when a definition exists without a colocated test file.
+  Scaffold a test file for an existing tool, resource, or service. Use when the user asks to add tests, improve coverage, or when a definition exists without a matching test file.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.3"
   audience: external
   type: reference
 ---
 
 ## Context
 
-Tests use Vitest and `createMockContext` from `@cyanheads/mcp-ts-core/testing`. Test files are colocated with their source: `foo.tool.ts` gets `foo.tool.test.ts` in the same directory.
+Tests use Vitest and `createMockContext` from `@cyanheads/mcp-ts-core/testing`. If the repo already has tests, match the existing layout. If the repo has no existing tests, create a root `tests/` directory that mirrors the `src/` structure (e.g. `tests/mcp-server/tools/definitions/echo.tool.test.ts` for `src/mcp-server/tools/definitions/echo.tool.ts`).
 
 For the full `createMockContext` API and testing patterns, read:
 
@@ -21,9 +21,9 @@ 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** colocated with the source
+3. **Create the test file** in the repo's existing test layout
 4. **Write test cases** covering happy path, error paths, and edge cases
-5. **Run `npm test`** to verify
+5. **Run `bun run test`** to verify
 6. **Run `bun run devcheck`** to verify types
 
 ## Determining What to Test
@@ -38,7 +38,8 @@ Read the handler and identify:
 | **`ctx.state` usage** | Use `createMockContext({ tenantId: 'test' })` to enable storage |
 | **`ctx.elicit` / `ctx.sample`** | Mock with `vi.fn()`, also test the absent case (undefined) |
 | **`ctx.progress`** | Use `createMockContext({ progress: true })` for task tools |
-| **`format` function** | Test separately if defined — it's pure, no ctx needed |
+| **`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. |
 | **Auth scopes** | Not tested at handler level (framework enforces) — skip |
 
 ## Templates
@@ -48,12 +49,12 @@ Read the handler and identify:
 ```typescript
 /**
  * @fileoverview Tests for {{TOOL_NAME}} tool.
- * @module mcp-server/tools/definitions/{{TOOL_NAME}}.test
+ * @module tests/tools/{{TOOL_NAME}}.tool.test
  */
 
 import { describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
-import { {{TOOL_EXPORT}} } from './{{tool-name}}.tool.js';
+import { {{TOOL_EXPORT}} } from '@/mcp-server/tools/definitions/{{tool-name}}.tool.js';
 
 describe('{{TOOL_EXPORT}}', () => {
   it('returns expected output for valid input', async () => {
@@ -75,11 +76,11 @@ describe('{{TOOL_EXPORT}}', () => {
     await expect({{TOOL_EXPORT}}.handler(input, ctx)).rejects.toThrow();
   });
 
-  it('formats output correctly', () => {
+  it('formats output completely', () => {
     const output = { /* mock output matching the output schema */ };
     const blocks = {{TOOL_EXPORT}}.format!(output);
-    expect(blocks).toHaveLength(1);
-    expect(blocks[0].type).toBe('text');
+    expect(blocks.some((block) => block.type === 'text')).toBe(true);
+    // Assert the rendered text includes the IDs/fields the LLM needs to act on.
   });
 });
 ```
@@ -89,12 +90,12 @@ describe('{{TOOL_EXPORT}}', () => {
 ```typescript
 /**
  * @fileoverview Tests for {{RESOURCE_NAME}} resource.
- * @module mcp-server/resources/definitions/{{RESOURCE_NAME}}.test
+ * @module tests/resources/{{RESOURCE_NAME}}.resource.test
  */
 
 import { describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
-import { {{RESOURCE_EXPORT}} } from './{{resource-name}}.resource.js';
+import { {{RESOURCE_EXPORT}} } from '@/mcp-server/resources/definitions/{{resource-name}}.resource.js';
 
 describe('{{RESOURCE_EXPORT}}', () => {
   it('returns data for valid params', async () => {
@@ -131,16 +132,16 @@ describe('{{RESOURCE_EXPORT}}', () => {
 ```typescript
 /**
  * @fileoverview Tests for {{SERVICE_NAME}} service.
- * @module services/{{domain}}/{{SERVICE_NAME}}.test
+ * @module tests/services/{{domain}}/{{domain}}-service.test
  */
 
 import { beforeEach, describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
-import { init{{ServiceClass}}, get{{ServiceClass}} } from './{{service-name}}-service.js';
+import { get{{ServiceClass}}, init{{ServiceClass}} } from '@/services/{{domain}}/{{domain}}-service.js';
 
 describe('{{ServiceClass}}', () => {
   beforeEach(() => {
-    // Re-initialize with fresh config/storage per suite
+    // Re-initialize with fresh config/storage for each test
     init{{ServiceClass}}(mockConfig, mockStorage);
   });
 
@@ -150,15 +151,11 @@ describe('{{ServiceClass}}', () => {
     const result = await service.doWork('input', ctx);
     expect(result).toBeDefined();
   });
-
-  it('throws when not initialized', () => {
-    // Reset the singleton — this is the only case where accessing
-    // the module internals is acceptable
-    expect(() => get{{ServiceClass}}()).toThrow(/not initialized/);
-  });
 });
 ```
 
+If you need to test the accessor's "not initialized" guard, do it in a separate isolated-module test (`vi.resetModules()` before importing the service module). Don't mix that assertion into a suite that already calls `init{{ServiceClass}}()` in `beforeEach()`.
+
 ### Task tool test
 
 For tools with `task: true`, use `createMockContext({ progress: true })`:
@@ -202,15 +199,17 @@ When scaffolding tests for an existing handler, use the Zod schemas to generate
 4. **Defaults** — omit optional fields, verify defaults are applied in the output
 5. **Boundaries** — if the schema has `.min()`, `.max()`, `.length()`, test at the boundaries
 6. **Error paths** — trace the handler logic for throw conditions, construct inputs that trigger each
+7. **Sparse upstream fixtures** — if the handler/service wraps a third-party API, add at least one fixture where upstream omits optional fields entirely. Assert that the output still validates and that `format()` renders uncertainty honestly (`Not available`, omitted badge, etc.) instead of fabricating values.
 
 ## Checklist
 
-- [ ] Test file created at `src/.../{{name}}.test.ts` (colocated with source)
+- [ ] Test file created in the repo's existing layout (`tests/...` or colocated with source)
 - [ ] JSDoc `@fileoverview` and `@module` header present
 - [ ] Happy path tested with valid input → expected output
 - [ ] Error paths tested (at least one `.rejects.toThrow()`)
 - [ ] `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
-- [ ] `npm test` passes
+- [ ] If wrapping external API: sparse-payload case tested (omitted upstream fields still validate; `format()` does not invent facts)
+- [ ] `bun run test` passes
 - [ ] `bun run devcheck` passes

package/skills/add-tool/SKILL.md

@@ -4,14 +4,14 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.3"
   audience: external
   type: reference
 ---
 
 ## 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 in the barrel `index.ts`.
+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:
 
@@ -23,7 +23,7 @@ For the full `tool()` API, `Context` interface, and error codes, read:
 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 `src/mcp-server/tools/definitions/index.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
 6. **Smoke-test** with `bun run dev:stdio` or `dev:http`
 
@@ -96,19 +96,23 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
 });
 ```
 
-### Barrel registration
+### Registration
 
 ```typescript
-// src/mcp-server/tools/definitions/index.ts
-import { existingTool } from './existing-tool.tool.js';
-import { {{TOOL_EXPORT}} } from './{{tool-name}}.tool.js';
-
-export const allToolDefinitions = [
-  existingTool,
-  {{TOOL_EXPORT}},
-];
+// src/index.ts (fresh scaffold default)
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { existingTool } from './mcp-server/tools/definitions/existing-tool.tool.js';
+import { {{TOOL_EXPORT}} } from './mcp-server/tools/definitions/{{tool-name}}.tool.js';
+
+await createApp({
+  tools: [existingTool, {{TOOL_EXPORT}}],
+  resources: [/* existing resources */],
+  prompts: [/* existing prompts */],
+});
 ```
 
+If the repo already uses `src/mcp-server/tools/definitions/index.ts`, update that barrel instead of switching patterns midstream.
+
 ## Tool Response Design
 
 Tool responses are the LLM's only window into what happened. Every response should leave the agent informed about outcome, current state, and what to do next. This applies to success, partial success, empty results, and errors alike.
@@ -177,6 +181,43 @@ if (results.length === 0) {
 }
 ```
 
+### Sparse upstream data must stay honest
+
+When tool output comes from a third-party API, don't overstate certainty. Upstream systems often omit fields entirely; the tool schema and `format()` should preserve that uncertainty instead of collapsing it into fake `false`, `0`, or empty-string facts.
+
+**Guidance:**
+
+- Use optional output fields when the upstream source is sparse.
+- Render unknown values explicitly (`Not available`, `Unknown`) instead of inventing a concrete value.
+- Only render booleans, badges, counts, and summary facts when they are actually known.
+
+```typescript
+output: z.object({
+  repos: z.array(z.object({
+    id: z.string().describe('Repository ID.'),
+    name: z.string().describe('Repository name.'),
+    archived: z.boolean().optional()
+      .describe('Archived status when provided by the upstream API. Omitted when unknown.'),
+    stars: z.number().optional()
+      .describe('Star count when provided by the upstream API. Omitted when unknown.'),
+  })).describe('Repositories returned by the search.'),
+}),
+
+format: (result) => [{
+  type: 'text',
+  text: result.repos.map((repo) => [
+    `## ${repo.name}`,
+    `**ID:** ${repo.id}`,
+    typeof repo.archived === 'boolean'
+      ? `**Archived:** ${repo.archived ? 'Yes' : 'No'}`
+      : '**Archived:** Not available',
+    repo.stars != null
+      ? `**Stars:** ${repo.stars}`
+      : '**Stars:** Not available',
+  ].join('\n')).join('\n\n'),
+}],
+```
+
 ### Error classification and messaging
 
 The framework auto-classifies many errors at runtime (HTTP status codes, JS error types, common patterns). Use explicit error factories when you want a specific code and clear recovery guidance; plain `throw new Error()` when auto-classification is sufficient.
@@ -270,8 +311,9 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 - [ ] 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
 - [ ] `format()` renders all data the LLM needs (not just a count or title) — `content[]` is the only field most clients forward to the model
+- [ ] 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
 - [ ] `task: true` added if the tool is long-running
-- [ ] Registered in `definitions/index.ts` barrel and `allToolDefinitions`
+- [ ] Registered in the project's existing `createApp()` tool list (directly or via barrel)
 - [ ] `bun run devcheck` passes
 - [ ] Smoke-tested with `bun run dev:stdio` or `dev:http`

package/skills/api-testing/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Testing patterns for MCP tool/resource handlers using `createMockContext` and Vitest. Covers mock context options, handler testing, McpError assertions, format testing, Vitest config setup, and test isolation conventions.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -13,7 +13,7 @@ metadata:
 
 Tests target handler behavior directly — call `handler(input, ctx)`, assert on the return value or thrown error. The framework's handler factory (try/catch, formatting, telemetry) is not involved. Use `createMockContext` from `@cyanheads/mcp-ts-core/testing` to construct the `ctx` argument.
 
-**Philosophy:** Test behavior, not implementation. Refactors should not break tests. Colocate test files with source (`foo.tool.ts` → `foo.tool.test.ts`). Integration tests at I/O boundaries over unit tests of internals.
+**Philosophy:** Test behavior, not implementation. Refactors should not break tests. Match the repo's existing test layout: fresh scaffolds use `tests/`, while colocated `src/**/*.test.ts` files are also supported. Integration tests at I/O boundaries over unit tests of internals.
 
 ---
 
@@ -28,8 +28,10 @@ createMockContext({ sample: vi.fn().mockResolvedValue(...) }) // with MCP sampli
 createMockContext({ elicit: vi.fn().mockResolvedValue(...) }) // with elicitation
 createMockContext({ progress: true })                        // with task progress (ctx.progress populated)
 createMockContext({ requestId: 'my-id' })                    // override request ID (default: 'test-request-id')
+createMockContext({ notifyResourceListChanged: () => {} })   // with resource-list change notifier
+createMockContext({ notifyResourceUpdated: (_uri) => {} })   // with resource update notifier
 createMockContext({ signal: controller.signal })             // custom AbortSignal
-createMockContext({ auth: { clientId: 'test', scopes: [] } }) // with auth context
+createMockContext({ auth: { clientId: 'test', scopes: [], sub: 'test-user' } }) // with auth context
 createMockContext({ uri: new URL('myscheme://item/123') })   // for resource handler testing
 ```
 
@@ -39,6 +41,8 @@ createMockContext({ uri: new URL('myscheme://item/123') })   // for resource han
 interface MockContextOptions {
   auth?: AuthContext;
   elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
+  notifyResourceListChanged?: () => void;
+  notifyResourceUpdated?: (uri: string) => void;
   progress?: boolean;
   requestId?: string;
   sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
@@ -53,6 +57,8 @@ interface MockContextOptions {
 | _(none)_ | Minimal context — `ctx.state` operations throw without `tenantId`; `ctx.elicit`/`ctx.sample`/`ctx.progress` are `undefined` |
 | `auth` | Sets `ctx.auth` for scope-checking tests |
 | `elicit` | Assigns a function to `ctx.elicit` for testing elicitation calls |
+| `notifyResourceListChanged` | Assigns `ctx.notifyResourceListChanged` for resource notification tests |
+| `notifyResourceUpdated` | Assigns `ctx.notifyResourceUpdated` for resource update notification tests |
 | `progress` | Populates `ctx.progress` with real state-tracking implementation (see below) |
 | `requestId` | Overrides `ctx.requestId` (default: `'test-request-id'`) |
 | `sample` | Assigns a function to `ctx.sample` for testing sampling calls |
@@ -101,8 +107,8 @@ expect(log.calls.some(c => c.level === 'info' && c.msg.includes('Processing'))).
 ## Full test example
 
 ```ts
-// src/mcp-server/tools/definitions/my-tool.tool.test.ts
-import { describe, expect, it, vi } from 'vitest';
+// tests/tools/my-tool.tool.test.ts
+import { describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
 import { myTool } from '@/mcp-server/tools/definitions/my-tool.tool.js';
 
@@ -120,15 +126,16 @@ describe('myTool', () => {
     await expect(myTool.handler(input, ctx)).rejects.toThrow();
   });
 
-  it('formats response correctly', () => {
+  it('formats response completely', () => {
     const result = { result: 'test' };
     const blocks = myTool.format!(result);
     expect(blocks[0].type).toBe('text');
+    expect((blocks[0] as { text?: string }).text).toContain('test');
   });
 });
 ```
 
-Parse input through `myTool.input.parse(...)` to validate against the Zod schema and produce the typed input the handler expects. Call `myTool.handler(input, ctx)` directly, not through the MCP SDK or any framework wrapper. Assert on the return value for happy paths; use `.rejects.toThrow()` for error paths. Test `format` separately if the tool defines one — it's a pure function and needs no `ctx`.
+Parse input through `myTool.input.parse(...)` to validate against the Zod schema and produce the typed input the handler expects. Call `myTool.handler(input, ctx)` directly, not through the MCP SDK or any framework wrapper. Assert on the return value for happy paths; use `.rejects.toThrow()` for error paths. Test `format` separately if the tool defines one — it's a pure function and needs no `ctx`. Verify the rendered text includes the fields the LLM needs, and for projection-style tools, add a case with non-default field selections.
 
 ---
 
@@ -138,7 +145,7 @@ Parse input through `myTool.input.parse(...)` to validate against the Zod schema
 it('uses elicitation when available', async () => {
   const elicit = vi.fn().mockResolvedValue({
     action: 'accept',
-    data: { format: 'json' },
+    content: { format: 'json' },
   });
   const ctx = createMockContext({ elicit });
   const input = myTool.input.parse({ query: 'hello' });
@@ -203,6 +210,45 @@ The pattern: parse through the schema (confirms Zod accepts the payload), call t
 
 ---
 
+## Testing with sparse upstream payloads
+
+This is a different problem from form-client `''` payloads. Here the upstream API omits fields entirely. The risk is either a validation failure from an over-strict schema or a quiet lie where missing data turns into a concrete fact.
+
+```ts
+describe('sparse upstream payloads', () => {
+  it('preserves missing upstream fields as unknown', async () => {
+    const upstream = {
+      id: 'repo-123',
+      name: 'Widget Repo',
+      // archived and star_count omitted entirely
+    };
+
+    const normalized = normalizeRepo(upstream);
+    expect(normalized).toEqual({
+      id: 'repo-123',
+      name: 'Widget Repo',
+    });
+
+    const output = repoSearchTool.output.parse({
+      repos: [normalized],
+    });
+    const blocks = repoSearchTool.format!(output);
+    expect((blocks[0] as { text: string }).text).toContain('Archived:** Not available');
+    expect((blocks[0] as { text: string }).text).not.toContain('Archived:** No');
+  });
+});
+```
+
+**What to verify:**
+
+- Fixtures omit fields entirely, not just set them to `null` or `''`.
+- Normalization/helpers tolerate missing fields without fabricating defaults.
+- Handler output still validates against the declared output schema.
+- `format()` uses explicit unknown-state fallbacks instead of inventing facts.
+- Tool-semantic defaults are tested separately from upstream absence so the distinction stays clear.
+
+---
+
 ## Vitest config
 
 Extend the framework's base config using `mergeConfig`. The base provides `globals: true`, `pool: 'forks'`, `isolate: true`, `tsconfigPaths`, and a Zod SSR compatibility fix. Add only the `@/` alias for your server's source:
@@ -244,8 +290,8 @@ describe('myTool with service', () => {
 });
 ```
 
-- Re-init services with `initMyService()` (or equivalent) per test suite — the module-level singleton must be reset so tests don't share state.
-- Vitest runs test files in separate worker threads — parallel file execution is safe by default.
+- Re-init services with `initMyService()` (or equivalent) in `beforeEach` when tests share a module-level singleton.
+- Vitest runs test files in separate workers — parallel file execution is safe by default.
 - Use `createMockContext({ tenantId })` whenever the handler accesses `ctx.state` — omitting `tenantId` causes `ctx.state` to throw.
 
 ---