@cyanheads/mcp-ts-core 0.9.0 → 0.9.2

package/skills/polish-docs-meta/references/server-json.md

@@ -20,7 +20,7 @@ The manifest uses the official MCP schema. A typical server has two package entr
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.org-name/my-mcp-server",
-  "description": "MCP server for the Acme API — project management and task tracking.",
+  "description": "Search projects, manage tasks, track teams.",
   "repository": {
     "url": "https://github.com/org-name/my-mcp-server",
     "source": "github"
@@ -126,7 +126,7 @@ The manifest uses the official MCP schema. A typical server has two package entr
 |:------|:---------|:------------|
 | `$schema` | Yes | Always `"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json"` |
 | `name` | Yes | Reverse-domain identifier: `io.github.{owner}/{repo}`. Matches `mcpName` in `package.json`. |
-| `description` | Yes | One-line description of the server. |
+| `description` | Yes | One-line description of the server. **Action-first** — lead with the actions/workflows (e.g., `"Search projects, manage tasks, track teams."`), not `"MCP server for …"`. Drop the `via MCP. STDIO …` suffix that the `package.json` description carries — registry context already implies MCP. |
 | `repository` | No | `{ "url": "https://github.com/...", "source": "github" }` |
 | `version` | Yes | Semver version. Must match `package.json` version. |
 | `packages` | Yes | Array of package entries — one per transport/runtime combo. |

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

@@ -1,10 +1,10 @@
 ---
 name: release-and-publish
 description: >
-  Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GHCR). Runs the final verification gate, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit, annotated tag) is already complete — this skill is the post-wrapup publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
+  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, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit, annotated tag) is already complete — this skill is the post-wrapup 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.2"
+  version: "2.4"
   audience: external
   type: workflow
 ---
@@ -26,7 +26,7 @@ If any are missing, halt and tell the user to finish wrapup first. Do not attemp
 
 ## Failure Protocol
 
-Steps 3–6 are network-bound. For those, **retry transient failures up to 2 times** with short backoff (~5 s before the first retry, ~15 s before the second) before halting. All other steps halt on the first non-zero exit — they're deterministic and a second attempt won't change the outcome.
+Steps 3–7 are network-bound. For those, **retry transient failures up to 2 times** with short backoff (~5 s before the first retry, ~15 s before the second) before halting. All other steps halt on the first non-zero exit — they're deterministic and a second attempt won't change the outcome.
 
 ### Retry on transient patterns
 
@@ -38,7 +38,7 @@ Match stderr (case-insensitive) against any of these — if matched, the failure
 - `timed out` / `request timeout` — server or network timeout
 - HTTP `502` / `503` / `504` — transient registry error
 
-**Before retrying `docker buildx --push` (step 6)**, run `docker builder prune -f` to drop any cached corrupt layer. Skip this extra step for other retries.
+**Before retrying `docker buildx --push` (step 7)**, run `docker builder prune -f` to drop any cached corrupt layer. Skip this extra step for other retries.
 
 ### Never retry on idempotent-success signals
 
@@ -46,6 +46,7 @@ These mean the step already succeeded on a prior run — treat as success and pr
 
 - npm (`bun publish`): `version already exists`, `You cannot publish over the previously published versions`
 - MCP Registry (`mcp-publisher publish`): `cannot publish duplicate version`
+- GitHub Release (`gh release create`): `release already exists` — fall back to `gh release upload --clobber` (see step 6)
 
 ### Halt fallback
 
@@ -54,7 +55,7 @@ If retries are exhausted, or the failure matches none of the transient patterns,
 1. Which step failed
 2. The exact error output
 3. Retry count attempted (0 for terminal errors, 2 for exhausted retries)
-4. Which destinations already received the release (npm published? tag pushed? MCP Registry? GHCR?) — the partial state across destinations
+4. Which destinations already received the release (npm published? tag pushed? MCP Registry? GitHub Release with `.mcpb`? GHCR?) — the partial state across destinations
 
 The user fixes locally and re-invokes. On re-invocation, already-published destinations hit the idempotent-success signal and skip naturally — no manual step-skipping required.
 
@@ -126,7 +127,35 @@ security add-generic-password -a "$USER" -s mcp-publisher-github-pat -w
 
 Halt on any publisher error other than "cannot publish duplicate version".
 
-### 6. Publish Docker image
+### 6. Attach MCPB bundle to GitHub Release
+
+Only if `manifest.json` exists at the repo root (otherwise skip).
+
+Build the bundle, then create a Release on the existing annotated tag and attach the `.mcpb`. The Release sits on top of the tag from wrapup — `--verify-tag` enforces that the tag already exists on the remote and prevents `gh` from creating a lightweight tag that would shadow the annotated one. `--notes-from-tag` pulls release notes directly from the annotated tag message (no duplication).
+
+```bash
+bun run bundle              # produces dist/<name>.mcpb (stable filename, no version)
+gh release create v<VERSION> --verify-tag --notes-from-tag dist/*.mcpb
+```
+
+The stable filename matters: it lets the README "Install in Claude Desktop" badge point at `releases/latest/download/<name>.mcpb` and always resolve to the most recent release. The `bundle` script in the templates outputs `dist/{{PACKAGE_NAME}}.mcpb` for this reason.
+
+If the release already exists (re-invocation after a prior partial run), `gh release create` exits with "release already exists" — fall back to uploading the asset to the existing release:
+
+```bash
+gh release upload v<VERSION> dist/*.mcpb --clobber
+```
+
+Deterministic download URLs:
+
+- Pinned to this version: `https://github.com/<OWNER>/<REPO>/releases/download/v<VERSION>/<name>.mcpb`
+- Always latest (powers the install badge): `https://github.com/<OWNER>/<REPO>/releases/latest/download/<name>.mcpb`
+
+If `server.json` includes an MCPB `packages[]` entry, its `identifier` should match this URL and `fileSha256` should match `shasum -a 256 <bundle>` — keep these in sync during wrapup, not here.
+
+Halt on any error other than "release already exists" (handled via the upload fallback above).
+
+### 7. Publish Docker image
 
 Only if `Dockerfile` exists at the repo root (otherwise skip).
 
@@ -144,12 +173,13 @@ docker buildx build --platform linux/amd64,linux/arm64 \
 
 If the project uses a non-GHCR registry or a custom image name, respect the project's convention. Halt on build or push failure.
 
-### 7. Report the deployed artifacts
+### 8. Report the deployed artifacts
 
 Print clickable URLs for every destination that succeeded:
 
 - npm: `https://www.npmjs.com/package/<package.json#name>/v/<version>`
 - MCP Registry: `https://registry.modelcontextprotocol.io/v0/servers?search=<package.json#mcpName>`
+- GitHub Release: `https://github.com/<OWNER>/<REPO>/releases/tag/v<VERSION>` (with `.mcpb` asset attached)
 - GHCR: `ghcr.io/<OWNER>/<REPO>:<VERSION>`
 
 Skip any destination that was skipped in its step.
@@ -164,5 +194,6 @@ Skip any destination that was skipped in its step.
 - [ ] Tags pushed to origin
 - [ ] `bun publish --access public` succeeds
 - [ ] `bun run publish-mcp` succeeds (if `server.json` present)
+- [ ] `bun run bundle` + `gh release create --verify-tag --notes-from-tag` succeeds (if `manifest.json` present)
 - [ ] Docker buildx multi-arch push succeeds (if `Dockerfile` present)
 - [ ] Deployed artifact URLs reported to the user

package/skills/setup/SKILL.md

@@ -45,7 +45,7 @@ Dockerfile                                      # Starter multi-stage image
 .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
+scripts/                                        # build, clean, devcheck, lint-mcp, list-skills, build-changelog, tree, check-docs-sync
 skills/                                         # External skills copied from the package (source of truth)
 src/
   index.ts                                      # createApp() entry point

package/templates/AGENTS.md

@@ -295,6 +295,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, 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 |
@@ -302,6 +303,42 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `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) |
+| `npm run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+
+---
+
+## Bundling
+
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+
+**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 `cursor://` deep link with base64 JSON config. |
+| VS Code / Insiders | Official `vscode:mcp/install?...` and `vscode-insiders:mcp/install?...` deep links with URL-encoded JSON. |
+| 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)](cursor://anysphere.cursor-deeplink/mcp/install?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)](vscode:mcp/install?<URLENCODED_JSON>)
+```
+
+Generate the encoded configs (replace `<PACKAGE_NAME>` and adjust the install command — `npx -y …` is the standard shape for an npm-published stdio server):
+
+```bash
+# Cursor: base64-encoded JSON
+echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"]}' | base64
+
+# VS Code: URL-encoded JSON
+node -p 'encodeURIComponent(JSON.stringify({name:"<PACKAGE_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"]}))'
+```
+
+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.
 
 ---
 

package/templates/CLAUDE.md

@@ -295,6 +295,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, 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 |
@@ -302,6 +303,42 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `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) |
+| `npm run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+
+---
+
+## Bundling
+
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+
+**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 `cursor://` deep link with base64 JSON config. |
+| VS Code / Insiders | Official `vscode:mcp/install?...` and `vscode-insiders:mcp/install?...` deep links with URL-encoded JSON. |
+| 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)](cursor://anysphere.cursor-deeplink/mcp/install?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)](vscode:mcp/install?<URLENCODED_JSON>)
+```
+
+Generate the encoded configs (replace `<PACKAGE_NAME>` and adjust the install command — `npx -y …` is the standard shape for an npm-published stdio server):
+
+```bash
+# Cursor: base64-encoded JSON
+echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"]}' | base64
+
+# VS Code: URL-encoded JSON
+node -p 'encodeURIComponent(JSON.stringify({name:"<PACKAGE_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"]}))'
+```
+
+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.
 
 ---
 

package/templates/_.mcpbignore

@@ -0,0 +1,13 @@
+src/
+tests/
+coverage/
+.env*
+.mcpregistry_*
+.claude/
+Dockerfile
+bun.lock
+bunfig.toml
+wrangler.toml
+biome.json
+tsconfig*.json
+vitest.config.ts

package/templates/manifest.json

@@ -0,0 +1,26 @@
+{
+  "manifest_version": "0.3",
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "description": "",
+  "author": { "name": "" },
+  "server": {
+    "type": "node",
+    "entry_point": "dist/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/dist/index.js"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_AUTH_MODE": "none",
+        "NODE_ENV": "production"
+      }
+    }
+  },
+  "compatibility": {
+    "runtimes": { "node": ">=24.0.0" }
+  },
+  "tools_generated": true,
+  "prompts_generated": true,
+  "user_config": {}
+}

package/templates/package.json

@@ -23,9 +23,13 @@
     "rebuild": "tsx scripts/clean.ts && tsx scripts/build.ts",
     "clean": "tsx scripts/clean.ts",
     "devcheck": "tsx scripts/devcheck.ts",
+    "audit:refresh": "rm -f bun.lock && bun install && bun audit",
     "tree": "tsx scripts/tree.ts",
+    "list-skills": "tsx scripts/list-skills.ts",
     "format": "biome check --write --unsafe .",
     "lint:mcp": "tsx scripts/lint-mcp.ts",
+    "lint:packaging": "tsx scripts/lint-packaging.ts",
+    "bundle": "npm run build && npx -y @anthropic-ai/mcpb pack . dist/{{PACKAGE_NAME}}.mcpb",
     "changelog:build": "tsx scripts/build-changelog.ts",
     "changelog:check": "tsx scripts/build-changelog.ts --check",
     "test": "vitest run",
@@ -52,7 +56,8 @@
   },
   "dependencies": {
     "@cyanheads/mcp-ts-core": "^{{FRAMEWORK_VERSION}}",
-    "pino-pretty": "^13.1.3"
+    "pino-pretty": "^13.1.3",
+    "zod": "{{ZOD_VERSION}}"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.7",