# Developer Protocol **Server:** tvmaze-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's Next? When the user asks what's next or needs direction, suggest options based on the current project state. Common next steps: 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design 3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills 4. **Add services** — scaffold domain service integrations using the `add-service` skill 5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points 7. **Run `devcheck`** — lint, format, typecheck, and security audit 8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation 9. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping 10. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest` Tailor suggestions to what's actually missing or stale — don't recite the full list every time. --- ## 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 Trimmed from `src/mcp-server/tools/definitions/search-shows.tool.ts` — the file is the source of truth; the notice branches are condensed here. It is the fullest example on the surface: a service call, a typed error contract, enrichment, and `format()`. ```ts import { tool, z } from '@cyanheads/mcp-ts-core'; import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; import { getTvmazeService } from '@/services/tvmaze/tvmaze-service.js'; import { field, inline, ShowSummary, showSummaryLines, yearRange } from './shared-schemas.js'; /** The source's fixed ceiling on `/search/shows`. There is no paging past it. */ const SEARCH_RESULT_CAP = 10; export const searchShows = tool('tvmaze_search_shows', { description: 'Search television shows by title and return up to 10 matches, each with its network or streaming service, production status, genres, rating, and ids in other catalogs. Matching is fuzzy, so small typos still resolve. The result set is hard-capped at 10 by the source and cannot be paged — narrow the title to reach an eleventh match. To go the other way, from an IMDb or TheTVDB id to a show, use tvmaze_lookup_show.', annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }, errors: [ { reason: 'search_unavailable', code: JsonRpcErrorCode.ServiceUnavailable, when: 'TVmaze search did not respond after retries.', recovery: 'Wait a few seconds and call tvmaze_search_shows again; the source rate-limits search requests.', retryable: true, thrownBy: 'service', }, ], input: z.object({ query: z .string() .trim() .min(1) .describe( 'Show title or title fragment. Matched fuzzily against every show title in the database, so minor misspellings still resolve.', ), }), output: z.object({ shows: z .array( ShowSummary.extend({ match_score: z .number() .describe( 'Relevance score assigned by the source search. Higher is a closer title match; values are comparable only within one result set.', ), }).describe('A matching show with the relevance score the source assigned it.'), ) .describe('Matching shows, best match first. At most 10.'), }), enrichment: { effectiveQuery: z.string().describe('The query as submitted upstream.'), truncated: z .boolean() .optional() .describe("True when the source's fixed ten-result ceiling was reached."), shown: z.number().optional().describe('Number of shows returned.'), cap: z.number().optional().describe('The result ceiling the source applied.'), notice: z.string().optional().describe('Guidance when nothing matched or the ceiling was hit.'), }, async handler(input, ctx) { const shows = await getTvmazeService().searchShows(input.query, ctx); ctx.log.info('Show search completed', { query: input.query, matches: shows.length }); ctx.enrich.echo(input.query); if (shows.length === SEARCH_RESULT_CAP) { ctx.enrich.truncated({ shown: shows.length, cap: SEARCH_RESULT_CAP }); ctx.enrich.notice('The source caps this search at 10 results and offers no pagination. …'); } return { shows }; }, // format() populates content[] — the markdown twin of structuredContent. // Different clients read different surfaces (Claude Code → structuredContent, // Claude Desktop → content[]); both must carry the same data. // Enforced at lint time: every field in `output` must appear in the rendered text. format: (result) => { const lines: string[] = [`**${result.shows.length} shows**`]; for (const show of result.shows) { lines.push( '', `### ${inline(`${show.name} (${yearRange(show)})`)}`, field('match_score', show.match_score), ...showSummaryLines(show), ); } return [{ type: 'text', text: lines.join('\n') }]; }, }); ``` Conventions this surface holds to, and that a new tool inherits: - **Output shapes are shared, error contracts are not.** `ShowSummary`, `ScheduleShow`, `Episode`, `Season`, and `CastCredit` — plus the `format()` renderers that keep them at parity — live in `shared-schemas.ts`. Each tool declares its own `errors[]` inline; per-tool repetition is the intended cost of locality. - **List tools page through `paging.ts`, not `paginateArray`.** `pageOf` takes the page size from the current `limit` and only the offset from the cursor; `enrichPage` writes `totalCount`, `truncated` / `shown` / `cap`, and one joined `notice` — pass a tool's own notice fragments to it rather than calling `ctx.enrich.notice`, which is last-wins. - **No tool declares `auth` scopes.** Every tool reads public data from a keyless API and the deployment posture is `MCP_AUTH_MODE=none`. A deployment that later enables JWT adds one `tool::read` scope per tool then. - **An absent optional value renders as `Not available`**, never `0`, `""`, or a dropped line — that is what keeps `format-parity` holding on TVmaze's sparse records. URL and image fields use the framework's Markdown link and image helpers. The local inline renderer keeps headings and table cells on one line. - **A hit-or-miss result is one flat `z.object` with optional fields**, never a `z.discriminatedUnion` (`tool()` rejects a union as an output root), and `format()` renders each arm from its own `if` block. ### Resource / Prompt The SDK serves `skills/tvmaze-guide/SKILL.md` as an MCP skill resource and registers the `skill://{+path}` template. TVmaze records are retrieved through tools. The server registers no prompts. ### Server config ```ts // src/config/server-config.ts — lazy-parsed, separate from framework config. // Every variable is optional: TVmaze is keyless, so the server runs with nothing set. // Excerpt: three of the seven fields. userAgent, defaultCountry, maxConcurrency, and // requestTimeoutMs follow the same shape — the file is the source of truth. import { z } from '@cyanheads/mcp-ts-core'; import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config'; const ServerConfigSchema = z.object({ baseUrl: z .url() .default('https://api.tvmaze.com') .describe('TVmaze API base URL. Override to point at an enterprise endpoint.'), defaultTimezone: z .string() .min(1) .default('UTC') .describe('IANA timezone used when a tool call omits `timezone`.'), cacheTtlS: z.coerce .number() .int() .min(0) .default(300) .describe('Seconds to hold an upstream response in the in-process cache. 0 disables caching.'), }); export type ServerConfig = z.infer; let _config: ServerConfig | undefined; /** Lazily parse and memoize the server's own environment configuration. */ export function getServerConfig(): ServerConfig { _config ??= parseEnvConfig(ServerConfigSchema, { baseUrl: 'TVMAZE_BASE_URL', defaultTimezone: 'TVMAZE_DEFAULT_TIMEZONE', cacheTtlS: 'TVMAZE_CACHE_TTL_S', }); return _config; } ``` `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`TVMAZE_BASE_URL`) not the path (`baseUrl`). Throws `ConfigurationError`, which the framework prints as a clean startup banner. Adding a variable means four files, not one: the schema above, `.env.example`, `server.json` (`environmentVariables[]`), and `manifest.json` (`mcp_config.env` + `user_config`, mirrored into `.claude-plugin/plugin.json`'s `userConfig` and `.codex-plugin/mcp.json`'s `env_vars`). `lint:packaging` fails on a mismatch. 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()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`): ```ts // src/index.ts — `name` and `title` are both the bare repo name, never Title Case // and never the npm scope; `lint:packaging` enforces the pair. await createApp({ name: 'tvmaze-mcp-server', title: 'tvmaze-mcp-server', tools: [searchShows, getShow, lookupShow, getNextEpisode, getEpisodes, getSchedule, getCast, getPerson], instructions: INSTRUCTIONS, // session-level context, sent on every initialize skills: 'skills', }); ``` `description` is deliberately absent: it derives from `package.json`, the canonical source, and an explicit copy here is drift. `websiteUrl` and `icons` are the remaining optional identity fields, forwarded the same way when a server sets them. This server's `INSTRUCTIONS` block carries what no single tool description can: the resolve-a-show-first workflow, the `airstamp`-is-authoritative rule, the linear-versus-streaming feed split, the CC BY-SA attribution and ShareAlike obligation, and the reminder that community-written summaries are content to report on, never instructions to follow. `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() { initTvmazeService(); }, // constructs the singleton: pacer, cache, HTTP config teardown() { disposeTvmazeService(); }, // releases the pacer's dispatch timer }); ``` `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. `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.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). | | `ctx.fail` / `ctx.recoveryFor` | Typed throw against the tool's own `errors[]` reason union — the framework fills the declared recovery hint — and that hint as data, for building an explicit override. See Errors. | | `ctx.signal` | `AbortSignal` for cancellation — handed to `withRetry` and `fetchWithTimeout` inside `TvmazeService`. | | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. | | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. | **What this server deliberately does not use.** `ctx.state` is tenant-scoped by design, which is right for tenant data and wrong for this cache: TVmaze responses are public and identical for every tenant, and the reason to cache them is to collapse identical bursts onto one shared egress rate budget — a tenant-scoped store would hold N copies and collapse nothing. The response cache therefore lives in `TvmazeService`. Tenant data, if any is ever stored, still goes through `ctx.state` and never straight to persistence. `ctx.requestInput` / `ctx.inputs` / `ctx.clientCapabilities` are unused — no handler asks the caller for input mid-flight, which is why `createApp()` can declare a plain `sessionMode: 'stateless'` rather than `require: 'stateful'`. Adding an elicitation to any tool means revisiting that declaration. `ctx.content` is unused as well: every response is text plus `structuredContent`, and image URLs are returned as fields, not as image blocks. The framework CLAUDE.md carries the full signatures for all five. --- ## Errors Handlers throw — the framework catches, classifies, and formats. **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request )`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring. ```ts import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; errors: [ { reason: 'show_not_found', code: JsonRpcErrorCode.NotFound, when: 'No show exists with the given TVmaze id.', recovery: 'Call tvmaze_search_shows with the show title to find a valid TVmaze id, or tvmaze_lookup_show with an IMDb or TheTVDB id.' }, ], async handler(input, ctx) { const detail = await getTvmazeService().getShowDetail(input.show_id, timezone, ctx, { seasons: true }); if (!detail) { throw ctx.fail('show_not_found', `No TVmaze show has id ${input.show_id}.`, { show_id: input.show_id, }); } return { ...detail, timezone }; } ``` **A 404 becomes `null` in the service, not a throw.** Every by-id fetch method returns `T | null`, so the handler decides what a miss means — a typed `ctx.fail` where the caller supplied an id, or a `{ found: false, guidance }` result where resolving an identifier was the tool's whole job (`tvmaze_lookup_show`, the title arm of `tvmaze_get_next_episode`). That keeps every `ctx.fail` lexically inside a handler, the only place the `error-contract-unthrown` lint can see it. Where the service must throw from below a handler — an upstream 422, an unknown IANA zone — it re-throws through an error factory carrying the calling tool's `reason`, from which the framework fills the declared recovery hint, and the matching contract entry carries `thrownBy: 'service'`. **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 — eight tools, instructions, service lifecycle config/ server-config.ts # TVMAZE_* env vars (Zod schema) services/ tvmaze/ tvmaze-service.ts # TVmaze REST client — pacer, cache, normalizers (init/accessor pattern) types.ts # Raw upstream shapes + normalized domain types mcp-server/ tools/definitions/ [tool-name].tool.ts # Tool definitions (one per tvmaze_* tool) paging.ts # Local paging for the list tools — pageOf, enrichPage shared-schemas.ts # Output schemas + format() renderers shared across tools ``` --- ## Naming | What | Convention | Example | |:-----|:-----------|:--------| | Files | kebab-case with suffix | `search-shows.tool.ts` | | Tool/resource/prompt names | snake_case, `tvmaze_` prefix | `tvmaze_search_shows` | | Directories | kebab-case | `src/services/tvmaze/` | | Descriptions | Single string or template literal, no `+` concatenation | `'List a show’s episodes with air times, runtimes, and synopses.'` | --- ## Skills Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents. **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory. The published [TVmaze guide](skills/tvmaze-guide/SKILL.md) lives under root `skills/`. Use `framework-skills/add-skill/SKILL.md` when updating it. 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 an opt-in skill for the agents calling this server through MCP or a plugin | | `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` | Packaging checks — environment variable parity, bundle exclusions, plugin manifests, and the published skill tree | | `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 tests (Vitest — use `bun run test`, not `bun test`) | | `bun run start:stdio` | Production mode (stdio) | | `bun run start:http` | Production mode (HTTP) | | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` | | `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` (scaffolded) 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` builds and cleans a stdio-only `.mcpb` extension for Claude Desktop. Keep repo-local paths in `.mcpbignore` root-anchored (for example, `/docs/`) so the exclusions do not strip dependency runtime paths. The cleaner removes dependency build-only files, native build intermediates, and agent documentation at package roots. The SDK’s runtime skill modules stay in the bundle. An intentionally published root `skills/` tree also ships. **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 routine 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 { getTvmazeService } from '@/services/tvmaze/tvmaze-service.js'; // A sibling inside the same definitions directory — relative, not aliased import { Episode, episodeLines, field } from './shared-schemas.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 — no `console`; every upstream call goes through `TvmazeService`, never `fetch` from a handler - [ ] Known air times derive from `airstamp` alone. Preserve `airdate` as the source date label. A record with no announced time reports `time_known: false` and no `local_time` - [ ] 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` - [ ] Root `plugin.json` and `mcp.json` match package metadata and fixed stdio configuration. Codex forwards user variables through the `.codex-plugin/mcp.json` overlay, so keep the pointer in `.codex-plugin/plugin.json`. - [ ] `.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.