@cyanheads/mcp-ts-core 0.5.4 → 0.6.0

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.3"
+  version: "1.4"
   audience: external
   type: workflow
 ---
@@ -22,11 +22,7 @@ The init CLI generates both `CLAUDE.md` and `AGENTS.md` with the same purpose. K
 
 Both files serve the same purpose: project-specific agent instructions. Prefer committing one authoritative copy rather than trying to keep both in sync by hand.
 
-For the full framework API, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
-
-Read that file once per session. It contains the exports catalog, tool/resource/prompt contracts, error codes, context API, and common import patterns.
+For the full framework API, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` once per session. It contains the exports catalog, tool/resource/prompt contracts, error codes, context API, and common import patterns.
 
 ## Project Structure
 
@@ -95,9 +91,9 @@ This step is the **bootstrap** — it creates the agent directory. From then on,
 
 ## Project Scaffolding
 
-After installing dependencies (prefer `bun install`; `npm install` also works), complete these one-time setup tasks:
+After `bun install`, complete these one-time setup tasks:
 
-1. **Update dependencies to latest** — `bun update --latest` (or `npx npm-check-updates -u && npm install` if using npm). The scaffolded `package.json` pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.
+1. **Update dependencies to latest** — `bun update --latest`. The scaffolded `package.json` pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.
 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.
 

package/templates/AGENTS.md

@@ -264,7 +264,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run build` | Compile TypeScript |
 | `npm run rebuild` | Clean + build |
 | `npm run clean` | Remove build artifacts |
-| `npm run devcheck` | Lint + format + typecheck + security |
+| `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
 | `npm run tree` | Generate directory structure doc |
 | `npm run format` | Auto-fix formatting |
 | `npm test` | Run tests |
@@ -272,6 +272,28 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run dev:http` | Dev mode (HTTP) |
 | `npm run start:stdio` | Production mode (stdio) |
 | `npm run start:http` | Production mode (HTTP) |
+| `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
+| `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
+
+---
+
+## Changelog
+
+Directory-based, grouped by minor series using the `.x` semver-wildcard convention. Source of truth is `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per released version, shipped in the npm package. Work-in-progress entries live at the top level in `changelog/unreleased.md` and are moved into the appropriate series directory on release. `CHANGELOG.md` is a **navigation index** (header + link + one-line summary per version), regenerated by `npm run changelog:build`. Devcheck hard-fails on drift. Never hand-edit `CHANGELOG.md`.
+
+Each per-version file opens with YAML frontmatter:
+
+```markdown
+---
+summary: One-line headline, ≤250 chars  # required — powers the rollup index
+breaking: false                          # optional — true flags breaking changes
+---
+
+# 0.1.0 — YYYY-MM-DD
+...
+```
+
+`breaking: true` renders a `· ⚠️ Breaking` badge in the rollup — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames).
 
 ---
 

package/templates/CLAUDE.md

@@ -264,7 +264,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run build` | Compile TypeScript |
 | `npm run rebuild` | Clean + build |
 | `npm run clean` | Remove build artifacts |
-| `npm run devcheck` | Lint + format + typecheck + security |
+| `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
 | `npm run tree` | Generate directory structure doc |
 | `npm run format` | Auto-fix formatting |
 | `npm test` | Run tests |
@@ -272,6 +272,28 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run dev:http` | Dev mode (HTTP) |
 | `npm run start:stdio` | Production mode (stdio) |
 | `npm run start:http` | Production mode (HTTP) |
+| `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
+| `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
+
+---
+
+## Changelog
+
+Directory-based, grouped by minor series using the `.x` semver-wildcard convention. Source of truth is `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per released version, shipped in the npm package. Work-in-progress entries live at the top level in `changelog/unreleased.md` and are moved into the appropriate series directory on release. `CHANGELOG.md` is a **navigation index** (header + link + one-line summary per version), regenerated by `npm run changelog:build`. Devcheck hard-fails on drift. Never hand-edit `CHANGELOG.md`.
+
+Each per-version file opens with YAML frontmatter:
+
+```markdown
+---
+summary: One-line headline, ≤250 chars  # required — powers the rollup index
+breaking: false                          # optional — true flags breaking changes
+---
+
+# 0.1.0 — YYYY-MM-DD
+...
+```
+
+`breaking: true` renders a `· ⚠️ Breaking` badge in the rollup — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames).
 
 ---
 

package/templates/changelog/unreleased.md

@@ -0,0 +1,40 @@
+---
+# Required. One-line headline describing the release. Max 250 chars. No markdown.
+# This line is what the CHANGELOG.md rollup shows — write it like a GitHub Release title.
+summary: ""
+
+# Set to `true` only if this release has breaking changes (API removals, signature
+# changes, config renames, anything that requires consumer code changes on update).
+# Flagged as ⚠️ Breaking in the rollup.
+breaking: false
+---
+
+# Unreleased
+
+<!--
+  Optional narrative intro — 1-3 sentences framing the release theme. Delete if not needed.
+
+  Linking issues/PRs: use full URLs so the link works everywhere (GitHub web UI,
+  npm/node_modules reads, local editors). GitHub's bare `#NN` auto-link only
+  resolves inside its own UI.
+
+    [#12](https://github.com/<owner>/<repo>/issues/12)   ← issue
+    [#17](https://github.com/<owner>/<repo>/pull/17)     ← PR
+
+  Only link numbers you've verified exist (via `gh issue view NN` or
+  `gh pr view NN`). Never speculate on a future number — `#17` for "my
+  upcoming PR" will quietly resolve to whatever real item already owns 17,
+  and GitHub timeline previews will pull in that unrelated item's title.
+-->
+
+## Added
+
+-
+
+## Changed
+
+-
+
+## Fixed
+
+-

package/templates/package.json

@@ -9,6 +9,7 @@
     "{{PACKAGE_NAME}}": "dist/index.js"
   },
   "files": [
+    "changelog/",
     "dist/",
     "README.md",
     "LICENSE",
@@ -25,6 +26,8 @@
     "tree": "tsx scripts/tree.ts",
     "format": "biome check --write --unsafe .",
     "lint:mcp": "tsx scripts/lint-mcp.ts",
+    "changelog:build": "tsx scripts/build-changelog.ts",
+    "changelog:check": "tsx scripts/build-changelog.ts --check",
     "test": "vitest run",
     "dev:stdio": "MCP_TRANSPORT_TYPE=stdio tsx --watch src/index.ts",
     "dev:http": "MCP_TRANSPORT_TYPE=http tsx --watch src/index.ts",