@cyanheads/mcp-ts-core 0.10.4 → 0.10.6

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.4"
+  version: "1.5"
   audience: external
   type: reference
 ---
@@ -198,3 +198,99 @@ export function getServerConfig() {
 > `DuckDB canvas requires Node.js or Bun. Set CANVAS_PROVIDER_TYPE=none or omit it for Cloudflare Workers deployment.`
 
 Leave the env unset (or set to `none`) for Worker deployments. Tools that conditionally use canvas should check the module-level accessor (`if (!getCanvas()) { ... }`) and surface a clear "feature unavailable on this deployment" message. See `api-canvas` for the full DataCanvas reference and setup wiring pattern.
+
+---
+
+## Testing Workers with miniflare
+
+`bun run test:worker` runs the worker suite under `vitest.worker.ts` (using `@cloudflare/vitest-pool-workers` + miniflare). Each test **file** gets its own fresh V8 isolate — module scope (including `createWorkerHandler`'s `appPromise` singleton) is reset between files.
+
+### vitest.worker.ts miniflare bindings
+
+Declare all storage bindings used in the suite:
+
+```ts
+cloudflareTest({
+  main: './tests/fixtures/worker-runtime.fixture.ts',
+  miniflare: {
+    bindings: { STORAGE_PROVIDER_TYPE: 'cloudflare-kv', ... },
+    kvNamespaces: ['KV_NAMESPACE', 'CUSTOM_KV'],
+    r2Buckets:    ['R2_BUCKET'],
+    d1Databases:  ['DB'],
+  },
+})
+```
+
+Binding names must match the hardcoded names in `storageFactory.ts` (`KV_NAMESPACE`, `R2_BUCKET`, `DB`).
+
+### Per-provider test isolation
+
+`bindings.STORAGE_PROVIDER_TYPE` is a global default. Per-provider test files override it by passing a modified env to `worker.fetch()`:
+
+```ts
+import { env } from 'cloudflare:workers';
+
+// Fresh isolate per file — appPromise starts null.
+// First fetch initialises the singleton with the overridden provider type.
+const r2Env = { ...env, STORAGE_PROVIDER_TYPE: 'cloudflare-r2' };
+await worker.fetch(request, r2Env, ctx);
+```
+
+Use `reset()` from `cloudflare:test` in `afterEach` to clear binding state between tests. For D1, re-apply migrations immediately after each `reset()` (reset wipes the schema):
+
+```ts
+import { applyD1Migrations, reset } from 'cloudflare:test';
+
+afterEach(async () => {
+  await reset();
+  await applyD1Migrations(env.DB, [{ name: '0001_schema', queries: [CREATE_TABLE_SQL] }]);
+});
+```
+
+### D1 schema setup
+
+The `cloudflare-d1` provider requires the `kv_store` table before any operations. Apply it in `beforeAll` via `applyD1Migrations`:
+
+```ts
+const KV_STORE_MIGRATION = `
+CREATE TABLE IF NOT EXISTS kv_store (
+  tenant_id TEXT NOT NULL,
+  key       TEXT NOT NULL,
+  value     TEXT NOT NULL,
+  expires_at INTEGER,
+  PRIMARY KEY (tenant_id, key)
+)`;
+
+beforeAll(async () => {
+  await applyD1Migrations(env.DB, [
+    { name: '0001_create_kv_store', queries: [KV_STORE_MIGRATION] },
+  ]);
+  sessionId = await openSession(d1Env);
+});
+```
+
+### R2 list limit
+
+The R2 provider fetches `limit + 1` objects to detect further pages. Miniflare caps R2 `MaxKeys` at 1000, so the default `limit=1000` → request 1001 → error. Pass `limit: 100` (or any value ≤ 999) to `ctx.state.list()` in test fixtures to stay under the cap:
+
+```ts
+const result = await ctx.state.list(prefix, { limit: 100 });
+```
+
+### Storage probe pattern
+
+Expose storage operations as MCP tools in the fixture to test them through the real HTTP surface:
+
+```ts
+const storageSetTool = tool('storage_set', {
+  input: z.object({ key: z.string().describe('...'), value: z.string().describe('...') }),
+  output: z.object({ ok: z.boolean().describe('Always true on success') }),
+  async handler(input, ctx) {
+    await ctx.state.set(input.key, input.value);
+    return { ok: true };
+  },
+  format: (r) => [{ type: 'text', text: `ok=${r.ok}` }],
+});
+```
+
+Call via `tools/call` over MCP JSON-RPC and assert on `structuredContent`. See `tests/worker/storage-r2.worker.test.ts` and `tests/worker/storage-d1.worker.test.ts` for the full pattern.

package/skills/orchestrations/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Pick and run a multi-phase workflow that chains foundational task skills (`git-wrapup`, `release-and-publish`, `maintenance`, `field-test`, `setup`, etc.) end-to-end. Routes user intent to a workflow file under `workflows/` — greenfield builds, maintenance + release, field-test + fix, or known-work + release. Single source for the universal rules (no commits without authorization, no destructive git, no marketing language), the orchestrator posture (own the goal, ground sub-agents in primary sources, verify against the goal), and the sub-agent strategy (orient block, parallel fanout, isolation, normalization) that apply across every workflow. Sub-agents are an optional capability — workflows run linearly when fanout isn't available.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: workflow
 ---

package/skills/orchestrations/workflows/fix-wrapup-release.md

@@ -63,7 +63,7 @@ Each phase's Objective column is the goal state per target — the verifiable en
 | 1b | Fix | Per target: targeted issues fixed in source, tests updated/added, `devcheck` + `rebuild` + `test` green, each fixed issue commented with fix details, working tree dirty for review | parallel fanout (one sub-agent per target — hard constraint) | **barrier** — orchestrator reviews diffs before verify (explicit gate in checklist) |
 | 2 | Verify | Per target: full diff cold-reviewed; simplified if warranted; each fix re-exercised against the running server with actual tool output in the summary | parallel fanout | **barrier** — orchestrator reviews simplified diff and verified outputs; release authorization required |
 | 3 | Wrap-up + release | Per target: fixes split into per-file commits with a release commit on top; annotated tag; published per repo visibility; tag annotation is structured markdown with issue backlinks | parallel fanout (Bash git only) | gate-free |
-| 4 | Issue cleanup | Every GH issue that shipped a fix closed with "Fixed in v\<version\>" comment | orchestrator (serial) | — |
+| 4 | Issue cleanup | Every shipped issue closed (reason: completed) carrying exactly one what-landed comment that cites the version | orchestrator (serial) | — |
 
 Phase 1a is conditional — only runs when the input is a handoff document or otherwise unvalidated. When the input is already tracked GH issues, skip directly to Phase 1b. The release portion of Phase 3 is conditional on user authorization to ship.
 
@@ -137,14 +137,18 @@ The tag annotation and changelog cover ALL fixes — the commit split is about g
 **Tag annotations** are for end users — internal dev cleanup (lockfile refreshes, linter fixes, build config) belongs in commit bodies, not the tag annotation.
 
 ### Phase 4: Issue cleanup
-Close issues that shipped fixes — only those. Skipped issues stay open.
+Close issues that shipped — only those. Skipped issues stay open.
+
+Each issue gets exactly ONE substantive comment recording what landed — concrete changes, file paths, and the version — written either by the fix sub-agent (Phase 1b) or by the orchestrator here. Then close without an additional comment:
 
 ```bash
-for n in <fixed-issue-numbers>; do
-  gh issue close "$n" -R "<owner>/<repo>" --reason completed --comment "Fixed in v<version>."
+for n in <shipped-issue-numbers>; do
+  gh issue close "$n" -R "<owner>/<repo>" --reason completed
 done
 ```
 
+If no what-landed comment exists yet, the version belongs in that one comment ("Shipped in v\<version\>: …"). Never stack a bare "Fixed in v\<version\>" trailer on top of an existing summary — it duplicates the record, and "fixed" misdescribes enhancements (enhancements ship/land; only bugs are fixed).
+
 ## Workflow-specific gotchas
 
 | # | Gotcha | Mitigation |
@@ -170,6 +174,6 @@ done
 - [ ] Orchestrator gate after Phase 2: simplified diff reviewed, field-test claims verified
 - [ ] Phase 3: version bumped, fix commits + release commit, annotated tag per target — scope matches private/public status
 - [ ] Phase 3: published per scope (push, npm if public, MCP Registry if applicable, GH release, Docker if applicable)
-- [ ] Phase 4: fixed issues closed; skipped issues remain open
+- [ ] Phase 4: shipped issues closed, one what-landed comment each; skipped issues remain open
 - [ ] Post-workflow verification: `git ls-remote --tags origin`, `npm view <pkg>@<version>` if public, GH release artifacts attached
 - [ ] Tag/release quality review: tag subject omits version number, structured markdown, no marketing adjectives, issue backlinks present

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: "2.6"
+  version: "2.7"
   audience: external
   type: workflow
 ---
@@ -76,6 +76,8 @@ Key fields: `name`, `description`, `repository`, `author`, `homepage`, `bugs`, `
 
 **`name` must communicate the server's domain at a glance.** See `references/package-meta.md` for the naming convention — ambiguous abbreviations and acronym-only names fail the scannability test for humans and agents alike.
 
+**`name` and `title` in `createApp()` / `createWorkerHandler()` must match the unscoped `package.json` `name`** — display identity is the machine name on every surface; `lint:packaging` (run by `devcheck`) enforces the match and warns when the pair is partial. `description` is never duplicated into the entrypoint — `package.json` is the canonical source (the framework derives the served description from it).
+
 **`description` is the canonical source.** Every other surface (README header, `server.json`, Dockerfile OCI label, GitHub repo description) derives from it. Write it here first, then propagate.
 
 ### 6. `server.json`
@@ -193,7 +195,7 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 
 **`package.json` scripts:**
 
-- `bundle` — builds the `.mcpb` (e.g., `mcpb pack --output dist/`)
+- `bundle` — builds the `.mcpb` (`mcpb pack`, then `scripts/clean-mcpb.ts` prunes dev deps and strips dependency-shipped agent docs)
 - `lint:packaging` — validates `manifest.json` ↔ `server.json` env var consistency (run by `devcheck`)
 
 **Cross-file consistency:**

package/templates/AGENTS.md

@@ -335,13 +335,13 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run start:http` | Production mode (HTTP) |
 | `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
 | `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
-| `npm run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+| `npm run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
 ---
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
 

package/templates/CLAUDE.md

@@ -335,13 +335,13 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run start:http` | Production mode (HTTP) |
 | `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
 | `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
-| `npm run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+| `npm run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
 ---
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
 

package/templates/manifest.json

@@ -22,6 +22,5 @@
   },
   "tools_generated": true,
   "prompts_generated": true,
-  "repository": { "type": "git", "url": "" },
   "user_config": {}
 }

package/templates/package.json

@@ -30,7 +30,7 @@
     "format:unsafe": "biome check --write --unsafe .",
     "lint:mcp": "bun run scripts/lint-mcp.ts",
     "lint:packaging": "bun run scripts/lint-packaging.ts",
-    "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/{{PACKAGE_NAME}}.mcpb",
+    "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/{{PACKAGE_NAME}}.mcpb && bun run scripts/clean-mcpb.ts dist/{{PACKAGE_NAME}}.mcpb",
     "changelog:build": "bun run scripts/build-changelog.ts",
     "changelog:check": "bun run scripts/build-changelog.ts --check",
     "release:github": "bun run scripts/release-github.ts",

package/templates/src/index.ts

@@ -12,6 +12,8 @@ import { echoAppUiResource } from './mcp-server/resources/definitions/echo-app-u
 import { echoPrompt } from './mcp-server/prompts/definitions/echo.prompt.js';
 
 await createApp({
+  name: '{{PACKAGE_NAME}}',
+  title: '{{PACKAGE_NAME}}',
   tools: [echoTool, echoAppTool],
   resources: [echoResource, echoAppUiResource],
   prompts: [echoPrompt],

package/templates/tests/tools/echo.tool.test.ts

@@ -5,8 +5,29 @@
 
 import { describe, expect, it } from 'vitest';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { mcpTest } from '@cyanheads/mcp-ts-core/testing/vitest';
 import { echoTool } from '@/mcp-server/tools/definitions/echo.tool.js';
 
+// ---------------------------------------------------------------------------
+// Fixture-based tests (mcpTest) — fresh ctx per test, no manual construction
+// ---------------------------------------------------------------------------
+
+mcpTest('echoTool: echoes the message back (fixture)', async ({ ctx }) => {
+  const input = echoTool.input.parse({ message: 'hello world' });
+  const result = await echoTool.handler(input, ctx);
+  expect(result).toEqual({ message: 'hello world' });
+});
+
+mcpTest('echoTool: output conforms to declared schema (fixture)', async ({ ctx }) => {
+  const input = echoTool.input.parse({ message: 'hello world' });
+  const result = await echoTool.handler(input, ctx);
+  expect(result).toEqual(expect.schemaMatching(echoTool.output));
+});
+
+// ---------------------------------------------------------------------------
+// Classic describe/it tests (createMockContext) — shown for comparison
+// ---------------------------------------------------------------------------
+
 describe('echoTool', () => {
   it('echoes the message back', async () => {
     const ctx = createMockContext();