@cyanheads/mcp-ts-core 0.13.0 → 0.13.1

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

@@ -123,18 +123,22 @@ If a public hosted instance is available, **promote it to a top-level callout**
 
 Keep the full connection-config JSON block inside a `### Public Hosted Instance` subsection under Getting Started (covered below). This callout is just the visibility pointer.
 
+No hosted instance → omit the callout, the Getting Started subsection, and any hosted mention in the Overview. Never state the absence ("no public hosted instance"); self-hosting is the default a reader already assumes.
+
 ### Overview
 
 The first section after the header rule. Two parts: a short description paragraph, then one two-column table per primitive type. This is what a visitor reads to decide whether the server is for them, so it must scan in one screen.
 
-**Description paragraph:** two or three sentences — what the server sits on top of (the upstream APIs), what a user can do with it (the headline workflows, action verbs), and how it runs (transports, the hosted endpoint if any). Not a count, and not "an MCP server that…" framing.
+**Description paragraph:** two or three sentences — what the server sits on top of (the upstream APIs), what a user can do with it (the headline workflows, action verbs), and how it runs (transports, plus the hosted endpoint when one exists). Not a count.
+
+The opening sentence names the subject, not the container. The reader is already on an MCP server's repo page — the `<h1>`, the badge row, and the framework line all say so — so an opener that restates it ("An MCP server over…", "An MCP calculator…", "An MCP server that…") spends the most-read sentence on nothing. Lead with the domain or the upstream as a noun phrase, article optional: "Calculator powered by math.js.", "Seismic data from USGS ComCat and the EMSC SeismicPortal.", "The Acme v2 API — projects, tasks, and team activity.", "Read, write, and search Obsidian vault notes over the Local REST API plugin." The words "MCP server" appear at most once in the paragraph, and never as its first noun.
 
 **Primitive tables:** a `### Tools` table, then `### Resources` and `### Prompts` tables when the server has any. Omit a heading whose table would be empty, but keep a one-row table rather than folding it into another. Two columns, Name/Description, one-line descriptions — the detail lives in the Capability reference.
 
 ```markdown
 ## Overview
 
-An MCP server over the Acme v2 API. Search projects, manage tasks, and track team activity from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+Project management over the Acme v2 API. Search projects, manage tasks, and track team activity from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
 
 ### Tools
 
@@ -201,12 +205,12 @@ Link an examples file from an entry when one exists: `[View detailed examples](.
 
 ### Features
 
-A one-sentence framework line naming what a user gets from the framework (transports, auth, storage, observability — not how the code is organized; contributor facts belong in the Development guide), then two bullet groups: domain-specific capabilities, then agent-friendly output design.
+The framework line below, verbatim — it names what a user gets from the framework (transports, auth, storage, observability), so it replaces any framework-feature bullets; contributor facts about code organization belong in the Development guide. Then two labeled bullet groups, both always present: `<Upstream>-specific:` (3–5 bullets on the server's own integration), then `Agent-friendly output:`.
 
 ```markdown
 ## Features
 
-Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
 Acme-specific:
 
@@ -221,7 +225,7 @@ Agent-friendly output:
 - Discriminated output contracts — typed status and source fields let callers branch on data, not string parsing
 ```
 
-The **Agent-friendly output** subsection documents output-design choices that make the server work well as an AI-agent backend. Include it when the server exhibits at least two of these patterns. Write bullets grounded in the server's actual behavior — not aspirational framework capabilities. Examples of what fits:
+The **Agent-friendly output** subsection documents output-design choices that make the server work well as an AI-agent backend. Always include it, with 2–4 bullets in the "Pattern — concrete detail" form, each naming fields or behavior verified in the server's source — not aspirational framework capabilities. Drop a pattern the server doesn't have (no batch tools → no partial-failure bullet) rather than claiming it. Examples of what fits:
 
 - Provenance: source labels (`viaSource`, `source`), license/access-level fields, effective-query echo, best-effort warnings on lossy tiers
 - Partial failure: per-item status in batch operations, structured error rows alongside successes, recovery hints ("Next Step" text)
@@ -434,10 +438,10 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
 
 ### Cloudflare Workers
 
-1. **Build the Worker bundle:**
+1. **Run locally under wrangler:**
 
 \`\`\`sh
-bun run build:worker
+bun run deploy:dev
 \`\`\`
 
 2. **Deploy:**
@@ -447,7 +451,7 @@ bun run deploy:prod
 \`\`\`
 ```
 
-Include the Docker or Workers subsection only if the server supports it. The Docker trailing paragraph (log directory, OTEL build arg) is important — it documents Dockerfile behavior that isn't obvious from the build command.
+Include the Docker subsection only if the server ships a Dockerfile, and the Workers subsection only if it ships a `src/worker.ts` entry. The Docker trailing paragraph (log directory, OTEL build arg) is important — it documents Dockerfile behavior that isn't obvious from the build command.
 
 ### Project Structure
 

package/framework-skills/release-and-publish/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GitHub Releases for `.mcpb` bundles, GHCR). Runs the final verification gate, fast-forwards `main` when the release rode a release PR, creates the annotated tag on the commit `main` now points at, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit stack — and in release PR mode, the pushed branch and open PR) is already complete — this skill is the post-wrapup merge + tag + publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
 metadata:
   author: cyanheads
-  version: "2.16"
+  version: "2.17"
   audience: external
   type: workflow
 ---
@@ -111,12 +111,15 @@ If `--ff-only` refuses, `main` moved underneath the release branch. Halt and rep
 The tag goes on HEAD. In release PR mode that is `main`'s tip after step 3 — the commit the PR's `headRefOid` names — so the tag is created on the branch it stays reachable from.
 
 ```bash
-git tag -a v<version> --cleanup=whitespace -m "<tag message with embedded newlines>"
+cat > /tmp/tag-v<version>.md <<'TAG'
+<tag message>
+TAG
+git tag -a v<version> --cleanup=whitespace -F /tmp/tag-v<version>.md
 ```
 
 If `v<version>` already exists and points at HEAD, a prior run created it — proceed. If it exists and points anywhere else, **halt and report the conflict** with the version string, the existing tag SHA, and HEAD. Never delete or move a tag without explicit authorization.
 
-Use `-m` with embedded newlines in the string (plain `-m` only — no heredoc, no command substitution). The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string.
+Write the message to a file through a quoted-delimiter heredoc and pass it with `-F`, never inline with `-m`: the body carries backticks, which a double-quoted string runs as command substitution and silently deletes, and apostrophes, which end a single-quoted string. The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string.
 
 **Release PR mode: the tag body is the PR body's `## Changes` bullets plus its final changelog link, verbatim** — `gh pr view <N> --json body -q .body` (`<N>` from step 1 — on `main` there is no branch for `gh` to infer it from), take the theme line as the subject, the bullets under `## Changes`, and the last line; drop `## Gates` and the headers. That digest was authored at wrapup and reviewed on the PR; re-authoring it here would publish unreviewed words. The one addition: append ` · release PR #<N>` to that final line, so the GitHub Release points at its audit trail (GitHub autolinks the bare `#<N>`). Without a PR, author it from the changelog entry at `changelog/<major.minor>.x/<version>.md` — every claim in the tag must appear in that file, and the file's `summary:` line is the tag's theme.
 
@@ -193,10 +196,16 @@ Halt on publish error other than "version already exists" (which means this step
 
 Only if `server.json` exists at the repo root (otherwise skip). Note: `server.json` (MCP Registry metadata) and `manifest.json` (MCPB bundle manifest, step 8) are independent — a project may have either, both, or neither.
 
+The registry checks that the npm version exists before it registers, and npm's read endpoint can lag `bun publish` by several minutes. Wait for the version to be served before publishing; a publisher error saying the npm version was not found is this lag, not a terminal failure:
+
 ```bash
+curl -sf --retry 30 --retry-delay 30 --retry-all-errors -o /dev/null \
+  "https://registry.npmjs.org/<package-name>/<version>"
 bun run publish-mcp
 ```
 
+Step 8 depends only on the pushed tag, so it may run while this wait is in progress.
+
 If `publish-mcp` isn't defined in `package.json`, add it permanently (one-time setup, macOS):
 
 ```json

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

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.10"
+  version: "1.11"
   audience: external
   type: workflow
 ---
@@ -181,6 +181,7 @@ Every issue needs exactly one primary label. Stack secondary labels on top when
 | `performance` | Memory, CPU, latency, or resource usage |
 | `security` | Vulnerability, CVE, or hardening work |
 | `breaking-change` | Fix/feature will break public API; requires a major bump |
+| `blocked-by-sdk` | Fix requires changes in `@modelcontextprotocol/sdk` |
 | `surplus-token-idea` | Worth exploring when token budget allows |
 
 Combine labels: `--label "bug" --label "regression"`.

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

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: workflow
 ---
@@ -165,8 +165,12 @@ Every issue needs exactly one primary label. Stack secondary labels on top when
 | `performance` | Memory, CPU, latency, or resource usage |
 | `security` | Vulnerability, CVE, or hardening work |
 | `breaking-change` | Change will break public API; requires a major bump |
+| `blocked-by-framework` | Fix requires a released change in `@cyanheads/mcp-ts-core`; pairs with a `Depends on: cyanheads/mcp-ts-core#N` line in the body |
+| `blocked-by-sdk` | Fix requires changes in `@modelcontextprotocol/sdk` |
 | `surplus-token-idea` | Worth exploring when token budget allows |
 
+`blocked-by-framework` comes off when this server adopts the release that ships the fix. An issue blocked on the SDK *through* the framework takes `blocked-by-framework`, not `blocked-by-sdk` — the server's own unblock is still a framework release.
+
 Combine labels: `--label "bug" --label "regression"`.
 
 Secondary labels are not GitHub defaults — if `gh issue create --label "regression"` fails with `label not found`, create it once:
@@ -176,6 +180,8 @@ gh label create regression --color e99695 --description "Worked before, broken a
 gh label create performance --color 5319e7 --description "Memory, CPU, latency, or resource usage"
 gh label create security --color b60205 --description "Vulnerability, CVE, or hardening work"
 gh label create breaking-change --color d93f0b --description "Change will break public API; requires a major bump"
+gh label create blocked-by-framework --color fbca04 --description "Fix requires a released change in @cyanheads/mcp-ts-core"
+gh label create blocked-by-sdk --color c5def5 --description "Fix requires changes in @modelcontextprotocol/sdk"
 gh label create surplus-token-idea --color FF10F0 --description "Worth exploring when token budget allows"
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.",
   "files": [
@@ -25,7 +25,7 @@
     "templates/",
     "AGENTS.md",
     "CLAUDE.md",
-    "tsconfig.base.json",
+    "config/tsconfig.base.json",
     "vitest.config.base.mjs",
     "biome.json"
   ],
@@ -123,7 +123,7 @@
       "import": "./dist/testing/vitest.js",
       "default": "./dist/testing/vitest.js"
     },
-    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./tsconfig.base.json": "./config/tsconfig.base.json",
     "./vitest.config": "./vitest.config.base.mjs",
     "./biome": "./biome.json",
     "./package.json": "./package.json"
@@ -163,8 +163,8 @@
     "format": "biome check --write .",
     "format:unsafe": "biome check --write --unsafe .",
     "typecheck": "bunx tsc --noEmit",
-    "typecheck:scripts": "bunx tsc --project tsconfig.scripts.json --noEmit",
-    "typecheck:worker": "bunx tsc --project tsconfig.worker.json --noEmit",
+    "typecheck:scripts": "bunx tsc --project config/tsconfig.scripts.json --noEmit",
+    "typecheck:worker": "bunx tsc --project config/tsconfig.worker.json --noEmit",
     "list-skills": "bun run scripts/list-skills.ts",
     "tree": "bun run scripts/tree.ts",
     "fetch-spec": "bun run scripts/fetch-openapi-spec.ts",
@@ -234,7 +234,7 @@
     "js-yaml": "^5.4.1",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
-    "openai": "^7.10.0",
+    "openai": "^7.15.0",
     "papaparse": "^5.7.0",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",

package/scripts/build.ts

@@ -95,8 +95,8 @@ async function main() {
   const projectIdx = process.argv.indexOf('--project');
   const project =
     projectIdx !== -1
-      ? (process.argv[projectIdx + 1] ?? 'tsconfig.build.json')
-      : 'tsconfig.build.json';
+      ? (process.argv[projectIdx + 1] ?? 'config/tsconfig.build.json')
+      : 'config/tsconfig.build.json';
 
   console.log(`\x1b[1mBuilding ${pkg.name}@${pkg.version}\x1b[0m`);
   console.log(`\x1b[2m  tsconfig: ${project}\x1b[0m`);

package/scripts/devcheck.ts

@@ -866,12 +866,12 @@ const ALL_CHECKS: Check[] = [
     // globals cannot share one with @types/node's (#397). It reads the built
     // declarations, so it only has something to check after a build.
     getCommand: (ctx) => {
-      if (!existsSync(path.join(ctx.rootDir, 'tsconfig.worker.json'))) return null;
+      if (!existsSync(path.join(ctx.rootDir, 'config', 'tsconfig.worker.json'))) return null;
       if (!existsSync(path.join(ctx.rootDir, 'dist'))) return null;
       return [
         path.join(ctx.rootDir, 'node_modules', '.bin', 'tsc'),
         '--project',
-        'tsconfig.worker.json',
+        'config/tsconfig.worker.json',
         '--noEmit',
       ];
     },

package/templates/.env.example

@@ -1,7 +1,7 @@
 # ── Transport ──────────────────────────────────────────────────────────
 # MCP_TRANSPORT_TYPE=stdio          # stdio | http (default: stdio)
 # MCP_HTTP_PORT=3010                # HTTP port (default: 3010)
-# MCP_HTTP_HOST=localhost           # HTTP host (default: localhost)
+# MCP_HTTP_HOST=127.0.0.1           # HTTP host (default: 127.0.0.1)
 # 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)
@@ -14,7 +14,10 @@
 # STORAGE_PROVIDER_TYPE=in-memory   # in-memory | filesystem | supabase | cloudflare-r2 | cloudflare-kv | cloudflare-d1
 
 # ── Session ──────────────────────────────────────────────────────────
-# MCP_SESSION_MODE=auto             # stateful | stateless | auto (default: auto, resolves to stateful)
+MCP_SESSION_MODE=stateless          # stateful | stateless | auto. Set here, not left to the schema default
+                                    # (auto, which resolves to stateful). Stateless fits a data API:
+                                    # no session store, horizontally scalable. Use stateful when a tool
+                                    # asks the caller for input mid-handler (ctx.requestInput).
 # MCP_HTTP_RESUMABILITY=false       # SSE replay on a dropped stateful stream. Default: true.
                                     # Kill switch only — no effect on stateless serving.
 # MCP_HTTP_RESUMABILITY_MAX_EVENTS=512   # Retained per session, oldest evicted first

package/templates/AGENTS.md

@@ -174,6 +174,22 @@ await createApp({
 
 `instructions` is optional server-level orientation, sent 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.
 
+### Session posture and shutdown
+
+Two more `createApp()` options shape how the server runs rather than how it presents itself:
+
+```ts
+await createApp({
+  sessionMode: 'stateless',          // or { default: 'stateful', require: 'stateful' }
+  setup(core) { startMyWatcher(core.config); },
+  async teardown() { await stopMyWatcher(); },
+});
+```
+
+`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
+
+`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling).
+
 ---
 
 ## Context

package/templates/CLAUDE.md

@@ -174,6 +174,22 @@ await createApp({
 
 `instructions` is optional server-level orientation, sent 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.
 
+### Session posture and shutdown
+
+Two more `createApp()` options shape how the server runs rather than how it presents itself:
+
+```ts
+await createApp({
+  sessionMode: 'stateless',          // or { default: 'stateful', require: 'stateful' }
+  setup(core) { startMyWatcher(core.config); },
+  async teardown() { await stopMyWatcher(); },
+});
+```
+
+`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
+
+`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling).
+
 ---
 
 ## Context

package/templates/src/index.ts

@@ -20,4 +20,14 @@ await createApp({
   // instructions: 'Server-level orientation forwarded to the model on every initialize.\n' +
   //   '- Use shortcut `X` for the most common case\n' +
   //   '- Tools require auth via the `inventory:read` scope',
+
+  // Session posture in code rather than in a Dockerfile. MCP_SESSION_MODE still
+  // wins when it is set. Add `require: 'stateful'` — `{ default: 'stateful',
+  // require: 'stateful' }` — when a tool asks the caller for input mid-handler,
+  // so a stateless deployment fails at startup instead of losing that tool.
+  // sessionMode: 'stateless',
+
+  // Release what setup() allocated: a watcher, a socket, a timer the framework
+  // cannot see. Runs after the transport stops and before the logger closes.
+  // teardown(core) { core.logger.info('bye', { requestId: 'shutdown', timestamp: new Date().toISOString() }); },
 });