setup

Context

This skill assumes bunx @cyanheads/mcp-ts-core init [name] has already run. The CLI created the project's CLAUDE.md and AGENTS.md for different agents, copied external skills to framework-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 identical content — CLAUDE.md is read by Claude Code, AGENTS.md by Codex, Cursor, Windsurf, and other agents. Keep both. Shipping both keeps the project agent-agnostic, and they're cheap to hold in sync: edit one, then cp CLAUDE.md AGENTS.md (the framework keeps its own pair byte-identical the same way, enforced by check-docs-sync). Only delete one if you're certain the project will never be opened by the other family of agents.

For the full framework docs, read node_modules/@cyanheads/mcp-ts-core/CLAUDE.md (or its identical twin AGENTS.md) 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 — Claude Code
AGENTS.md                                       # Agent protocol — other agents (Codex, Cursor, etc.)
package.json                                    # Starter deps + scripts (placeholders substituted on init)
tsconfig.json                                   # Typecheck config — covers src/ and tests/, emits nothing
tsconfig.build.json                             # Build config — emits src/ to dist/, tests excluded
vitest.config.ts                                # Test runner config
biome.json                                      # Lint + format config
devcheck.config.json                            # Which devcheck steps to run
Dockerfile                                      # Starter multi-stage image
.dockerignore
.env.example                                    # Copy to .env and fill in
.gitignore
.github/ISSUE_TEMPLATE/                         # Bug / feature-request issue forms
.vscode/                                        # Recommended extensions + editor settings
server.json                                     # MCP Registry publishing metadata
changelog/template.md                           # Format reference for per-version changelog files
scripts/                                        # Framework scripts (build, devcheck and its checks, lint-mcp, lint-packaging, Docker install-otel and prune-musl-packages, release-github, …), re-synced by `maintenance`
framework-skills/                               # External skills copied from the package (source of truth)
src/
  index.ts                                      # createApp() entry point
  mcp-server/
    tools/definitions/
      echo.tool.ts                              # Standard tool starter
      echo-app.app-tool.ts                      # UI-enabled app tool starter (pairs with echo-app-ui resource)
    resources/definitions/
      echo.resource.ts                          # Standard resource starter
      echo-app-ui.app-resource.ts               # UI resource paired with echo-app app tool
    prompts/definitions/
      echo.prompt.ts                            # Prompt starter
tests/
  tools/echo.tool.test.ts                       # Starter tests (one per echo definition)
  resources/echo.resource.test.ts
  prompts/echo.prompt.test.ts
  smoke/definitions.smoke.test.ts               # Every shipped definition executed once
  integration/echo-contract.int.test.ts         # The echo tool driven through the production surfaces
  fuzz/echo-tool.fuzz.test.ts                   # Property-based coverage, via the fast-check dev dep