@cyanheads/mcp-ts-core 0.6.9 → 0.6.11

package/skills/setup/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: workflow
 ---
@@ -29,19 +29,39 @@ For the full framework API, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
 What `init` actually creates:
 
 ```text
-CLAUDE.md                                       # Agent protocol (project-specific)
-AGENTS.md                                       # Alternate agent protocol file — keep the one your agent uses
-.github/ISSUE_TEMPLATE/                         # GitHub issue templates (bug report, feature request)
-skills/                                         # Project skills (source of truth)
+CLAUDE.md                                       # Agent protocol — Claude Code
+AGENTS.md                                       # Agent protocol — other agents (Codex, Cursor, etc.)
+package.json                                    # Starter deps + scripts (placeholders substituted on init)
+tsconfig.json                                   # TypeScript config
+tsconfig.build.json                             # Build-only TS config
+vitest.config.ts                                # Test runner config
+biome.json                                      # Lint + format config
+devcheck.config.json                            # Which devcheck steps to run
+Dockerfile                                      # Starter multi-stage image
+.dockerignore
+.env.example                                    # Copy to .env and fill in
+.gitignore
+.github/ISSUE_TEMPLATE/                         # Bug / feature-request issue forms
+.vscode/                                        # Recommended extensions + editor settings
+server.json                                     # MCP Registry publishing metadata
+changelog/template.md                           # Format reference for per-version changelog files
+scripts/                                        # build, clean, devcheck, lint-mcp, build-changelog, tree, check-docs-sync
+skills/                                         # External skills copied from the package (source of truth)
 src/
   index.ts                                      # createApp() entry point
   mcp-server/
     tools/definitions/
-      echo.tool.ts                              # Echo tool (starter — replace when ready)
+      echo.tool.ts                              # Standard tool starter
+      echo-app.app-tool.ts                      # UI-enabled app tool starter (pairs with echo-app-ui resource)
     resources/definitions/
-      echo.resource.ts                          # Echo resource (starter — replace when ready)
+      echo.resource.ts                          # Standard resource starter
+      echo-app-ui.app-resource.ts               # UI resource paired with echo-app app tool
     prompts/definitions/
-      echo.prompt.ts                            # Echo prompt (starter — replace when ready)
+      echo.prompt.ts                            # Prompt starter
+tests/
+  tools/echo.tool.test.ts                       # Starter tests (one per echo definition)
+  resources/echo.resource.test.ts
+  prompts/echo.prompt.test.ts
 ```
 
 Add these as needed:
@@ -59,11 +79,24 @@ src/
 
 ## Scaffolded Echo Definitions
 
-The init creates echo definitions for tools, resources, and prompts. They're functional examples with inline comments explaining conventions. After init:
+The init creates five echo definitions plus matching starter tests:
 
-1. Clean up what you don't need. If your server has no prompts, the echo prompt definition and its registration in `src/index.ts` can go. Same for resources.
-2. Rename and replace what you keep. The echo definitions show the pattern — swap them out for your real tools/resources/prompts.
-3. Definitions register directly in `src/index.ts`. No barrel files, just import and add to the arrays.
+| File | Demonstrates |
+|:--|:--|
+| `echo.tool.ts` | Standard MCP tool: input/output Zod schemas, `handler`, `format` |
+| `echo-app.app-tool.ts` | MCP App tool — same as a tool, but emits a UI (`ui_app://` link) for clients that render MCP Apps |
+| `echo.resource.ts` | Standard MCP resource with a parameterised URI template |
+| `echo-app-ui.app-resource.ts` | UI resource served to MCP App clients; paired with `echo-app.app-tool.ts` |
+| `echo.prompt.ts` | Prompt template (pure message generator) |
+| `tests/**/echo.*.test.ts` | Starter tests using `createMockContext` — edit alongside the definitions |
+
+After init:
+
+1. **Clean up what you don't need.** If your server has no prompts, delete the echo prompt and its registration in `src/index.ts`. Same for resources, or the app-tool pair if you're not targeting UI-capable clients.
+2. **Rename and replace what you keep.** The echo definitions and their tests show the pattern — swap them out for your real tools/resources/prompts.
+3. **Definitions register directly in `src/index.ts`.** No barrel files, just import and add to the `tools` / `resources` / `prompts` arrays.
+
+See the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt`, and `add-test` skills for the scaffolding patterns when you start adding real definitions.
 
 ## Conventions
 
@@ -71,7 +104,7 @@ The init creates echo definitions for tools, resources, and prompts. They're fun
 |:-----------|:-----|
 | File names | kebab-case |
 | Tool/resource/prompt names | snake_case, prefixed with server name (e.g. `tasks_fetch_list`) |
-| File suffixes | `.tool.ts`, `.resource.ts`, `.prompt.ts` |
+| File suffixes | `.tool.ts`, `.resource.ts`, `.prompt.ts`, `.app-tool.ts` (UI-enabled), `.app-resource.ts` (paired UI resource) |
 | Imports (framework) | `@cyanheads/mcp-ts-core` and subpaths |
 | Imports (server code) | `@/` path alias for `src/` |
 
@@ -97,6 +130,23 @@ After `bun install`, complete these one-time setup tasks:
 2. **Initialize git** — `git init && git add -A && git commit -m "chore: scaffold from @cyanheads/mcp-ts-core"`
 3. **Verify agent protocol placeholders** — if the `init` CLI was run without a `[name]` argument, `{{PACKAGE_NAME}}` may remain as a literal in `CLAUDE.md`/`AGENTS.md` and `package.json`. Replace it with the actual server name.
 
+## Changelog Convention
+
+`changelog/template.md` ships as a **format reference** — never edit, rename, or move it. For each release, author a per-version file at `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) with YAML frontmatter (`summary:` + optional `breaking:`) and grouped sections (Added / Changed / Fixed / Removed). Then regenerate the rollup with `bun run changelog:build` — `CHANGELOG.md` is an auto-generated navigation index, never hand-edited. See the `release-and-publish` skill for the full release flow.
+
+## Next Steps
+
+The included skills form a rough progression — not a rigid sequence, but the typical flow through a new server:
+
+1. **`design-mcp-server`** — map the domain into tools, resources, and services before writing any definitions
+2. **`add-tool`** / **`add-app-tool`** / **`add-resource`** / **`add-prompt`** / **`add-service`** — scaffold each piece as you go
+3. **`add-test`** — pair tests with each definition (or retrofit later)
+4. **`field-test`** — exercise the built surface with real and adversarial inputs; produces a report of issues and pain points
+5. **`polish-docs-meta`** — finalize README, metadata, and agent protocol before shipping
+6. **`maintenance`** — after `bun update --latest`, investigate upstream changelogs and re-sync skills
+
+Skip or reorder as the project calls for it. The agent protocol's "What's Next?" section is the authoritative map once the first session is over.
+
 ## Checklist
 
 - [ ] Agent protocol file selected — keep one authoritative file (`CLAUDE.md` or `AGENTS.md`)
@@ -106,4 +156,4 @@ After `bun install`, complete these one-time setup tasks:
 - [ ] Skills copied to agent directory (`cp -R skills/* .claude/skills/` or equivalent)
 - [ ] Project structure understood (definitions directories, entry point)
 - [ ] `bun run devcheck` passes
-- [ ] If new server: proceed to `design-mcp-server` skill to plan the tool surface
+- [ ] Next: if new server, move on to `design-mcp-server` to plan the tool surface

package/skills/release/SKILL.md

@@ -1,142 +0,0 @@
----
-name: release
-description: >
-  Verify release readiness and publish. The git wrapup protocol handles version bumps, changelog, README, commits, and tagging during the coding session. This skill verifies nothing was missed, runs final checks, and presents the irreversible publish commands.
-metadata:
-  author: cyanheads
-  version: "1.5"
-  audience: internal
-  type: workflow
----
-
-## Context
-
-By the time this skill runs, the git wrapup protocol should have already handled: changelog entry, version bumps, README updates, atomic commits, and an annotated tag. This skill is the **final verification gate** before irreversible publish commands. Its job is to catch anything the wrapup missed or got wrong — not to redo the work.
-
-## Steps
-
-### 1. Confirm the Target Version
-
-Read `package.json` to get the version. This is the source of truth. If the user hasn't decided on the bump level yet (patch/minor/major), ask now — but usually this was already set during wrapup.
-
-### 2. Verify Version Consistency
-
-The wrapup protocol bumps versions, but sometimes a file gets missed. **Search for the old version string** across the repo and verify the new version appears in all required locations:
-
-| File | What to Verify |
-|:-----|:---------------|
-| `package.json` | `version` field |
-| `server.json` | Root `version` + `version` in each `packages[]` entry (3 total) |
-| `CLAUDE.md` | Version in the header (`**Version:** X.Y.Z`) |
-| `README.md` | Version badge (`Version-X.Y.Z-blue`) and any other version references |
-| `templates/CLAUDE.md` | `**Version:** X.Y.Z` in the header |
-| `templates/AGENTS.md` | Same — these files are identical |
-
-Fix any mismatches. A grep for the **old** version is the fastest way to find stragglers.
-
-### 3. Finalize the Per-Version Changelog File
-
-The changelog is directory-based, grouped by minor series using the `.x` semver-wildcard convention: per-version files live at `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.5.x/0.5.4.md`), and `CHANGELOG.md` is an auto-generated rollup (`bun run changelog:build`). `changelog/template.md` is a **pristine format reference** — never edited, never moved, never renamed. At release time, you're authoring (or finalizing) the per-version file for the version being shipped.
-
-Create or finalize `changelog/<series>/<version>.md`:
-
-1. Determine the series: `0.5.5` → `0.5.x/`. Create the directory if it doesn't exist: `mkdir -p changelog/<series>`
-2. If the file doesn't exist yet, scaffold it by copying the structure of `changelog/template.md` into the new path. Do **not** `git mv` or otherwise rename `template.md` itself — it stays where it is.
-3. Set the H1: `# <version> — <date>` (em-dash, ISO date)
-4. **Fill in the frontmatter** at the top of the file:
-   - `summary:` — one-line headline, ≤250 chars, no markdown. Write it like a GitHub Release title. Required.
-   - `breaking:` — set to `true` if this release requires consumer code changes (API removal, signature change, config rename). Defaults to `false`. Renders `· ⚠️ Breaking` in the rollup when true.
-5. Verify content:
-   - Sections grouped correctly (Added / Changed / Fixed / Removed)
-   - Accurately reflects what shipped — cross-reference with `git log` since the last tag
-   - If this release absorbed pre-release versions (e.g., `0.6.0-beta.1`), consolidate their entries as `##`/`###` sub-headers inside this file (they share this version's frontmatter — no separate files)
-   - **Issue/PR references use full URLs**, not bare `#NN`. GitHub's auto-link only renders inside its own UI; these files are read from `node_modules` too, where bare `#NN` is dead text. Use `[#38](https://github.com/<owner>/<repo>/issues/38)` (or `/pull/NN` for PRs). Only link numbers verified via `gh issue view NN` / `gh pr view NN` — never speculate on future numbers, since GitHub will happily resolve `#42` to whatever unrelated item already owns 42 and pull its title into timeline previews.
-6. Regenerate the rollup: `bun run changelog:build` — warnings about missing summaries are expected during the legacy-file backfill period but should not include this release
-
-Never hand-edit `CHANGELOG.md` — it's a build artifact. Devcheck's `Changelog Sync` step will fail if it drifts. Never edit `changelog/template.md` — it's the format reference, not a worksheet.
-
-### 4. Verify README.md
-
-Beyond the version badge, confirm:
-
-- Feature counts (tool count, resource count, etc.) match reality if the surface area changed
-- Descriptions and capability lists reflect new features
-- MCP SDK version badge is current if the dependency was bumped
-- Code examples still match current APIs
-
-### 5. Verify Skill Versions
-
-For any skills whose `SKILL.md` was modified in this release cycle, confirm `metadata.version` in their YAML frontmatter was bumped. This is how the `maintenance` skill detects updates — if the version didn't bump, consumers won't get the new content on `bun update`.
-
-### 6. Verify `docs/tree.md`
-
-If the file structure changed, regenerate and confirm it's current:
-
-```bash
-bun run tree
-```
-
-Skip if no structural changes occurred.
-
-### 7. Run Final Checks
-
-All must pass:
-
-```bash
-bun run devcheck
-bun run test
-bun run build
-```
-
-### 8. Verify Commit and Tag
-
-Confirm a clean release commit and annotated tag exist:
-
-- Commit message: `chore: release v{{VERSION}}`
-- Annotated tag: `v{{VERSION}}` with a concise summary of key changes
-
-If the wrapup created the commit and tag already, verify they're correct. If not, create them now.
-
-Tag message examples:
-
-```text
-v0.2.0: Cloudflare Workers support, task tools, Graph service
-v0.1.7: OTel instrumentation refactor, lighter semconv
-v0.1.6: Error factory functions, auto-classification patterns
-```
-
-### 9. Stop and Present Publish Commands
-
-The following commands are irreversible. Present them to the user for manual execution:
-
-```bash
-# Push commit and tag
-git push && git push --tags
-
-# Publish to npm
-bun publish --access public
-
-# Build and push Docker image
-docker buildx build --platform linux/amd64,linux/arm64 \
-  -t ghcr.io/cyanheads/mcp-ts-core:{{VERSION}} \
-  -t ghcr.io/cyanheads/mcp-ts-core:latest \
-  --push .
-
-# Publish MCP listing (if applicable)
-mcp-publisher publish
-```
-
-## Pre-Publish Checklist
-
-- [ ] Version consistent across all files (package.json, server.json ×3, CLAUDE.md, README.md, templates)
-- [ ] No stale old-version references found in repo
-- [ ] `changelog/<major.minor>.x/<version>.md` created/finalized with concrete version, date, and frontmatter; `CHANGELOG.md` regenerated via `bun run changelog:build`; `changelog/template.md` untouched
-- [ ] README.md current — feature counts, badges, descriptions, examples
-- [ ] Modified skill versions bumped in YAML frontmatter
-- [ ] `docs/tree.md` current (if structure changed)
-- [ ] `bun run devcheck` passes
-- [ ] `bun run test` passes
-- [ ] `bun run build` succeeds
-- [ ] Clean release commit exists
-- [ ] Annotated git tag exists with summary message
-- [ ] User presented with publish commands (push, npm, Docker, mcp-publisher)