@cyanheads/mcp-ts-core 0.6.8 → 0.6.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -146,7 +146,7 @@
     "audit:fix": "bun audit --fix",
     "changelog:build": "bun run scripts/build-changelog.ts",
     "changelog:check": "bun run scripts/build-changelog.ts --check",
-    "publish-mcp": "bunx mcp-publisher publish"
+    "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish"
   },
   "resolutions": {
     "brace-expansion": "1.1.14",
@@ -160,7 +160,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.12",
-    "@cloudflare/workers-types": "^4.20260422.1",
+    "@cloudflare/workers-types": "^4.20260423.1",
     "@hono/otel": "^1.1.1",
     "@opentelemetry/instrumentation-http": "^0.215.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.215.0",
@@ -171,7 +171,7 @@
     "@opentelemetry/sdk-node": "^0.215.0",
     "@opentelemetry/sdk-trace-node": "^2.7.0",
     "@opentelemetry/semantic-conventions": "^1.40.0",
-    "@supabase/supabase-js": "^2.104.0",
+    "@supabase/supabase-js": "^2.104.1",
     "@types/bun": "^1.3.13",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.6.0",
@@ -202,7 +202,7 @@
     "typescript": "^6.0.3",
     "unpdf": "^1.6.0",
     "validator": "^13.15.35",
-    "vite": "8.0.9",
+    "vite": "8.0.10",
     "vitest": "^4.1.5"
   },
   "keywords": [

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

@@ -7,7 +7,7 @@ Fields that may still be empty or generic from scaffolding. Check each one and f
 | Field | Default / Scaffolded | What It Should Be |
 |:------|:---------------------|:------------------|
 | `name` | `{{PACKAGE_NAME}}` (substituted by init) | Verify it's correct. Use scoped name if publishing (`@org/my-server`). |
-| `version` | `0.1.0` | Keep for initial development. Bump via the `release` skill. |
+| `version` | `0.1.0` | Keep for initial development. Bump via the `release-and-publish` skill. |
 | `mcpName` | _(often missing)_ | Reverse-domain identifier: `"io.github.{owner}/{repo}"`. Used in `server.json` `name` field and Dockerfile OCI labels. |
 | `description` | `""` (empty) | One sentence: what the server does and what it wraps. Appears on npm and in `npm search`. |
 | `repository` | _(often missing)_ | `{ "type": "git", "url": "git+https://github.com/org/repo.git" }` |

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

@@ -0,0 +1,150 @@
+---
+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. Halts and alerts the user on the first failure.
+metadata:
+  author: cyanheads
+  version: "2.0"
+  audience: external
+  type: workflow
+---
+
+## Preconditions
+
+This skill runs **after** git wrapup. By the time it's invoked:
+
+- `package.json` version is bumped
+- `changelog/<major.minor>.x/<version>.md` is authored
+- `CHANGELOG.md` is regenerated
+- README and every version-bearing file is in sync
+- Release commit (`chore: release v<version>`) exists
+- Annotated tag (`v<version>`) exists locally
+- Working tree is clean
+
+If any are missing, halt and tell the user to finish wrapup first. Do not attempt to redo wrapup work from inside this skill.
+
+## Failure Protocol
+
+**Stop on the first non-zero exit.** No retries, no remediation from inside the skill. Report to the user:
+
+1. Which step failed
+2. The exact error output
+3. Which destinations already received the release (npm published? tag pushed? etc.) so they know the partial state
+
+The user fixes locally and re-invokes, or runs the remaining steps manually. Publishes hard-fail with "version already exists" if replayed — that's the signal the step already succeeded.
+
+## Steps
+
+### 1. Sanity-check wrapup outputs
+
+Read `package.json` → capture `version`. Then verify:
+
+```bash
+git status --porcelain          # must be empty — clean working tree
+git describe --exact-match --tags HEAD 2>&1   # must equal v<version>
+git rev-parse --abbrev-ref HEAD  # note the branch name for step 3
+```
+
+If working tree is dirty or HEAD isn't on `v<version>`, halt.
+
+### 2. Run the verification gate
+
+All three must succeed. Use `test:all` if the script exists in `package.json`, otherwise fall back to `test`:
+
+```bash
+bun run devcheck
+bun run rebuild
+bun run test:all        # or `bun run test` if no test:all
+```
+
+Any non-zero exit → halt with the failing command's output.
+
+### 3. Push to origin
+
+```bash
+git push
+git push --tags
+```
+
+If the remote rejects either push, halt.
+
+### 4. Publish to npm
+
+```bash
+bun publish --access public
+```
+
+`bun publish` uses whatever npm auth the user has configured in `~/.npmrc`. If 2FA is enabled on the npm account, the command will prompt for an OTP or open a browser — that's expected; the user completes it interactively.
+
+**Friction reducers (optional, configure once):**
+
+| Option | How |
+|:--|:--|
+| **npm granular access token** with "Bypass 2FA for publish" | Generate at npmjs.com → replace `_authToken` in `~/.npmrc` → no OTP prompt at all |
+| **1Password CLI TOTP injection** (requires `brew install --cask 1password-cli` + signed-in `op`) | `bun publish --access public --otp="$(op item get 'npm' --otp)"` |
+
+Halt on publish error other than "version already exists" (which means this step already ran).
+
+### 5. Publish to MCP Registry
+
+Only if `server.json` exists at the repo root (otherwise skip).
+
+```bash
+bun run publish-mcp
+```
+
+If `publish-mcp` isn't defined in `package.json`, add it (macOS):
+
+```json
+"publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish"
+```
+
+Prereq: a GitHub PAT with `read:org` + `read:user` scopes stored in Keychain under the service name `mcp-publisher-github-pat`:
+
+```bash
+security add-generic-password -a "$USER" -s mcp-publisher-github-pat -w
+# paste PAT at the silent prompt
+```
+
+Halt on any publisher error other than "cannot publish duplicate version".
+
+### 6. Publish Docker image
+
+Only if `Dockerfile` exists at the repo root (otherwise skip).
+
+Derive:
+
+- `OWNER/REPO` from `git remote get-url origin` (strip `.git`, handle both `https://github.com/<owner>/<repo>` and `git@github.com:<owner>/<repo>` forms)
+- `VERSION` from `package.json` (step 1)
+
+```bash
+docker buildx build --platform linux/amd64,linux/arm64 \
+  -t ghcr.io/<OWNER>/<REPO>:<VERSION> \
+  -t ghcr.io/<OWNER>/<REPO>:latest \
+  --push .
+```
+
+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
+
+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>`
+- GHCR: `ghcr.io/<OWNER>/<REPO>:<VERSION>`
+
+Skip any destination that was skipped in its step.
+
+## Checklist
+
+- [ ] Working tree clean; HEAD tagged `v<version>`
+- [ ] `bun run devcheck` passes
+- [ ] `bun run rebuild` succeeds
+- [ ] `bun run test:all` (or `test`) passes
+- [ ] `git push` succeeds
+- [ ] `git push --tags` succeeds
+- [ ] `bun publish --access public` succeeds
+- [ ] `bun run publish-mcp` succeeds (if `server.json` present)
+- [ ] Docker buildx multi-arch push succeeds (if `Dockerfile` present)
+- [ ] Deployed artifact URLs reported to the user

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/dist/mcp-server/transports/http/landing-page.d.ts

@@ -1,48 +0,0 @@
-/**
- * @fileoverview HTML landing page served at `GET /`. Self-contained,
- * zero-dependency renderer producing a branded, a11y-conscious,
- * `prefers-color-scheme`-aware page from the shared `ServerManifest`.
- *
- * The page is the human-facing sibling of `/mcp` (bespoke JSON) and
- * `/.well-known/mcp.json` (SEP-1649 Server Card). Framework owns the design
- * system; servers supply content through `LandingConfig`.
- *
- * ## Surfaces
- *
- * - Hero — eyebrow, display-size server name, version + pre-release chips,
- *   tagline, single-line status strip, terminal-chrome connection card,
- *   framework attribution pill
- * - Tools section — responsive 2-column card grid; prefix-grouped; per-card
- *   annotation chips, invocation snippet, view-source link, schema preview
- * - Resources section — URI template, mime type, description, view-source link
- * - Prompts section — args list, view-source link
- * - Extensions section — rendered when SEP-2133 extensions are present
- * - Footer — single-row, dim, separator-dot delimited
- *
- * @module src/mcp-server/transports/http/landing-page
- */
-import type { Context } from 'hono';
-import type { ServerManifest } from '../../../core/serverManifest.js';
-/**
- * Render the full landing page. `baseUrl` is the request origin
- * (e.g. `https://pubmed.example.com`) — used in connect snippets and OG meta.
- * `degraded` reduces the body when `requireAuth` gates unauth callers.
- */
-export declare function renderLandingPage(manifest: ServerManifest, baseUrl: string, degraded?: boolean): string;
-/**
- * Factory for the `GET /` route handler.
- *
- * Cache behavior and body shape depend on `manifest.landing.requireAuth`:
- *
- * | `requireAuth` | Authenticated | Unauthenticated |
- * |:---|:---|:---|
- * | `false` (default) | full page · `Cache-Control: public, max-age=60` | full page · same |
- * | `true` | full page · `Cache-Control: private, max-age=60` · `Vary: Authorization` | reduced hero-only page · same cache headers |
- *
- * The check is header-presence based — we don't validate the bearer token
- * here (that's the MCP endpoint's job). If a caller presents any Authorization
- * header, the full inventory renders; if not, they see a stub and a pointer
- * to the docs link when available.
- */
-export declare function createLandingPageHandler(manifest: ServerManifest): (c: Context) => Response;
-//# sourceMappingURL=landing-page.d.ts.map

package/dist/mcp-server/transports/http/landing-page.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"landing-page.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/http/landing-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAKV,cAAc,EACf,MAAM,0BAA0B,CAAC;AAwlDlC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,MAAM,EACf,QAAQ,UAAQ,GACf,MAAM,CAmCR;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,cAAc,IACvD,GAAG,OAAO,KAAG,QAAQ,CA+B9B"}