setup

---

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.12" audience: external type: workflow

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

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 five echo definitions plus matching starter tests:

File	Demonstrates
echo.tool.ts	Standard MCP tool: input/output Zod schemas, handler, format
echo-app.app-tool.ts	MCP App tool — same as a tool, but emits a UI (ui_app:// link) for clients that render MCP Apps
echo.resource.ts	Standard MCP resource with a parameterised URI template
echo-app-ui.app-resource.ts	UI resource served to MCP App clients; paired with echo-app.app-tool.ts
echo.prompt.ts	Prompt template (pure message generator)
tests/**/echo.*.test.ts	Starter tests using createMockContext — edit alongside the definitions

After init:

1. Clean up what you don't need. If your server has no prompts, delete the echo prompt and its registration in src/index.ts. Same for resources, or the app-tool pair if you're not targeting UI-capable clients.
2. Rename and replace what you keep. The echo definitions and their tests show the pattern — swap them out for your real tools/resources/prompts.
3. Definitions register directly in src/index.ts. The init scaffold uses direct imports — no barrel files yet. As the definition count grows, the add-tool/add-resource/add-prompt skills introduce definitions/index.ts barrels per the framework convention.

See the add-tool, add-app-tool, add-resource, add-prompt, add-service, and add-test skills for the scaffolding patterns when you start adding real definitions.

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, .app-tool.ts (UI-enabled), .app-resource.ts (paired UI resource)
Imports (framework)	@cyanheads/mcp-ts-core and subpaths
Imports (server code)	@/ path alias for src/

Skill Sync

Copy all project skills into your agent's skill directory so they're available as context. framework-skills/ is the source of truth. It is deliberately not skills/: Claude Code and Codex auto-load a plugin's root skills/, and these are development skills, not skills for the agents that install the server — leave skills/ for those.

Don't edit framework-skills/*/SKILL.md or framework-skills/*/references/*. These are external skill files synced from @cyanheads/mcp-ts-core — the maintenance skill overwrites them on package updates, so local edits get lost. Project-specific agent context belongs in CLAUDE.md / AGENTS.md.

For Claude Code:

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

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

This step is the bootstrap — it creates the agent directory. From then on, use the maintenance skill to refresh it after package updates (Phase B). Maintenance only refreshes directories that already exist; it won't create a new agent directory on your behalf.

Project Scaffolding

Complete these one-time setup tasks:

1. Install dependencies — bun install

2. Update dependencies to latest — bun update --latest. The scaffolded package.json pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.

3. Initialize git — use your git tools: init the repo, stage all files, and commit with message chore: scaffold from @cyanheads/mcp-ts-core

4. Verify the substituted server name — when init runs without a [name] argument, the package name defaults to the cwd directory name. If that's not what you want as the published server name, update package.json, CLAUDE.md/AGENTS.md, and server.json to your actual server name.

5. Populate the publishing identity — the scaffold ships identity fields empty on purpose, so the first devcheck run is a to-do list rather than a green light. These fail the gate until they are set:

   File	Gated fields	Gate
   server.json	name (reverse-DNS, e.g. io.github.<owner>/<server>), description, repository.url	lint:mcp
   .claude-plugin/plugin.json	description	lint:packaging
   .codex-plugin/plugin.json	description, interface.shortDescription, interface.longDescription	lint:packaging

   Fill the rest of the same blocks while you are in them — package.json description and repository.url, both plugin manifests' author / homepage / repository / keywords, the Codex manifest's interface.developerName / category / websiteURL, and manifest.json description / author.name. Nothing gates them, and every install surface reads them.

   When the server takes a user-supplied value (an API key, a contact email, an instance URL), wire it into the plugin manifests the way each client delivers it — never as "KEY": "" in env, which lint:packaging rejects because the empty value replaces the user's exported key and is read as unset. In .claude-plugin/plugin.json, declare the option under userConfig (type, title, description; sensitive: true for keys and tokens; required: true or default: "") and set "KEY": "${user_config.<option>}" in env. In .codex-plugin/mcp.json, list the variable name in env_vars. Mirror the user_config block you write in manifest.json.

   A server that will never be published or installed as a plugin can drop the plugin-manifest gate instead — set "packaging": { "pluginManifests": false } in devcheck.config.json.

6. Verify the scaffold builds clean — bun run devcheck. Fix any issues before starting real work.

Changelog Convention

changelog/template.md ships as a format reference — never edit, rename, or move it. For each release, author a per-version file at changelog/<major.minor>.x/<version>.md (e.g. changelog/0.1.x/0.1.0.md) with YAML frontmatter (summary: + optional breaking: / security:) and grouped sections (Added / Changed / Fixed / Removed). Then regenerate the rollup with bun run changelog:build — CHANGELOG.md is an auto-generated navigation index, never hand-edited. See the release-and-publish skill for the full release flow.

Next Steps

The included skills form a rough progression — not a rigid sequence, but the typical flow through a new server:

1. design-mcp-server — map the domain into tools, resources, and services before writing any definitions
2. add-tool / add-app-tool / add-resource / add-prompt / add-service — scaffold each piece as you go
3. add-test — pair tests with each definition (or retrofit later)
4. field-test — exercise the built surface with real and adversarial inputs; produces a report of issues and pain points
5. security-pass — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
6. polish-docs-meta — finalize README, metadata, and agent protocol before shipping
7. release-and-publish — post-wrapup ship workflow: verification gate, push commits and tags, publish to npm/MCP Registry/GHCR
8. maintenance — after bun update --latest, investigate upstream changelogs and re-sync skills

Skip or reorder as the project calls for it. The agent protocol's "What's Next?" section is the authoritative map once the first session is over.

Checklist

• Agent protocol files kept — both CLAUDE.md and AGENTS.md present and in sync (or the unused one deliberately deleted)
• bun install run
• Dependencies updated (bun update --latest)
• Git repo initialized and initial commit made (chore: scaffold from @cyanheads/mcp-ts-core)
• Substituted server name verified in package.json, agent protocol file, and server.json
• Publishing identity populated (server.json, package.json, plugin manifests, manifest.json) — or the plugin-manifest gate opted out
• Framework docs read (node_modules/@cyanheads/mcp-ts-core/CLAUDE.md or AGENTS.md)
• Unused echo definitions cleaned up (and unregistered from src/index.ts)
• Skills copied to agent directory (cp -R framework-skills/* .claude/skills/ or equivalent)
• Project structure understood (definitions directories, entry point)
• bun run devcheck passes
• Next: if new server, move on to design-mcp-server to plan the tool surface