Skip to content
Skills Library
Programming · Learning & explanation

setup

/setup

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.

Repository
mcp-ts-core ↗
Licence
Apache-2.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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.

Original author 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.

How it works

  1. Context
  2. Agent Protocol File
  3. Project Structure
  4. Scaffolded Echo Definitions
  5. Conventions
  6. Skill Sync
  7. Project Scaffolding
  8. Changelog Convention
  9. Next Steps
  10. Checklist
Original SKILL.md headings · 173 lines, 1,754 words
SKILL.md preview
---
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.13"
  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:

```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/                                        # 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:

```text
skills/                                         # Skills the server publishes to the agents that use it — `add-skill`; usually none
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. Root `skills/` is for those — the skills the server publishes, written by hand with the `add-skill` skill. Neither `init` nor this sync nor `maintenance` creates or modifies it.

**Don't edit the framework's skills in `framework-skills/`** (`SKILL.md` and `references/` of any skill carrying `metadata.audience: external`). They are 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`, or in a development skill of the server's own, which leaves out `metadata.audience`.

**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` |
   | `plugin.json` | `description` | `lint:packaging` |

   Fill the rest of the same blocks while you are in them — `package.json` `description` and `repository.url`, all three 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`. Root `mcp.json` keeps only the fixed `env` it shares with `.codex-plugin/mcp.json`: Agent Plugins has no credential mechanism. Codex ≥ 0.150.0 starts the server from root `mcp.json` and merges the overlay's `env_vars` into it only while `.codex-plugin/plugin.json` keeps `"mcpServers": "./.codex-plugin/mcp.json"`; Claude Code keeps reading `.claude-plugin/plugin.json`. Don't document a keyed server as working in Cursor, GitHub Copilot, VS Code, or Kiro.

   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

Versions

RepositoryScoreLicence
This page · cyanheads/mcp-ts-core100Apache-2.0
HwangSlater/harness-fit100MIT
nesquikm/dev-process-toolkit100MIT
userKael/rastro100MIT
als-apg/osprey100BSD-3-Clause
dedujeong/gemba100Apache-2.0
eigenwise/eigenwise-toolshed100MIT
awrshift/agent-memory-kit100MIT
lifecycle-innovations-limited/claude-ops100MIT

Identical content appears in 11 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version f89338f977a1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100add-export
    Add a new subpath export to the @cyanheads/mcp-ts-core package. Use when creating a new public API surface that consumers import from a dedicated subpath (e.g., @cyanheads/mcp-ts-core/newutil).
  • 100report-issue-framework
    File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
  • 100report-issue-framework
    File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
  • 95api-utils
    API reference for all utilities exported from `@cyanheads/mcp-ts-core/utils`. Use when looking up utility method signatures, options, peer dependencies, or usage patterns.
  • 95api-utils
    API reference for all utilities exported from `@cyanheads/mcp-ts-core/utils`. Use when looking up utility method signatures, options, peer dependencies, or usage patterns.
  • 100project-check
    Existing project health scan — audits Infrastructure, Security, Quality, and Harness setup. Read-only. Use when: '/project-check', 'project health check', 'project audit', 'what\\'s missing', 'analyze my project', 'check setup'. Ends with /project-init and /setup…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.