@cyanheads/mcp-ts-core 0.6.16 → 0.7.0

package/dist/utils/internal/error-handler/mappings.js

@@ -86,6 +86,7 @@ export const ERROR_TYPE_MAPPINGS = {
     URIError: JsonRpcErrorCode.ValidationError,
     EvalError: JsonRpcErrorCode.InternalError,
     AggregateError: JsonRpcErrorCode.InternalError,
+    ZodError: JsonRpcErrorCode.ValidationError,
 };
 /**
  * Common error patterns for classifying errors by message/name.

package/dist/utils/internal/error-handler/mappings.js.map

@@ -1 +1 @@
-{"version":3,"file":"mappings.js","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/mappings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mappings.js","sourceRoot":"","sources":["../../../../src/utils/internal/error-handler/mappings.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.6.16",
+  "version": "0.7.0",
   "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",
@@ -263,7 +263,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/api": "^1.9.1",
     "dotenv": "^17.4.2",
-    "hono": "^4.12.14",
+    "hono": "^4.12.15",
     "jose": "^6.2.2",
     "pino": "^10.3.1",
     "zod": "^4.3.6"

package/scripts/build-changelog.ts

@@ -27,7 +27,7 @@
  * @module scripts/build-changelog
  */
 
-import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import process from 'node:process';
 
@@ -194,6 +194,12 @@ function reportMissingSummaries(missing: string[]): void {
 
 function main(): void {
   const checkOnly = process.argv.includes('--check');
+
+  if (!existsSync(CHANGELOG_DIR)) {
+    console.log(`Skipped: ${CHANGELOG_DIR} does not exist (single-file CHANGELOG.md project).`);
+    process.exit(0);
+  }
+
   const { content: generated, missingSummary } = buildRollup();
 
   if (checkOnly) {

package/scripts/devcheck.ts

@@ -453,11 +453,10 @@ const ALL_CHECKS: Check[] = [
     flag: '--no-changelog-sync',
     canFix: false,
     // --check exits non-zero if CHANGELOG.md drifts from changelog/*.md.
-    // Skipped cleanly when neither CHANGELOG.md nor changelog/ exists (non-mcp-ts-core projects).
+    // Skipped cleanly when the directory-based changelog isn't in use — CHANGELOG.md
+    // alone is a supported configuration (runtime-only consumers, opt-out per #41).
     getCommand: () => {
-      const hasChangelog = existsSync(path.join(ROOT_DIR, 'changelog'));
-      const hasRollup = existsSync(path.join(ROOT_DIR, 'CHANGELOG.md'));
-      if (!hasChangelog && !hasRollup) return null;
+      if (!existsSync(path.join(ROOT_DIR, 'changelog'))) return null;
       return ['bun', 'run', 'scripts/build-changelog.ts', '--check'];
     },
     tip: (c) =>

package/skills/api-linter/SKILL.md

@@ -4,7 +4,7 @@ description: >
   MCP definition linter rules reference. Use when `bun run lint:mcp`, `bun run devcheck`, or `createApp()` startup reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: reference
 ---
@@ -134,7 +134,18 @@ input: z.object({ items: z.array(z.string()).describe('List of items') })
 
 Every field in `input`, `output`, `params`, or `args` needs a `.describe('...')` call. Descriptions ship to the client and the LLM — missing ones make tools harder to use correctly.
 
-**Fix:** add `.describe('...')` to every leaf. The linter reports which path is missing a description (e.g., `input.filters.status`), so it's a mechanical fix.
+**Fix:** add `.describe('...')` to the paths the linter flags. The diagnostic names which path is missing a description (e.g., `input.filters.status`).
+
+**Recursion rules** — the linter walks selectively; primitive array elements are intentionally skipped. Knowing what's walked prevents over-application of describes that end up as noise in the generated JSON Schema.
+
+| Schema position | Walked? | Describe required on inner? |
+|:---|:---|:---|
+| `z.object({ ... })` field | Yes | Yes, on each field |
+| `z.array(compound)` element — object, array, or union | Yes | Yes, on the element |
+| `z.array(primitive)` element — string, number, enum, regex-branded primitive, etc. | **No** | No — outer array describe is sufficient |
+| `z.union([a, b, ...])` option | Yes (every option) | Yes, on each option |
+
+The asymmetry that catches agents: inside `z.union([z.string(), z.array(z.string())])`, the outer `z.string()` option **does** need a describe (unions walk every option), but the `z.string()` inside the inner array does **not** (arrays don't walk primitive elements). If the linter didn't flag a path, don't add a describe there — the redundant describe ships to the JSON Schema as clutter.
 
 ### schema-serializable
 

package/skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: workflow
 ---
@@ -77,7 +77,7 @@ Cross-reference each finding against the server's code. Collect adoption opportu
 
 **Template review.** The framework also ships `templates/CLAUDE.md` and `templates/AGENTS.md` as scaffolding for consumer agent protocol files. The consumer's `CLAUDE.md`/`AGENTS.md` was copied at init time and has since diverged (local customizations, echo replacements, server-specific sections). Read the upstream template fresh at `node_modules/@cyanheads/mcp-ts-core/templates/CLAUDE.md`.
 
-Skip the mechanical diff — consumer customizations create too much noise to filter. Instead, read end-to-end with fresh eyes, mentally comparing against the current `CLAUDE.md`. Look for: new conventions, updated skill references, expanded checklists, new callouts, clearer explanations, restructured sections. Present findings; let the user cherry-pick what to adopt. Never auto-merge — the consumer's file is theirs.
+Read the upstream template end-to-end, mentally comparing against the current `CLAUDE.md`/`AGENTS.md`. Apply framework-authored updates directly — new skill references in the skills table, new entries in the "What's Next?" section, updated convention callouts, clarified patterns. These are factual updates, not taste decisions; the consumer's agent protocol file is meant to track the framework's. Only surface a decision when a template change conflicts with a section the consumer has intentionally customized (server-specific domain context, bespoke checklists, etc.) — in that case, note the conflict and ask.
 
 ### 5. Sync project skills and scripts
 
@@ -140,14 +140,25 @@ If the consumer customized a framework script, the overwrite discards those chan
 
 ### 6. Adopt changes in the codebase
 
-Apply the findings from Steps 3 and 4:
+Apply the findings from Steps 3 and 4. Framework changes and third-party library changes have different adoption defaults — the asymmetry is deliberate.
 
-- **Breaking changes** — fix call sites
-- **Deprecations** — migrate now, while context is fresh
-- **New framework features** — refactor targeted spots only; don't cargo-cult everywhere
-- **New configuration** — update `.env.example`, server config schema, README if user-facing
+**Framework changes (`@cyanheads/mcp-ts-core`) — default adopt.**
 
-Keep diffs focused. Don't sweep refactors beyond the update's scope.
+The consumer opted into the framework; its templates, skills, scripts, linter rules, and conventions are authoritative. Adopt directly unless the change genuinely conflicts with a documented local override.
+
+- **Breaking changes** — fix call sites. Not optional.
+- **Deprecations** — migrate now, while context is fresh.
+- **New linter rules** — if the rule now flags existing code, fix the code; don't silence the rule.
+- **New utilities that supersede local code** — swap them in. The point of the framework is to centralize.
+- **New conventions** (template changes, new config keys, renamed env vars) — adopt and update `.env.example`, server config schema, `server.json`, and README if user-facing.
+- **New framework features that don't match existing use cases** — skip; those are for future features, not retroactive refactors.
+
+**Third-party library changes — default cost/benefit.**
+
+- Read the changelog findings from Step 3, assess impact against actual call sites in `src/`.
+- Adopt when the change is a clear win (performance, correctness, removed deprecation warning, smaller surface).
+- Skip when marginal — a new convenience API isn't a reason to touch working code.
+- If the library added a feature the server could use, note it but don't refactor speculatively.
 
 ### 7. Rebuild and verify
 
@@ -171,7 +182,7 @@ Present a concise numbered summary to the user:
 2. **Breaking changes handled** — call sites fixed
 3. **Features adopted** — new framework APIs now in use
 4. **Skills synced** — added/updated with versions (Phase A) and agent directories refreshed (Phase B)
-5. **Needs attention** — anything deferred, flagged for decision, or risky
+5. **Open decisions** — genuinely ambiguous items: breaking changes with multiple migration paths, framework changes that conflict with a documented local override, third-party adoptions where the cost/benefit is close
 6. **Status** — rebuild / devcheck / test results
 
 ## Checklist

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. Halts and alerts the user on the first failure.
+  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.
 metadata:
   author: cyanheads
-  version: "2.0"
+  version: "2.1"
   audience: external
   type: workflow
 ---
@@ -26,13 +26,37 @@ If any are missing, halt and tell the user to finish wrapup first. Do not attemp
 
 ## Failure Protocol
 
-**Stop on the first non-zero exit.** No retries, no remediation from inside the skill. Report to the user:
+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.
+
+### Retry on transient patterns
+
+Match stderr (case-insensitive) against any of these — if matched, the failure is almost always a network blip; retry:
+
+- `integrity check failed` / `IntegrityCheckFailed` — corrupt tarball during download
+- `ECONNRESET` / `EAI_AGAIN` / `ETIMEDOUT` / `ENOTFOUND` — network layer
+- `connection reset` / `connection refused` — transport blip
+- `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.
+
+### Never retry on idempotent-success signals
+
+These mean the step already succeeded on a prior run — treat as success and proceed to the next step:
+
+- npm (`bun publish`): `version already exists`, `You cannot publish over the previously published versions`
+- MCP Registry (`mcp-publisher publish`): `cannot publish duplicate version`
+
+### Halt fallback
+
+If retries are exhausted, or the failure matches none of the transient patterns, halt and report:
 
 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
+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
 
-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.
+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.
 
 ## Steps
 

package/skills/report-issue-framework/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: workflow
 ---
@@ -69,6 +69,7 @@ Structure the `--body` to match the template's form fields:
 gh issue create -R cyanheads/mcp-ts-core \
   --title "bug(scope): concise description" \
   --label "bug" \
+  --assignee "@me" \
   --body "$(cat <<'ISSUE'
 ### mcp-ts-core version
 
@@ -153,15 +154,26 @@ Format: `bug(<scope>): concise description`
 
 ### Labels
 
+Every issue needs exactly one primary label. Stack secondary labels on top when applicable.
+
+**Primary (required — pick one):**
+
 | Label | When |
 |:------|:-----|
 | `bug` | Something broken |
-| `regression` | Worked before, broken after update |
-| `types` | TypeScript type issue |
-| `docs` | Documentation is wrong or misleading |
-| `enhancement` | Feature request or improvement (not a bug) |
+| `enhancement` | Feature request or improvement |
+| `documentation` | Documentation is wrong, missing, or misleading |
+
+**Secondary (optional — stack on top of primary):**
+
+| Label | When |
+|:------|:-----|
+| `regression` | Worked before, broken after an update |
+| `performance` | Memory, CPU, latency, or resource usage |
+| `security` | Vulnerability, CVE, or hardening work |
+| `breaking-change` | Fix/feature will break public API; requires a major bump |
 
-Combine labels: `--label "bug" --label "types"`.
+Combine labels: `--label "bug" --label "regression"`.
 
 ### Attaching logs or stack traces
 
@@ -174,6 +186,7 @@ bun run dev:stdio 2>&1 | head -100 > /tmp/mcp-error.log
 gh issue create -R cyanheads/mcp-ts-core \
   --title "bug(transport): stdio crashes on large payload" \
   --label "bug" \
+  --assignee "@me" \
   --body-file /tmp/mcp-error.log
 
 # Or as a comment on an existing issue
@@ -196,6 +209,7 @@ Template below demonstrates the richer structure. Omit sections you don't need
 gh issue create -R cyanheads/mcp-ts-core \
   --title "feat(scope): concise description" \
   --label "enhancement" \
+  --assignee "@me" \
   --body "$(cat <<'ISSUE'
 Concrete statement of what's currently missing or broken in the framework. Name the specific builder, utility, context method, or config field. Two or three sentences — the reader should know the gap before the end of the paragraph.
 

package/skills/report-issue-local/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: workflow
 ---
@@ -78,6 +78,7 @@ Structure the `--body` to match the template's form fields:
 gh issue create \
   --title "bug(tool_name): concise description" \
   --label "bug" \
+  --assignee "@me" \
   --body "$(cat <<'ISSUE'
 ### Server version
 
@@ -139,16 +140,36 @@ Examples:
 
 ### Labels
 
+Every issue needs exactly one primary label. Stack secondary labels on top when applicable.
+
+**Primary (required — pick one):**
+
 | Label | When |
 |:------|:-----|
 | `bug` | Something broken |
 | `enhancement` | New feature or improvement |
-| `docs` | Documentation issue |
-| `config` | Configuration or environment issue |
+| `documentation` | Documentation is wrong, missing, or misleading |
+
+**Secondary (optional — stack on top of primary):**
+
+| Label | When |
+|:------|:-----|
 | `regression` | Worked before, broken after a change |
+| `performance` | Memory, CPU, latency, or resource usage |
+| `security` | Vulnerability, CVE, or hardening work |
+| `breaking-change` | Change will break public API; requires a major bump |
 
 Combine labels: `--label "bug" --label "regression"`.
 
+Secondary labels are not GitHub defaults — if `gh issue create --label "regression"` fails with `label not found`, create it once:
+
+```bash
+gh label create regression --color e99695 --description "Worked before, broken after a change"
+gh label create performance --color 5319e7 --description "Memory, CPU, latency, or resource usage"
+gh label create security --color b60205 --description "Vulnerability, CVE, or hardening work"
+gh label create breaking-change --color d93f0b --description "Change will break public API; requires a major bump"
+```
+
 ### Attaching logs or large output
 
 ```bash
@@ -158,6 +179,7 @@ bun run dev:stdio 2>&1 | head -200 > /tmp/server-error.log
 gh issue create \
   --title "bug(ingest): crashes on large payload" \
   --label "bug" \
+  --assignee "@me" \
   --body-file /tmp/server-error.log
 
 # Or as a comment on an existing issue
@@ -180,6 +202,7 @@ Template below demonstrates the richer structure. Omit sections you don't need
 gh issue create \
   --title "feat(scope): concise description" \
   --label "enhancement" \
+  --assignee "@me" \
   --body "$(cat <<'ISSUE'
 Concrete statement of what's currently missing or broken. Name the specific tool, service, resource, or domain area. Two or three sentences — the reader should know the gap before the end of the paragraph.
 

package/templates/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,12 +1,21 @@
 name: Bug Report
 description: Report a bug in {{PACKAGE_NAME}}
 labels: ["bug"]
+# assignees: ["your-github-username"]  # uncomment to auto-assign new issues
 body:
   - type: markdown
     attributes:
       value: |
         **Do not include secrets, credentials, API keys, or tokens.** Redact sensitive values from env vars, headers, and logs before submitting. GitHub issues are public.
 
+        **Secondary labels.** `bug` is applied automatically — also add one or more of the following in the sidebar if they apply:
+        - `regression` — worked before, broken after a change
+        - `performance` — memory, CPU, latency, or resource usage
+        - `security` — vulnerability, CVE, or hardening work
+        - `breaking-change` — fix will break public API
+
+        If a label doesn't exist in this repo yet, create it once: `gh label create <name>`.
+
   - type: input
     id: version
     attributes:

package/templates/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,7 +1,18 @@
 name: Feature Request
 description: Suggest a new feature or improvement for {{PACKAGE_NAME}}
 labels: ["enhancement"]
+# assignees: ["your-github-username"]  # uncomment to auto-assign new issues
 body:
+  - type: markdown
+    attributes:
+      value: |
+        **Secondary labels.** `enhancement` is applied automatically — also add one or more of the following in the sidebar if they apply:
+        - `performance` — improves memory, CPU, latency, or resource usage
+        - `security` — hardens the security posture
+        - `breaking-change` — will break public API; requires a major bump
+
+        If a label doesn't exist in this repo yet, create it once: `gh label create <name>`.
+
   - type: textarea
     id: use-case
     attributes: