setup

Context

This skill assumes @cyanheads/mcp-ts-core init has already run. The CLI created the project's CLAUDE.md and AGENTS.md for different agents, copied external skills to skills/, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.

Agent Protocol File

The init CLI generates both CLAUDE.md and AGENTS.md with the same purpose. Keep one authoritative file for the agent you actually use:

• Claude Code — keep CLAUDE.md, discard AGENTS.md
• All other agents (Codex, Cursor, Windsurf, etc.) — keep AGENTS.md, discard CLAUDE.md

Both files serve the same purpose: project-specific agent instructions. Prefer committing one authoritative copy rather than trying to keep both in sync by hand.

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

What init actually creates:

CLAUDE.md                                       # Agent protocol (project-specific)
AGENTS.md                                       # Alternate agent protocol file — keep the one your agent uses
.github/ISSUE_TEMPLATE/                         # GitHub issue templates (bug report, feature request)
skills/                                         # Project skills (source of truth)
src/
  index.ts                                      # createApp() entry point
  mcp-server/
    tools/definitions/
      echo.tool.ts                              # Echo tool (starter — replace when ready)
    resources/definitions/
      echo.resource.ts                          # Echo resource (starter — replace when ready)
    prompts/definitions/
      echo.prompt.ts                            # Echo prompt (starter — replace when ready)

Add these as needed:

src/
  worker.ts                                     # createWorkerHandler() — only for Cloudflare Workers
  config/
    server-config.ts                            # Server-specific env vars (own Zod schema)
  services/
    [domain]/
      [domain]-service.ts                       # Init/accessor pattern
      types.ts

Scaffolded Echo Definitions

The init creates echo definitions for tools, resources, and prompts. They're functional examples with inline comments explaining conventions. After init:

1. Clean up what you don't need. If your server has no prompts, the echo prompt definition and its registration in src/index.ts can go. 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

Skill Sync

Copy all project skills into your agent's skill directory so they're available as context. skills/ is the source of truth.

For Claude Code:

mkdir -p .claude/skills && cp -R skills/* .claude/skills/

For other agents (Codex, Cursor, Windsurf, etc.) — copy to the equivalent directory (e.g., .codex/skills/, .cursor/skills/).

After the initial copy, use the maintenance skill to keep them in sync after package updates.

Project Scaffolding

After installing dependencies (prefer bun install; npm install also works), complete these one-time setup tasks:

1. Update dependencies to latest — bun update --latest (or npx npm-check-updates -u && npm install if using npm). The scaffolded package.json pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.
2. Initialize git — git init && git add -A && git commit -m "chore: scaffold from @cyanheads/mcp-ts-core"
3. Verify agent protocol placeholders — if the init CLI was run without a [name] argument, {{PACKAGE_NAME}} may remain as a literal in CLAUDE.md/AGENTS.md and package.json. Replace it with the actual server name.

Checklist

• Agent protocol file selected — keep one authoritative file (CLAUDE.md or AGENTS.md)
• {{PACKAGE_NAME}} placeholders replaced in agent protocol file (if not auto-substituted by init)
• Core framework CLAUDE.md read (node_modules/@cyanheads/mcp-ts-core/CLAUDE.md)
• Unused echo definitions cleaned up (and unregistered from src/index.ts)
• Skills copied to agent directory (cp -R skills/* .claude/skills/ or equivalent)
• Project structure understood (definitions directories, entry point)
• bun run devcheck passes
• If new server: proceed to design-mcp-server skill to plan the tool surface