# Developer Protocol **Server:** docgen-mcp-server **Version:** 0.4.0 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22` **Engines:** Bun ≥1.4.4, Node ≥24.0.0 **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0 **Zod:** ^4.6.7 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only. --- ## What this server does docgen-mcp-server renders structured agent content into downloadable binary documents. The agent composes the content; the server prints the file a human downloads. Every render is stored tenant-scoped under a TTL and handed back as a `DocumentEnvelope` (a `documentId` + resource URI + inline base64 when small enough); a later call re-fetches it within the TTL. **Surface:** | Definition | Kind | What it does | |:-----------|:-----|:-------------| | `docgen_render_pdf` | tool | HTML / markdown / `{{template}}+data` → PDF (lightweight pdf-lib engine). Sets `degraded` for dropped styling or character replacement on any text surface; smart-punctuation transliteration alone remains non-degraded. | | `docgen_export_spreadsheet` | tool | One or more named row sheets → `.xlsx` (exceljs), with an optional per-column type/format spec. | | `docgen_fill_form` | tool | Fill (and optionally flatten) AcroForm fields from `{ base64 }` or an SSRF-guarded `{ url }`. Reports unmatched names, resolved aliases, checkbox notices, and dropdowns made editable; invalid assignments fail together as `invalid_field_value`. | | `docgen_list_form_fields` | tool | Read-only field discovery: names, types, required flags, choices, stored values, and available labels, length limits, checkbox on-states and first-widget pages. Types: text, checkbox, dropdown, optionList, radioGroup, signature, button. Signatures/buttons are discovery only. No PDF modification or document storage. | | `docgen_get_document` | tool | Re-fetch a previously rendered document by its `documentId`. Pure read; `document_expired` once the TTL lapses. | | `docgen://document/{documentId}` | resource | The stable-URI delivery surface — a byte blob (real mime type) + a JSON metadata block. | | `skill://docgen-guide/SKILL.md` | resource | Published guide for inspecting, filling, reviewing and flattening PDFs, also available through the Skills extension. | **Services (`src/services/document/`):** - `render-service.ts` — the bundled rendering stack (PDF, xlsx, form-fill); enforces the byte ceiling + per-render timeout and classifies failures into the typed reasons the tools declare. - `document-store.ts` — mints opaque ids, persists bytes + metadata via tenant-scoped `ctx.state` under a shared TTL, builds the envelope. A leaked id never crosses the tenant boundary. - `fetch-guard.ts` — HTTPS PDF fetcher shared by both form tools. Vets all resolved addresses at every redirect hop, tries vetted addresses with bounded TCP fallback, preserves TLS identity and Host, and blocks private/loopback/link-local/metadata destinations. Accepts PDF content type or octet-stream bodies starting with `%PDF-`; enforces byte cap, deadline and cancellation. Failures are leak-free `source_unfetchable` errors. - `form-assignments.ts` / `form-inventory.ts` — AcroForm name resolution, assignment validation and read-only field metadata. - `source-pdf.ts` — shared source-pair validation, base64 decoding and guarded URL resolution. - `html-blocks.ts` — reduces HTML/markdown to a linear block model for the lightweight engine (no JS execution, no remote-resource fetch); flags `degraded` for anything it can't render. - `format-envelope.ts` / `types.ts` / `render-types.ts` — the shared `DocumentEnvelope` formatter, domain types, and render-input schemas. **Config (`src/config/server-config.ts`):** the `DOCGEN_*` env vars — document TTL, byte ceiling, render timeout, inline threshold, and the PDF engine (`lightweight` only in v1; `chromium` is reserved and rejected at startup). --- ## Core Rules - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters. - **Use `ctx.log`** for request-scoped logging. No `console` calls. - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly. - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler. - **Secrets in env vars only** — never hardcoded. - **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets. - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them. --- ## Patterns ### Tool ```ts import { tool, z } from '@cyanheads/mcp-ts-core'; import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; import { getDocumentStore } from '@/services/document/document-store.js'; import { formatEnvelopeLines } from '@/services/document/format-envelope.js'; import { DocumentEnvelopeSchema } from '@/services/document/types.js'; export const getDocumentTool = tool('docgen_get_document', { title: 'Get Document', description: 'Re-fetch a previously rendered document by the id a docgen render/export/fill tool returned.', annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, input: z.object({ documentId: z .string() .min(1) .describe('The opaque id returned by an earlier docgen render/export/fill call.'), }), output: z.object({ document: DocumentEnvelopeSchema }), errors: [ { reason: 'document_expired', code: JsonRpcErrorCode.NotFound, when: 'No stored document for that id — expired past its TTL, or never existed.', recovery: 'Re-render with the originating docgen render/export/fill tool; ids are single-render and not reusable.', }, ], async handler(input, ctx) { const store = getDocumentStore(); const resolved = await store.get(input.documentId, ctx); // The framework fills the declared recovery hint on both error surfaces. if (!resolved) { throw ctx.fail('document_expired', `No document found for id ${input.documentId}.`); } return { document: store.buildEnvelope(resolved.meta, resolved.bytes, ctx) }; }, // format() is the markdown twin of structuredContent — both surfaces carry the same envelope. format: (result) => { const d = result.document; return [ { type: 'text', text: formatEnvelopeLines(`Retrieved ${(d.byteSize / 1024).toFixed(1)} KB.`, d) }, ]; }, }); ``` ### Resource ```ts import { resource, z } from '@cyanheads/mcp-ts-core'; import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; import { getDocumentStore } from '@/services/document/document-store.js'; export const documentResource = resource('docgen://document/{documentId}', { name: 'docgen-document', title: 'Rendered Document', description: 'Fetch a rendered document by id — raw bytes as a blob plus a JSON metadata block.', mimeType: 'application/octet-stream', // per-item mime types are set on the returned content params: z.object({ documentId: z .string() .min(1) .describe('The opaque id returned by a docgen render/export/fill tool.'), }), errors: [ { reason: 'document_expired', code: JsonRpcErrorCode.NotFound, when: 'No stored document for that id — expired past its TTL, or never existed.', recovery: 'Re-render with the originating docgen render/export/fill tool; ids are single-render and not reusable.', }, ], async handler(params, ctx) { const resolved = await getDocumentStore().get(params.documentId, ctx); if (!resolved) { throw ctx.fail('document_expired', `No document found for id ${params.documentId}.`); } return resolved; }, }); ``` ### Server config ```ts // src/config/server-config.ts — lazy-parsed, separate from framework config import { z } from '@cyanheads/mcp-ts-core'; import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config'; const ServerConfigSchema = z.object({ documentTtlSeconds: z.coerce .number() .int() .positive() .default(900) .describe('How long a rendered document is retrievable before it expires, in seconds.'), maxDocumentBytes: z.coerce .number() .int() .positive() .default(26_214_400) .describe('Hard ceiling on a single rendered artifact in bytes; exceeding it aborts the render.'), renderTimeoutMs: z.coerce .number() .int() .positive() .default(30_000) .describe('Per-render wall-clock budget in milliseconds; exceeding it aborts the render.'), inlineMaxBytes: z.coerce .number() .int() .nonnegative() .default(5_242_880) .describe('Artifacts at or under this byte size are returned inline as base64; larger ones omit it.'), pdfEngine: z .enum(['lightweight', 'chromium']) .default('lightweight') .describe('Selects the PDF rendering engine. Only `lightweight` is implemented in v1.'), }); let _config: z.infer | undefined; export function getServerConfig() { _config ??= parseEnvConfig(ServerConfigSchema, { documentTtlSeconds: 'DOCGEN_DOCUMENT_TTL_SECONDS', maxDocumentBytes: 'DOCGEN_MAX_DOCUMENT_BYTES', renderTimeoutMs: 'DOCGEN_RENDER_TIMEOUT_MS', inlineMaxBytes: 'DOCGEN_INLINE_MAX_BYTES', pdfEngine: 'DOCGEN_PDF_ENGINE', }); return _config; } ``` `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`DOCGEN_DOCUMENT_TTL_SECONDS`) not the path (`documentTtlSeconds`). Throws `ConfigurationError`, which the framework prints as a clean startup banner — `chromium` is parsed but rejected here until the high-fidelity engine ships. For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables. ### Server identity and instructions `createApp()` uses the bare repository name for both identity fields. The package description and website remain canonical in `package.json` and are not duplicated here: ```ts await createApp({ name: 'docgen-mcp-server', title: 'docgen-mcp-server', instructions: 'Render structured content into downloadable PDF and xlsx documents.', }); ``` `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set. ### Session posture and shutdown Two more `createApp()` options shape how the server runs rather than how it presents itself: ```ts await createApp({ sessionMode: 'stateless', // or { default: 'stateful', require: 'stateful' } setup(core) { startMyWatcher(core.config); }, async teardown() { await stopMyWatcher(); }, }); ``` `sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused. docgen declares `sessionMode: 'stateless'`: no tool calls `ctx.requestInput`, and rendered documents live in tenant-scoped `ctx.state`, not the session store, so they stay retrievable across requests. Switch to `{ default: 'stateful', require: 'stateful' }` if a tool ever gates on `ctx.requestInput`. `teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling). --- ## Context Handlers receive a unified `ctx` object. Key properties: | Property | Description | |:---------|:------------| | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino and `notifications/message` to the client, so treat it as client-visible. | | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts JSON-serializable values; reads return their JSON form (a Date reads as its ISO string). | | `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. | | `ctx.inputs` | Client-supplied responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to the capabilities the client declared. Consent gates redeem a server-stored record bound to the operation, caller, target and content; see `api-context`. | | `ctx.clientCapabilities` | Capabilities declared for this request, or undefined. Decides whether to ask for optional context, never whether to skip consent. | | `ctx.enrich` | Success-path agent context — `.notice()`, `.total()`, `.echo()`, `.truncated()`, or a definition-specific object. Reaches `structuredContent` and `content[]` when the definition declares `enrichment`. | | `ctx.content` | Non-text success content — `.image(data, mimeType)`, `.audio(data, mimeType)`, or a raw block. Prepended to `content[]`; never enters `structuredContent`. | | `ctx.signal` | `AbortSignal` for cancellation. | | `ctx.recoveryFor(reason)` | Typed lookup of the contract `recovery` for a declared reason. Returns `{ recovery: { hint } }` for known reasons, `{}` otherwise. Use for direct handler tests or intentional hint overrides; production tool calls fill declared hints automatically. | | `ctx.requestId` | Framework-generated request ID carried by log records and error envelopes as `data.requestId`. The client's JSON-RPC id is logged separately as `jsonRpcId`. | | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. | --- ## Errors Handlers throw — the framework catches, classifies, and formats. docgen semantic reasons use `ValidationError` (`-32007`): empty_workbook, invalid_source, invalid_sheet_name, invalid_pdf_source, not_a_form, invalid_field_value, template_render_failed, document_too_large. Schema failures stay `InvalidParams` (`-32602`); fetch, timeout and missing-document codes remain unchanged. **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)`. Production tool calls fill `data.recovery.hint` from the matching declared reason when the throw has no hint; both `structuredContent` and `content[]` carry it. Explicit hints override the contract. `recovery` is required (≥ 5 words, lint-validated). Tool error envelopes carry `data.requestId`, and tool error text closes with the request id. Resource parameter rejections (`-32602`) preserve `data: { uri }`; generic protocol errors need not carry a request id. Direct handler calls bypass the tool hint fill, so service and resource tests that assert a hint directly retain `ctx.recoveryFor`. Mark service-thrown entries `thrownBy: 'service'` so `error-contract-unthrown` skips them; docgen's render and fetch services use this pattern. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) need no declaration. ```ts import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; errors: [ { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No item matched the query', recovery: 'Broaden the query or check the spelling and try again.' }, ], async handler(input, ctx) { const item = await db.find(input.id); if (!item) throw ctx.fail('no_match', `No item ${input.id}`); return item; } ``` **Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality. **Fallback (no contract entry fits):** throw via factories or plain `Error`. ```ts // Error factories — explicit code import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors'; throw notFound('Item not found', { itemId }); throw serviceUnavailable('API unavailable', { url }, { cause: err }); // Plain Error — framework auto-classifies from message patterns throw new Error('Item not found'); // → NotFound throw new Error('Invalid query format'); // → ValidationError // McpError — when no factory exists for the code import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' }); ``` See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference. --- ## Structure ```text src/ index.ts # createApp() entry point — wires services, registers the surface config/ server-config.ts # DOCGEN_* env vars (Zod schema) services/ document/ render-service.ts # Bundled render stack (PDF, xlsx, form-fill); byte ceiling + timeout document-store.ts # Tenant-scoped, TTL-bounded artifact store; mints ids, builds the envelope fetch-guard.ts # SSRF-guarded PDF fetcher for the fill_form url source form-assignments.ts # Field-name resolution and aggregate assignment validation form-inventory.ts # Read-only AcroForm constraints and stored values html-blocks.ts # HTML/markdown → linear block model for the lightweight engine format-envelope.ts # Shared DocumentEnvelope formatter render-types.ts # Render-input Zod schemas source-pdf.ts # Shared form-source validation and resolution types.ts # Domain types (DocumentEnvelope, StoredDocumentMeta) mcp-server/ tools/definitions/ render-pdf.tool.ts # docgen_render_pdf export-spreadsheet.tool.ts # docgen_export_spreadsheet fill-form.tool.ts # docgen_fill_form list-form-fields.tool.ts # docgen_list_form_fields get-document.tool.ts # docgen_get_document resources/definitions/ document.resource.ts # docgen://document/{documentId} ``` --- ## Naming | What | Convention | Example | |:-----|:-----------|:--------| | Files | kebab-case with suffix | `search-docs.tool.ts` | | Tool/resource/prompt names | snake_case | `search_docs` | | Directories | kebab-case | `src/services/doc-search/` | | Descriptions | Single string or template literal, no `+` concatenation | `'Search items by query and filter.'` | --- ## Skills Development skills live in `framework-skills/`. Read the matching skill directly, such as `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the registry. Published skills live in root `skills/` and teach tool workflows to agents using the server. Plugin installs, the npm package, Docker, and the MCPB carry this tree. `createApp({ skills: 'skills' })` also serves it to MCP clients. Author and validate published skills with `framework-skills/add-skill/SKILL.md`. **Agent skill directory:** Copy `framework-skills/` into the directory your development agent discovers (Claude Code: `.claude/skills/`, others: equivalent). The `maintenance` skill re-syncs these copies after framework updates. Available skills: | Skill | Purpose | |:------|:--------| | `setup` | Post-init project orientation | | `design-mcp-server` | Design tool surface, resources, and services for a new server | | `add-tool` | Scaffold a new tool definition | | `add-app-tool` | Scaffold an MCP App tool + paired UI resource | | `add-resource` | Scaffold a new resource definition | | `add-prompt` | Scaffold a new prompt definition | | `add-skill` | Author and validate a published skill in root `skills/` | | `add-service` | Scaffold a new service integration | | `add-test` | Scaffold test file for a tool, resource, or service | | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues | | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions | | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation | | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase | | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping | | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode | | `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only | | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` | | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs | | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents | | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI | | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI | | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns | | `api-auth` | Auth modes, scopes, JWT/OAuth | | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in | | `api-config` | AppConfig, parseConfig, env vars | | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input | | `api-errors` | McpError, JsonRpcErrorCode, error patterns | | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` | | `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in | | `api-services` | LLM, Speech, Graph services | | `api-testing` | createMockContext, test patterns | | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers | | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules | | `api-workers` | Cloudflare Workers runtime | **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase. When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`). --- ## Commands **Runtime:** Scripts use Bun's native TypeScript execution — `bun run ` is the standard invocation. `npm run ` also works (npm delegates to bun). | Command | Purpose | |:--------|:--------| | `bun run build` | Compile TypeScript | | `bun run rebuild` | Clean + build | | `bun run clean` | Remove build artifacts | | `bun run devcheck` | Lint + format + typecheck + security + changelog sync | | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update `, then `bun dedupe` | | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update `, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` | | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) | | `bun run lint:packaging` | Check env-var parity, `.mcpbignore` coverage, plugin manifests and published skills | | `bun run list-skills` | Print the skill registry | | `bun run tree` | Generate directory structure doc | | `bun run format` | Auto-fix formatting (safe fixes only) | | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior | | `bun run test` | Run all Vitest projects | | `bun run test:coverage` | Run all Vitest projects with Istanbul coverage | | `bun run start:stdio` | Production mode (stdio) | | `bun run start:http` | Production mode (HTTP) | | `bun run changelog:build` | Regenerate `CHANGELOG.md` from per-version files | | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) | | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install | **CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it. --- ## Bundling `bun run bundle` produces a stdio `.mcpb` extension for Claude Desktop. List build-only and local files in `.mcpbignore` with root-anchored patterns such as `/docs/`. Root `skills/` ships in the bundle. After packing, `scripts/clean-mcpb.ts` prunes dev dependencies, agent docs at dependency roots, platform-specific native bindings, node-gyp build metadata and framework build files. Nested runtime `skills/` modules stay in the bundle. **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`. **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`. --- ## Changelog Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/.x/.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `npm run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `npm run changelog:build` — devcheck hard-fails on drift; never hand-edit it. Each per-version file opens with YAML frontmatter: ```markdown --- summary: "One-line headline, ≤350 chars" # required — powers the rollup index breaking: false # optional — true flags breaking changes security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump --- # 0.1.0 — YYYY-MM-DD ... ``` `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's own source code, never for a dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`. `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say. **Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers. **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference. --- ## Publishing **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. --- ## Imports ```ts // Framework — z is re-exported, no separate zod import needed import { tool, z } from '@cyanheads/mcp-ts-core'; import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; // Server's own code — via path alias import { getMyService } from '@/services/my-domain/my-service.js'; ``` --- ## Checklist - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`) - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`. - [ ] JSDoc `@fileoverview` + `@module` on every file - [ ] `ctx.log` for logging, `ctx.state` for storage - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data - [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields - [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields - [ ] Registered in `createApp()` arrays (directly or via barrel exports) - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing` - [ ] Keep the root Agent Plugins manifests `plugin.json` and `mcp.json` aligned with package metadata and the fixed stdio environment. Keep user-supplied values in the existing Claude and Codex overlays. - [ ] Validate any published `skills/` tree with `lint:packaging` and field-test its workflows. - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.