@cyanheads/mcp-ts-core 0.9.12 → 0.9.14

package/skills/api-canvas/SKILL.md

@@ -4,7 +4,7 @@ description: >
   DataCanvas primitive reference — a Tier 3 SQL/analytical workspace for tabular MCP servers, backed by DuckDB. Use when registering tables from upstream APIs, running ad-hoc SQL across them, and exporting results. Covers the acquire → register → query → export flow, the token-sharing pattern for multi-agent collaboration, env config, and Cloudflare Workers fail-closed behavior.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -245,8 +245,113 @@ If your tool surfaces row data via `structuredContent`, the JSON-safe shape flow
 
 ---
 
+## Minimum viable spillover server
+
+Most canvas use cases are public-data analytics: fetch from an upstream API, stage the full result, let the agent SQL it. The primitives are domain-neutral — `canvas.acquire()`, `spillover()`, `instance.query()` — so the minimum viable shape is small and generic. Reach for it first; add scoping only when a real multi-tenant requirement appears.
+
+### Simple-shape defaults
+
+| Concern | Simple-shape answer |
+|:--|:--|
+| Canvas scoping | One shared canvas per tenant. Omit `canvas_id` on the first call to mint one; pass the returned id back to reuse it. |
+| Table naming | `spillover()` auto-names the table `spilled_<id>`; pass `tableName` for a stable handle. A dataframe-query surface commonly adds its own `df_<id>` convention. |
+| Access control | Possession of the `canvas_id` is access — unguessable in practice (see [token-sharing model](#the-token-sharing-model)). TTL + the framework rate limiter backstop brute force. |
+| Enable flag | None of your own — canvas presence is the gate (`CANVAS_PROVIDER_TYPE=duckdb`; `getCanvas()` returns `undefined` otherwise). |
+| Tools | A fetcher that spills, plus `dataframe_query` for SQL. `dataframe_describe` / `dataframe_drop` are optional consumer conventions, not framework-provided. |
+| Fetcher output | Two things in one response: the inline preview (answer to the immediate question) and the table handle (escape hatch for follow-up SQL via `dataframe_query`). Neither replaces the other. |
+
+> The `MCP_HTTP_MAX_BODY_BYTES` request-body cap is **inbound-only** — it bounds the JSON-RPC request, not the upstream data a handler stages into the canvas or the rows it returns. Canvas servers send small requests (queries, SQL, canvas IDs) regardless of dataset size, so the cap never constrains canvas ingestion.
+
+### Recipe
+
+A fetcher that spills and a query tool that runs SQL across what was spilled — the whole surface. Swap `fetchUpstream` for any paginated or streamed source; nothing here is domain-specific.
+
+```ts
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { spillover } from '@cyanheads/mcp-ts-core/canvas';
+import { getCanvas } from '@/services/canvas-accessor.js';
+
+/** Fetch an upstream dataset, inline a preview, spill the full result to a canvas table. */
+export const fetchDataset = tool('fetch_dataset', {
+  description:
+    'Fetch a dataset and stage it on a DataCanvas. Returns an inline preview plus a ' +
+    'canvas_id + table you can query with dataframe_query for the full result set.',
+  annotations: { readOnlyHint: true },
+  input: z.object({
+    query: z.string().describe('Upstream search/filter expression'),
+    canvas_id: z
+      .string()
+      .optional()
+      .describe('Canvas ID from a prior call. Omit to start fresh — the response returns a new one.'),
+  }),
+  output: z.object({
+    canvas_id: z.string().describe('Canvas ID — pass to dataframe_query or another fetch call'),
+    table_name: z.string().describe('Canvas table holding the full result (empty when not spilled)'),
+    spilled: z.boolean().describe('True when the result exceeded the preview and was staged'),
+    preview: z.array(z.record(z.string(), z.unknown())).describe('Inline rows — the immediate answer'),
+    row_count: z.number().describe('Rows staged on the canvas (preview length when not spilled)'),
+  }),
+  async handler(input, ctx) {
+    const canvas = getCanvas();
+    if (!canvas) throw new Error('DataCanvas is not enabled. Set CANVAS_PROVIDER_TYPE=duckdb.');
+
+    const instance = await canvas.acquire(input.canvas_id, ctx);
+    const result = await spillover({
+      canvas: instance,
+      source: fetchUpstream(input.query), // any AsyncIterable<Row> | Iterable<Row>
+      previewChars: 100_000, // ≈ 25k tokens inline
+      signal: ctx.signal,
+    });
+
+    return {
+      canvas_id: instance.canvasId,
+      table_name: result.spilled ? result.handle.tableName : '',
+      spilled: result.spilled,
+      preview: result.previewRows,
+      row_count: result.spilled ? result.handle.rowCount : result.previewRows.length,
+    };
+  },
+});
+
+/** Run read-only SQL across tables staged on a canvas. */
+export const dataframeQuery = tool('dataframe_query', {
+  description: 'Run a read-only SQL SELECT against tables staged on a canvas by fetch_dataset.',
+  annotations: { readOnlyHint: true },
+  input: z.object({
+    canvas_id: z.string().describe('Canvas ID returned by fetch_dataset'),
+    sql: z.string().describe('Read-only SELECT. Reference tables by the names fetch_dataset returned.'),
+  }),
+  output: z.object({
+    rows: z.array(z.record(z.string(), z.unknown())).describe('Result rows (capped at the canvas row limit)'),
+    row_count: z.number().describe('Full result count before the row cap'),
+  }),
+  async handler(input, ctx) {
+    const canvas = getCanvas();
+    if (!canvas) throw new Error('DataCanvas is not enabled. Set CANVAS_PROVIDER_TYPE=duckdb.');
+
+    const instance = await canvas.acquire(input.canvas_id, ctx);
+    const result = await instance.query(input.sql, { signal: ctx.signal });
+    return { rows: result.rows, row_count: result.rowCount };
+  },
+});
+```
+
+### When the simple shape is enough
+
+| Condition | Simple shape suffices? |
+|:--|:--|
+| Underlying data is publicly accessible | ✅ |
+| Single-user deployment (stdio, or HTTP with one user) | ✅ — no cross-user surface regardless of data sensitivity |
+| Use case is research / analytics, not multi-tenant SaaS | ✅ |
+| Dataframes must age individually | ⚠️ TTL is canvas-level today (a hot canvas keeps stale tables alive); per-table TTL is tracked in [#140](https://github.com/cyanheads/mcp-ts-core/issues/140). Backstop with `ctx.state` bookkeeping in the interim. |
+| Per-user row visibility matters in a multi-user deployment | ❌ — add session/tenant scoping at the server level |
+
+The germplasm-flavored [consumer tool template](#consumer-tool-template) below is the same pattern with domain-specific naming.
+
 ## Consumer tool template
 
+A domain-specific instance of the [minimum viable spillover server](#minimum-viable-spillover-server) above — the same `acquire → register → return handle` flow with germplasm naming.
+
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { getCanvas } from '@/services/canvas-accessor.js';

package/skills/api-config/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: reference
 ---
@@ -52,6 +52,7 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variable
 | `MCP_HTTP_PORT` | `mcpHttpPort` | `3010` | Port for HTTP transport |
 | `MCP_HTTP_HOST` | `mcpHttpHost` | `127.0.0.1` | Bind address |
 | `MCP_HTTP_ENDPOINT_PATH` | `mcpHttpEndpointPath` | `/mcp` | HTTP endpoint path |
+| `MCP_HTTP_MAX_BODY_BYTES` | `mcpHttpMaxBodyBytes` | `1048576` (1 MiB) | Max **inbound** JSON-RPC request body; oversized requests get `413` before per-request allocation. Does **not** cap upstream data staged into a canvas or response sizes. `0` disables (defer to runtime/proxy). |
 | `MCP_HTTP_MAX_PORT_RETRIES` | `mcpHttpMaxPortRetries` | `15` | Retry count if port is busy |
 | `MCP_HTTP_PORT_RETRY_DELAY_MS` | `mcpHttpPortRetryDelayMs` | `50` | Delay between port retries (ms) |
 | `MCP_SESSION_MODE` | `mcpSessionMode` | `auto` | `stateless` \| `stateful` \| `auto` |

package/skills/api-context/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: api-context
 description: >
-  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.progress`), and when to use each.
+  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.progress`, `ctx.enrich`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -57,6 +57,12 @@ interface Context {
   // Raw URI — present only for resource handlers
   readonly uri?: URL;
 
+  // Agent-facing success-path enrichment — accumulates notices, query echo, totals
+  // onto the request; reaches structuredContent + content[]. Always present (no-op
+  // when no `enrichment` block), strictly typed on HandlerContext<R, E> against the
+  // declared fields. Kind-tagged helpers: enrich.notice / .total / .echo.
+  readonly enrich: Enrich;
+
   // Opt-in contract resolver — always present (returns {} when no contract is attached
   // or the reason is unknown), strictly typed on HandlerContext<R> against declared reasons.
   recoveryFor(reason: string): { recovery: { hint: string } } | {};
@@ -520,6 +526,62 @@ The `≥5 words` lint rule on contract `recovery` (validated at lint time) makes
 
 ---
 
+## `ctx.enrich`
+
+Always present on `Context`. Accumulates agent-facing **success-path** context — empty-result notices, the query/filter as the server parsed it, pagination totals — onto the request. The framework merges it into `structuredContent`, advertises `output.extend(enrichment)` as the tool's `outputSchema`, and mirrors it into a `content[]` trailer. The success-path counterpart to `ctx.fail` / `ctx.recoveryFor`.
+
+```ts
+export const search = tool('search', {
+  description: 'Search the catalog.',
+  input: z.object({ query: z.string().describe('Search terms') }),
+  output: z.object({ items: z.array(z.string()).describe('Matching items') }),
+  enrichment: {
+    effectiveQuery: z.string().describe('Query as the server parsed it'),
+    totalCount: z.number().describe('Total matches before the limit'),
+    notice: z.string().optional().describe('Guidance when nothing matched'),
+  },
+  async handler(input, ctx) {
+    const res = await runSearch(input.query);
+    ctx.enrich.echo(res.parsed);              // → effectiveQuery + "Query: …" trailer
+    ctx.enrich.total(res.total);              // → totalCount + "N total" trailer
+    if (res.items.length === 0) ctx.enrich.notice(`No matches for "${input.query}".`);
+    return { items: res.items };              // enrichment never rides in the domain return
+  },
+});
+```
+
+### Signature
+
+```ts
+// Loose (always present on Context — works without a block; service-callable):
+ctx.enrich(fields: Record<string, unknown>): void
+
+// Strict (HandlerContext<R, E> when the definition declares an enrichment block):
+ctx.enrich(fields: Partial<z.infer<ZodObject<E>>>): void
+
+// Kind-tagged field-helpers (always present) — write a conventional key and tag
+// the content[] trailer rendering:
+ctx.enrich.notice(text: string): void      // writes `notice`         → blockquote
+ctx.enrich.total(count: number): void       // writes `totalCount`     → "N total"
+ctx.enrich.echo(query: string): void        // writes `effectiveQuery`  → "Query: …"
+```
+
+### Behavior
+
+| Aspect | Detail |
+|:-------|:-------|
+| Accumulation | Each call merges its fields onto the request; later calls override earlier keys. |
+| Both surfaces | Merged into `structuredContent` (validated against `output.extend(enrichment)`) and appended to `content[]` as a trailer — even when the tool defines no `format()`. |
+| Domain payload untouched | `content[]` renders the handler's return via `format()` (or the JSON default); enrichment is a separate trailer, never double-rendered. The handler return must NOT carry enrichment fields. |
+| Required-field guard | A required enrichment field never populated fails the effective-output parse — the bug surfaces loudly rather than dropping silently. |
+| No block | Calling `ctx.enrich` on a tool that declared no `enrichment` is a silent no-op (values are stripped by the parse) — the price of service-layer callability. |
+| Service usage | Services accepting `ctx: Context` can call `ctx.enrich(...)`; the value reaches `structuredContent` exactly as if the handler had. |
+| `format-parity` | Enrichment lives outside `output`, so the `format-parity` lint never requires it in `format()`. |
+
+See `add-tool`'s **Tool Response Design** and `skills/api-linter` (`enrichment-*` rules) for the full pattern. Test enrichment with `getEnrichment(ctx)` from `@cyanheads/mcp-ts-core/testing`.
+
+---
+
 ## Quick reference
 
 | Property | Type | Present when |
@@ -534,6 +596,7 @@ The `≥5 words` lint rule on contract `recovery` (validated at lint time) makes
 | `ctx.log` | `ContextLogger` | Always |
 | `ctx.state` | `ContextState` | Always (throws if `tenantId` missing) |
 | `ctx.signal` | `AbortSignal` | Always |
+| `ctx.enrich` | `Enrich` | Always; typed on `HandlerContext<R, E>` when an `enrichment` block is declared |
 | `ctx.elicit` | `function \| undefined` | Client supports elicitation |
 | `ctx.sample` | `function \| undefined` | Client supports sampling |
 | `ctx.notifyResourceListChanged` | `function \| undefined` | Transport supports resource notifications |

package/skills/api-linter/SKILL.md

@@ -4,7 +4,7 @@ description: >
   MCP definition linter rules reference. Use when `bun run lint:mcp` or `bun run devcheck` reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -53,6 +53,7 @@ Grouped by family. Jump to any rule ID via its anchor.
 | Handler body | `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error` | [Handler body rules](#handler-body-rules) |
 | Error contract (structural) | `error-contract-type`, `error-contract-empty`, `error-contract-entry-type`, `error-contract-code-type`, `error-contract-code-unknown`, `error-contract-code-unknown-error`, `error-contract-reason-required`, `error-contract-reason-format`, `error-contract-reason-unique`, `error-contract-when-required`, `error-contract-retryable-type`, `error-contract-recovery-required`, `error-contract-recovery-empty`, `error-contract-recovery-min-words` | [Error contract rules](#error-contract-rules) |
 | Error contract (conformance) | `error-contract-conformance`, `error-contract-prefer-fail` | [Error contract rules](#error-contract-rules) |
+| Enrichment | `enrichment-type`, `enrichment-empty`, `enrichment-field-type`, `enrichment-output-collision`, `enrichment-prefer-block` | [Enrichment rules](#enrichment-rules) |
 | server.json | ~40 rules prefixed `server-json-*` | [server.json rules](#server-json-rules) |
 
 ---
@@ -708,6 +709,52 @@ The diagnostic message includes the declared reason(s) for the code so you can c
 
 ---
 
+## Enrichment rules
+
+Validate the `enrichment` block — the success-path counterpart to `errors[]`. Enrichment fields are merged into `structuredContent` and advertised as `output.extend(enrichment)`, so the linter guards the block's shape and its disjointness from `output`. See `api-context`'s `ctx.enrich` and `add-tool`'s **Tool Response Design**.
+
+### enrichment-type
+
+**Severity:** error
+
+Fires when `enrichment` is present but isn't a plain object mapping field names to Zod schemas (a `ZodRawShape`) — e.g. an array or a primitive.
+
+**Fix:** declare `enrichment: { <name>: <ZodType>, … }`.
+
+### enrichment-empty
+
+**Severity:** warning
+
+Fires when `enrichment: {}` is declared with no fields — a no-op.
+
+**Fix:** drop the field, or declare the agent-facing fields `ctx.enrich(...)` will populate.
+
+### enrichment-field-type
+
+**Severity:** error
+
+Fires when an enrichment field's value isn't a Zod schema.
+
+**Fix:** use a Zod type (`z.string().describe(…)`, `z.number().describe(…)`, …) for every enrichment field.
+
+### enrichment-output-collision
+
+**Severity:** error
+
+Fires when an enrichment key matches an `output` key. The effective output schema is `output.extend(enrichment)`, so a collision silently overrides the `output` field.
+
+**Fix:** rename one side so enrichment keys are disjoint from output keys.
+
+### enrichment-prefer-block
+
+**Severity:** warning
+
+Advisory. Fires when a tool has **no** `enrichment` block but an `output` field whose name strongly signals agent-facing context (`notice`, `effectiveQuery`, `queryEcho`) rather than domain payload.
+
+**Fix:** move the field into an `enrichment` block and populate it via `ctx.enrich(...)` — it reaches both client surfaces without a `format()` entry. Ignore if the field is genuinely domain data. Deliberately conservative — common domain fields like `totalCount` are not flagged.
+
+---
+
 ## Escape hatches
 
 ### Dynamic upstream data

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.12"
+  version: "2.13"
   audience: external
   type: workflow
 ---
@@ -351,6 +351,7 @@ output: z.object({
 - **Truncate large output with counts.** When a list exceeds a reasonable display size, show the top N and append "...and X more". Don't silently drop results.
 - **Spill big tabular results to a queryable surface.** When a tool's row set can exceed any reasonable context budget — paginated APIs, streamed exports, big query results — pair an inline preview with a `DataCanvas` table holding the full set, returned as a token the agent can SQL. Compute distributions or refinement hints across the full result, not the preview, so aggregate signal stays honest. See `api-canvas` for the `spillover()` helper.
 - **`format()` is the markdown twin of `structuredContent` — make both content-complete.** Different MCP clients forward different surfaces to the model: some (e.g., Claude Code) read `structuredContent` from `output`, others (e.g., Claude Desktop) read `content[]` from `format()`. Both must carry the same data so every client sees the same picture — `format()` just dresses it up with markdown. A thin `format()` that returns only a count or title leaves `content[]`-only clients blind to data that `structuredContent` clients can see. Render all fields the LLM needs, with structured markdown (headers, bold labels, lists) for readability.
+- **Agent-facing context must reach both client surfaces — put it in `enrichment`.** `structuredContent` (from `output`) and `content[]` (from `format()`) are read by different clients. Empty-result notices, the query/filter as the server parsed it, and pagination totals — the context the agent *reasons with*, distinct from the domain payload — reach only `content[]` if hand-authored into `format()` text alone, leaving `structuredContent`-only clients (Claude Code) blind. (The reverse can't happen: `format-parity` drags every `output` field into `format()`, so `output`-authored context already reaches both.) An `enrichment` block — the success-path counterpart to `errors[]`, populated via `ctx.enrich(...)` — reaches both automatically: merged into `structuredContent`, advertised as `output.extend(enrichment)`, mirrored into a `content[]` trailer, no `format()` entry needed. See `add-tool`'s **Tool Response Design**.
 
 #### Batch input design
 

package/skills/orchestrations/SKILL.md

@@ -69,7 +69,7 @@ The orchestrator owns the goals. Workflow phases are not "run skill X" — they
 Before running a phase (or spawning a sub-agent for it), write down four things:
 
 1. **Goal** — the verifiable end state this phase must produce. Concrete and testable: "v0.5.2 tag exists at HEAD with structured-markdown annotation; `bun run devcheck` green; `npm view <pkg>@0.5.2` resolves." Not fuzzy: "ran the release-and-publish skill."
-2. **Primary sources** — the specific files, GH issues, and reference docs the sub-agent must read directly. Inlining content into the prompt is a paraphrase that loses nuance; agents grounded in the source catch details the orchestrator's summary missed. For GH issues, instruct `gh issue view N --comments` — body alone misses thread clarifications. The orchestrator reads these sources too (to construct the prompt), but that's prompt construction, not a substitute for the sub-agent reading them.
+2. **Primary sources** — the specific files, GH issues, and reference docs the sub-agent must read directly. Inlining content into the prompt is a paraphrase that loses nuance; agents grounded in the source catch details the orchestrator's summary missed. For GH issues, instruct both `gh issue view N --comments` (the comment thread) and the timeline cross-reference query in the Orient block (what references the issue, including cross-repo) — the body alone misses both. The orchestrator reads these sources too (to construct the prompt), but that's prompt construction, not a substitute for the sub-agent reading them.
 3. **Path** — the Tier 1 skill(s) and steps that get to the goal. This is what gets handed to the sub-agent.
 4. **Verification** — the read-only checks that confirm the goal was hit. Defined upfront, not as an afterthought.
 
@@ -91,6 +91,8 @@ Sub-agents are optional. Match the mechanism to your platform's capability — t
 
 Phases, gates, goals, and constraints are identical across all three tiers — only the fanout mechanism changes. Use the most capable tier available, and don't hand-roll what the platform does natively (e.g., rolling concurrency). Choose by scope and capability, not by default.
 
+**Model tier ≠ orchestration tier.** A higher orchestration tier is not automatically the right choice. On some platforms, programmatically-orchestrated or *nested* sub-agents (an agent spawning agents) silently run on a cheaper/downgraded model, while the strongest model is reachable only by sub-agents the **main loop spawns directly** (tier 2). When a phase needs the top model (heavy generation, design, framework adoption), prefer direct main-loop fanout even when a more "capable" orchestration primitive exists — the primitive can cost you the model. Verify the model your platform actually assigned via its UI/telemetry; never infer it from a sub-agent's transcript, which interleaves auxiliary calls (titles, summaries) on cheaper models and will mislead you.
+
 The decision tree below is orthogonal to tier — it governs *whether* a given phase fans out, by target count and conflict risk:
 
 | Situation | Strategy |
@@ -119,10 +121,12 @@ order. If any file does not exist, note it and continue.
    available skills with descriptions and locations.
 5. Read the skill file(s) for this task: `[Tier 1 skill paths]`.
 6. Read the primary sources for this task directly — design docs (`docs/design.md`),
-   GH issues (use `gh issue view <N> --comments` to capture the full thread, not
-   just the body), handoff documents, reference/gold-standard files. List each
-   one explicitly: `[primary source paths and gh commands]`. Skip this step only
-   if no primary source applies (rare).
+   GH issues, handoff documents, reference/gold-standard files. For a GH issue, read
+   both the comment thread and its cross-references — the body alone misses both:
+     - `gh issue view <N> --comments` — description + comment thread
+     - `gh api 'repos/{owner}/{repo}/issues/<N>/timeline' --paginate --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'` — issues/PRs that reference this one, including from other repos
+   List each source explicitly: `[primary source paths and gh commands]`. Skip this
+   step only if no primary source applies (rare).
 
 Only after that, begin the task below.
 

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.3"
+  version: "2.4"
   audience: external
   type: workflow
 ---
@@ -212,7 +212,6 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 - If `manifest.json` exists, the README should include the Claude Desktop install badge linking to `releases/latest/download/<name>.mcpb`
 - If the package is published to npm, include Cursor and VS Code install badges
 - See `references/readme.md` for badge format and config generation commands
-- See the **Bundling** section of `templates/CLAUDE.md` for `base64` / `encodeURIComponent` generation
 
 ### 12. `LICENSE`
 

package/skills/polish-docs-meta/references/readme.md

@@ -54,7 +54,21 @@ Centered HTML. The `<h1>` is the server name — use the scoped package name if
 </div>
 ```
 
-See the **Bundling** section of `templates/CLAUDE.md` (or `templates/AGENTS.md`) for how to generate the `<BASE64_CONFIG>` and `<URLENCODED_JSON>` payloads. Omit any install badge whose target doesn't apply (e.g. no `.mcpb` bundle → drop the Claude Desktop badge).
+Generate the `<BASE64_CONFIG>` (Cursor) and `<URLENCODED_JSON>` (VS Code) payloads — replace `<PACKAGE_NAME>` / `<SHORT_NAME>` and add `env` only for required API keys:
+
+```bash
+# Cursor: base64-encoded JSON. Split command/args, add env when keys are needed.
+echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"],"env":{"API_KEY":"your-api-key"}}' | base64
+# Without env (no required keys):
+echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"]}' | base64
+
+# VS Code: URL-encoded JSON. Same shape plus a `name` field.
+node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"],env:{API_KEY:"your-api-key"}}))'
+# Without env:
+node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"]}))'
+```
+
+Both clients use the same `{command, args, env}` shape; VS Code adds a top-level `name`. Omit `env` entirely when no API keys are needed — don't include empty objects or framework-only vars like `MCP_TRANSPORT_TYPE`. Install links route through HTTPS endpoints (`cursor.com/en/install-mcp`, `vscode.dev/redirect`) because GitHub-rendered markdown strips non-HTTP schemes — a raw `cursor://` or `vscode:` link won't click through. Omit any install badge whose target doesn't apply (e.g. no `.mcpb` bundle → drop the Claude Desktop badge).
 
 The header tagline must match the `package.json` `description`.
 

package/skills/report-issue-framework/SKILL.md

@@ -30,7 +30,12 @@ For general `gh` CLI workflows outside issue filing (PRs, workflows, API access)
 4. **Search existing issues** — don't file duplicates:
 
 ```bash
-gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword"
+gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword" --state all
+
+# Assess a close match before commenting — is it already linked to a fix or referenced elsewhere?
+gh issue view <number> -R cyanheads/mcp-ts-core --comments
+gh api 'repos/cyanheads/mcp-ts-core/issues/<number>/timeline' --paginate \
+  --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'
 ```
 
 5. **For documentation- or contract-shaped requests, audit all three doc layers first** — proposals to add reference docs, public-API conventions, attribute/event catalogs, or stability commitments often duplicate surface that already exists. Check `src/` for behavior, `docs/` for human-facing reference, and `skills/` for agent-facing reference. Skill files marked `audience: external` are the framework's public contract — treat them as authoritative when evaluating whether a documentation gap exists. Also verify the constants or types you'd reference aren't already exported from `@cyanheads/mcp-ts-core` or one of its subpaths.
@@ -273,8 +278,8 @@ ISSUE
 ## Following Up
 
 ```bash
-# Check issue status
-gh issue view <number> -R cyanheads/mcp-ts-core
+# Check issue status (with comment thread)
+gh issue view <number> -R cyanheads/mcp-ts-core --comments
 
 # Add context or respond to maintainer questions
 gh issue comment <number> -R cyanheads/mcp-ts-core --body "Additional context..."

package/skills/report-issue-local/SKILL.md

@@ -35,7 +35,12 @@ gh repo view --json nameWithOwner -q '.nameWithOwner'
 2. **Search existing issues** — if a close match exists (same symptom, different tool; same tool, different symptom; closed issue that might cover the new case), add a comment on that issue instead of filing a new one — unless the symptom or scope is distinct enough to warrant separate tracking:
 
 ```bash
-gh issue list --search "your error message or keyword"
+gh issue list --search "your error message or keyword" --state all
+
+# Assess a close match before commenting — is it already linked to a fix or referenced elsewhere?
+gh issue view <number> --comments
+gh api 'repos/{owner}/{repo}/issues/<number>/timeline' --paginate \
+  --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'
 ```
 
 3. **Reproduce the issue** — confirm it's reproducible. Note the exact input, transport mode, and any relevant env vars.
@@ -280,8 +285,8 @@ When genuinely ambiguous, file against this server's repo and note that it might
 ## Following Up
 
 ```bash
-# View issue details
-gh issue view <number>
+# View issue details (with comment thread)
+gh issue view <number> --comments
 
 # Add context
 gh issue comment <number> --body "Additional findings..."

package/templates/.env.example

@@ -3,6 +3,7 @@
 # MCP_HTTP_PORT=3010                # HTTP port (default: 3010)
 # MCP_HTTP_HOST=localhost           # HTTP host (default: localhost)
 # MCP_HTTP_ENDPOINT_PATH=/mcp      # HTTP endpoint path (default: /mcp)
+# MCP_HTTP_MAX_BODY_BYTES=1048576  # Max request body bytes; 413 over limit, 0 disables (default: 1048576)
 # MCP_PUBLIC_URL=                  # Public origin behind a TLS-terminating proxy (e.g. https://mcp.example.com)
 
 # ── Auth ──────────────────────────────────────────────────────────────

package/templates/AGENTS.md

@@ -50,6 +50,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
 - **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
 - **Secrets in env vars only** — never hardcoded.
+- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
 ---
 
@@ -151,6 +152,10 @@ export function getServerConfig() {
 
 `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.
 
+### Server instructions
+
+`createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
+
 ---
 
 ## Context
@@ -177,6 +182,8 @@ Handlers throw — the framework catches, classifies, and formats.
 **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
 errors: [
   { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
     when: 'No item matched the query',
@@ -271,7 +278,6 @@ Available skills:
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
 | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
-| `migrate-mcp-ts-template` | One-time migration of an existing project to the current framework template |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
@@ -319,40 +325,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 **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.
 
-**README install badges.** Drop these into the project README to give users one-click install paths. Fill in `<OWNER>` / `<REPO>` / `<PACKAGE_NAME>` and encode the per-server config. Cursor + VS Code badges assume the server is published to npm; Claude Desktop downloads the `.mcpb` directly so npm publishing isn't required.
-
-| Client | Mechanism |
-|:-------|:----------|
-| Claude Desktop | Browser downloads the `.mcpb` from the latest GitHub Release; OS file handler routes it to Claude Desktop, which opens the install dialog. No deep-link URL scheme yet — this is the canonical path. |
-| Cursor | Official `https://cursor.com/en/install-mcp` endpoint with base64 JSON config. |
-| VS Code / Insiders | Official `vscode:mcp/install?...` deep link, wrapped in `https://vscode.dev/redirect?url=` so GitHub-rendered markdown doesn't strip the non-HTTP scheme. |
-| Claude Code / Codex | CLI only (`claude mcp add` / `codex mcp add`); no URL scheme. |
-
-```markdown
-[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/<OWNER>/<REPO>/releases/latest/download/<PACKAGE_NAME>.mcpb)
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=<PACKAGE_NAME>&config=<BASE64_CONFIG>)
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?<URLENCODED_JSON>)
-```
-
-Both install links route through HTTPS endpoints (`cursor.com/en/install-mcp` and `vscode.dev/redirect`) — GitHub-rendered markdown strips non-HTTP URL schemes from anchors, so a raw `cursor://` or `vscode:` link won't click through from github.com.
-
-Generate the encoded configs (replace `<PACKAGE_NAME>` and add env vars for any required API keys):
-
-```bash
-# Cursor: base64-encoded JSON. Split command/args, add env when keys are needed.
-echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"],"env":{"API_KEY":"your-api-key"}}' | base64
-# Without env (no required keys):
-echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"]}' | base64
-
-# VS Code: URL-encoded JSON. Same shape plus a `name` field.
-node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"],env:{API_KEY:"your-api-key"}}))'
-# Without env:
-node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"]}))'
-```
-
-Both clients use the same `{command, args, env}` shape (matching `mcp.json` schema). VS Code adds a top-level `name` field. Omit `env` entirely when no API keys are needed — don't include empty objects or framework-only vars like `MCP_TRANSPORT_TYPE`.
-
-The Claude Desktop badge requires the bundle to ship with a stable filename — `bun run bundle` outputs `dist/<PACKAGE_NAME>.mcpb`, and `release-and-publish` attaches that file to the GitHub Release. `releases/latest/download/<PACKAGE_NAME>.mcpb` then redirects to the most recent release.
+**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
 
 ---