@cyanheads/mcp-ts-core 0.1.0-beta.12

package/skills/maintenance/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: maintenance
+description: >
+  Sync skills and dependencies after package updates. Use after running `bun update @cyanheads/mcp-ts-core` to ensure project skills and agent skill directories are up to date, or periodically to check for drift.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: workflow
+---
+
+## Context
+
+Skills flow through three tiers:
+
+1. **Package** — `node_modules/@cyanheads/mcp-ts-core/skills/` (canonical source)
+2. **Project** — `skills/` at project root (source of truth for this project)
+3. **Agent** — your agent skill directory (e.g., `.claude/skills/`)
+
+After `bun update @cyanheads/mcp-ts-core`, Tier 1 may have newer skills than Tier 2 And Tier 3 may be out of sync with Tier 2 at any time.
+
+## Steps
+
+### Sync project skills (Tier 1 → Tier 2)
+
+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 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)
+
+### Sync agent skills (Tier 2 → Tier 3)
+
+1. Compare your agent skill directory against project `skills/`
+2. Copy any missing skills from `skills/` to your agent directory
+3. For existing skills, compare file contents — update if `skills/` is newer
+4. Do not remove skills from your agent directory that aren't in `skills/`
+
+### Dependency updates
+
+1. Run `bun update` to update all dependencies
+2. Check `bun outdated` for any remaining outdated packages
+3. Review changelogs for major version bumps before updating
+
+## Checklist
+
+- [ ] Package skills compared against project `skills/` (version check)
+- [ ] New or updated skills copied to project `skills/`
+- [ ] Agent skill directory in sync with project `skills/`
+- [ ] Dependencies updated (`bun update`)
+- [ ] `bun run devcheck` passes

package/skills/migrate-mcp-ts-template/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: migrate-mcp-ts-template
+description: >
+  Migrate an existing mcp-ts-template fork to use @cyanheads/mcp-ts-core as a package dependency. Use when a project was cloned/forked from github.com/cyanheads/mcp-ts-template and carries framework source code in its own src/ — this skill rewrites those internal imports to package subpath imports and removes the bundled framework files.
+metadata:
+  author: cyanheads
+  version: "2.0"
+  audience: external
+  type: workflow
+---
+
+## Context
+
+Before `@cyanheads/mcp-ts-core` was published as a package, users built servers by forking/cloning the `mcp-ts-template` repo. Those forks carry the full framework source code in their `src/` and use `@/` path aliases to import framework internals alongside their own server code.
+
+This skill converts such a project to use `@cyanheads/mcp-ts-core` as a dependency — rewriting framework imports to package subpaths and removing the bundled framework files, while leaving server-specific code (tools, resources, prompts, services) untouched.
+
+For the full exports catalog, see `CLAUDE.md` → Exports Reference.
+
+## Steps
+
+1. **Install the package**: `bun add @cyanheads/mcp-ts-core`
+2. **Search for all `@/` imports** across `src/` that reference framework internals
+3. **Rewrite each import** using the mapping table below
+4. **Remove migrated framework source files** that now live in `node_modules`
+5. **Update entry point** (`src/index.ts`) to use `createApp()` from the package
+6. **Update build configs**: `tsconfig.json` extends `@cyanheads/mcp-ts-core/tsconfig.base.json`, `biome.json` extends `@cyanheads/mcp-ts-core/biome.json`
+7. **Run `bun run devcheck`** to verify no broken imports remain
+8. **Verify no `@/` imports** point to files that were removed
+
+## Import Mapping
+
+These are the actual `@/` import paths used in framework source. Rewrite any that appear in server-specific files (tools, resources, services, config).
+
+### Core
+
+| Old `@/` import | New package import |
+|:----------------|:-------------------|
+| `@/config/index.js` | `@cyanheads/mcp-ts-core/config` |
+| `@/context.js` | `@cyanheads/mcp-ts-core/context` or `@cyanheads/mcp-ts-core` |
+| `@/types-global/errors.js` | `@cyanheads/mcp-ts-core/errors` |
+| `@/storage/core/StorageService.js` | `@cyanheads/mcp-ts-core/storage` |
+| `@/storage/core/IStorageProvider.js` | `@cyanheads/mcp-ts-core/storage/types` |
+| `@/mcp-server/transports/auth/lib/checkScopes.js` | `@cyanheads/mcp-ts-core/auth` |
+| `@/testing/index.js` | `@cyanheads/mcp-ts-core/testing` |
+
+### Definition types
+
+| Old `@/` import | New package import |
+|:----------------|:-------------------|
+| `@/mcp-server/tools/utils/toolDefinition.js` | `@cyanheads/mcp-ts-core/tools` |
+| `@/mcp-server/tools/utils/newToolDefinition.js` | `@cyanheads/mcp-ts-core/tools` or `@cyanheads/mcp-ts-core` (for `tool()` builder) |
+| `@/mcp-server/resources/utils/resourceDefinition.js` | `@cyanheads/mcp-ts-core/resources` |
+| `@/mcp-server/resources/utils/newResourceDefinition.js` | `@cyanheads/mcp-ts-core/resources` or `@cyanheads/mcp-ts-core` (for `resource()` builder) |
+| `@/mcp-server/prompts/utils/promptDefinition.js` | `@cyanheads/mcp-ts-core/prompts` |
+| `@/mcp-server/prompts/utils/newPromptDefinition.js` | `@cyanheads/mcp-ts-core/prompts` or `@cyanheads/mcp-ts-core` (for `prompt()` builder) |
+| `@/mcp-server/tasks/utils/taskToolDefinition.js` | `@cyanheads/mcp-ts-core/tasks` |
+
+### Utils — internal
+
+| Old `@/` import | New package import |
+|:----------------|:-------------------|
+| `@/utils/internal/logger.js` | `@cyanheads/mcp-ts-core/utils/logger` |
+| `@/utils/internal/requestContext.js` | `@cyanheads/mcp-ts-core/utils/requestContext` |
+| `@/utils/internal/error-handler/errorHandler.js` | `@cyanheads/mcp-ts-core/utils/errorHandler` |
+| `@/utils/internal/runtime.js` | `@cyanheads/mcp-ts-core/utils/runtime` |
+
+### Utils — public
+
+| Old `@/` import | New package import |
+|:----------------|:-------------------|
+| `@/utils/formatting/*.js` | `@cyanheads/mcp-ts-core/utils/formatting` |
+| `@/utils/parsing/*.js` | `@cyanheads/mcp-ts-core/utils/parsing` |
+| `@/utils/security/*.js` | `@cyanheads/mcp-ts-core/utils/security` |
+| `@/utils/network/*.js` | `@cyanheads/mcp-ts-core/utils/network` |
+| `@/utils/pagination/pagination.js` | `@cyanheads/mcp-ts-core/utils/pagination` |
+| `@/utils/types/guards.js` | `@cyanheads/mcp-ts-core/utils/types` |
+| `@/utils/scheduling/*.js` | `@cyanheads/mcp-ts-core/utils/scheduling` |
+
+## Files to Remove
+
+After rewriting imports, remove these framework directories/files. **Do not remove** server-specific code under `mcp-server/tools/definitions/`, `mcp-server/resources/definitions/`, `mcp-server/prompts/definitions/`, `services/` (server's own), or `config/server-config.ts`.
+
+Framework files to delete:
+
+- `src/app.ts`, `src/worker.ts`, `src/context.ts`
+- `src/config/index.ts` (keep `server-config.ts` if it exists)
+- `src/types-global/`
+- `src/storage/`
+- `src/mcp-server/server.ts`
+- `src/mcp-server/transports/`
+- `src/mcp-server/roots/`
+- `src/mcp-server/tasks/` (core task infra — not tool definitions)
+- `src/mcp-server/tools/utils/`, `tool-registration.ts`
+- `src/mcp-server/resources/utils/`, `resource-registration.ts`
+- `src/mcp-server/prompts/utils/`, `prompt-registration.ts`
+- `src/utils/internal/`
+- `src/utils/telemetry/`
+- `src/utils/metrics/`
+- `src/testing/`
+- `src/services/llm/`, `src/services/speech/`, `src/services/graph/` (framework services)
+
+## Entry Point Rewrite
+
+Replace the fork's `src/index.ts` with:
+
+```ts
+#!/usr/bin/env node
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { allToolDefinitions } from './mcp-server/tools/definitions/index.js';
+import { allResourceDefinitions } from './mcp-server/resources/definitions/index.js';
+import { allPromptDefinitions } from './mcp-server/prompts/definitions/index.js';
+
+await createApp({
+  tools: allToolDefinitions,
+  resources: allResourceDefinitions,
+  prompts: allPromptDefinitions,
+});
+```
+
+## Checklist
+
+- [ ] `@cyanheads/mcp-ts-core` installed as a dependency
+- [ ] All framework `@/` imports rewritten to `@cyanheads/mcp-ts-core/*` subpaths
+- [ ] No `@/` imports point to removed framework files
+- [ ] `src/index.ts` uses `createApp()` from the package
+- [ ] `tsconfig.json` extends `@cyanheads/mcp-ts-core/tsconfig.base.json`
+- [ ] `biome.json` extends `@cyanheads/mcp-ts-core/biome.json`
+- [ ] Framework source files removed from `src/`
+- [ ] Server-specific `@/` imports (own tools, services) still work
+- [ ] `bun run devcheck` passes

package/skills/release/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: release
+description: >
+  Prepare and publish a core package release. Use when bumping the version, updating the changelog, and publishing to npm/Docker/GitHub. Stops before publish commands for user confirmation.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: workflow
+---
+
+## Context
+
+Publishing is a multi-step process with irreversible actions (npm publish, Docker push). This skill handles preparation but stops before destructive commands, requiring the user to execute them manually.
+
+## Steps
+
+1. **Determine version bump** — ask the user: patch, minor, or major?
+2. **Update version** in:
+   - `package.json` (`version` field)
+   - `server.json` (`version` field, if present)
+   - `CLAUDE.md` (version reference at the top)
+   - `README.md` (version badge, if present)
+3. **Update CHANGELOG.md** — add a new entry with:
+   - Concrete version number and date (NEVER use `[Unreleased]`)
+   - Grouped changes: Added, Changed, Fixed, Removed
+   - Reference relevant PRs or commits
+4. **Run `bun run devcheck`** — must pass cleanly
+5. **Run `bun run test`** — all tests must pass
+6. **Run `bun run build`** — verify build succeeds
+7. **Commit** with message: `chore(release): v{{VERSION}}`
+8. **Stop and inform the user** — the following commands require manual execution:
+
+```bash
+# Publish to npm
+bun publish --access public
+
+# Build and push Docker image
+docker buildx build --platform linux/amd64,linux/arm64 \
+  -t ghcr.io/cyanheads/mcp-ts-core:{{VERSION}} \
+  -t ghcr.io/cyanheads/mcp-ts-core:latest \
+  --push .
+
+# Publish MCP listing (if applicable)
+mcp-publisher publish
+```
+
+## Wrapup Checklist
+
+Before committing, verify these files are in sync:
+
+- `README.md` — version badge, feature counts, descriptions
+- `package.json` — version
+- `server.json` — version (if present)
+- `CHANGELOG.md` — new entry with concrete version and date
+- `CLAUDE.md` — version reference
+- `docs/tree.md` — updated if structure changed
+
+## Checklist
+
+- [ ] Version bumped in all locations (package.json, server.json, CLAUDE.md, README.md)
+- [ ] CHANGELOG.md updated with concrete version number and date
+- [ ] `bun run devcheck` passes
+- [ ] `bun run test` passes
+- [ ] `bun run build` succeeds
+- [ ] Release commit created: `chore(release): v{{VERSION}}`
+- [ ] User informed of publish commands (npm, Docker, mcp-publisher)

package/skills/setup/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: setup
+description: >
+  Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
+metadata:
+  author: cyanheads
+  version: "1.1"
+  audience: external
+  type: workflow
+---
+
+## Context
+
+This skill assumes `@cyanheads/mcp-ts-core init` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` (identical content), copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill orients you to what was created.
+
+## Agent Protocol File
+
+The init CLI generates both `CLAUDE.md` and `AGENTS.md` with identical content. Keep the one your agent uses and delete the other:
+
+- **Claude Code** — keep `CLAUDE.md`, delete `AGENTS.md`
+- **All other agents** (Codex, Cursor, Windsurf, etc.) — keep `AGENTS.md`, delete `CLAUDE.md`
+
+Both files serve the same purpose: project-specific agent instructions. Only one should exist in the committed project.
+
+For the full framework API, read:
+
+    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+
+Read that file once per session. It contains the exports catalog, tool/resource/prompt contracts, error codes, context API, and common import patterns.
+
+## Project Structure
+
+```
+CLAUDE.md                                       # Agent protocol (project-specific)
+skills/                                         # Project skills (source of truth)
+src/
+  index.ts                                      # createApp() entry point
+  worker.ts                                     # createWorkerHandler() (if using Workers)
+  config/
+    server-config.ts                            # Server-specific env vars (own Zod schema)
+  services/
+    [domain]/
+      [domain]-service.ts                       # Init/accessor pattern
+      types.ts
+  mcp-server/
+    tools/definitions/
+      echo.tool.ts                              # Echo tool (starter — replace or delete)
+    resources/definitions/
+      echo.resource.ts                          # Echo resource (starter — replace or delete)
+    prompts/definitions/
+      echo.prompt.ts                            # Echo prompt (starter — replace or delete)
+```
+
+## Scaffolded Echo Definitions
+
+The init creates echo definitions for tools, resources, and prompts as starting points. They're functional examples with inline comments explaining conventions. After init:
+
+1. **Delete what you don't need.** If your server has no prompts, delete `echo.prompt.ts` and remove its import/registration from `src/index.ts`. Same for resources.
+2. **Rename and replace what you keep.** The echo definitions show the pattern — swap them out for your real tools/resources/prompts.
+3. **Definitions register directly in `src/index.ts`.** No barrel files — just import and add to the arrays.
+
+## Conventions
+
+| Convention | Rule |
+|:-----------|:-----|
+| File names | kebab-case |
+| Tool/resource/prompt names | snake_case, prefixed with server name (e.g. `tasks_fetch_list`) |
+| File suffixes | `.tool.ts`, `.resource.ts`, `.prompt.ts` |
+| Imports (framework) | `@cyanheads/mcp-ts-core` and subpaths |
+| Imports (server code) | `@/` path alias for `src/` |
+
+## Skill Sync
+
+Your agent skill directory (e.g., `.claude/skills/`) must stay in sync with the project's `skills/` directory. The project `skills/` is the source of truth.
+
+1. Compare your agent skill directory against `skills/`
+2. Copy any missing or updated skills into your agent directory
+3. Do not remove server-specific skills from either location
+
+For detailed sync procedures, see the `/maintenance` skill.
+
+## Checklist
+
+- [ ] Agent protocol file selected — keep `CLAUDE.md` or `AGENTS.md`, delete the other
+- [ ] Core framework CLAUDE.md read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`)
+- [ ] Unused echo definitions deleted (and unregistered from `src/index.ts`)
+- [ ] Agent skill directory in sync with project `skills/`
+- [ ] Project structure understood (definitions directories, entry point)
+- [ ] `bun run devcheck` passes

package/skills/walkthrough-init/SKILL.md

@@ -0,0 +1,50 @@
+---
+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 `templates/CLAUDE.md` (or wherever the template lives). 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

package/templates/.env.example

@@ -0,0 +1,17 @@
+# ── Transport ──────────────────────────────────────────────────────────
+# MCP_TRANSPORT_TYPE=stdio          # stdio | http (default: stdio)
+# MCP_HTTP_PORT=3000                # HTTP port (default: 3000)
+# MCP_HTTP_HOST=localhost           # HTTP host (default: localhost)
+
+# ── Auth ──────────────────────────────────────────────────────────────
+# MCP_AUTH_MODE=none                # none | jwt | oauth (default: none)
+# MCP_AUTH_SECRET_KEY=              # JWT secret (required for jwt mode)
+
+# ── Storage ───────────────────────────────────────────────────────────
+# STORAGE_PROVIDER_TYPE=in-memory   # in-memory | filesystem | supabase
+
+# ── Logging ───────────────────────────────────────────────────────────
+# MCP_LOG_LEVEL=info                # debug | info | notice | warning | error
+
+# ── Server-specific ──────────────────────────────────────────────────
+# Add your server's environment variables below

package/templates/AGENTS.md

@@ -0,0 +1,113 @@
+# Agent Protocol
+
+**Server:** {{SERVER_NAME}}
+**Version:** 0.1.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+
+> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
+
+---
+
+## Core Rules
+
+- **Logic throws, handlers catch.** Tool/resource handlers are pure — throw `McpError`, no `try/catch`. The framework catches and formats.
+- **Use `ctx.log`** for request-scoped logging. No `console` calls.
+- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
+- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
+- **Secrets in env vars only** — never hardcoded.
+
+---
+
+## Structure
+
+```
+src/
+  index.ts                              # createApp() entry point
+  config/
+    server-config.ts                    # Server-specific env vars (Zod schema)
+  services/
+    [domain]/
+      [domain]-service.ts               # Domain service (init/accessor pattern)
+      types.ts                          # Domain types
+  mcp-server/
+    tools/definitions/
+      [tool-name].tool.ts               # Tool definitions
+      index.ts                          # allToolDefinitions barrel
+    resources/definitions/
+      [resource-name].resource.ts       # Resource definitions
+      index.ts                          # allResourceDefinitions barrel
+    prompts/definitions/
+      [prompt-name].prompt.ts           # Prompt definitions
+      index.ts                          # allPromptDefinitions barrel
+```
+
+---
+
+## Naming
+
+| What | Convention | Example |
+|:-----|:-----------|:--------|
+| Files | kebab-case with suffix | `search-docs.tool.ts` |
+| Tool/resource/prompt names | snake_case | `search_docs` |
+| Directories | kebab-case | `src/services/doc-search/` |
+
+---
+
+## Skills
+
+Skills are modular instructions in `skills/`. They guide you through common tasks.
+
+**Sync:** Keep your agent skill directory (e.g., `.claude/skills/`) in sync with `skills/`. Copy any missing or updated skills from `skills/` to your directory.
+
+Available skills:
+
+| Skill | Purpose |
+|:------|:--------|
+| `setup` | Post-init project orientation |
+| `add-tool` | Scaffold a new tool definition |
+| `add-resource` | Scaffold a new resource definition |
+| `add-prompt` | Scaffold a new prompt definition |
+| `add-service` | Scaffold a new service integration |
+| `devcheck` | Lint, format, typecheck, audit |
+| `migrate-mcp-ts-template` | Migrate legacy template fork to package dependency |
+| `maintenance` | Sync skills and dependencies after updates |
+
+When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
+
+---
+
+## Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| `bun run build` | Compile TypeScript |
+| `bun run devcheck` | Lint + format + typecheck |
+| `bun run test` | Run tests |
+| `bun run format` | Auto-fix formatting |
+| `bun run dev:stdio` | Dev mode (stdio) |
+| `bun run dev:http` | Dev mode (HTTP) |
+
+---
+
+## Imports
+
+```ts
+// Framework — from node_modules
+import { tool } from '@cyanheads/mcp-ts-core';
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+// Server's own code — via path alias
+import { getMyService } from '@/services/my-domain/my-service.js';
+```
+
+---
+
+## Checklist
+
+- [ ] Zod schemas: all fields have `.describe()`
+- [ ] JSDoc `@fileoverview` + `@module` on every file
+- [ ] `ctx.log` for logging, `ctx.state` for storage
+- [ ] Handlers throw `McpError`, no try/catch
+- [ ] Registered in `definitions/index.ts` barrel
+- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `bun run devcheck` passes

package/templates/CLAUDE.md

@@ -0,0 +1,113 @@
+# Agent Protocol
+
+**Server:** {{SERVER_NAME}}
+**Version:** 0.1.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+
+> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
+
+---
+
+## Core Rules
+
+- **Logic throws, handlers catch.** Tool/resource handlers are pure — throw `McpError`, no `try/catch`. The framework catches and formats.
+- **Use `ctx.log`** for request-scoped logging. No `console` calls.
+- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
+- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
+- **Secrets in env vars only** — never hardcoded.
+
+---
+
+## Structure
+
+```
+src/
+  index.ts                              # createApp() entry point
+  config/
+    server-config.ts                    # Server-specific env vars (Zod schema)
+  services/
+    [domain]/
+      [domain]-service.ts               # Domain service (init/accessor pattern)
+      types.ts                          # Domain types
+  mcp-server/
+    tools/definitions/
+      [tool-name].tool.ts               # Tool definitions
+      index.ts                          # allToolDefinitions barrel
+    resources/definitions/
+      [resource-name].resource.ts       # Resource definitions
+      index.ts                          # allResourceDefinitions barrel
+    prompts/definitions/
+      [prompt-name].prompt.ts           # Prompt definitions
+      index.ts                          # allPromptDefinitions barrel
+```
+
+---
+
+## Naming
+
+| What | Convention | Example |
+|:-----|:-----------|:--------|
+| Files | kebab-case with suffix | `search-docs.tool.ts` |
+| Tool/resource/prompt names | snake_case | `search_docs` |
+| Directories | kebab-case | `src/services/doc-search/` |
+
+---
+
+## Skills
+
+Skills are modular instructions in `skills/`. They guide you through common tasks.
+
+**Sync:** Keep your agent skill directory (e.g., `.claude/skills/`) in sync with `skills/`. Copy any missing or updated skills from `skills/` to your directory.
+
+Available skills:
+
+| Skill | Purpose |
+|:------|:--------|
+| `setup` | Post-init project orientation |
+| `add-tool` | Scaffold a new tool definition |
+| `add-resource` | Scaffold a new resource definition |
+| `add-prompt` | Scaffold a new prompt definition |
+| `add-service` | Scaffold a new service integration |
+| `devcheck` | Lint, format, typecheck, audit |
+| `migrate-mcp-ts-template` | Migrate legacy template fork to package dependency |
+| `maintenance` | Sync skills and dependencies after updates |
+
+When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
+
+---
+
+## Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| `bun run build` | Compile TypeScript |
+| `bun run devcheck` | Lint + format + typecheck |
+| `bun run test` | Run tests |
+| `bun run format` | Auto-fix formatting |
+| `bun run dev:stdio` | Dev mode (stdio) |
+| `bun run dev:http` | Dev mode (HTTP) |
+
+---
+
+## Imports
+
+```ts
+// Framework — from node_modules
+import { tool } from '@cyanheads/mcp-ts-core';
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+// Server's own code — via path alias
+import { getMyService } from '@/services/my-domain/my-service.js';
+```
+
+---
+
+## Checklist
+
+- [ ] Zod schemas: all fields have `.describe()`
+- [ ] JSDoc `@fileoverview` + `@module` on every file
+- [ ] `ctx.log` for logging, `ctx.state` for storage
+- [ ] Handlers throw `McpError`, no try/catch
+- [ ] Registered in `definitions/index.ts` barrel
+- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `bun run devcheck` passes

package/templates/_tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "resolveJsonModule": true,
+    "allowJs": false,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}