Developer Protocol

Server: met-museum-mcp-server Version: 0.1.2 Framework: @cyanheads/mcp-ts-core ^0.9.19 Engines: Bun ≥1.3.0, Node ≥24.0.0 MCP SDK: @modelcontextprotocol/sdk ^1.29.0 Zod: ^4.4.3

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.

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.
• Check ctx.elicit / ctx.sample for presence before calling.
• Secrets in env vars only — never hardcoded.
• 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

import { tool, z } from '@cyanheads/mcp-ts-core';
import { getMetService } from '@/services/met/met-service.js';

export const metSearch = tool('met_search', {
  description: 'Search the Metropolitan Museum of Art collection by keyword and optional filters.',
  annotations: { readOnlyHint: true, idempotentHint: true },
  input: z.object({
    q: z.string().min(1).describe('Keyword query.'),
    limit: z.number().int().min(1).max(500).default(20).describe('Max object IDs to return.'),
  }),
  output: z.object({
    total: z.number().int().describe('Total matching objects.'),
    objectIDs: z.array(z.number().int().describe('A Met object ID.')).describe('Matching IDs.'),
    returned: z.number().int().describe('Count of IDs in this response.'),
    truncated: z.boolean().describe('True when total > returned.'),
  }),

  async handler(input, ctx) {
    const result = await getMetService().search({ q: input.q, limit: input.limit }, ctx);
    ctx.log.info('Met search', { q: input.q, total: result.total });
    return result;
  },

  // 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) => [{
    type: 'text',
    text: `**Total:** ${result.total} | **Returned:** ${result.returned}${result.truncated ? ' (truncated)' : ''}\n\n${result.objectIDs.join(', ')}`,
  }],
});

Server config

// 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({
  baseUrl: z.string().url().default('https://collectionapi.metmuseum.org/public/collection/v1'),
  requestTimeoutMs: z.coerce.number().int().positive().default(10_000),
  batchConcurrency: z.coerce.number().int().min(1).max(20).default(5),
});

let _config: z.infer<typeof ServerConfigSchema> | undefined;
export function getServerConfig() {
  _config ??= parseEnvConfig(ServerConfigSchema, {
    baseUrl: 'MET_BASE_URL',
    requestTimeoutMs: 'MET_REQUEST_TIMEOUT_MS',
    batchConcurrency: 'MET_BATCH_CONCURRENCY',
  });
  return _config;
}

parseEnvConfig maps Zod schema paths → env var names so errors name the variable (MY_API_KEY) not the path (apiKey). Throws ConfigurationError, which the framework prints as a clean startup banner.

Server instructions

createApp({ instructions }) — optional server-level orientation, sent to clients 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.

Context

Handlers receive a unified ctx object. Key properties:

Errors

Handlers throw — the framework catches, classifies, and formats.

Recommended: typed error contract. Declare errors: [{ reason, code, when, recovery, retryable? }] 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 descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire data.recovery.hint (mirrored into content[] text), pass explicitly at the throw site when dynamic context matters: ctx.fail('reason', msg, { recovery: { hint: '...' } }). Baseline codes (InternalError, ServiceUnavailable, Timeout, ValidationError, SerializationError) bubble freely and don't need declaring.

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.

// 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.DatabaseError, '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

src/
  index.ts                              # createApp() entry point
  config/
    server-config.ts                    # Server-specific env vars (Zod schema)
  services/
    met/
      met-service.ts                    # Met Collection API client (init/accessor pattern)
      types.ts                          # Domain types
  mcp-server/
    tools/definitions/
      met-list-departments.tool.ts      # met_list_departments
      met-search.tool.ts                # met_search
      met-get-object.tool.ts            # met_get_object

Naming

Skills

Skills are modular instructions in skills/ at the project root. Read them directly when a task matches — e.g., skills/add-tool/SKILL.md when adding a tool.

Agent skill directory: Copy skills into the directory your agent discovers (Claude Code: .claude/skills/, others: equivalent). Skills then load as context without referencing skills/ paths. After framework updates, run the maintenance skill — Phase B re-syncs the agent directory.

Available skills:

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 tsx — both npm run <cmd> and bun run <cmd> work. bun is slightly faster for script invocation but not required.

Bundling

npm run bundle produces a .mcpb extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete manifest.json and .mcpbignore; lint:packaging skips cleanly.

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.

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 skills/polish-docs-meta/references/readme.md.

Changelog

Directory-based, grouped by minor series via the .x semver-wildcard convention. Source of truth: changelog/<major.minor>.x/<version>.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:

---
summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
breaking: false                            # optional — true flags breaking changes
security: false                            # optional — true flags security fixes
---

# 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. 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 (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. 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.

Imports

// 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
• .codex-plugin/plugin.json populated — name, version, description, repository, license from package.json; interface.displayName = package name; interface.shortDescription from package.json description
• .codex-plugin/mcp.json updated — server name key matches package.json name; env vars added for any required API keys
• .claude-plugin/plugin.json populated — name, version, description, repository, license from package.json; inline mcpServers entry with server name key, env vars for any required API keys
• npm run devcheck passes