Developer Protocol

Server: gnomad-genetics-mcp-server Version: 0.1.5 Framework: @cyanheads/mcp-ts-core ^0.10.10 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 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

Real definitions from this server, condensed. The full versions live under src/mcp-server/.

Tool (`src/mcp-server/tools/definitions/gnomad-get-gene-constraint.tool.ts`)

import { tool, z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
import { getGnomadService } from '@/services/gnomad/gnomad-service.js';
import { datasetField, geneField, referenceGenomeField } from '../shared-schemas.js';

export const gnomadGetGeneConstraint = tool('gnomad_get_gene_constraint', {
  title: 'gnomad-genetics-mcp-server: get gene constraint',
  description: 'Fetch gnomAD loss-of-function constraint for a gene — pLI, LOEUF, …',
  annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
  input: z.object({ gene: geneField, dataset: datasetField, reference_genome: referenceGenomeField }),
  output: z.object({
    gene_id: z.string().describe('Ensembl gene ID resolved for the gene.'),
    symbol: z.string().describe('HGNC gene symbol.'),
    pli: z.number().nullable().describe('pLI — probability of LoF intolerance; >0.9 intolerant.'),
    // … remaining flat constraint fields, all nullable
    constraint_flags: z.array(z.string()).describe('Constraint caveat flags (e.g. v4 beta notes).'),
  }),
  // Typed error contract — ctx.fail('gene_not_found', …) is type-checked against this union.
  errors: [
    { reason: 'gene_not_found', code: JsonRpcErrorCode.NotFound,
      when: 'No gene matched the symbol or Ensembl ID in this build.',
      recovery: 'Check the symbol spelling or resolve a stable Ensembl gene ID via ensembl_lookup_gene.' },
  ],

  async handler(input, ctx) {
    const svc = getGnomadService();
    const dsCtx = svc.resolveDatasetContext(input.dataset, input.reference_genome);
    const constraint = await svc.getGeneConstraint(input.gene, dsCtx, ctx);
    if (!constraint) throw ctx.fail('gene_not_found', `Gene "${input.gene}" not found.`);
    return constraint;
  },

  // 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: `## ${result.symbol} (${result.gene_id})` }],
});

Resource (`src/mcp-server/resources/definitions/gene-constraint.resource.ts`)

import { resource, z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
import { GNOMAD_DATASETS } from '@/config/server-config.js';
import { getGnomadService } from '@/services/gnomad/gnomad-service.js';
import type { Dataset } from '@/services/gnomad/types.js';

export const geneConstraintResource = resource('gnomad://gene/{dataset}/{gene}/constraint', {
  description: 'gnomAD loss-of-function constraint for a gene. Mirrors gnomad_get_gene_constraint.',
  name: 'gnomAD gene constraint',
  mimeType: 'application/json',
  params: z.object({
    dataset: z.enum(GNOMAD_DATASETS).describe('gnomAD dataset segment.'),
    gene: z.string().describe('Gene — HGNC symbol or Ensembl gene ID.'),
  }),
  errors: [
    { reason: 'gene_not_found', code: JsonRpcErrorCode.NotFound,
      when: 'No gene matched the symbol or Ensembl ID in this build.',
      recovery: 'Check the symbol spelling or resolve a stable Ensembl gene ID via ensembl_lookup_gene.' },
  ],
  async handler(params, ctx) {
    const svc = getGnomadService();
    const dsCtx = svc.resolveDatasetContext(params.dataset as Dataset);
    const constraint = await svc.getGeneConstraint(params.gene, dsCtx, ctx);
    if (!constraint) throw ctx.fail('gene_not_found', `Gene "${params.gene}" not found.`);
    return constraint;
  },
});

Prompt (`src/mcp-server/prompts/definitions/variant-triage.prompt.ts`)

import { prompt, z } from '@cyanheads/mcp-ts-core';

export const variantTriagePrompt = prompt('gnomad_variant_triage', {
  description: 'Guided rare-disease variant-triage workflow over gnomAD: frequency → constraint → coverage.',
  title: 'gnomAD variant triage',
  args: z.object({
    variant: z.string().describe('Variant to triage — a chrom-pos-ref-alt variantId or an rsID.'),
    gene: z.string().optional().describe('Gene symbol or Ensembl ID for the constraint step.'),
    dataset: z.string().optional().describe('gnomAD dataset to use. Defaults to the server default.'),
  }),
  generate: (args) => [
    { role: 'user', content: { type: 'text', text: `Triage variant ${args.variant} for rare-disease causality…` } },
  ],
});

Server config (`src/config/server-config.ts`)

// Lazy-parsed, separate from framework config. parseEnvConfig maps schema paths →
// env var names so errors name the variable, not the path.
import { z } from '@cyanheads/mcp-ts-core';
import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';

export const GNOMAD_DATASETS = ['gnomad_r4', 'gnomad_r3', 'gnomad_r2_1', 'exac'] as const;

const ServerConfigSchema = z.object({
  gnomadApiBaseUrl: z.string().url().default('https://gnomad.broadinstitute.org/api'),
  defaultDataset: z.enum(GNOMAD_DATASETS).default('gnomad_r4'),
  maxConcurrency: z.coerce.number().int().positive().default(2),
  // env booleans use z.stringbool(), never z.coerce.boolean() (Boolean("false") is true).
  dataframeDropEnabled: z.stringbool().default(false),
});

let _config: z.infer<typeof ServerConfigSchema> | undefined;
export function getServerConfig() {
  _config ??= parseEnvConfig(ServerConfigSchema, {
    gnomadApiBaseUrl: 'GNOMAD_API_BASE_URL',
    defaultDataset: 'GNOMAD_DEFAULT_DATASET',
    maxConcurrency: 'GNOMAD_MAX_CONCURRENCY',
    dataframeDropEnabled: 'GNOMAD_DATAFRAME_DROP_ENABLED',
  });
  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.

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):

await createApp({
  name: 'my-mcp-server',
  title: 'My Server',                         // human-readable display name
  websiteUrl: 'https://github.com/owner/repo', // canonical homepage URL
  description: 'One-line description.',        // wins over MCP_SERVER_DESCRIPTION
  icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],
  instructions: 'Use shortcut alpha for the most common case.', // session-level context
});

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.

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.
`ctx.state`	Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value.
`ctx.elicit`	Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. Check for presence first: `if (ctx.elicit) { ... }`
`ctx.signal`	`AbortSignal` for cancellation.
`ctx.progress`	Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`.
`ctx.requestId`	Unique request ID.
`ctx.tenantId`	Tenant ID from JWT or `'default'` for stdio.

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 — wires services, registers surface
  config/
    server-config.ts                         # Server-specific env vars (Zod schema)
  services/
    gnomad/
      gnomad-service.ts                      # gnomAD GraphQL client (init/accessor pattern)
      queries.ts                             # Parameterized GraphQL query documents
      types.ts                               # Domain types (VariantRecord, GeneConstraint, …)
    clinvar/
      clinvar-service.ts                     # NCBI E-utilities client (optional source)
      types.ts                               # ClinVar domain types
    canvas-accessor.ts                       # Module-level DataCanvas accessor (set in setup())
  mcp-server/
    tools/
      shared-schemas.ts                      # Reused Zod field fragments + resolveGenomeTarget()
      definitions/
        gnomad-get-variant.tool.ts           # 5 gnomAD tools + 3 canvas dataframe tools
        …
    resources/definitions/
      variant.resource.ts                    # gnomad://variant/{dataset}/{variantId}
      gene-constraint.resource.ts            # gnomad://gene/{dataset}/{gene}/constraint
    prompts/definitions/
      variant-triage.prompt.ts               # gnomad_variant_triage chain

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

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:

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-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
`devcheck`	Lint, format, typecheck, audit
`polish-docs-meta`	Finalize docs, README, metadata, and agent protocol for shipping
`git-wrapup`	Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only.
`release-and-publish`	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
`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, logger, state, progress
`api-errors`	McpError, JsonRpcErrorCode, error patterns
`api-linter`	Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck`
`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, 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 <cmd> is the standard invocation. npm run <cmd> also works (npm delegates to bun).

Command	Purpose
`npm run build`	Compile TypeScript
`npm run rebuild`	Clean + build
`npm run clean`	Remove build artifacts
`npm run devcheck`	Lint + format + typecheck + security + changelog sync
`bun run audit:refresh`	Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real.
`npm run tree`	Generate directory structure doc
`npm run format`	Auto-fix formatting (safe fixes only)
`npm run format:unsafe`	Also apply Biome's unsafe autofixes — review the diff; they can change behavior
`npm test`	Run tests
`npm run start:stdio`	Production mode (stdio)
`npm run start:http`	Production mode (HTTP)
`npm run changelog:build`	Regenerate `CHANGELOG.md` from `changelog/*.md`
`npm run changelog:check`	Verify `CHANGELOG.md` is in sync (used by devcheck)
`npm run bundle`	Build, pack, and clean a `.mcpb` for one-click Claude Desktop install

Bundling

npm run bundle produces a .mcpb extension bundle for one-click install in Claude Desktop. The pack step is followed by scripts/clean-mcpb.ts, which prunes dev dependencies (mcpb clean) and strips dependency-shipped agent docs (node_modules/** skills/, .claude/, .agents/, SKILL.md) that root-anchored .mcpbignore patterns cannot reach. 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';

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Developer Protocol

Core Rules

Patterns

Tool (`src/mcp-server/tools/definitions/gnomad-get-gene-constraint.tool.ts`)

Resource (`src/mcp-server/resources/definitions/gene-constraint.resource.ts`)

Prompt (`src/mcp-server/prompts/definitions/variant-triage.prompt.ts`)

Server config (`src/config/server-config.ts`)

Server identity and instructions

Context

Errors

Structure

Naming

Skills

Commands

Bundling

Changelog

Imports

Checklist

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

Developer Protocol

Core Rules

Patterns

Tool (src/mcp-server/tools/definitions/gnomad-get-gene-constraint.tool.ts)

Resource (src/mcp-server/resources/definitions/gene-constraint.resource.ts)

Prompt (src/mcp-server/prompts/definitions/variant-triage.prompt.ts)

Server config (src/config/server-config.ts)

Server identity and instructions

Context

Errors

Structure

Naming

Skills

Commands

Bundling

Changelog

Imports

Checklist

Tool (`src/mcp-server/tools/definitions/gnomad-get-gene-constraint.tool.ts`)

Resource (`src/mcp-server/resources/definitions/gene-constraint.resource.ts`)

Prompt (`src/mcp-server/prompts/definitions/variant-triage.prompt.ts`)

Server config (`src/config/server-config.ts`)