@cyanheads/mcp-ts-core 0.4.1 → 0.5.2

package/templates/CLAUDE.md

@@ -14,8 +14,7 @@
 
 1. **Read the framework API** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
 2. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
-3. **Check for Bun** — run `bun --version`. If [Bun](https://bun.sh) is available, it's the recommended runtime: update `package.json` scripts to use `bun` instead of `tsx` (e.g., `"devcheck": "bun scripts/devcheck.ts"`), prefer `bun run` over `npm run` for all commands, and update the Commands table and Checklist in this file to match.
-4. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
+3. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
 
 ---
 
@@ -31,7 +30,7 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
 7. **Run `devcheck`** — lint, format, typecheck, and security audit
 8. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
-9. **Run the `maintenance` skill** — sync skills and dependencies after framework updates
+9. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
 
 Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
 
@@ -77,6 +76,7 @@ export const searchItems = tool('search_items', {
 
   // format() populates content[] — the only field most LLM clients forward to
   // the model. Render all data the LLM needs, not just a count or title.
+  // Enforced at lint time: every field in `output` must appear in the rendered text.
   format: (result) => [{
     type: 'text',
     text: result.items.map(i => `**${i.id}**: ${i.name}`).join('\n'),
@@ -122,20 +122,26 @@ export const reviewCode = prompt('review_code', {
 
 ```ts
 // src/config/server-config.ts — lazy-parsed, separate from framework config
+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),
 });
+
 let _config: z.infer<typeof ServerConfigSchema> | undefined;
 export function getServerConfig() {
-  _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;
 }
 ```
 
+`parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable (`MY_API_KEY`) rather than the internal path (`apiKey`). It throws a `ConfigurationError` the framework catches and prints as a clean startup banner.
+
 ---
 
 ## Context
@@ -215,7 +221,7 @@ src/
 
 Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, re-copy to pick up changes.
+**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
 
 Available skills:
 
@@ -232,7 +238,7 @@ Available skills:
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `maintenance` | Sync skills and dependencies after updates |
+| `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 |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -250,6 +256,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Commands
 
+**Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. Use whichever package manager you have; `bun` is slightly faster for invoking scripts but not required.
+
 | Command | Purpose |
 |:--------|:--------|
 | `npm run build` | Compile TypeScript |
@@ -281,7 +289,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 
 ## Checklist
 
-- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, etc.)
+- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
 - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage

package/skills/devcheck/SKILL.md

@@ -1,54 +0,0 @@
----
-name: devcheck
-description: >
-  Lint, format, typecheck, and verify the project is clean. Use after making changes, before committing, or when the user asks to verify quality.
-metadata:
-  author: cyanheads
-  version: "1.3"
-  audience: external
-  type: workflow
----
-
-## What It Runs
-
-`bun run devcheck` runs a broader check suite than just lint + types. By default it includes local hygiene checks, MCP definition linting, Biome, TypeScript, and slow dependency/security checks unless `--fast` is passed. Tests are opt-in via `--test`.
-
-| Check | Tool | Notes |
-|:------|:-----|:------|
-| TODOs / FIXMEs | `git grep` | Fails on tracked TODO/FIXME markers outside excluded files |
-| Tracked secrets | `git ls-files` | Flags tracked `.env`, keys, credentials, and similar sensitive files |
-| MCP definitions | `bun run scripts/lint-mcp.ts` | Validates tool/resource/prompt definitions against framework rules |
-| Biome | `biome check` | Unified lint + format — read-only by default |
-| TypeScript | `tsc --noEmit` | Full project type check |
-| Unused dependencies | `depcheck` | Runs by default; network-free but slower on large repos |
-| Security audit | `bun audit` | Runs by default unless `--fast` or `--no-audit` |
-| Outdated dependencies | `bun outdated` | Runs by default unless `--fast` or `--no-deps` |
-| Tests | `vitest run` | Off by default; enable with `bun run devcheck --test` |
-
-To auto-fix lint/format issues, run `bun run format`.
-
-## Steps
-
-1. Run `bun run devcheck`
-2. Read the failing checks in the summary and per-check output
-3. Fix the reported issues
-4. Re-run `bun run devcheck` until clean
-5. If the change touches runtime behavior, also run `bun run devcheck --test` or `bun run test`
-6. Do not consider this skill complete until the required commands exit successfully with no errors
-
-## Common Issues
-
-| Check | Error Type | Typical Fix |
-|:------|:-----------|:------------|
-| TODOs / FIXMEs | Tracked work markers | Resolve or remove the marker before committing |
-| Tracked secrets | Sensitive files in git | Add to `.gitignore` and remove from the index |
-| MCP definitions | Definition lint errors | Fix schema/name/annotation issues reported by `lint-mcp` |
-| Biome | Lint/format errors | Run `bun run format` to auto-fix, or address the flagged rule manually |
-| TypeScript | Type errors | Fix type mismatches, missing properties, incorrect generics |
-| Security audit | Vulnerabilities in direct deps | Update or replace the affected dependency |
-| Outdated deps | Stale package versions | Run `bun update` or allowlist intentionally pinned packages |
-
-## Checklist
-
-- [ ] `bun run devcheck` exits with no errors
-- [ ] Tests run when needed (`bun run devcheck --test` or `bun run test`)

package/skills/walkthrough-init/SKILL.md

@@ -1,50 +0,0 @@
----
-name: walkthrough-init
-description: >
-  Trace the agent onboarding flow after `init` scaffolds a new project. Starts from the agent reading CLAUDE.md for the first time and follows every instruction chain through skills and framework docs. Use to audit the onboarding path, find dead ends, or catch missing instructions.
-metadata:
-  author: cyanheads
-  version: "1.0"
-  audience: internal
-  type: debug
----
-
-## What this skill does
-
-A developer has run `npx @cyanheads/mcp-ts-core init banking-mcp-server` and `bun install`. They open the project and run `claude`. You are that agent, seeing this project for the first time.
-
-Trace the onboarding path through the actual files as they exist right now. Follow every instruction chain — read what you're told to read, do what you're told to do, and report what happens.
-
----
-
-## Instructions
-
-### Step 1: Read the project's CLAUDE.md
-
-This is the first file the agent sees. Read `CLAUDE.md` at the project root. Report:
-
-- What does it tell you to do first?
-- What files does it point you to?
-- Does it mention the `setup` skill? How?
-
-### Step 2: Follow the first instruction
-
-Whatever CLAUDE.md says to do first — do it. If it says to read a file, read it. If it says to run a skill, read that skill's SKILL.md. Report what you find and what it tells you to do next.
-
-### Step 3: Keep following the chain
-
-Continue following instructions until you've completed the full onboarding loop. At each step:
-
-- What file are you reading?
-- What does it tell you to do?
-- Can you actually do it? (Do the referenced files/paths exist?)
-- What's the next step it points you to?
-
-### Step 4: Report
-
-After the chain ends (or breaks), produce:
-
-1. **The path you followed** — ordered list of files read and actions taken
-2. **Broken links** — instructions that point to files that don't exist, skills that aren't written, or actions that can't be completed
-3. **Dead ends** — places where the instructions stop and you don't know what to do next
-4. **The complete onboarding flow** — a summary of what a new agent actually experiences, step by step