@cyanheads/mcp-ts-core 0.1.4 → 0.1.8

package/skills/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "2.0"
   audience: external
   type: workflow
 ---
@@ -69,19 +69,160 @@ This is the raw material. Not everything becomes a tool.
 **Common traps:**
 
 - **Everything-is-a-tool**: "Fetch by ID" with no other params is a resource. Resources let clients inject context without a tool call.
-- **CRUD explosion**: Don't map every REST endpoint to a tool. One `update_task` beats `update_task_status` + `assign_task` + `update_task_fields`.
+- **CRUD explosion**: Don't map every REST endpoint to a tool. Related operations on the same noun often belong in one tool with an `operation`/`mode` parameter (see Step 4).
 - **Ignoring resources**: If the server has reference data, schemas, or entities the LLM should read — expose them as resources.
+- **1:1 endpoint mirroring**: API endpoints are designed for programmatic consumers. LLM tools should be designed for workflows — what an agent is *trying to accomplish*, not what HTTP calls happen under the hood.
 
 ### 4. Design Tools
 
-For each tool:
+This is the highest-leverage step. Tool definitions — names, descriptions, parameters, output schemas — are the **entire interface contract** the LLM reads to decide whether and how to call a tool. Every field is context. Design accordingly.
+
+#### Think in workflows, not endpoints
+
+The unit of a tool is a *useful action*, not an API call. Ask: "What is the agent trying to accomplish?" — not "What endpoints does the API have?"
+
+A single tool can call multiple APIs internally, apply local filtering, reshape data, and return enriched results. The LLM doesn't know or care about the underlying calls.
+
+**Consolidation via operation/mode enum.** When a domain noun has several related operations that share parameters, consolidate into one tool with a discriminated parameter. This keeps the tool surface small and lets the LLM discover all capabilities in one place.
+
+```ts
+// One tool for all branch operations — not five separate tools
+const gitBranch = tool('git_branch', {
+  description: 'Manage branches: list, show current, create, delete, or rename.',
+  input: z.object({
+    operation: z.enum(['list', 'create', 'delete', 'rename', 'show-current'])
+      .describe('Branch operation to perform.'),
+    name: z.string().optional().describe('Branch name (required for create/delete/rename).'),
+    newName: z.string().optional().describe('New name (required for rename).'),
+  }),
+  // ...
+});
+```
+
+```ts
+// Workflow tool — search + local filter pipeline, not a raw API proxy
+const findEligibleStudies = tool('clinicaltrials_find_eligible_studies', {
+  description: 'Matches patient demographics and medical profile to eligible clinical trials. '
+    + 'Filters by age, sex, conditions, location, and healthy volunteer status. '
+    + 'Returns ranked list of matching studies with eligibility explanations.',
+  // handler: listStudies() → filter by eligibility → rank by location proximity → slice
+});
+```
+
+**When to consolidate vs. split:**
+
+| Consolidate (one tool) | Split (separate tools) |
+|:------------------------|:-----------------------|
+| Operations share the same noun and most parameters | Operations have fundamentally different inputs/outputs |
+| Related CRUD on a single entity | Read-only lookup vs. multi-step workflow |
+| Agent would naturally think of them together | Agent would use them in different contexts |
+
+There is no fixed ceiling on tool count — tools need to earn their keep, but don't artificially limit the surface. If the domain genuinely has 20 distinct workflows, expose 20 tools.
+
+#### Tool descriptions
+
+The description is the LLM's primary signal for tool selection. It must answer: *what does this do, and when should I use it?*
+
+- **Be concrete about capability.** "Search for clinical trial studies using queries and filters" beats "Interact with studies."
+- **Include operational guidance when it matters.** If the tool has prerequisites, constraints, or gotchas the LLM needs to know, say so in the description. Don't add boilerplate workflow hints when the tool is self-explanatory.
+
+```ts
+// Good — describes a prerequisite the LLM must know
+description: 'Set the session working directory for all git operations. '
+  + 'This allows subsequent git commands to omit the path parameter.'
+
+// Good — self-explanatory, no workflow hints needed
+description: 'Show the working tree status including staged, unstaged, and untracked files.'
+
+// Good — warns about constraints
+description: 'Fetches trial results data for completed studies. '
+  + 'Only available for studies where hasResults is true.'
+```
+
+Context-dependent: a simple read-only tool needs a one-line description. A tool with prerequisites, modes, or non-obvious behavior needs more. Match depth of description to complexity of tool.
+
+#### Parameter descriptions
+
+Every `.describe()` is prompt text the LLM reads. Parameters should convey: what the value is, what it affects, and (where non-obvious) how to use it well.
+
+- **Constrain the type.** Enums and literals over free strings. Regex validation for formatted IDs. Ranges for numeric bounds.
+- **Explain costs and tradeoffs** when a parameter choice has meaningful consequences.
+- **Name alternative approaches** when a simpler path exists.
+- **Include format patterns** for structured values, but don't pad descriptions with redundant examples.
+
+```ts
+// Good — explains cost, recommends action, names the alternative
+fields: z.array(z.string()).optional()
+  .describe('Specific fields to return (reduces payload size). '
+    + 'STRONGLY RECOMMENDED — without this, the full study record (~70KB each) is returned. '
+    + 'Use full data only when you need detailed eligibility criteria, locations, or results.'),
+
+// Good — explains what the flag does AND how to override
+autoExclude: z.boolean().default(true)
+  .describe('Automatically exclude lock files and generated files from diff output '
+    + 'to reduce context bloat. Set to false if you need to inspect these files.'),
+
+// Good — names the format and gives one example
+nctIds: z.union([z.string(), z.array(z.string()).max(5)])
+  .describe('A single NCT ID (e.g., "NCT12345678") or an array of up to 5 NCT IDs to fetch.'),
+```
+
+#### Output design
+
+The output schema and `format` function control what the LLM reads back. Design for the agent's *next decision*, not for a UI or an API consumer.
+
+**Principles:**
+
+- **Include IDs and references for chaining.** If the agent might act on a result, return the identifiers it needs for follow-up tool calls.
+- **Curate vs. pass-through depends on domain.** Medical/scientific data — don't trim fields that could alter correctness. CRUD responses — return what the agent needs, not the full API payload. Match fidelity to consequence.
+- **Surface what was done, not just results.** After a write operation, include the new state. (`git_commit` auto-includes post-commit `git status`. The LLM sees the repo state without an extra round trip.)
+- **Communicate filtering.** If the tool silently excluded content, tell the LLM what was excluded and how to get it back. The agent can't act on what it doesn't know about.
+
+```ts
+// git_diff — when lock files are filtered, the output tells the LLM
+output: z.object({
+  diff: z.string().describe('Unified diff output.'),
+  excludedFiles: z.array(z.string()).optional()
+    .describe('Files automatically excluded from the diff (e.g., lock files). '
+      + 'Call again with autoExclude=false to include them.'),
+}),
+```
+
+- **Truncate large output with counts.** When a list exceeds a reasonable display size, show the top N and append "...and X more". Don't silently drop results.
+- **Use the `format` function for readable summaries** while keeping the full structured data in the output object for programmatic use.
+
+#### Error messages as LLM guidance
+
+When a tool throws, the error message is the agent's only signal for recovery. A good error message tells the LLM *what happened and what to do next*.
+
+```ts
+// Bad — the LLM has no recovery path
+throw new Error('Not found');
+
+// Good — names both resolution options
+"No session working directory set. Please specify a 'path' or use 'git_set_working_dir' first."
+
+// Good — structured hint in error data
+throw new McpError(JsonRpcErrorCode.Forbidden,
+  "Cannot perform 'reset --hard' on protected branch 'main' without explicit confirmation.",
+  { branch: 'main', operation: 'reset --hard', hint: 'Set the confirmed parameter to true to proceed.' },
+);
+```
+
+Think about the common failure modes for each tool and write error messages that guide recovery. This is part of the tool's interface design, not an afterthought.
+
+#### Design table
+
+Summarize each tool:
 
 | Aspect | Decision |
 |:-------|:---------|
 | **Name** | `snake_case`, verb-noun: `search_papers`, `create_task`. Prefix with server domain if ambiguous. |
-| **Granularity** | One tool per user intent, not per API call. A tool can call multiple APIs internally. |
-| **Input schema** | What the LLM provides. `.describe()` on every field. Prefer enums/literals over free strings. Optional fields with defaults over required where reasonable. |
-| **Output schema** | What the LLM needs to see. Curate — not a raw API dump. Design for the LLM's next decision, not for a UI. |
+| **Granularity** | One tool per user-meaningful workflow, not per API call. Consolidate related operations with `operation`/`mode` enum. |
+| **Description** | Concrete capability statement. Add operational guidance (prerequisites, constraints, gotchas) when non-obvious. |
+| **Input schema** | `.describe()` on every field. Constrained types (enums, literals, regex). Explain costs/tradeoffs of parameter choices. |
+| **Output schema** | Designed for the LLM's next action. Include chaining IDs. Communicate filtering. Post-write state where useful. |
+| **Error messages** | Name what went wrong and what the LLM should do about it. Include hints for common recovery paths. |
 | **Annotations** | `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Helps clients auto-approve safely. |
 | **Auth scopes** | `tool:noun:read`, `tool:noun:write`. Skip for read-only or stdio-only servers. |
 
@@ -180,10 +321,13 @@ Execute the plan using the scaffolding skills:
 - [ ] External APIs/dependencies researched and verified (docs fetched, SDKs identified)
 - [ ] Domain operations mapped (nouns + verbs)
 - [ ] Each operation classified as tool, resource, prompt, or excluded
-- [ ] Tool names follow verb-noun `snake_case` convention
-- [ ] Tool outputs designed for LLM consumption, not raw API passthrough
+- [ ] Related operations consolidated (operation/mode enum) — not one tool per endpoint
+- [ ] Tool descriptions are concrete and include operational guidance where non-obvious
+- [ ] Parameter `.describe()` text explains what the value is, what it affects, and tradeoffs
+- [ ] Input schemas use constrained types (enums, literals, regex) over free strings
+- [ ] Output schemas designed for LLM's next action — chaining IDs, post-write state, filtering communicated
+- [ ] Error messages guide recovery — name what went wrong and what to do next
 - [ ] Annotations set correctly (`readOnlyHint`, `destructiveHint`, etc.)
-- [ ] Input schemas use constrained types (enums, literals) where the domain allows
 - [ ] Resource URIs use `{param}` templates, pagination planned for large lists
 - [ ] Service layer planned (or explicitly skipped with reasoning)
 - [ ] Server config env vars identified

package/skills/polish-docs-meta/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: polish-docs-meta
+description: >
+  Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: workflow
+---
+
+## When to Use
+
+- Server implementation is functionally complete (tools, resources, prompts, services all working)
+- `bun run devcheck` passes, tests pass
+- You're preparing for first commit, first release, or making the repo public
+- User says "polish", "polish docs", "finalize", "make it ship-ready", "clean up docs", or similar
+- Re-running after adding/removing tools, resources, or other surface area changes
+
+Prefer running after implementation is complete, but safe to re-run at any point — steps are idempotent.
+
+## Prerequisites
+
+- [ ] All tools/resources/prompts implemented and registered
+- [ ] `bun run devcheck` passes
+- [ ] Tests pass (`npm test`)
+
+If these aren't met, address them first.
+
+## Steps
+
+### 1. Audit the Surface Area
+
+Read all tool, resource, and prompt definitions. Build a mental model of what the server actually does — names, descriptions, input/output shapes, auth scopes. This inventory drives every document below.
+
+Read:
+- `src/index.ts` (what's registered in `createApp()`)
+- All files in `src/mcp-server/tools/definitions/`
+- All files in `src/mcp-server/resources/definitions/`
+- All files in `src/mcp-server/prompts/definitions/`
+- All files in `src/services/` (if any)
+- `src/config/server-config.ts` (if any)
+
+Capture: tool count, resource count, prompt count, service count, required env vars.
+
+### 2. README.md
+
+Read `references/readme.md` for structure and conventions. If `README.md` doesn't exist, create it from scratch. If it exists, diff the current content against the audit — update tool/resource/prompt tables, env var lists, and descriptions to match the actual surface area. Don't rewrite sections that are already accurate.
+
+### 3. Agent Protocol (CLAUDE.md / AGENTS.md)
+
+Update the project's agent protocol file to reflect the actual server.
+
+Read `references/agent-protocol.md` for the full update checklist, then review the current file and address what's stale or missing:
+
+- If a "First Session" onboarding block is still present, remove it
+- If example patterns still use generic/template names (e.g., `searchItems`, `itemData`), replace with real definitions from this server
+- If server-specific skills were added, update the skills table
+- Verify the structure diagram matches the actual directory layout
+- If custom scripts were added to `package.json`, update the commands table
+
+### 4. `.env.example`
+
+Compare `.env.example` against the server config Zod schema. Add any missing server-specific vars with a comment and default (if any). Remove vars for features that no longer exist. Group by category. Preserve existing framework vars that are still relevant.
+
+### 5. `package.json` Metadata
+
+Check for empty or placeholder metadata fields. Read `references/package-meta.md` for which fields matter and why. Fill in anything still missing — skip fields that are already correct.
+
+Key fields: `description`, `repository`, `author`, `homepage`, `bugs`, `keywords`.
+
+### 6. `CHANGELOG.md`
+
+If `CHANGELOG.md` doesn't exist, create it with an initial entry. If it exists, verify the latest entry reflects the current state:
+
+```markdown
+# Changelog
+
+## 0.1.0 — YYYY-MM-DD
+
+Initial release.
+
+### Added
+- [list tools, resources, prompts, key capabilities]
+```
+
+Use a concrete version and date. Never `[Unreleased]`.
+
+### 7. `LICENSE`
+
+Confirm a license file exists. If not, ask the user which license to use (default: Apache-2.0, matching the scaffolded `package.json`). Create the file.
+
+### 8. `Dockerfile`
+
+If a `Dockerfile` exists, verify the OCI labels and runtime config match the actual server:
+
+- `org.opencontainers.image.title` matches the package name
+- `org.opencontainers.image.description` is filled in (not empty placeholder)
+- `org.opencontainers.image.source` points to the real repository URL (add if missing)
+- Log directory path in `mkdir` and `LOGS_DIR` uses the correct server name
+
+If no `Dockerfile` exists and the server is deployed via HTTP transport, consider scaffolding one — the template is available via `npx @cyanheads/mcp-ts-core init`.
+
+### 9. `docs/tree.md`
+
+Regenerate the directory structure:
+
+```bash
+bun run tree
+```
+
+Review the output for anything unexpected (leftover files, missing directories).
+
+### 10. Final Verification
+
+Run the full check suite one last time:
+
+```bash
+bun run devcheck
+npm test
+```
+
+Both must pass clean.
+
+## Checklist
+
+- [ ] Surface area audited — tool/resource/prompt/service inventory built
+- [ ] `README.md` accurate — tool/resource tables, config, descriptions match actual code
+- [ ] Agent protocol file accurate — no stale template content, real examples, structure matches reality
+- [ ] `.env.example` in sync with server config schema
+- [ ] `package.json` metadata complete (`description`, `repository`, `author`, `keywords`)
+- [ ] `CHANGELOG.md` exists with current entry
+- [ ] `LICENSE` file present
+- [ ] `Dockerfile` OCI labels and runtime config accurate (if present)
+- [ ] `docs/tree.md` regenerated
+- [ ] `bun run devcheck` passes
+- [ ] `npm test` passes

package/skills/polish-docs-meta/references/agent-protocol.md

@@ -0,0 +1,78 @@
+# Finalizing the Agent Protocol File
+
+Guide for updating the project's `CLAUDE.md` or `AGENTS.md` to reflect the actual server. The file may still contain scaffolded template content (onboarding blocks, generic examples) or may have been partially updated — review the current state and address what's stale or missing.
+
+## What to Update
+
+### 1. Strip the "First Session" Block (if present)
+
+The scaffolded template includes a `## First Session` section with one-time onboarding steps. If this section is still present, delete it entirely (header through the `---` separator after it). If it's already been removed, skip this step.
+
+**What it looks like:**
+
+```markdown
+## First Session
+
+> **Remove this section** from CLAUDE.md / AGENTS.md after completing these steps.
+
+1. **Read the framework API** — ...
+2. **Run the `setup` skill** — ...
+3. **Design the server** — ...
+
+---
+```
+
+### 2. Replace Example Patterns with Real Definitions
+
+Check the Patterns section for generic template examples (e.g., `searchItems`, `itemData`, `reviewCode`). If still present, replace them with actual tool/resource/prompt definitions from the server — or the most representative ones if there are many. If the examples already reflect real definitions, verify they're still accurate.
+
+Pick examples that:
+- Show the most common or important capability
+- Demonstrate any non-trivial patterns the server uses (e.g., `ctx.state`, `ctx.elicit`, `task: true`, services)
+- Include a handler with real business logic, not just passthrough
+
+Keep 1-2 examples per primitive type (tool, resource, prompt). Don't list every definition — the README handles that.
+
+### 3. Update the Structure Diagram
+
+Compare the structure diagram against the actual directory layout. If it still reflects the generic template or has fallen out of date:
+
+- Add directories/files that exist but aren't listed (e.g., `config/server-config.ts`, service directories, `worker.ts`)
+- Remove entries for directories that don't exist (e.g., if no prompts were added, remove the prompts line)
+- Verify nesting and naming match reality
+
+### 4. Update the Context Table
+
+Review the `ctx` feature table. Remove rows for features the server doesn't use (e.g., `ctx.elicit`, `ctx.sample` if no tools call them). Add any custom context usage that's become important. The table should reflect what this server actually uses, not the full framework surface.
+
+### 5. Update Server Config Example
+
+If the server has a `server-config.ts`, check whether the Patterns section still shows a generic config example. If so, replace it with the actual schema (or a representative subset). If the server has no custom config, remove the config example entirely.
+
+### 6. Update the Skills Table
+
+Check for server-specific skills added to `skills/` that aren't in the table yet. Add any missing entries. Remove framework skills the server doesn't use (rare — most are useful).
+
+### 7. Update the Commands Table
+
+Compare the commands table against `package.json` scripts. Add any custom scripts that are missing. Remove or rename entries that no longer match. The table should reflect the current `scripts` block.
+
+### 8. Update the Checklist
+
+Review the checklist for completeness. Add server-specific items that are missing (e.g., required env vars, external service dependencies, custom naming conventions). Remove items that don't apply to this server.
+
+## What to Preserve
+
+These sections should remain intact unless you have a specific reason to change them:
+
+- **Core Rules** — universal to all servers built on the framework
+- **Errors section** — the three-level escalation pattern is universal
+- **Imports section** — keep unless the alias convention was changed
+- **Framework reference pointer** — the line directing agents to `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
+
+## Pitfalls
+
+- Don't duplicate the full framework CLAUDE.md into the project file. The project file covers server-specific conventions; the framework file covers the API. The pointer at the top connects them.
+- Don't remove `## Core Rules` even if it seems obvious — agents read this fresh each session.
+- Don't add implementation details that change frequently. The agent protocol file should be stable — update it when the server's shape changes, not on every commit.
+- Don't assume this is a one-time pass. The protocol file should be revisited whenever the server's surface area changes (tools added/removed, new services, config changes).

package/skills/polish-docs-meta/references/package-meta.md

@@ -0,0 +1,63 @@
+# package.json Metadata
+
+Fields that may still be empty or generic from scaffolding. Check each one and fill in anything that's missing or placeholder.
+
+## Fields to Check
+
+| Field | Default / Scaffolded | What It Should Be |
+|:------|:---------------------|:------------------|
+| `name` | `{{PACKAGE_NAME}}` (substituted by init) | Verify it's correct. Use scoped name if publishing (`@org/my-server`). |
+| `version` | `0.1.0` | Keep for initial development. Bump via the `release` skill. |
+| `description` | `""` (empty) | One sentence: what the server does and what it wraps. Appears on npm and in `npm search`. |
+| `repository` | _(often missing)_ | `{ "type": "git", "url": "https://github.com/org/repo.git" }` |
+| `homepage` | _(often missing)_ | Repository URL or docs URL. |
+| `bugs` | _(often missing)_ | `{ "url": "https://github.com/org/repo/issues" }` |
+| `author` | _(often missing)_ | `"Name <email>"` or `{ "name": "...", "email": "..." }` |
+| `keywords` | `["mcp", "mcp-server", "model-context-protocol"]` | Add domain-specific keywords. Keep the MCP ones. |
+| `license` | `Apache-2.0` | Change if using a different license. Must match the LICENSE file. |
+
+## Fields That Should Be Correct
+
+These are set by `init` and generally don't need changes. Verify they're present and correct:
+
+| Field | Value | Why |
+|:------|:------|:----|
+| `type` | `"module"` | ESM — required by the framework |
+| `main` | `"dist/index.js"` | Entry point after build |
+| `types` | `"dist/index.d.ts"` | TypeScript declarations |
+| `files` | `["dist/"]` | What npm publishes |
+| `engines` | `{ "node": ">=22.0.0" }` | Minimum Node version |
+| `scripts` | _(various)_ | Build, dev, test scripts |
+| `dependencies` | `@cyanheads/mcp-ts-core`, `pino-pretty` | Core framework + log formatting |
+
+## Keywords
+
+Good keywords improve npm discoverability. Include:
+
+1. The base MCP keywords (already scaffolded): `mcp`, `mcp-server`, `model-context-protocol`
+2. The domain: `project-management`, `task-tracking`, `acme-api`
+3. The transport if non-default: `http`, `sse`, `cloudflare-workers`
+
+Example:
+
+```json
+"keywords": [
+  "mcp",
+  "mcp-server",
+  "model-context-protocol",
+  "acme",
+  "project-management",
+  "task-tracking"
+]
+```
+
+## Publishing Checklist
+
+If publishing to npm, also verify these (skip for private/internal servers):
+
+- `name` doesn't conflict with an existing package
+- `publishConfig.access` is `"public"` (already set by init for scoped packages)
+- `files` includes everything needed at runtime (`dist/` is correct for most servers)
+- `bin` is set if the server should be runnable via `npx` (add `"bin": { "my-server": "dist/index.js" }`)
+
+The `bin` field is the most commonly missed one. Without it, `npx my-server` won't work — the client config must use `node dist/index.js` instead.

package/skills/polish-docs-meta/references/readme.md

@@ -0,0 +1,183 @@
+# README.md Conventions for MCP Servers
+
+Structure and content guide for creating or updating a README for an MCP server built on `@cyanheads/mcp-ts-core`. If a README already exists, use this as a reference to audit and improve it — don't blindly rewrite sections that are already accurate.
+
+## Structure
+
+Use this section order. Omit sections that don't apply (e.g., skip Docker if the server doesn't ship a container image).
+
+```text
+# {Server Name}
+
+One-line description of what the server does.
+
+## Overview
+## Features (tool/resource table)
+## Installation
+## Configuration
+## Usage
+## Docker (if Dockerfile present)
+## Development
+## License
+```
+
+## Section Guide
+
+### Title + Description
+
+The `h1` is the server name. Follow it with a single sentence or short paragraph explaining what the server wraps and who it's for. Include badges if publishing to npm.
+
+```markdown
+# my-mcp-server
+
+MCP server for the Acme API — exposes project management, task tracking, and team operations to LLM clients.
+
+[![npm](https://img.shields.io/npm/v/my-mcp-server)](https://www.npmjs.com/package/my-mcp-server)
+```
+
+### Overview
+
+2-4 sentences expanding on the description. What system does it wrap? What can the LLM do through it? What's the value proposition?
+
+Avoid marketing language. State what it does, not why it's amazing.
+
+### Features
+
+A table of tools and resources is the most useful thing a README can provide. It tells both humans and LLMs exactly what the server exposes.
+
+**Tools table:**
+
+```markdown
+### Tools
+
+| Tool | Description | Key Inputs |
+|:-----|:------------|:-----------|
+| `search_projects` | Search projects by name or status | `query`, `status?` |
+| `create_task` | Create a new task in a project | `projectId`, `title`, `description?` |
+| `update_task` | Update task status or assignment | `taskId`, `status?`, `assignee?` |
+```
+
+**Resources table (if any):**
+
+```markdown
+### Resources
+
+| URI Pattern | Description |
+|:------------|:------------|
+| `acme://projects/{projectId}` | Project details by ID |
+| `acme://tasks/{taskId}` | Task details by ID |
+```
+
+**Prompts table (if any):**
+
+```markdown
+### Prompts
+
+| Prompt | Description |
+|:-------|:------------|
+| `project_summary` | Summarize a project's status and open tasks |
+```
+
+Derive these tables directly from the actual tool/resource/prompt definitions. Use the real names and descriptions from the Zod schemas.
+
+### Installation
+
+Show the install command and minimum viable configuration.
+
+```markdown
+## Installation
+
+\`\`\`bash
+npm install my-mcp-server
+\`\`\`
+
+### MCP Client Configuration
+
+Add to your MCP client config (e.g., `claude_desktop_config.json`):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "my-mcp-server": {
+      "command": "npx",
+      "args": ["my-mcp-server"],
+      "env": {
+        "ACME_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+\`\`\`
+```
+
+If the server supports HTTP transport, show that config too.
+
+### Configuration
+
+Table of environment variables. Include framework vars only if the server uses non-default values.
+
+```markdown
+## Configuration
+
+| Variable | Required | Default | Description |
+|:---------|:---------|:--------|:------------|
+| `ACME_API_KEY` | Yes | — | API key for the Acme service |
+| `ACME_BASE_URL` | No | `https://api.acme.com` | API base URL |
+| `MCP_TRANSPORT_TYPE` | No | `stdio` | Transport: `stdio` or `http` |
+| `MCP_LOG_LEVEL` | No | `info` | Log level |
+```
+
+Source this from the server config Zod schema and `.env.example`.
+
+### Usage
+
+Brief examples of how an LLM (or human via MCP client) would use the server. Show 1-2 tool calls with example inputs/outputs if it helps understanding. Keep it short — the tool descriptions should be self-explanatory.
+
+### Development
+
+Commands table for contributors.
+
+```markdown
+## Development
+
+| Command | Purpose |
+|:--------|:--------|
+| `npm run build` | Compile TypeScript |
+| `npm run dev:stdio` | Dev mode (stdio, watch) |
+| `npm run dev:http` | Dev mode (HTTP, watch) |
+| `bun run devcheck` | Lint + format + typecheck |
+| `npm test` | Run tests |
+```
+
+### Docker
+
+Include only if a `Dockerfile` exists. Show how to build and run the image.
+
+```markdown
+## Docker
+
+\`\`\`bash
+docker build -t my-mcp-server .
+docker run -p 3010:3010 -e MY_API_KEY=your-key my-mcp-server
+\`\`\`
+```
+
+Keep it minimal — the Dockerfile's defaults handle transport, port, and log config. Only document env vars the user must provide.
+
+### License
+
+One line referencing the LICENSE file.
+
+```markdown
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE) for details.
+```
+
+## Principles
+
+- **Accuracy over aspiration.** Only document what exists. Don't describe planned features as if they're implemented.
+- **Tables over prose** for structured data (tools, config, commands). Scannable and diff-friendly.
+- **Real names from code.** Tool names, env vars, and URIs should match the source exactly. Copy from the definitions, don't paraphrase.
+- **No badges unless publishing.** Badges for unpublished packages are noise.
+- **Keep it current.** The README should be updated whenever tools are added or removed. The `polish-docs-meta` skill handles both initial creation and subsequent updates.