@cyanheads/mcp-ts-core 0.4.1 → 0.5.2

package/skills/api-config/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -189,9 +189,10 @@ Use the lazy init/accessor pattern — do not parse `process.env` at module top-
 ```ts
 // src/config/server-config.ts
 import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 
 const ServerConfigSchema = z.object({
-  myApiKey: z.string().describe('External API key'),
+  apiKey: z.string().describe('External API key'),
   maxResults: z.coerce.number().default(100),
 });
 
@@ -200,12 +201,23 @@ export type ServerConfig = z.infer<typeof ServerConfigSchema>;
 let _config: ServerConfig | undefined;
 
 export function getServerConfig(): ServerConfig {
-  _config ??= ServerConfigSchema.parse({
-    myApiKey: process.env.MY_API_KEY,
-    maxResults: process.env.MY_MAX_RESULTS,
+  _config ??= parseEnvConfig(ServerConfigSchema, {
+    apiKey: 'MY_API_KEY',
+    maxResults: 'MY_MAX_RESULTS',
   });
   return _config;
 }
 ```
 
+**Why `parseEnvConfig`?** It maps Zod schema paths to env var names so validation errors name the actual variable at fault. A missing `MY_API_KEY` produces:
+
+```
+Server config validation failed:
+  - MY_API_KEY (apiKey): Invalid input: expected string, received undefined
+```
+
+Instead of a raw `ZodError` dump at startup. The framework catches the resulting `ConfigurationError` and prints a clean banner (full stack behind `DEBUG=true`).
+
+Direct `ServerConfigSchema.parse(...)` still works — the framework intercepts raw `ZodError` thrown from `setup()` and converts it — but error messages won't know about env var names, so they show the Zod path (`apiKey`) instead of the variable name (`MY_API_KEY`).
+
 **Workers:** Do not parse `process.env` at module top-level. In Workers, env bindings are injected at request time via `injectEnvVars()`, after all static imports. Lazy parsing is required.

package/skills/field-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Exercise tools, resources, and prompts with real-world inputs to verify behavior end-to-end. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface. Calls each definition with realistic and adversarial inputs and produces a report of issues, pain points, and recommendations.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: debug
 ---
@@ -36,7 +36,7 @@ For every tool, resource, and prompt, run through these categories:
 | Category | What to test |
 |:---------|:-------------|
 | **Happy path** | Realistic input that should succeed. Verify output shape matches the output schema. Verify format function produces sensible content blocks. |
-| **`structuredContent` parity** | Compare the raw handler return, the data captured in `structuredContent`, and what `format()` renders into `content[]`. Flag fields or records that exist in the handler result or `structuredContent` but are absent from `content[]` unless the omission is explicit and acceptable for the tool's purpose. Most LLM clients only see `content[]`, so silent formatter drops are real bugs. |
+| **`structuredContent` parity** | The `format-parity` lint rule already asserts every terminal field in the output schema appears in `format()`'s rendered text (via sentinel injection at startup). Field testing layers real-data checks on top: are values rendered accurately (not just their labels)? Do conditional-render branches in `format()` still render every field when specific values are present? Does the content look right to a human reading the LLM's view? |
 | **Variations** | Different valid input combinations — optional fields omitted, optional fields included, different enum values, min/max boundaries. |
 | **Field selection / projection** | For tools with `fields`, `include`, `expand`, `view`, or similar parameters, call the tool with non-default selections. Verify the handler returns the requested fields and `format()` renders each requested field rather than a hardcoded summary subset. |
 | **Edge cases** | Empty strings, zero values, very long inputs, special characters, Unicode. |

package/skills/maintenance/SKILL.md

@@ -1,48 +1,167 @@
 ---
 name: maintenance
 description: >
-  Sync skills and dependencies after package updates. Use after running `bun update @cyanheads/mcp-ts-core` to ensure project skills are up to date, or periodically to check for drift.
+  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.2"
+  version: "1.3"
   audience: external
   type: workflow
 ---
 
-## Context
+## When to Use
 
-Skills flow from the package to the project:
+- After running `bun update --latest` yourself and wanting to review the impact (**Mode B** — typical)
+- To run the whole flow end-to-end — outdated check → update → investigate → adopt → verify (**Mode A**)
+- Periodically, to check for skill drift from the package
 
-1. **Package** — `node_modules/@cyanheads/mcp-ts-core/skills/` (canonical source, updated via `bun update`)
-2. **Project** — `skills/` at project root (working copy, can have local overrides or server-specific skills)
+## Entry Modes
 
-After `bun update @cyanheads/mcp-ts-core`, the package may have newer skills than the project. This skill syncs them and handles general dependency upkeep.
+| Mode | Starting Point | First Step |
+|:-----|:---------------|:-----------|
+| **A — Full flow** | Lockfile is current; want to update | Step 1 |
+| **B — Post-update review** | User already ran `bun update --latest` + `bun run rebuild` + `bun run test` | Skip to Step 3 with the update output or `git diff bun.lock` |
+
+Both modes converge at Step 3 and end at Step 8.
 
 ## Steps
 
-### Sync project skills (Package → Project)
+### 1. Survey what's outdated (Mode A only)
+
+```bash
+bun outdated
+```
+
+Note: `bun update --latest` crosses semver majors; `bun update` alone respects ranges. Use `--latest` unless a package is intentionally pinned.
+
+### 2. Apply the update (Mode A only)
+
+```bash
+bun update --latest
+```
+
+Capture the `↑ package old → new` lines from stdout — these feed Step 3. Alternatively, `git diff bun.lock` surfaces version deltas after the fact.
+
+### 3. Investigate changelogs
+
+Invoke the **`changelog`** skill with the captured list of updated packages. It resolves each repo, fetches release notes (or CHANGELOG entries) between old and new versions, and cross-references changes against actual imports in `src/`. Output per package: what changed, impact on this project, action items.
+
+Do not redo this investigation inline — the `changelog` skill handles tag-format detection, monorepo patterns, and fallbacks.
+
+### 4. Framework review (`@cyanheads/mcp-ts-core`)
+
+If `@cyanheads/mcp-ts-core` was updated, do a deeper pass beyond what the `changelog` skill covers. Read:
+
+```bash
+node_modules/@cyanheads/mcp-ts-core/CHANGELOG.md
+```
+
+Extract entries between the old and new version. Scan specifically for:
+
+| Area | Adoption Check |
+|:-----|:---------------|
+| New error factories in `/errors` | Replace ad-hoc `new McpError(...)` with factories where applicable |
+| New utilities in `/utils` | Identify any that supersede local helper code |
+| New context capabilities | Added `ctx.*` methods worth adopting |
+| Provider/service APIs | Updates to `OpenRouterProvider`, `SpeechService`, `GraphService`, etc. |
+| Deprecations | Migrate now, before the next breaking release |
+| Config changes | New env vars, renamed keys, changed defaults |
+| Linter rules | New definition-lint rules that may now flag existing tools/resources |
+
+Cross-reference each finding against the server's code. Collect adoption opportunities for Step 6.
+
+**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:
+
+```bash
+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.
+
+### 5. Sync project skills
+
+Skills flow in two hops: package → project `skills/` → agent directories.
+
+**Phase A — Package → Project `skills/`**
+
+1. **Package** — `node_modules/@cyanheads/mcp-ts-core/skills/` (canonical source)
+2. **Project** — `skills/` at project root (working copy; may contain local overrides or server-specific skills)
+
+Procedure:
 
 1. List all skill directories in `node_modules/@cyanheads/mcp-ts-core/skills/`
 2. For each skill with `metadata.audience: external` in its `SKILL.md` frontmatter:
-   - If the skill does not exist in project `skills/`, copy the full directory
-   - If it exists, compare `metadata.version` — if the package version is newer, replace the full directory
+   - If missing in project `skills/`, copy the full directory
+   - If present, compare `metadata.version` — replace if the package version is newer
    - If the local version is equal or newer, skip (local override)
 3. Do not touch skills in `skills/` that don't exist in the package (server-specific)
 
-### Dependency updates
+**Phase B — Project `skills/` → Agent directories**
+
+The `setup` skill instructs consumers to copy `skills/*` into their agent's skill directory at init time. Those copies go stale unless re-synced. Detect which agent directories exist and propagate:
+
+| Agent | Directory |
+|:------|:----------|
+| Claude Code | `.claude/skills/` |
+| Generic / shared | `.agents/skills/` |
+| Codex | `.codex/skills/` |
+| Cursor | `.cursor/skills/` |
+| Windsurf | `.windsurf/skills/` |
+
+For each agent directory that exists:
+
+1. For every directory in project `skills/`, copy it into the agent dir (overwrite on match, add if missing)
+2. Do **not** delete skills in the agent dir that aren't in project `skills/` — they may be general-purpose skills sourced elsewhere (e.g., `code-security`, `cloudflare`, `changelog`)
+
+If no agent directory exists, skip Phase B — the project hasn't opted in to per-agent skill copies.
+
+**Report** which skills were added/updated in Phase A (with version deltas) and which agent directories were refreshed in Phase B. The user needs to know what new guidance is now available and where.
+
+### 6. Adopt changes in the codebase
+
+Apply the findings from Steps 3 and 4:
+
+- **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
+
+Keep diffs focused. Don't sweep refactors beyond the update's scope.
+
+### 7. Rebuild and verify
+
+```bash
+bun run rebuild
+bun run devcheck
+bun run test
+```
+
+`rebuild` (clean + build) catches API surface and type-alignment issues that `devcheck` alone may miss — module resolution, path aliases, post-build processing. `devcheck` includes `bun audit` and `bun outdated`, so no separate audit step is needed.
+
+In **Mode B**, the user already ran rebuild + test before invoking this skill, but run them again here — Step 6 made code changes that need verification.
+
+Fix anything that fails. Re-run until clean.
+
+### 8. Summary
+
+Present a concise numbered summary to the user:
 
-1. Run `bun outdated` to see what's available
-2. For any major version bumps, review changelogs before proceeding
-3. Run `bun update` to apply updates
-4. Run `bun audit` to check for vulnerabilities introduced by the update
-5. Run `bun run devcheck` to confirm lint, definitions, types, and dependency/security checks still pass
-6. Run `bun run test` to confirm runtime behavior still passes
+1. **Updated packages** — short list with version deltas (N total)
+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
+6. **Status** — rebuild / devcheck / test results
 
 ## Checklist
 
-- [ ] Package skills compared against project `skills/` (version check)
-- [ ] New or updated skills copied to project `skills/`
-- [ ] Dependencies updated (`bun update`)
-- [ ] `bun audit` passes (no new vulnerabilities)
-- [ ] `bun run devcheck` passes
+- [ ] Update applied (`bun update --latest`) — Mode A, or already done by user — Mode B
+- [ ] `changelog` skill invoked for each updated package
+- [ ] Framework CHANGELOG reviewed if `@cyanheads/mcp-ts-core` was updated
+- [ ] Adoption opportunities identified and applied
+- [ ] Project `skills/` synced from package (Phase A), with a change report
+- [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `skills/` (Phase B)
+- [ ] `bun run rebuild` succeeds
+- [ ] `bun run devcheck` passes (includes audit + outdated)
 - [ ] `bun run test` passes
+- [ ] Numbered summary presented to user

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: "1.3"
+  version: "1.4"
   audience: external
   type: workflow
 ---
@@ -48,7 +48,7 @@ Capture: tool count, resource count, prompt count, service count, required env v
 
 Read `references/readme.md` for structure and conventions. If `README.md` doesn't exist, create it from scratch. If it exists, diff the current content against the audit — update tool/resource/prompt tables, env var lists, and descriptions to match the actual surface area. Don't rewrite sections that are already accurate.
 
-The header tagline (`<p><b>...</b></p>`) must match the `package.json` `description`.
+The bold header tagline (the `<b>` text inside the first `<p>`) must match the `package.json` `description`. The surface count is a nested `<div>` inside the same `<p>`, separated by `•`.
 
 ### 3. Agent Protocol (CLAUDE.md / AGENTS.md)