@cyanheads/mcp-ts-core 0.9.10 → 0.9.12

package/skills/orchestrations/workflows/fix-wrapup-release.md

@@ -0,0 +1,175 @@
+---
+name: fix-wrapup-release
+description: >
+  Workflow for landing known work (handoff document findings, tracked GH issues, observed gaps) and shipping it: fix → optional simplify and field-test verification → wrap-up → release across one or more MCP server projects. Generalizes "I have known issues to fix and ship" regardless of how the issues were surfaced. Chains the `field-test`, `report-issue-local`, `code-simplifier`, `git-wrapup`, and `release-and-publish` skills. Read `../SKILL.md` first for the universal rules and sub-agent strategy.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: workflow
+---
+
+# Fix + Wrap-up + Release Workflow
+
+Use after reading `../SKILL.md`. Use this workflow when there's a clear list of known fixes to apply and ship — sourced from a handoff document, tracked GH issues, observed gaps you've already validated, or any combination.
+
+## Trigger contexts
+
+The input varies but the workflow is the same. Read the inputs into a common shape before kicking off:
+
+| Source | Shape it as |
+|:---|:---|
+| Handoff document (numbered findings, repro steps, acceptance criteria) | Validate each finding live in Phase 1a; file each valid one as a GH issue via `report-issue-local`; skip invalidated findings |
+| GH issues already filed | Use as-is. Read each with `gh issue view N --comments` to capture the full thread (the body alone misses clarifications and decision updates) |
+| Observed gap or casual report ("I noticed this", "fix the description on tool X") | If material enough to ship in a release, file a GH issue first to capture rationale and create an audit trail. Trivial typo-fix-and-ship can skip the issue step. |
+
+The validation/filing step is the difference between "input is a hypothesis" (handoff) and "input is verified" (tracked GH issues). The rest of the workflow is identical.
+
+## When applicable
+
+- One or more existing servers have known work to land — issues, handoff findings, or specific verified bugs
+- The work is the deliverable; the workflow ends in a commit + tag and (optionally) a release
+- N = 1 (single-server handoff) and N > 1 (multi-server fix batch) both apply
+
+For unsourced QA — where the bugs are unknown until you test — use `field-test-fix.md` instead; that workflow includes the field-test discovery phase first.
+
+## Tier 1 skills referenced
+
+| Phase | Tier 1 skill(s) |
+|:---|:---|
+| Validate (handoff input only) | `skills/field-test/SKILL.md` + `skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
+| Fix | (No single skill — sub-agent reads issues, validates, fixes) |
+| Verify | `skills/field-test/SKILL.md` (live verification) + `skills/code-simplifier/SKILL.md` (optional) |
+| Wrap-up | `skills/git-wrapup/SKILL.md` |
+| Release | `skills/release-and-publish/SKILL.md` |
+
+## Pre-flight
+
+Per target:
+
+1. **Identify issues** — collect GH issue numbers to fix, the handoff document, or the explicit gap description. Read each issue with `gh issue view N --comments` to capture the full thread.
+2. **Clean working tree** — `git status --short` must be empty
+3. **Current version** — `git describe --tags --abbrev=0`, `grep '"version"' package.json`
+4. **Repo visibility** — `gh repo view --json visibility -q '.visibility'`. Determines wrap-up scope.
+5. **Build** — `bun run rebuild` per target. All must pass before Phase 1.
+
+## Phases
+
+Each phase's Objective column is the goal state per target — the verifiable end state the phase must produce.
+
+| # | Phase | Objective | Sub-agent mode |
+|:--|:---|:---|:---|
+| 1a | Validate (conditional) | Each handoff finding field-tested live; valid ones filed as GH issues; invalidated ones reported back with reason. If zero validate, workflow stops | one sub-agent per target |
+| 1b | Fix | Per target: targeted issues fixed in source, tests updated/added, `devcheck` + `rebuild` + `test` green, each fixed issue commented with fix details, working tree dirty for review | parallel fanout (one sub-agent per target — hard constraint) |
+| 2 | Verify | Per target: full diff cold-reviewed; simplified if warranted; each fix re-exercised against the running server with actual tool output in the summary | parallel fanout |
+| 3 | Wrap-up + release | Per target: fixes split into per-file commits with a release commit on top; annotated tag; published per repo visibility; tag annotation is structured markdown with issue backlinks | parallel fanout (Bash git only) |
+| 4 | Issue cleanup | Every GH issue that shipped a fix closed with "Fixed in v\<version\>" comment | orchestrator (serial) |
+
+Phase 1a is conditional — only runs when the input is a handoff document or otherwise unvalidated. When the input is already tracked GH issues, skip directly to Phase 1b. The release portion of Phase 3 is conditional on user authorization to ship.
+
+## Phase notes
+
+### Phase 1a: Validate (handoff input)
+One sub-agent per target. The sub-agent:
+1. Field-tests each handoff claim against the running server (project-specific helpers per the `field-test` skill)
+2. For validated findings, traces the relevant source to confirm shape of fix
+3. Reads `.github/ISSUE_TEMPLATE/` first to understand the repo's issue conventions
+4. Files one GH issue per validated finding using `report-issue-local` patterns
+5. Reports back: validated (with GH issue links and one-line reason), invalidated (with why), and observations not in the original handoff
+
+**Noise filter:** every filed issue must pass "Would a maintainer coming to this cold say 'yes, this needs fixing'?"
+
+**Do not file against `@cyanheads/mcp-ts-core`** unless the bug is clearly in the framework — file against the server's own repo.
+
+**Unique field-test ID** in helper file path: `/tmp/<project>-handoff-<5CHAR>.sh`.
+
+If zero findings validate, report to the user and stop the workflow.
+
+### Phase 1b: Fix
+**One sub-agent per target — hard constraint** (no file-locking; concurrent edits to the same `src/` conflict).
+
+Each sub-agent:
+1. Reads all open issues for its target via `gh issue view N --comments` (full thread — body alone misses clarifications)
+2. **Validates each issue against source code** — the issue's analysis or proposed approach may be wrong; sub-agent applies judgment about the right fix and notes any deviation in its GH comment
+3. Prioritizes: security → crashes → bugs → enhancements → docs/chore
+4. Implements fixes using the best modern approach (the GH issue is input, not a spec)
+5. Updates or adds tests as needed
+6. Exit gate: `bun run devcheck` + `bun run rebuild` + `bun run test` all pass before reporting completion
+7. Comments on each fixed GH issue with a concise fix summary (cite file paths)
+8. Leaves everything uncommitted
+
+**Constraints to restate:**
+- Surgical fixes only — don't refactor surrounding code unless the fix requires it
+- If a fix is disproportionate (major architecture change), note it on the issue and skip
+- The exit gate is non-negotiable — do not report completion if any of devcheck/rebuild/test is red
+
+### Phase 2: Verify
+Fresh sub-agent per target, reads the full `git diff` cold. Two passes:
+
+1. **Code-simplify** — read `code-simplifier`, review the diff through that lens (over-engineering, unnecessary abstractions, redundant guards, style mismatches with surrounding code). Apply cleanup if warranted; skip if changes are minimal — don't run as ceremony.
+2. **Re-field-test** — spin up the server, run the repro steps from each fixed issue, include actual tool call output in the summary. A fix that compiles but wasn't verified against a running server is not done.
+
+Exit gate: `bun run devcheck && bun run rebuild && bun run test`.
+
+### Phase 3: Wrap-up + release
+Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-publish/SKILL.md`.
+
+**Orchestrator responsibility:** before spawning Phase 3 sub-agents, collect all open GH issue numbers per target (`gh issue list -R <owner>/<repo> --state open --json number,title`) and include them in each sub-agent's prompt. Phase 3 sub-agents have no context from prior phases — they need the explicit issue list to know what to close.
+
+**Commit structure.** Fixes are NOT collapsed into a single commit:
+1. Analyze the diff — understand which fixes touch which files
+2. Group by file boundaries — fixes sharing a file ship in the same commit
+3. Commit each group: `fix(scope): description` (Conventional Commits)
+4. Release commit on top: `chore(release): v<version>` — version bump + changelog + regenerated artifacts
+5. Tag the release commit
+
+The tag annotation and changelog cover ALL fixes — the commit split is about git history, not release notes.
+
+**Version bump.** Default **patch** for bug-fix releases. **Minor** when enhancements are included.
+
+**Wrap-up scope.** Determined by repo visibility:
+
+| Status | Scope |
+|:---|:---|
+| Private / in-development | Version bump → changelog → commit → tag → mcpb bundle → push → `gh release create`. Skip `bun publish`, Docker, MCP Registry. |
+| Public / launched | Full `release-and-publish`: push + `bun publish` + `publish-mcp` + bundle + GH release + Docker (if Dockerfile). |
+
+**Tag annotations** are for end users — internal dev cleanup (lockfile refreshes, linter fixes, build config) belongs in commit bodies, not the tag annotation.
+
+### Phase 4: Issue cleanup
+Close issues that shipped fixes — only those. Skipped issues stay open.
+
+```bash
+for n in <fixed-issue-numbers>; do
+  gh issue close "$n" -R "<owner>/<repo>" --reason completed --comment "Fixed in v<version>."
+done
+```
+
+## Workflow-specific gotchas
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | Multiple fix sub-agents editing the same server's `src/` | Hard constraint: 1 sub-agent per server in Phase 1b |
+| 2 | Fix sub-agent "fixed" an issue but the change is a band-aid | Orchestrator gate after Phase 1b reviews approach, not just "does it compile" |
+| 3 | Fix sub-agent doesn't update tests for schema changes | Exit gate requires tests pass; sub-agent must update/add tests before finishing |
+| 4 | Field-test in Phase 2 fails but sub-agent reports success | Sub-agent must include actual tool call output in summary; orchestrator spot-checks |
+| 5 | Code-simplify removes intentional complexity | Orchestrator gate after Phase 2 reviews the full diff |
+| 6 | Wrap-up sub-agent collapses multi-fix diff into one commit | Phase 3 prompt enumerates the commit structure |
+| 7 | Wrap-up sub-agent makes unplanned intermediate commits outside the planned structure | Prompt defines exact commit shape; agents must not invent extras |
+| 8 | Reading `gh issue view N` alone misses thread context where decisions were updated | Always include `--comments` |
+| 9 | MCP Registry returns 502 transiently during publish | Retry up to 2x with backoff |
+| 10 | Phase 1a sub-agent validates an issue that's actually a misunderstanding | Sub-agent must field-test, not just read the claim — live verification catches false positives |
+
+## Checklist
+
+- [ ] Pre-flight: issues identified per target (or handoff captured), working trees clean, builds pass
+- [ ] Phase 1a (if handoff): findings validated live, GH issues filed for valid findings, invalidated reported back
+- [ ] Phase 1b: fix sub-agents complete — fixes implemented, tests updated, GH issues commented, exit gate green
+- [ ] Orchestrator gate after Phase 1b: diffs reviewed, devcheck + tests green
+- [ ] Phase 2: verify sub-agents complete — code-simplify (if applicable), re-field-test with actual outputs in summary
+- [ ] Orchestrator gate after Phase 2: simplified diff reviewed, field-test claims verified
+- [ ] Phase 3: version bumped, fix commits + release commit, annotated tag per target — scope matches private/public status
+- [ ] Phase 3: published per scope (push, npm if public, MCP Registry if applicable, GH release, Docker if applicable)
+- [ ] Phase 4: fixed issues closed; skipped issues remain open
+- [ ] Post-workflow verification: `git ls-remote --tags origin`, `npm view <pkg>@<version>` if public, GH release artifacts attached
+- [ ] Tag/release quality review: tag subject omits version number, structured markdown, no marketing adjectives, issue backlinks present

package/skills/orchestrations/workflows/greenfield-build.md

@@ -0,0 +1,143 @@
+---
+name: greenfield-build
+description: >
+  Workflow: scaffold one or more new MCP server projects from `bunx @cyanheads/mcp-ts-core init` through design → build → polish → first public release. Each phase invokes a foundational skill end-to-end; this file is the sequencing and gates, not the procedural detail. Read `../SKILL.md` first for the universal rules and sub-agent strategy.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: workflow
+---
+
+# Greenfield Build Workflow
+
+Use after reading `../SKILL.md`. Drives one or more freshly-scaffolded MCP servers from idea to first public release by sequencing foundational skills with gates and verification.
+
+## When applicable
+
+- One or more new servers from `bunx @cyanheads/mcp-ts-core init <name>` need to be driven through design → build → ship
+- Each target is a freshly-scaffolded project with no implementation yet (echo definitions still present)
+- N = 1 and N > 1 both apply — parallelism is the optimization; the phase structure is the value
+
+## Pre-flight
+
+1. **Target list** — absolute paths and intended GitHub owner/org per target
+2. **`gh auth status`** — Phase 1 creates GH repos
+3. **`npm whoami`** — required if Phase 18 publishes publicly
+4. **API key inventory** per target — Phase 11 (field-test loop) skips targets without keys
+5. **Gold-standard reference(s)** — repo(s) the `polish-docs-meta` phase anchors on for README/metadata style. Skip the phase if no anchor exists in the ecosystem.
+
+## Versioning strategy
+
+Everything stays at **v0.1.0** through the build. Intermediate commits don't bump versions. The launch version (typically v0.1.1) is set in Phase 17.
+
+## Tier 1 skills referenced
+
+| Phase | Tier 1 skill(s) |
+|:---|:---|
+| Scaffold (1) | `skills/setup/SKILL.md` |
+| Initial commit, design commit, build commit, pre-launch commit (2, 5, 10, 16) | `skills/git-wrapup/SKILL.md` (commit + tag, no push) |
+| Design + validation (3, 4) | `skills/design-mcp-server/SKILL.md` |
+| Build (6) | `skills/add-tool/SKILL.md`, `skills/add-app-tool/SKILL.md`, `skills/add-resource/SKILL.md`, `skills/add-prompt/SKILL.md`, `skills/add-service/SKILL.md` |
+| Tool-def audit (7) | `skills/tool-defs-analysis/SKILL.md` |
+| Test coverage (8) | `skills/add-test/SKILL.md` |
+| Field-test loop (11) | → `workflows/field-test-fix.md` as a sub-loop (see Phase 11 note) |
+| Simplify (12) | `skills/code-simplifier/SKILL.md` |
+| Polish docs/meta (13) | `skills/polish-docs-meta/SKILL.md` |
+| Security pass (14) | `skills/security-pass/SKILL.md` |
+| Final wrap-up (17) | `skills/git-wrapup/SKILL.md` |
+| Release (18) | `skills/release-and-publish/SKILL.md` |
+
+## Phases
+
+Each phase's Objective column is the goal state per target — the verifiable end state the phase must produce. Phase notes only appear for orchestration overrides; phases without notes run the foundational skill end-to-end.
+
+| # | Phase | Objective | Sub-agent mode |
+|:--|:---|:---|:---|
+| 1 | Scaffold + repo | `bunx init` scaffold complete; `--private` GH repo created; LICENSE in place; working tree dirty (no commit) | parallel fanout |
+| 2 | Initial commit | v0.1.0 commit + annotated tag + push to private GH repo | parallel fanout |
+| 3 | Design | `docs/design.md` authored with Decisions Log | parallel fanout |
+| 4 | Design validation | `docs/design.md` hardened by review pass; gate sub-agent returned PASS | two sub-agents per target |
+| 5 | Design commit | Design changes committed and pushed | parallel fanout |
+| 6 | Build | All designed tools/resources/prompts implemented; no echo definitions; `devcheck` + `test` green | parallel fanout |
+| 7 | Tool-def audit | `tool-defs-analysis` findings reviewed and applied | parallel fanout |
+| 8 | Test coverage | Tests extended beyond happy path; `devcheck` + `test` green | parallel fanout |
+| 9 | Design ↔ implementation check | Every surface element in `docs/design.md` has a definition (or `docs/design.md` updated to reflect what shipped) | parallel fanout or orchestrator-direct |
+| 10 | Build commit | Build work committed and pushed | parallel fanout |
+| 11 | Field-test loop (optional) | Live API surface exercised; valid findings filed and fixed (or skipped with note) | conditional |
+| 12 | Simplify | `code-simplifier` applied; `devcheck` + `test` green — last source-code modification | parallel fanout |
+| 13 | Polish docs/meta | README, metadata, and agent protocol aligned to gold-standard reference | parallel fanout |
+| 14 | Security pass | `security-pass` findings addressed; no open security gaps | parallel fanout |
+| 15 | Final-state check | `rebuild` + `devcheck` + `test:all` + `lint:packaging` green; LICENSE present; no unfinished TODO/FIXME | orchestrator-direct |
+| 16 | Pre-launch commit | Final polish + security work committed and pushed | parallel fanout |
+| 17 | Final wrap-up | Launch version (typically v0.1.1) commit + annotated tag in place; **not pushed** | parallel fanout (Bash git only) |
+| 18 | Release | Pushed and published per scope; tag annotation renders as structured markdown on GitHub Release; artifacts reachable | parallel fanout or serial (per npm 2FA mode) |
+
+Phase 11 is optional. Phase 12 is the last phase that modifies source code — everything after is docs/metadata/verification.
+
+## Phase notes
+
+Only phases with orchestration overrides or non-obvious instructions appear below. Other phases run their foundational skill end-to-end.
+
+### Phase 1: Scaffold + repo
+Sub-agent runs `bunx @cyanheads/mcp-ts-core init <name>`, follows the `setup` skill, then creates a **private** GitHub repo (`gh repo create --private`). Override the `setup` skill's commit step — **do NOT commit**; Phase 2 is the commit. Copy `LICENSE` from `node_modules/@cyanheads/mcp-ts-core/LICENSE` if not already present.
+
+### Phase 2: Initial commit
+Sub-agent verifies `gh repo view --json visibility` returns `PRIVATE` (or has explicit user authorization for public) before push. Tag is `v0.1.0`.
+
+### Phase 4: Design validation
+Two sub-agents per target, sequential:
+
+1. **Review** — fresh sub-agent re-runs `design-mcp-server` against the existing `docs/design.md` cold (no `docs/idea.md`, no prior context). Goal: spot what the original author justified away. Output: hardened `docs/design.md`.
+2. **Gate** — sub-agent reads ONLY the hardened design and returns **PASS** or **FAIL**. PASS means "ready to build as-is." FAIL flags structural issues that would cause wasted build effort: missing tool the API clearly supports and users would expect; wrong endpoint or data model that would fail at runtime; contradictory constraints; missing error handling strategy for common failures. **Filter style preferences and marginal scope suggestions** — those are not gate failures.
+
+If gate fails, spawn a focused fix sub-agent for that target, then re-gate.
+
+### Phase 6: Build
+Sub-agents will exhaust context on targets with 4+ tools — work persists to disk but the sub-agent can't continue. Plan a follow-up "finish" iteration as a normal backstop, not a fallback for failure. After Phase 6 lands, the orchestrator inspects each target (`bun run devcheck`, `bun run test`, `ls src/mcp-server/tools/definitions/`) and spawns a narrow-scope finish sub-agent per incomplete target with a concrete punch list: "X TS errors here, tools A/B/C missing tests, echo definitions still present in `<file>`." Narrow scope is the antidote to context exhaustion.
+
+### Phase 9: Design ↔ implementation check
+For each tool / resource / prompt named in `docs/design.md`, verify a definition file exists in `src/mcp-server/{tools,resources,prompts}/definitions/`. For missing surface, decide: implement it (spawn a narrow-scope sub-agent), drop it from the design (update `docs/design.md`), or defer to a follow-up (record in the Decisions Log). This is orchestration glue — small enough that the orchestrator can run it directly for N ≤ 3, fan out for larger N.
+
+### Phase 11: Field-test loop (optional)
+When the upstream API supports live testing and an API key is available, run the phases of `field-test-fix.md` as a sub-loop here, ending at its field-test commit. Skip with a note if blocked.
+
+### Phase 12: Simplify
+Last phase that modifies source code. Everything after is docs/metadata/verification.
+
+### Phase 15: Final-state check
+Orchestrator-direct mechanical verification per target: `bun run rebuild`, `bun run devcheck`, `bun run test:all` (or `test`), `bun run lint:packaging`. `LICENSE` present. No `TODO`/`FIXME` indicating unfinished work. `CHANGELOG.md` current. `docs/tree.md` reflects current structure. Fix anything red before Phase 16; this is verification, not a sub-agent task.
+
+### Phase 17: Final wrap-up
+Version bump intent is typically **patch** — v0.1.0 was the scaffold tag; the launch is the first real release at v0.1.1. Bash git only; **do not push** — Phase 18 owns the push.
+
+## Workflow-specific gotchas
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | `gh repo create` defaults to public if `--private` is omitted | Phase 1 prompt restates the rule; Phase 2 sub-agent re-verifies `gh repo view --json visibility` before push |
+| 2 | Build sub-agents exhaust context on targets with 4+ tools | Expected — plan a finish iteration with a concrete punch list, narrow scope |
+| 3 | Design gate sub-agents flag style preferences as failures | Gate prompt: "Do NOT flag style preferences or marginal scope suggestions — only structural issues that would cause wasted build effort" |
+| 4 | Sub-agent commits during Phase 1 despite the orchestration override | Phase 1 prompt restates: "Do NOT commit — leave working tree dirty for Phase 2" verbatim |
+
+## Checklist
+
+- [ ] Pre-flight: targets confirmed, `gh` + `npm` auth verified, gold-standard reference(s) named, API key inventory complete
+- [ ] Phase 1: scaffold + setup run, private repo created, LICENSE present, working tree dirty (no commits)
+- [ ] Phase 2: v0.1.0 commit + annotated tag + push verified per target
+- [ ] Phase 3: `docs/design.md` authored per target with Decisions Log
+- [ ] Phase 4: design hardened by review pass; gate returns PASS per target
+- [ ] Phase 5: design committed per target
+- [ ] Phase 6: build complete — all designed surface implemented, green devcheck + test
+- [ ] Phase 7: `tool-defs-analysis` audit + fixes applied
+- [ ] Phase 8: dedicated test coverage pass — beyond happy path
+- [ ] Phase 9: every designed surface element has a definition (or `docs/design.md` updated to reflect what shipped)
+- [ ] Phase 10: build committed per target
+- [ ] Phase 11 (optional): field-test loop completed or skipped with note
+- [ ] Phase 12: code-simplifier — final source-code cleanup, green devcheck + test
+- [ ] Phase 13: polish-docs-meta against named gold-standard
+- [ ] Phase 14: security-pass complete, findings addressed
+- [ ] Phase 15: final-state check — rebuild + devcheck + test:all + lint:packaging green; LICENSE; no TODO/FIXME
+- [ ] Phase 16: pre-launch commit per target
+- [ ] Phase 17: final wrap-up — version bumped, changelog authored, commit + annotated tag per target
+- [ ] Phase 18: release — published per scope, artifacts verified reachable

package/skills/orchestrations/workflows/maintenance-release.md

@@ -0,0 +1,173 @@
+---
+name: maintenance-release
+description: >
+  Workflow: run the `maintenance` skill against one or more existing MCP server projects (dependency updates, framework adoption, skill sync), verify adoption gaps in a double-check pass, then wrap up and release via `git-wrapup` and `release-and-publish`. Read `../SKILL.md` first for the universal rules and sub-agent strategy.
+metadata:
+  author: cyanheads
+  version: "1.1"
+  audience: internal
+  type: workflow
+---
+
+# Maintenance + Release Workflow
+
+Use after reading `../SKILL.md`. Drives maintenance, adoption verification, wrap-up, and release across N existing MCP server projects.
+
+## When applicable
+
+- One or more existing servers built on `@cyanheads/mcp-ts-core` need updates from `bun outdated` landed and shipped
+- N = 1 still benefits — fresh-context sub-agents per phase keep each focused and within context budget
+- Each target should have a clean working tree before the workflow starts — uncommitted work blocks the `maintenance` skill's verification gate
+
+**Scope boundary.** This workflow ships dependency, framework-adoption, and skill-sync upkeep — it does not consult, fix, or close issues in the tracker. Issue-driven work belongs to `fix-wrapup-release.md`. If a maintenance pass incidentally surfaces a genuine bug, file it (don't fix it here) and let a later `fix-wrapup-release` run address it.
+
+## Tier 1 skills referenced
+
+| Phase | Tier 1 skill(s) |
+|:---|:---|
+| Maintenance | `skills/maintenance/SKILL.md` |
+| Double-check | `skills/polish-docs-meta/SKILL.md` (the cross-file consistency reference is the most commonly missed surface) |
+| Wrap-up | `skills/git-wrapup/SKILL.md` |
+| Release | `skills/release-and-publish/SKILL.md` |
+
+## Pre-flight
+
+Per target:
+
+1. **Clean working tree** — `git status --short` must be empty. Halt if dirty; user fixes locally before re-invoking.
+2. **Latest tag and version** — `git describe --tags --abbrev=0`, `grep '"version"' package.json`
+3. **`list-skills` script presence** — `test -f scripts/list-skills.ts && grep -q '"list-skills"' package.json`. If missing, note it — the `maintenance` skill's Phase C will install it.
+4. **`publish-mcp` script** — when `server.json` exists, check `grep -q '"publish-mcp"' package.json`. If missing, flag it — the maintenance sub-agent adds it.
+5. **Publish destinations** — note which exist: `server.json` (MCP Registry), `manifest.json` (MCPB / GH Release), `Dockerfile` (GHCR). If `server.json` exists but `manifest.json` doesn't, flag — maintenance scaffolds it.
+6. **`npm whoami`** — required if releasing publicly.
+7. **Framework version delta** — `grep '"version"' node_modules/@cyanheads/mcp-ts-core/package.json` vs `npm view @cyanheads/mcp-ts-core version` to preview adoption scope.
+
+## Phases
+
+Each phase's Objective column is the goal state per target — the verifiable end state the phase must produce.
+
+| # | Phase | Objective | Sub-agent mode |
+|:--|:---|:---|:---|
+| 1 | Maintenance | Per target: deps updated, framework adoption applied, project skills synced, `rebuild` + `devcheck` + `test` green, Step 8 numbered summary returned | parallel fanout |
+| 2 | Double-check | Adoption gaps from Phase 1 fixed; `manifest.json`/`server.json` content validated; audience compliance verified; `rebuild` + `devcheck` + `test` green | parallel fanout |
+| 3 | Roll-up | Per-target headlines + cross-target patterns surfaced to user; version-bump intent confirmed (patch/minor/major) | orchestrator (serial) |
+| 4 | Wrap-up + release | Per target: version-bumped commit + annotated tag + push + publish per scope; tag annotation renders as structured markdown on GitHub Release | parallel fanout (Bash git only) |
+
+Phase 4 combines wrap-up and release in one sub-agent because the work is sequential and shares context (version, changelog, tag annotation). The sub-agent reads both Tier 1 skills.
+
+## Phase notes
+
+### Phase 1: Maintenance
+Each sub-agent runs `skills/maintenance/SKILL.md` Mode A — the full flow from `bun outdated` through verification.
+
+**Prompt phrasing matters.** Generic "run the maintenance skill" prompts cause sub-agents to stop at changelog analysis without executing. Include explicit steps in the prompt body:
+1. `bun outdated` — capture the list
+2. `bun update --latest` — apply, capturing the `↑ package old → new` lines for Step 3
+3. Invoke the `changelog` skill for each updated package (or read `node_modules/<pkg>/CHANGELOG.md` directly if the skill isn't synced yet)
+4. If `@cyanheads/mcp-ts-core` updated, do the deeper framework review per the maintenance skill's Step 4
+5. Run Step 5 skill/script sync — Phase A (package → project `skills/`), Phase B (project `skills/` → agent dirs), Phase C (package scripts + pristine references → project)
+6. Adopt changes per Step 6 — framework changes are auto-adopt at every applicable site in this pass; third-party libs are cost/benefit
+7. `bun run rebuild` → `bun run devcheck` → `bun run test`
+8. Produce the Step 8 numbered summary
+
+**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md` version is newer than the synced project copy, feature-adoption rows added in the new version don't surface. Sub-agent prompt instructs: after Phase A sync completes, re-read the synced `maintenance` SKILL.md and continue from Step 5 with the new version.
+
+**Skill audience compliance.** Only sync skills with `metadata.audience: external` into project `skills/`. Sub-agents miss this under context pressure — restate explicitly.
+
+**Constraints to restate verbatim:**
+- No commits, tags, pushes — leave working tree dirty for orchestrator review
+- Read-only git allowed and expected — `git diff skills/` after Phase A surfaces adoption signal
+- Halt and report verbatim if `bun run devcheck` can't be made green; `bun audit` failures from a transitive dep with no patch are note-not-halt
+- Output the Step 8 numbered summary at the end — the orchestrator parses it
+
+### Phase 2: Double-check
+Independent maintenance sub-agents diverge on incidental choices and miss adoption sites under context pressure. The double-check pass catches gaps before wrap-up.
+
+**Critical: these sub-agents audit AND fix, then re-verify.** Not analysis-only.
+
+Audit categories (sub-agent prompt enumerates):
+
+- **Adoption gaps** — features the updated skills say to do that weren't applied (error code semantic audit, missing scaffolding files like `manifest.json`/`.mcpbignore`, `publish-mcp` script)
+- **Audience compliance** — only skills with `metadata.audience: external` belong in project `skills/`; agents sometimes sync `internal`-audience skills
+- **Content accuracy** — `isRequired` flags in `server.json` match the upstream API's reality (does the API work without the key?); `manifest.json` `name` doesn't include the npm scope prefix; `user_config` entries have required `title` and `type` fields
+- **Cross-target consistency** — if a feature shows up in 3 of 5 Phase 1 summaries, the other 2 likely missed it
+- **Error code semantics** — `InvalidParams` only for malformed JSON-RPC params shape; `ValidationError` for domain validation; `NotFound` for missing entities
+- **Description alignment** — `package.json`, `manifest.json`, `server.json` (≤100 char), README header, GH repo description should be consistent
+- **README install badges** — Claude Desktop `.mcpb`, Cursor deeplink, VS Code deeplink — present when `manifest.json` exists
+
+Exit gate: `bun run rebuild && bun run devcheck && bun run test` after fixes.
+
+A lighter model (e.g. Sonnet-class) is appropriate here — verification + targeted fixes, not deep adoption work.
+
+### Phase 3: Roll-up
+The orchestrator collects Phase 1 + Phase 2 reports and produces:
+1. **Per-target headlines** — short table: target → packages updated → mcp-ts-core delta → devcheck/test status → gaps fixed
+2. **Cross-target patterns** — features adopted across multiple targets, breaking changes that hit a subset
+3. **Open decisions** — per-target ambiguities; group by decision so the user can rule once across multiple targets when the choice is the same
+4. **Outliers** — targets with unusually large diffs or where adoption couldn't complete cleanly
+
+**Version bump intent.** Default is **patch** unless the change shape indicates otherwise:
+
+| Bump | When |
+|:---|:---|
+| **patch** (default) | Dependency updates, framework adoption, doc polish, bug fixes — ~95% of maintenance runs |
+| **minor** | New tools/resources/prompts added, new user-facing features, new env vars that change behavior |
+| **major** | Breaking changes to the server's MCP surface (removed tools, renamed fields, changed semantics) |
+
+If a target's diff suggests minor-or-above, **pause that target and surface to the user during roll-up** — unaffected targets proceed to Phase 4 at patch.
+
+### Phase 4: Wrap-up + release
+Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-publish/SKILL.md`. Runs wrap-up (version bump, changelog authoring, commit, annotated tag), then release (push, npm publish, MCP Registry, GH release, Docker).
+
+**Framework changelog reading.** When `mcp-ts-core` was updated, the sub-agent must read the framework's changelog files for the version delta (e.g. `node_modules/@cyanheads/mcp-ts-core/changelog/0.9.x/0.9.2.md` through `0.9.6.md`) and distill user-facing changes relevant to this server into the changelog entry and tag annotation. "Picks up upstream fixes" is not acceptable — name what changed.
+
+**Wrap-up scope.** Determined by repo visibility (`gh repo view --json visibility`):
+
+| Status | Scope |
+|:---|:---|
+| Private / in-development | Version bump → changelog → commit → tag → mcpb bundle → push → `gh release create`. Skip `bun publish`, Docker, MCP Registry. |
+| Public / launched | Full `release-and-publish`: push + `bun publish` + `publish-mcp` + bundle + GH release + Docker (if Dockerfile). |
+
+**npm 2FA mode.** Parallel `bun publish` doesn't play nicely with interactive 2FA — OTP prompts from multiple sub-agents interleave. Either:
+- Bypass token configured (granular access token with "Bypass 2FA for publish") → Phase 4 runs as parallel fanout
+- No bypass → Phase 4 runs serially, orchestrator-driven, one target at a time
+- No npm publish involved (private only) → non-issue
+
+**Commit structure.** Version bump rides with the change that warrants it. For a maintenance pass with a single cohesive change shape (e.g. just dep updates, or just one framework adoption), that's **one commit** — subject can lead with the version (e.g. `feat: 0.5.2 — adopt new error factories, framework ^0.9.6`). For a maintenance pass containing multiple distinct concerns, split into per-concern commits with the version bump folded into the headline-change commit, not a separate ceremonial release commit.
+
+**Tag annotations are for end users.** Internal dev cleanup (lockfile refreshes, linter fixes, build config) belongs in the commit body, not the tag annotation.
+
+**Tag-moving protocol.** If post-version doc changes land after the version commit, move the tag to HEAD: delete remote release, delete remote + local tag, recreate tag at new HEAD with same annotation, re-push, recreate release with `.mcpb`. Authorized within the workflow — same-day forward move.
+
+### Watchtower-style container refresh (if applicable)
+For targets with hosted instances behind an auto-pull tool, trigger the refresh after GHCR images are verified reachable. This is operational, not part of the release-and-publish skill — handle in the orchestrator's post-Phase-4 step if the deployment infrastructure has it.
+
+## Workflow-specific gotchas
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | Generic "run the maintenance skill" prompts cause ~50% of sub-agents to halt at changelog analysis without executing | Include explicit execution steps in Phase 1 prompt body; respawn with directive if Step 8 summary missing |
+| 2 | Skill-version paradox — feature rows added in newer maintenance skill don't surface in the synced older copy | Sub-agent prompt: after Phase A sync, re-read synced `maintenance` SKILL.md and continue from Step 5 |
+| 3 | Per-target adoption divergence is expected — projects on different starting framework versions adopt different things | Don't try to normalize. Surface divergence as informational in Phase 3 roll-up. |
+| 4 | The `changelog` skill may not exist in a target's skill directory yet | Sub-agent falls back to direct `node_modules/<pkg>/CHANGELOG.md` reading |
+| 5 | Sub-agent runs write git commands despite instruction | Restate the no-write-git list + no-`stash` rule in prompt body; verify via `git log --oneline -1` per target after Phase 1 — should show no new commits |
+| 6 | Sub-agent syncs `internal`-audience skills into project `skills/` | Restate "Only sync skills with `metadata.audience: external`" — sub-agents miss this under context pressure |
+| 7 | `manifest.json` scaffolded with scoped name from `package.json` (e.g. `@scope/server-name`) — renders in mcpb install dialog | Phase 2 verifies `manifest.json` `name` doesn't contain `/` |
+| 8 | `manifest.json` `user_config` entries missing required `title`/`type` — `mcpb pack` fails at release time | Phase 2 verifies required fields |
+| 9 | `server.json` `isRequired` doesn't match upstream API reality | Phase 2 verifies against actual API behavior |
+| 10 | Framework version arrow in tag/changelog says nothing useful ("picks up upstream fixes") | Phase 4 prompt requires reading mcp-ts-core changelog files and distilling relevant changes |
+| 11 | Tag annotations render as flat comma-separated strings or balloon into full CHANGELOG copies | Phase 4 prompt: structured markdown with sections (Fixed, Dependencies, etc.), dep arrows (`pkg ^old → ^new`), test footer; length is earned |
+| 12 | Post-version doc changes land after the tag — release points at stale content | Tag-moving protocol; authorized within the workflow as a same-day forward move |
+| 13 | Background sub-agent bails early on context | Orchestrator checks for Step 8 summary; respawns continuation sub-agent if missing |
+| 14 | Big monorepo or many adoptions cause context exhaustion in a sub-agent | Narrow the prompt: if a target has many breaking framework changes, split the work into "update deps + verify" and "adopt features" against that target |
+
+## Checklist
+
+- [ ] Pre-flight: target list confirmed, clean working trees, `list-skills`/`publish-mcp`/`manifest.json` presence noted, framework version delta noted, npm 2FA mode confirmed if releasing publicly
+- [ ] Phase 1: maintenance sub-agents complete — Step 8 summary present per target, devcheck + test green
+- [ ] Phase 1 integrity: `git log --oneline -1` per target confirms no new commits written by sub-agents
+- [ ] Phase 2: double-check sub-agents complete — adoption gaps fixed, audience compliance verified, `manifest.json` and `server.json` validated; devcheck + test green after fixes
+- [ ] Phase 3: roll-up surfaced to user; version bump intent confirmed (patch default; minor/major surfaces if applicable)
+- [ ] Phase 4: wrap-up + release sub-agents complete — commit + annotated tag + push + publish per target, scope matches private/public status
+- [ ] Post-Phase-4 verification: `git ls-remote --tags origin` shows new tag; `npm view <pkg>@<version>` resolves (public); GH release artifacts attached; Docker image exists (if Dockerfile)
+- [ ] Tag/release quality review: tag subject omits version number, structured markdown, no marketing adjectives, dep arrows present, issue backlinks where applicable

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

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "2.2"
+  version: "2.3"
   audience: external
   type: workflow
 ---
@@ -202,6 +202,7 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 - Env var names in `manifest.json` (`mcp_config.env` + `user_config`) match `server.json` `environmentVariables` — `lint:packaging` enforces this, but verify the set is complete
 - `manifest.json` `name` matches `package.json` name **without the npm scope prefix** (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`); `description` matches `package.json`
 - `manifest.json` `user_config` entries must include `title` and `type` fields — `mcpb pack` validates these
+- For each `user_config` entry referenced as `${user_config.X}` in `mcp_config.env`: if it's not `required: true`, set `"default": ""`. MCPB hosts (Claude Desktop included) pass the literal placeholder string through to the process when an optional field is left blank without a default — strict consumer validators (`z.email()`, `z.url()`, `.regex()`) then crash at lazy config load, exiting silently after `initialize`. Server-side: pair every optional env-backed strict-validator field with a `z.preprocess` that strips `${...}` placeholders to `undefined`.
 - `server.json` env var `isRequired` must match the upstream API's actual requirement — if the API works without the value (rate-limited, DEMO_KEY fallback, polite pool), mark `isRequired: false` and describe the tradeoff in the description
 - Server description aligned across all surfaces: `package.json`, `manifest.json`, `server.json` (condensed, hard 100-char limit), README header `<p><b>`, and GitHub repo description (`gh repo edit --description`)
 - `package.json` `keywords` include baseline terms: `mcp`, `mcp-server`, `model-context-protocol`, `typescript`, `bun`, `stdio`, `streamable-http`, plus data-domain terms. GitHub repo topics (`gh repo edit --add-topic`) should match.

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.6"
+  version: "1.7"
   audience: external
   type: workflow
 ---
@@ -33,6 +33,8 @@ For general `gh` CLI workflows outside issue filing (PRs, workflows, API access)
 gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword"
 ```
 
+5. **For documentation- or contract-shaped requests, audit all three doc layers first** — proposals to add reference docs, public-API conventions, attribute/event catalogs, or stability commitments often duplicate surface that already exists. Check `src/` for behavior, `docs/` for human-facing reference, and `skills/` for agent-facing reference. Skill files marked `audience: external` are the framework's public contract — treat them as authoritative when evaluating whether a documentation gap exists. Also verify the constants or types you'd reference aren't already exported from `@cyanheads/mcp-ts-core` or one of its subpaths.
+
 ## Writing Well-Structured Issues
 
 Good issues are scannable, concrete, and self-contained — terse and fact-dense. Default to one or two sentences per bullet; if a bullet runs long, split it or cut it. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
@@ -286,6 +288,7 @@ gh issue list -R cyanheads/mcp-ts-core --author @me
 - [ ] Confirmed bug is in `@cyanheads/mcp-ts-core`, not server code
 - [ ] Running latest (or documented) framework version
 - [ ] Searched existing issues — no duplicate found
+- [ ] If documentation or contract enhancement: confirmed `src/`, `docs/`, `skills/`, and public exports don't already cover the surface
 - [ ] All secrets, credentials, and tokens redacted
 - [ ] Primary label assigned (`bug` / `enhancement` / `documentation`)
 - [ ] If bug: version, runtime, repro code, actual vs expected behavior included

package/templates/AGENTS.md

@@ -264,9 +264,14 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `migrate-mcp-ts-template` | One-time migration of an existing project to the current framework template |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
@@ -275,6 +280,7 @@ Available skills:
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, logger, state, progress |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |

package/templates/CLAUDE.md

@@ -265,9 +265,14 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `migrate-mcp-ts-template` | One-time migration of an existing project to the current framework template |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
@@ -276,6 +281,7 @@ Available skills:
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, logger, state, progress |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |

package/dist/logs/combined.log

@@ -1,4 +0,0 @@
-{"level":40,"time":1779856368095,"env":"testing","version":"0.9.10","pid":42668,"transport":"http","requestId":"K0H0F-OGJCX","timestamp":"2026-05-27T04:32:48.095Z","operation":"TransportManager.start","component":"HttpTransportSetup","msg":"MCP_ALLOWED_ORIGINS is not set — CORS is wildcard for CLI clients; browser Origin headers are restricted to loopback. Set MCP_ALLOWED_ORIGINS for production deployments accepting remote browser origins."}
-{"level":40,"time":1779856369836,"env":"testing","version":"0.9.10","pid":42668,"transport":"http","requestId":"K0H0F-OGJCX","timestamp":"2026-05-27T04:32:48.095Z","operation":"TransportManager.start","component":"HttpTransportSetup","sessionId":"not-a-real-session-1779856369835","msg":"Session validation failed - invalid or hijacked session"}
-{"level":50,"time":1779856373661,"env":"testing","version":"0.0.0-test","pid":42886,"requestId":"S73IT-N51J4","timestamp":"2026-05-27T04:32:53.660Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"d403b6f5b5a1acd6bef09780d848eb07995f35133a797a95095b91d16ad63d5f","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"d403b6f5b5a1acd6bef09780d848eb07995f35133a797a95095b91d16ad63d5f","toolName":"scoped_echo","requestId":"S73IT-N51J4","timestamp":"2026-05-27T04:32:53.660Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:146:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:184:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}
-{"level":50,"time":1779856373668,"env":"testing","version":"0.0.0-test","pid":42886,"requestId":"2Z3AI-0NEMI","timestamp":"2026-05-27T04:32:53.668Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"f6f091b254ded43dfd3db766e8ea167db6d7ba526bad1931f50f0ffc40f5a2e4","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"f6f091b254ded43dfd3db766e8ea167db6d7ba526bad1931f50f0ffc40f5a2e4","toolName":"scoped_echo","requestId":"2Z3AI-0NEMI","timestamp":"2026-05-27T04:32:53.668Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:146:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:184:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}