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: ```text 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/ # build, clean, devcheck, lint-mcp, list-skills, build-changelog, tree, check-docs-sync 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: ```text 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:** ```bash 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