@cyanheads/mcp-ts-core 0.9.11 → 0.9.13

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`.
 
 ---
 

package/templates/CLAUDE.md

@@ -152,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
@@ -178,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',
@@ -272,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 |
@@ -302,7 +307,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run rebuild` | Clean + build |
 | `npm run clean` | Remove build artifacts |
 | `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
-| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
 | `npm run tree` | Generate directory structure doc |
 | `npm run format` | Auto-fix formatting |
 | `npm test` | Run tests |
@@ -320,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`.
 
 ---
 

package/skills/migrate-mcp-ts-template/SKILL.md

@@ -1,162 +0,0 @@
----
-name: migrate-mcp-ts-template
-description: >
-  Migrate an existing mcp-ts-template fork to use @cyanheads/mcp-ts-core as a package dependency. Use when a project was cloned/forked from github.com/cyanheads/mcp-ts-template and carries framework source code in its own src/ — this skill rewrites those internal imports to package subpath imports and removes the bundled framework files.
-metadata:
-  author: cyanheads
-  version: "2.2"
-  audience: external
-  type: workflow
----
-
-## Context
-
-Before `@cyanheads/mcp-ts-core` was published as a package, users built servers by forking/cloning the `mcp-ts-template` repo. Those forks carry the full framework source code in their `src/` and use `@/` path aliases to import framework internals alongside their own server code.
-
-This skill converts such a project to use `@cyanheads/mcp-ts-core` as a dependency — rewriting framework imports to package subpaths and removing the bundled framework files, while leaving server-specific code (tools, resources, prompts, services) untouched.
-
-For the full exports catalog, see `CLAUDE.md` → Exports Reference.
-
-## Steps
-
-1. **Install the package**: `bun add @cyanheads/mcp-ts-core`
-2. **Search for all `@/` imports** across `src/` that reference framework internals: `grep -rn "from '@/" src/`
-3. **Rewrite each import** using the mapping table below
-4. **Identify framework source files** now provided by the package (see candidates below) — review each for server-specific additions before cleaning up
-5. **Update entry point** (`src/index.ts`) to use `createApp()` from the package and the project's chosen registration pattern (fresh scaffold default: direct imports in `src/index.ts`)
-6. **Update build configs**:
-   - `tsconfig.json` extends `@cyanheads/mcp-ts-core/tsconfig.base.json`
-   - `biome.json` extends `@cyanheads/mcp-ts-core/biome`
-   - `vitest.config.ts` spreads from `@cyanheads/mcp-ts-core/vitest.config`
-7. **Run `bun run devcheck`** to verify no broken imports remain
-8. **Verify no `@/` imports** point to framework files that are no longer local
-
-## Import mapping
-
-These are the actual `@/` import paths used in framework source. Rewrite any that appear in server-specific files (tools, resources, services, config).
-
-### Core
-
-| Old `@/` import | New package import |
-|:----------------|:-------------------|
-| `@/config/index.js` | `@cyanheads/mcp-ts-core/config` |
-| `@/context.js` or `@/core/context.js` | `@cyanheads/mcp-ts-core` |
-| `@/core/worker.js` | `@cyanheads/mcp-ts-core/worker` |
-| `@/types-global/errors.js` | `@cyanheads/mcp-ts-core/errors` |
-| `@/storage/core/StorageService.js` | `@cyanheads/mcp-ts-core/storage` |
-| `@/storage/core/IStorageProvider.js` | `@cyanheads/mcp-ts-core/storage/types` |
-| `@/mcp-server/transports/auth/lib/checkScopes.js` | `@cyanheads/mcp-ts-core/auth` |
-| `@/testing/index.js` | `@cyanheads/mcp-ts-core/testing` |
-
-### Definition types
-
-| Old `@/` import | New package import |
-|:----------------|:-------------------|
-| `@/mcp-server/tools/utils/toolDefinition.js` | `@cyanheads/mcp-ts-core/tools` (types only: `ToolDefinition`, `AnyToolDefinition`) or `@cyanheads/mcp-ts-core` (for the `tool()` builder) |
-| `@/mcp-server/resources/utils/resourceDefinition.js` | `@cyanheads/mcp-ts-core/resources` (types only: `ResourceDefinition`, `AnyResourceDefinition`) or `@cyanheads/mcp-ts-core` (for the `resource()` builder) |
-| `@/mcp-server/prompts/utils/promptDefinition.js` | `@cyanheads/mcp-ts-core/prompts` (types only: `PromptDefinition`) or `@cyanheads/mcp-ts-core` (for the `prompt()` builder) |
-| `@/mcp-server/tasks/utils/taskToolDefinition.js` | `@cyanheads/mcp-ts-core/tasks` |
-
-### Utils
-
-| Old `@/` import | New package import |
-|:----------------|:-------------------|
-| `@/utils/internal/logger.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/internal/requestContext.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/internal/error-handler/errorHandler.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/internal/runtime.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/internal/encoding.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/formatting/*.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/parsing/*.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/security/*.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/network/*.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/pagination/pagination.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/types/guards.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/scheduling/*.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/telemetry/*.js` | `@cyanheads/mcp-ts-core/utils` |
-| `@/utils/metrics/*.js` | `@cyanheads/mcp-ts-core/utils` |
-
-### Services
-
-| Old `@/` import | New package import |
-|:----------------|:-------------------|
-| `@/services/llm/*.js` | `@cyanheads/mcp-ts-core/services` |
-| `@/services/speech/*.js` | `@cyanheads/mcp-ts-core/services` |
-| `@/services/graph/*.js` | `@cyanheads/mcp-ts-core/services` |
-
-## Framework file candidates
-
-After rewriting imports, these directories and files are candidates for cleanup — they contain framework code now provided by the package. **Review each before acting**: the server may have added custom files alongside framework code in any of these directories. Preserve anything server-specific.
-
-**Preserve:** server-specific code under `mcp-server/tools/definitions/`, `mcp-server/resources/definitions/`, `mcp-server/prompts/definitions/`, the server's own `services/`, and `config/server-config.ts`.
-
-A file is server-specific if it doesn't appear in the `mcp-ts-template` repo at its path. Modified framework files should be extracted to a server-specific location (e.g., `src/utils/my-project/`) before deletion.
-
-Framework directories (typically safe to remove in full — verify no server-specific files were added):
-
-- `src/core/` (app, context, worker)
-- `src/cli/`
-- `src/types-global/`
-- `src/storage/`
-- `src/utils/`
-- `src/testing/`
-- `src/services/llm/`, `src/services/speech/`, `src/services/graph/` (framework-provided services — the server's own service directories are separate)
-
-Framework files within directories that contain server code:
-
-- `src/config/index.ts` (the framework config loader — `server-config.ts` is server-specific, keep it)
-- `src/mcp-server/server.ts`
-- `src/mcp-server/transports/` (entire directory)
-- `src/mcp-server/roots/` (entire directory)
-- `src/mcp-server/tasks/` (core task infra — tool definitions using `task: true` are server code)
-- `src/mcp-server/tools/utils/`, `src/mcp-server/tools/tool-registration.ts`
-- `src/mcp-server/resources/utils/`, `src/mcp-server/resources/resource-registration.ts`
-- `src/mcp-server/prompts/utils/`, `src/mcp-server/prompts/prompt-registration.ts`
-
-## Entry point rewrite
-
-Rewrite the `createApp()` call and its surrounding imports to use the package. Preserve the project's existing barrel structure and registration pattern if present:
-
-```ts
-#!/usr/bin/env node
-import { createApp } from '@cyanheads/mcp-ts-core';
-import { echoTool } from './mcp-server/tools/definitions/echo.tool.js';
-import { echoResource } from './mcp-server/resources/definitions/echo.resource.js';
-import { echoPrompt } from './mcp-server/prompts/definitions/echo.prompt.js';
-
-await createApp({
-  tools: [echoTool],
-  resources: [echoResource],
-  prompts: [echoPrompt],
-});
-```
-
-Add `setup()` if the server initializes services:
-
-```ts
-await createApp({
-  tools: [echoTool],
-  resources: [echoResource],
-  prompts: [echoPrompt],
-  setup(core) {
-    initMyService(core.config, core.storage);
-  },
-});
-```
-
-If the migrated project already has `definitions/index.ts` barrels and you want to keep them, that is fine. The important part is removing imports from framework internals and registering definitions consistently.
-
-## Checklist
-
-- [ ] `@cyanheads/mcp-ts-core` installed as a dependency
-- [ ] All framework `@/` imports rewritten to `@cyanheads/mcp-ts-core/*` subpaths
-- [ ] No `@/` imports point to framework files that are no longer local
-- [ ] `src/index.ts` uses `createApp()` from the package
-- [ ] `tsconfig.json` extends `@cyanheads/mcp-ts-core/tsconfig.base.json`
-- [ ] `biome.json` extends `@cyanheads/mcp-ts-core/biome`
-- [ ] `vitest.config.ts` spreads from `@cyanheads/mcp-ts-core/vitest.config`
-- [ ] Framework-only directories removed (`src/core/`, `src/cli/`, `src/types-global/`, `src/storage/`, `src/utils/`, `src/testing/`, framework service subdirs)
-- [ ] Framework files within mixed directories removed (`server.ts`, `transports/`, `roots/`, tasks infra, `*/utils/` dirs, `*-registration.ts` files)
-- [ ] `vitest.config.ts` includes `@/` alias: `resolve: { alias: { '@/': new URL('./src/', import.meta.url).pathname } }`
-- [ ] Server-specific `@/` imports (own tools, services) still work
-- [ ] `bun run devcheck` passes