@cyanheads/ensembl-mcp-server 0.4.2 → 0.4.4

package/Dockerfile

@@ -4,7 +4,7 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM oven/bun:1.3.14 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
 
 WORKDIR /usr/src/app
 
@@ -30,7 +30,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.3.14-slim AS production
+FROM oven/bun:1.4.0-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -41,7 +41,7 @@ ENV NODE_ENV=production
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
 ARG APP_VERSION
 LABEL org.opencontainers.image.title="@cyanheads/ensembl-mcp-server"
-LABEL org.opencontainers.image.description="Look up genes, fetch sequences, predict variant consequences, find orthologs and cross-database xrefs via Ensembl REST via MCP. STDIO or Streamable HTTP."
+LABEL org.opencontainers.image.description="Look up genes, fetch sequences, predict variant consequences, find orthologs, and retrieve cross-database xrefs from Ensembl REST via MCP. STDIO or Streamable HTTP."
 LABEL org.opencontainers.image.source="https://github.com/cyanheads/ensembl-mcp-server"
 LABEL org.opencontainers.image.licenses="Apache-2.0"
 LABEL org.opencontainers.image.version="${APP_VERSION}"
@@ -52,7 +52,7 @@ COPY package.json bun.lock ./
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
 RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --production --frozen-lockfile --ignore-scripts
+    bun install --production --frozen-lockfile --ignore-scripts --omit=peer
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # These are not bundled by default to keep the base image lean. Enable at build time
@@ -69,7 +69,8 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
         @opentelemetry/sdk-metrics \
         @opentelemetry/sdk-node \
         @opentelemetry/sdk-trace-node \
-        @opentelemetry/semantic-conventions; \
+        @opentelemetry/semantic-conventions \
+        --omit=dev --omit=peer --ignore-scripts; \
     fi
 
 # Copy the compiled application code from the build stage

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/ensembl-mcp-server</h1>
-  <p><b>Look up genes, fetch sequences, predict variant consequences, find orthologs and cross-database xrefs via Ensembl REST via MCP. STDIO or Streamable HTTP.</b>
+  <p><b>Look up genes, fetch sequences, predict variant consequences, find orthologs, and retrieve cross-database xrefs from Ensembl REST via MCP. STDIO or Streamable HTTP.</b>
   <div>7 Tools • 4 Resources • 1 Prompt</div>
   </p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.4.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/ensembl-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/ensembl-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/ensembl-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.4.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/ensembl-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/ensembl-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/ensembl-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -27,9 +27,11 @@
 
 ---
 
-## Tools
+## Overview
 
-Seven tools covering the core Ensembl REST API surface — species discovery, gene/transcript lookup, sequence retrieval, genomic region overlap, variant consequence prediction, cross-species homology, and external database cross-references:
+Gene, sequence, and variant data for vertebrates and other model organisms from the Ensembl REST API. Look up genes, fetch sequences, predict variant consequences, find orthologs, and cross-reference external databases from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+
+### Tools
 
 | Tool | Description |
 |:-----|:------------|
@@ -41,103 +43,125 @@ Seven tools covering the core Ensembl REST API surface — species discovery, ge
 | `ensembl_get_homology` | Find orthologs and/or paralogs of a gene across species with percent identity and taxonomy level |
 | `ensembl_get_xrefs` | Retrieve cross-database references for a gene — HGNC, UniProt, EntrezGene, OMIM, RefSeq, Reactome, and others |
 
-### `ensembl_list_species`
+### Resources
 
-Discovery tool for the Ensembl species catalog.
+| Resource | Description |
+|:---|:---|
+| `ensembl://gene/{id}` | Gene record by stable ID (`ENSG…`) — location, biotype, description, and transcript list |
+| `ensembl://transcript/{id}` | Transcript record by stable ID (`ENST…`) — parent gene, location, biotype, canonical flag, and length |
+| `ensembl://species` | Supported Ensembl species for the endpoint default division (vertebrates on the default endpoint) |
+| `ensembl://species/{division}` | Supported species in one division (`EnsemblVertebrates`, `EnsemblPlants`, `EnsemblFungi`, `EnsemblMetazoa`, `EnsemblProtists`) |
 
-- Filter by division: vertebrates, plants, fungi, metazoa, or protists
-- Optional name filter (`nameContains`) for local substring matching
-- Returns display name, common name, assembly, taxon ID, and Ensembl division for each species
-- Required first step — species names like `homo_sapiens` are opaque to non-biologists and are the input format every other tool expects
+All resource data is also reachable via the `ensembl_list_species` tool, which additionally filters by name.
 
----
+### Prompts
+
+| Prompt | Description |
+|:---|:---|
+| `ensembl_gene_dossier` | Structured workflow for assembling a complete gene profile: symbol → ID + location → sequence → variants → orthologs → xrefs |
 
-### `ensembl_lookup_gene`
+## Capability reference
 
-Single entry point for resolving gene identity.
+### `ensembl_list_species` <sub>tool</sub>
 
-- Symbol + species lookup (`BRCA2` + `homo_sapiens`) or direct stable ID lookup (`ENSG00000139618`)
-- Batch lookup of up to 20 IDs or symbols in one call via POST endpoints
-- Optional transcript expansion — returns full transcript list with biotype and canonical flag
-- Returns Ensembl stable ID, genomic location (chr:start-end:strand), biotype, description, and transcript list
-- Errors: `not_found` (symbol or ID not in Ensembl), `invalid_species` (call `ensembl_list_species` to discover valid names)
+- Filter by division (`EnsemblVertebrates`, `EnsemblPlants`, `EnsemblFungi`, `EnsemblMetazoa`, `EnsemblProtists`) or `nameContains` for a local substring match against name, display name, and common name
+- Omit `division` to return the endpoint default division (vertebrates, ~356 species on the default GRCh38 endpoint)
+- Returns internal name (the value every other tool expects), display name, common name, taxon ID, assembly, and division
+- Required first step — species names like `homo_sapiens` are opaque to non-biologists
 
 ---
 
-### `ensembl_get_sequence`
+### `ensembl_lookup_gene` <sub>tool</sub>
+
+- Exactly one of `symbol` (+ optional `species`, default `homo_sapiens`), `id`, `ids` (batch, up to 20), or `symbols` (batch, up to 20)
+- `expand_transcripts` (default `false`) adds the full transcript list with biotype and canonical flag
+- Batch modes (`ids`/`symbols`) return a `succeeded`/`failed` split with per-item error strings instead of failing the call
+- Errors: `not_found`, `invalid_species`, `no_input`, `conflicting_input`
+
+---
 
-Fetch any sequence type for any Ensembl feature.
+### `ensembl_get_sequence` <sub>tool</sub>
 
-- Molecule types: `genomic` (default, includes introns), `cdna` (spliced), `cds` (coding only), `protein`
-- Accepts stable IDs or `species:chr:start-end` region format for genomic region mode
-- Optional flanking sequence (`expand_5prime`, `expand_3prime`) in base pairs
-- Returns sequence with stable ID, molecule type, and character count — large sequences (e.g. BRCA2 at 85,183 bp genomic) returned in full with explicit length so callers can budget context usage
+- `type`: `genomic` (default, includes introns), `cdna` (spliced), `cds` (coding only), `protein`
+- Accepts a stable ID (`ENSG…`/`ENST…`/`ENSP…`) or a region — `species:chr:start-end`, or bare `chr:start-end` with `species` set
+- `expand_5prime` / `expand_3prime` (default `0`) extend flanking base pairs for genomic and region queries
+- `protein` and `cds` require a transcript or protein ID, not a gene ID
+- Every response states `length` so callers can budget context before consuming large sequences
+- Errors: `not_found`, `type_mismatch`, `missing_species`
 
 ---
 
-### `ensembl_query_region`
+### `ensembl_query_region` <sub>tool</sub>
+
+- `region` in `chr:start-end` format; `feature` array defaults to `["gene"]`, also accepts `transcript`, `variation`, `regulatory`, `exon`; optional `biotype` filter
+- Defaults to genes only — requesting `variation` on a large locus can return 44,000+ features
+- Exon rows carry a `parentId` and `rank`, since one exon is reported once per parent transcript
+- Errors: `invalid_region`, `invalid_species`
 
-Find all genomic features overlapping a chromosomal window.
+---
 
-- Region format: `chr:start-end` (e.g. `13:32315086-32400268`) — no `chr` prefix for vertebrates
-- Feature types: `gene` (default), `transcript`, `variation`, `regulatory`, `exon`
-- Optional biotype filter
-- Defaults to gene only to prevent context overload — a large locus can contain 44,000+ variants when all feature types are selected
+### `ensembl_predict_variant` <sub>tool</sub>
+
+- `variant` accepts HGVS (transcript-relative or genomic), region+allele (`chr:start:end:strand/allele`), or a dbSNP rsID
+- `max_transcript_consequences` (default `10`) and `max_pubmed_ids_per_variant` (default `10`) cap large VEP results; set either to `0` for the full set, or `include_all_colocated_pubmed: true` for uncapped PubMed IDs
+- Returns most severe consequence term, per-transcript impact (HIGH/MODERATE/LOW/MODIFIER), and colocated known variants with clinical significance
+- Totals (`transcriptConsequencesTotal`, `pubmedTotal`) are always reported even when capped
+- Errors: `invalid_notation`, `not_found`
 
 ---
 
-### `ensembl_predict_variant`
+### `ensembl_get_homology` <sub>tool</sub>
+
+- Exactly one of `symbol` (+ `species`, default `homo_sapiens`) or `id`; optional `target_species` filter
+- `type`: `orthologues` (default), `paralogues`, or `all`
+- `max_results` caps the homolog list (default `25`, `0` uncapped); `totalCount` always reports the true count available
+- Errors: `not_found`, `no_input`, `conflicting_input`
 
-Predict variant consequences via the Ensembl VEP.
+---
+
+### `ensembl_get_xrefs` <sub>tool</sub>
 
-- Accepts HGVS notation (transcript-relative: `ENST00000380152.8:c.2T>A`) or genomic region+allele format (`13:32316462:32316462:1/A`)
-- Returns most severe consequence term, affected transcripts and genes, impact level (HIGH/MODERATE/LOW/MODIFIER)
-- Includes colocated known variants with clinical significance (ClinVar, dbSNP)
-- Errors: `invalid_notation` (check format), `not_found` (location outside any known transcript)
+- `id` (`ENSG…`/`ENST…`) required; optional `dbname` filter (e.g. `HGNC`, `Uniprot_gn`, `EntrezGene`, `MIM_GENE`, `RefSeq_mRNA`, `Reactome`, `GO`)
+- Uses the `xrefs/id` endpoint, returning the full cross-reference set (56+ entries for well-annotated genes like BRCA2)
+- Errors: `not_found`
 
 ---
 
-### `ensembl_get_homology`
+### `ensembl://gene/{id}` <sub>resource</sub>
+
+- Returns location, biotype, description, and transcript list for a gene stable ID (`ENSG…`); version suffix optional
+- Errors: `not_found`
+
+---
 
-Cross-species homolog lookup.
+### `ensembl://transcript/{id}` <sub>resource</sub>
 
-- Returns orthologs (default) or paralogs, or both
-- Optional `target_species` filter to narrow to specific organisms
-- Each homolog carries stable ID, species, relationship type (ortholog_one2one, ortholog_one2many, etc.), `perc_id`, `perc_pos`, and taxonomy level
+- Returns parent gene, location, biotype, canonical flag, and length for a transcript stable ID (`ENST…`); version suffix optional
+- Errors: `not_found`
 
 ---
 
-### `ensembl_get_xrefs`
+### `ensembl://species` <sub>resource</sub>
 
-Full cross-database reference set for any Ensembl feature.
+- No parameters — returns the endpoint default division (vertebrates, ~356 species on the default GRCh38 endpoint)
+- For a named division, read `ensembl://species/{division}` instead
 
-- Returns all external IDs by default: HGNC, UniProt, EntrezGene, OMIM, RefSeq, Reactome, and more (56 xrefs for BRCA2)
-- Optional `dbname` filter (e.g. `HGNC`, `Uniprot_gn`, `EntrezGene`, `MIM_GENE`) to narrow output
-- Uses the `xrefs/id` endpoint (not `xrefs/symbol`) — returns the full cross-reference set
-- IDs returned here chain directly to protein, literature, disease, and pathway resources in other MCP servers
+---
 
-## Resources and prompts
+### `ensembl://species/{division}` <sub>resource</sub>
 
-| Type | Name | Description |
-|:-----|:-----|:------------|
-| Resource | `ensembl://gene/{id}` | Gene record by stable ID (`ENSG…`) — location, biotype, description, and transcript list |
-| Resource | `ensembl://transcript/{id}` | Transcript record by stable ID (`ENST…`) — parent gene, location, biotype, canonical flag, and length |
-| Resource | `ensembl://species` | Supported Ensembl species for the endpoint default division (vertebrates on the default endpoint) with name, display name, assembly, taxon ID, and division |
-| Resource | `ensembl://species/{division}` | Supported species in one division (`EnsemblVertebrates`, `EnsemblPlants`, `EnsemblFungi`, `EnsemblMetazoa`, `EnsemblProtists`) |
-| Prompt | `ensembl_gene_dossier` | Structured workflow for assembling a complete gene profile: symbol → ID + location → sequence → variants → orthologs → xrefs |
+- `division` required: `EnsemblVertebrates`, `EnsemblPlants`, `EnsemblFungi`, `EnsemblMetazoa`, or `EnsemblProtists`
 
-All resource data is also reachable via tools. `ensembl://species` returns the endpoint default division (vertebrates) and `ensembl://species/{division}` returns a named division; `ensembl_list_species` is the tool equivalent, filtering by division and name.
+---
 
-## Features
+### `ensembl_gene_dossier` <sub>prompt</sub>
 
-Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
+- Arguments: `gene_symbol` required; `species` optional (default `homo_sapiens`)
+- Sequences a 7-step workflow: resolve the gene → fetch the protein sequence → find variants in the locus → predict variant consequences → find cross-species orthologs → get external database IDs → synthesize the dossier
+
+## Features
 
-- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
-- Unified error handling — handlers throw, framework catches, classifies, and formats
-- Pluggable auth: `none`, `jwt`, `oauth`
-- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
-- Structured logging with optional OpenTelemetry tracing
-- STDIO and Streamable HTTP transports
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
 Ensembl-specific:
 
@@ -151,7 +175,7 @@ Agent-friendly output:
 
 - Sequence character count stated on every `ensembl_get_sequence` response so callers can budget context before consuming large genomic sequences
 - `ensembl_list_species` is explicitly the discovery step — tool descriptions call out the opaque internal-name format and direct agents to it before using species-dependent tools
-- Cross-tool chaining made explicit: xref IDs from `ensembl_get_xrefs` are described as inputs for protein and literature servers; the `ensembl_gene_dossier` prompt sequences the full 7-tool research workflow
+- Cross-tool chaining made explicit: xref IDs from `ensembl_get_xrefs` are described as inputs for protein and literature servers; the `ensembl_gene_dossier` prompt sequences all 6 tools into one research workflow
 
 ## Getting started
 
@@ -235,7 +259,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
 
 ### Prerequisites
 
-- [Bun v1.3.14](https://bun.sh/) or higher (or Node.js v24+).
+- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
 - No API key required — Ensembl REST is fully public.
 
 ### Installation
@@ -275,6 +299,7 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port | `3010` |
 | `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path | `/mcp` |
+| `MCP_SESSION_MODE` | HTTP session mode: `auto`, `stateful`, or `stateless`. Schema default `auto` resolves to stateful; this server explicitly uses stateless. | `stateless` |
 | `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
 | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |
 | `LOGS_DIR` | Directory for log files (Node.js only) | `<project-root>/logs` |
@@ -338,7 +363,7 @@ See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rule
 
 ## Contributing
 
-Issues and pull requests are welcome. Run checks and tests before submitting:
+Issues are welcome. Run checks and tests before submitting:
 
 ```sh
 bun run devcheck

package/changelog/0.4.x/0.4.3.md

@@ -0,0 +1,29 @@
+---
+summary: "MCP 2026-07-28 and SDK v2 adoption adds strict tool inputs, public cache hints, and an explicit stateless HTTP deployment"
+breaking: false
+security: false
+---
+
+# 0.4.3 — 2026-08-22
+
+## Added
+
+- **Public cache hints** now mark tool, prompt, resource, and discovery catalogs cacheable for one hour and resource reads for five minutes on MCP 2026-07-28 clients.
+
+## Changed
+
+- **MCP SDK v2 and protocol revision 2026-07-28** are available alongside the existing 2025-era clients. Tool calls reject undeclared top-level arguments, advertised schemas use JSON Schema 2020-12 and declare error envelopes, and `ctx.log` messages can reach clients that opt into MCP logging.
+- **`MCP_SESSION_MODE=stateless`** is explicit across the Docker image, `.env.example`, and README, so source and container HTTP runs use the same session policy.
+- **Request context propagation** now carries the handler's canonical trace, operation, tenant, and correlation fields into Ensembl upstream requests instead of retaining only the request ID.
+- **Build and test configuration** typechecks `tests/` separately from the production emit; prompt/resource tests follow the SDK v2 async and optional-schema contracts.
+- **Packaging and project templates** adopt Bun 1.4, production peer omission, portable MCPB cleanup, current dependency checks, community-health files, and the latest framework scripts, skills, and agent protocol.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.10.14` → `^0.12.3`
+- `@biomejs/biome` `^2.5.0` → `^2.5.9`
+- `@types/node` `^26.0.0` → `^26.2.0`
+- `ignore` `^7.0.5` → `^7.0.6`
+- `tsc-alias` `^1.9.0` → `^1.9.2`
+- `typescript` `^6.0.3` → `^7.0.2`
+- `vitest` `^4.1.10` → `^4.1.11`

package/changelog/0.4.x/0.4.4.md

@@ -0,0 +1,27 @@
+---
+summary: "mcp-ts-core 0.13.6 adoption: an unrecognized or misspelled argument key now succeeds instead of failing, argument rejections carry a reason and recovery hint under Invalid params, and every declared tool error closes with a (reason ...) suffix"
+breaking: false
+security: false
+---
+
+# 0.4.4 — 2026-09-19
+
+## Changed
+
+- **Tool calls tolerate minor argument mismatches instead of rejecting them** — an unrecognized top-level key is dropped, a differently-cased spelling of a declared parameter (`dbName` for `dbname`, `maxTranscriptConsequences` for `max_transcript_consequences`) is rewritten onto the real key, and a JSON-stringified array is parsed and retried once. Advertised `inputSchema` is unchanged; only calls that previously failed now succeed.
+- **Argument rejections report `Invalid params` (`-32602`)** instead of the previous validation-error code, with `data.reason: "invalid_arguments"` and a synthesized `Recovery: …` hint derived from the offending field and the root schema.
+- **Every declared tool error closes with `(reason <reason>)`** — e.g. `not_found`, `invalid_notation` — on the `content[]` text. `structuredContent.error.data.reason` already carried the reason and is unchanged; resource errors are unaffected.
+- **A caller that disconnects mid-call is reported as a cancellation**, not an internal server error.
+- **`sessionMode: 'stateless'`** is declared directly in `src/index.ts`, matching the deployment default it was previously left to.
+- **Bun engines floor raised to `>=1.4.0`**, matching the framework requirement.
+- **Framework scripts, skills, agent protocol, and issue templates** sync to `@cyanheads/mcp-ts-core` 0.13.6 — the development skill tree moves from `skills/` to `framework-skills/` so a plugin install no longer surfaces it to the installing agent, `devcheck` gains a Worker typecheck step and a README version-badge check, and a CodeQL workflow is added.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.13.6`
+- `zod` `^4.4.3` → `^4.6.5`
+- `@biomejs/biome` `^2.5.9` → `^2.5.14`
+- `@types/node` `^26.2.0` → `^26.6.1`
+- `ignore` `^7.0.6` → `^7.0.9`
+- `tsc-alias` `^1.9.2` → `^1.9.5`
+- `vitest` `^4.1.11` → `^5.0.1`

package/changelog/template.md

@@ -4,10 +4,11 @@
 # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
 # with a concrete date.
 
-# Required. One-line GitHub Release-style headline. 350 character cap.
-# Default short and scannable. Don't pad, don't stitch unrelated changes with
-# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
-# inside the value as a key separator and fails GitHub's strict parser.
+# Required. One-line GitHub Release-style headline. 350 character cap — a
+# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
+# unrelated changes with commas/semicolons into an inventory — pick the one
+# headline the release is about. Quotes required: unquoted YAML treats
+# `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
 # Set `true` when consumers must change code to upgrade: API removals,
@@ -24,9 +25,10 @@ security: false
 
 # Optional free-form notes for maintenance agents processing this release.
 # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
-# downstream servers. Use for adoption instructions that don't fit the
-# human-facing sections: new files to create, fields to populate, one-time
-# migration steps. Omit the field entirely when there's nothing to say.
+# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
+# populate, one-time migration steps. Never a second rendering of the body:
+# if a body bullet already says it, name the bullet's symbol instead of
+# re-explaining. Omit the field entirely when there's nothing to say.
 # agent-notes: |
 #   <instructions for downstream maintenance agents>
 ---
@@ -41,17 +43,54 @@ security: false
   each bullet with the symbol or concept name in **bold** so they can skip
   what's irrelevant and zoom in on what's not.
 
-  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
-  name the symbol, state what changed, stop. Use a second sentence only when
-  it carries weight. If a bullet feels long, it is.
-
-  Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
-  relevant skill), ceremonial framings ("This release introduces…",
-  backwards-compat paragraphs), file-by-file test enumerations, internal
-  implementation notes. Prefer code/symbol names over English re-explanations.
+  Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
+  changed + at most one consumer-facing caveat. One sentence by default, two
+  when the second carries weight — a bullet past ~40 words or three sentences
+  is wrong. The depth lives one hop away: the linked issue carries the why,
+  the commit diff carries the how. The changelog names what changed and what
+  a consumer does about it; a reader who wants mechanism opens the link.
+
+  Model length on THIS guide, never on the previous entry — entries modeled
+  on entries compound.
+
+  Cut (each has shipped as a wall of text; these are the cruft):
+  - History/justification narration — how the bug worked, why the old
+    behavior was wrong. One short clause at most; the issue carries the story.
+  - Design-rationale defense — "chosen over Y because…", "guarding the
+    getter is not enough…". That is the author arguing with a reviewer;
+    reviewers read the PR, not the changelog.
+  - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
+    <prev>". Keep one only where its absence would cause a real misread,
+    as a short parenthetical.
+  - Edge-case inventories — marker lists, not-flagged lists, escape tables.
+    Tests and the issue carry those.
+  - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
+    skill own those), ceremonial framings ("This release introduces…"),
+    backwards-compat paragraphs, file-by-file test enumerations. Prefer
+    code/symbol names over English re-explanations.
+
+  Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
+  the TRUTH of what you write, never the AMOUNT.
+
+  Example — same fact, right size:
+
+    TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
+    (#341). `fetch` resolves once headers arrive and the deadline was
+    cleared as the helper returned, so a peer that answered promptly and
+    then stalled the stream held the request open indefinitely. A 2xx
+    carrying a body now comes back as a passthrough wrapper that disarms
+    the deadline when the body closes, errors, or is cancelled; …
+    [+90 more words of mechanism and edge cases]
+
+    RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
+    exchange, not just the headers** (#341). A stalled body aborts with
+    the same `Timeout` error; the returned `Response` is a wrapper, so
+    identity assertions (`toBe(response)`) no longer hold.
 
   Narrative intro: skip by default. Add one short sentence only when the
-  release theme genuinely needs framing the bullets can't carry.
+  release theme genuinely needs framing the bullets can't carry. When many
+  bullets share one upgrade consequence, state it ONCE — intro line or
+  agent-notes — never per bullet.
 
   Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
   Fixed, Security. Include only sections with entries; delete the rest
@@ -78,30 +117,13 @@ security: false
   in that unrelated item's metadata.
 
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
-  via `gh release create --notes-from-tag`. The tag is a derivative of this
-  changelog entry — a condensed, scannable version, not a copy. Format:
-
-    <theme — omit version number, GitHub prepends it>
-                                                          ← blank line
-    <1-2 sentence context: what this release does>
-                                                          ← blank line
-    Dependency bumps:                                     ← section header
-                                                          ← blank line
-    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
-                                                          ← blank line
-    Changed:                                              ← only sections with entries
-                                                          ← blank line
-    - `format()` output includes `query` in text mode
-                                                          ← blank line
-    Added:
-                                                          ← blank line
-    - `manifest.json` scaffolded for MCPB bundle support
-    - Install badges (Claude Desktop, Cursor, VS Code)
-                                                          ← blank line
-    <N> tests pass; `bun run devcheck` clean.             ← footer
-
-  Never a flat comma-separated string. Always structured markdown with
-  sections. The tag must scan well as a rendered GitHub Release page.
+  via `gh release create --notes-from-tag`. It is a condensed digest of this
+  entry, never a copy, and its format is owned by the `release-and-publish`
+  skill (step 4, "Create the annotated tag"): a short subject line without the
+  version, flat headline bullets — no Keep-a-Changelog section headers, no
+  gates line — at most one deps line, issue backlinks, and the changelog link
+  last. In release-PR mode the `git-wrapup` skill authors those bullets as the
+  PR body's `## Changes` and the tag copies them.
 -->
 
 ## Added

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;iBAQtB,CAAC;AAIH,wBAAgB,eAAe;;EAK9B;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;iBAOtB,CAAC;AAIH,wBAAgB,eAAe;;EAK9B;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/config/server-config.js

@@ -8,8 +8,7 @@ const ServerConfigSchema = z.object({
     baseUrl: z
         .string()
         .default('https://rest.ensembl.org')
-        .describe('Ensembl REST API base URL. Override to point at GRCh37 legacy endpoint ' +
-        '(https://grch37.rest.ensembl.org) or a local mirror.'),
+        .describe('Ensembl REST API base URL. Override to point at the GRCh37 legacy endpoint (https://grch37.rest.ensembl.org) or a local mirror.'),
 });
 let _config;
 export function getServerConfig() {

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,OAAO,CAAC,0BAA0B,CAAC;SACnC,QAAQ,CACP,yEAAyE;QACvE,sDAAsD,CACzD;CACJ,CAAC,CAAC;AAEH,IAAI,OAAuD,CAAC;AAE5D,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,kBAAkB;KAC5B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,OAAO,CAAC,0BAA0B,CAAC;SACnC,QAAQ,CACP,iIAAiI,CAClI;CACJ,CAAC,CAAC;AAEH,IAAI,OAAuD,CAAC;AAE5D,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,kBAAkB;KAC5B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.js

@@ -19,6 +19,21 @@ import { initEnsemblService } from './services/ensembl/ensembl-service.js';
 await createApp({
     name: 'ensembl-mcp-server',
     title: 'ensembl-mcp-server',
+    /**
+     * Every tool here is a read-only Ensembl REST lookup — no handler calls
+     * `ctx.requestInput`, so nothing needs a session to come back to. `stateless`
+     * is declared in source rather than left to the deployment's
+     * `MCP_SESSION_MODE`, which still wins when it carries a meaningful value.
+     */
+    sessionMode: 'stateless',
+    cacheHints: {
+        'prompts/list': { ttlMs: 3_600_000, cacheScope: 'public' },
+        'resources/list': { ttlMs: 3_600_000, cacheScope: 'public' },
+        'resources/read': { ttlMs: 300_000, cacheScope: 'public' },
+        'resources/templates/list': { ttlMs: 3_600_000, cacheScope: 'public' },
+        'server/discover': { ttlMs: 3_600_000, cacheScope: 'public' },
+        'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' },
+    },
     tools: [
         ensemblListSpecies,
         ensemblLookupGene,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yDAAyD,CAAC;AACnG,OAAO,EAAE,mBAAmB,EAAE,MAAM,qDAAqD,CAAC;AAC1F,OAAO,EACL,gCAAgC,EAChC,sBAAsB,GACvB,MAAM,wDAAwD,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2DAA2D,CAAC;AACtG,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oDAAoD,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAC/F,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,oBAAoB;IAC3B,KAAK,EAAE;QACL,kBAAkB;QAClB,iBAAiB;QACjB,kBAAkB;QAClB,kBAAkB;QAClB,qBAAqB;QACrB,kBAAkB;QAClB,eAAe;KAChB;IACD,SAAS,EAAE;QACT,mBAAmB;QACnB,yBAAyB;QACzB,sBAAsB;QACtB,gCAAgC;KACjC;IACD,OAAO,EAAE,CAAC,wBAAwB,CAAC;IACnC,YAAY,EAAE;;;;oHAIoG;IAClH,KAAK,CAAC,IAAI;QACR,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yDAAyD,CAAC;AACnG,OAAO,EAAE,mBAAmB,EAAE,MAAM,qDAAqD,CAAC;AAC1F,OAAO,EACL,gCAAgC,EAChC,sBAAsB,GACvB,MAAM,wDAAwD,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2DAA2D,CAAC;AACtG,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oDAAoD,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAC/F,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,oBAAoB;IAC3B;;;;;OAKG;IACH,WAAW,EAAE,WAAW;IACxB,UAAU,EAAE;QACV,cAAc,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC1D,gBAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC5D,gBAAgB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC1D,0BAA0B,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACtE,iBAAiB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC7D,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;KACzD;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,iBAAiB;QACjB,kBAAkB;QAClB,kBAAkB;QAClB,qBAAqB;QACrB,kBAAkB;QAClB,eAAe;KAChB;IACD,SAAS,EAAE;QACT,mBAAmB;QACnB,yBAAyB;QACzB,sBAAsB;QACtB,gCAAgC;KACjC;IACD,OAAO,EAAE,CAAC,wBAAwB,CAAC;IACnC,YAAY,EAAE;;;;oHAIoG;IAClH,KAAK,CAAC,IAAI;QACR,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/species.resource.d.ts

@@ -8,11 +8,11 @@ import { z } from '@cyanheads/mcp-ts-core';
 export declare const ensemblSpeciesResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{}, z.core.$strip>, undefined, undefined>;
 export declare const ensemblSpeciesByDivisionResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
     division: z.ZodEnum<{
-        EnsemblVertebrates: "EnsemblVertebrates";
-        EnsemblPlants: "EnsemblPlants";
         EnsemblFungi: "EnsemblFungi";
         EnsemblMetazoa: "EnsemblMetazoa";
+        EnsemblPlants: "EnsemblPlants";
         EnsemblProtists: "EnsemblProtists";
+        EnsemblVertebrates: "EnsemblVertebrates";
     }>;
 }, z.core.$strip>, undefined, undefined>;
 //# sourceMappingURL=species.resource.d.ts.map

package/dist/mcp-server/tools/definitions/get-homology.tool.d.ts

@@ -10,9 +10,9 @@ export declare const ensemblGetHomology: import("@cyanheads/mcp-ts-core").ToolDe
     species: z.ZodDefault<z.ZodString>;
     target_species: z.ZodOptional<z.ZodString>;
     type: z.ZodDefault<z.ZodEnum<{
+        all: "all";
         orthologues: "orthologues";
         paralogues: "paralogues";
-        all: "all";
     }>>;
     max_results: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{

package/dist/mcp-server/tools/definitions/get-sequence.tool.d.ts

@@ -7,9 +7,9 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 export declare const ensemblGetSequence: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
     id: z.ZodString;
     type: z.ZodDefault<z.ZodEnum<{
-        genomic: "genomic";
         cdna: "cdna";
         cds: "cds";
+        genomic: "genomic";
         protein: "protein";
     }>>;
     species: z.ZodOptional<z.ZodString>;

package/dist/mcp-server/tools/definitions/list-species.tool.d.ts

@@ -5,11 +5,11 @@
 import { z } from '@cyanheads/mcp-ts-core';
 export declare const ensemblListSpecies: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
     division: z.ZodOptional<z.ZodEnum<{
-        EnsemblVertebrates: "EnsemblVertebrates";
-        EnsemblPlants: "EnsemblPlants";
         EnsemblFungi: "EnsemblFungi";
         EnsemblMetazoa: "EnsemblMetazoa";
+        EnsemblPlants: "EnsemblPlants";
         EnsemblProtists: "EnsemblProtists";
+        EnsemblVertebrates: "EnsemblVertebrates";
     }>>;
     nameContains: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{

package/dist/mcp-server/tools/definitions/query-region.tool.d.ts

@@ -10,9 +10,9 @@ export declare const ensemblQueryRegion: import("@cyanheads/mcp-ts-core").ToolDe
     feature: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         exon: "exon";
         gene: "gene";
+        regulatory: "regulatory";
         transcript: "transcript";
         variation: "variation";
-        regulatory: "regulatory";
     }>>>;
     biotype: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{