@cyanheads/ensembl-mcp-server 0.1.1

package/changelog/template.md

@@ -0,0 +1,127 @@
+---
+# FORMAT REFERENCE — do not edit. Copy this file to
+# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
+# 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.
+summary: ""
+
+# Set `true` when consumers must change code to upgrade: API removals,
+# signature changes, config renames, behavior changes that break existing
+# usage. Flagged as `Breaking` in the rollup.
+breaking: false
+
+# Set `true` if this release contains any security fix. Pairs with the
+# `## Security` section below. Flagged as `Security` in the rollup so
+# users can triage upgrade urgency at a glance.
+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.
+# agent-notes: |
+#   <instructions for downstream maintenance agents>
+---
+
+# <version> — YYYY-MM-DD
+
+<!--
+  AUTHORING GUIDE — applies to the new per-version file you create from this
+  template.
+
+  Audience: someone scanning release notes to decide what affects them. Lead
+  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.
+
+  Narrative intro: skip by default. Add one short sentence only when the
+  release theme genuinely needs framing the bullets can't carry.
+
+  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
+  Fixed, Security. Include only sections with entries; delete the rest
+  (including the commented-out scaffolding below). Don't ship empty headers.
+
+  Include: every distinct fact a reader needs to adopt or audit the release —
+  new exports, signatures, lint rule IDs, env vars, breaking changes, version
+  bumps on shipped skills. Nothing more.
+
+  Links: link issues, PRs, docs, or skills where they help a reader jump to
+  context. Once per item per entry — don't re-link the same issue in summary,
+  narrative, and bullet. Skip links for inline symbol names; code spans speak
+  for themselves.
+
+  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
+  inside its own UI, not in npm reads or local editors.
+
+      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
+
+  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
+  Never speculate on a future number — `#42` for an upcoming PR silently
+  resolves to whatever real item already owns 42, and timeline previews pull
+  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.
+-->
+
+## Added
+
+-
+
+## Changed
+
+-
+
+<!-- ## Deprecated
+
+- -->
+
+<!-- ## Removed
+
+- -->
+
+## Fixed
+
+-
+
+<!-- ## Security
+
+- -->

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

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Server-specific configuration for ensembl-mcp-server.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+declare const ServerConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export declare function getServerConfig(): {
+    baseUrl: string;
+};
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+export {};
+//# sourceMappingURL=server-config.d.ts.map

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

@@ -0,0 +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"}

package/dist/config/server-config.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Server-specific configuration for ensembl-mcp-server.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+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.'),
+});
+let _config;
+export function getServerConfig() {
+    _config ??= parseEnvConfig(ServerConfigSchema, {
+        baseUrl: 'ENSEMBL_BASE_URL',
+    });
+    return _config;
+}
+//# sourceMappingURL=server-config.js.map

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

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview ensembl-mcp-server MCP server entry point.
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview ensembl-mcp-server MCP server entry point.
+ * @module index
+ */
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { ensemblGeneDossierPrompt } from './mcp-server/prompts/definitions/gene-dossier.prompt.js';
+import { ensemblGeneResource } from './mcp-server/resources/definitions/gene.resource.js';
+import { ensemblSpeciesResource } from './mcp-server/resources/definitions/species.resource.js';
+import { ensemblTranscriptResource } from './mcp-server/resources/definitions/transcript.resource.js';
+import { ensemblGetHomology } from './mcp-server/tools/definitions/get-homology.tool.js';
+import { ensemblGetSequence } from './mcp-server/tools/definitions/get-sequence.tool.js';
+import { ensemblGetXrefs } from './mcp-server/tools/definitions/get-xrefs.tool.js';
+import { ensemblListSpecies } from './mcp-server/tools/definitions/list-species.tool.js';
+import { ensemblLookupGene } from './mcp-server/tools/definitions/lookup-gene.tool.js';
+import { ensemblPredictVariant } from './mcp-server/tools/definitions/predict-variant.tool.js';
+import { ensemblQueryRegion } from './mcp-server/tools/definitions/query-region.tool.js';
+import { initEnsemblService } from './services/ensembl/ensembl-service.js';
+await createApp({
+    tools: [
+        ensemblListSpecies,
+        ensemblLookupGene,
+        ensemblGetSequence,
+        ensemblQueryRegion,
+        ensemblPredictVariant,
+        ensemblGetHomology,
+        ensemblGetXrefs,
+    ],
+    resources: [ensemblGeneResource, ensemblTranscriptResource, ensemblSpeciesResource],
+    prompts: [ensemblGeneDossierPrompt],
+    instructions: `Ensembl genomics server — vertebrate and model organism gene, sequence, and variant data.
+Species names use Ensembl internal format: lowercase_underscore scientific names (homo_sapiens, mus_musculus).
+Discovery workflow: ensembl_list_species → ensembl_lookup_gene → ensembl_get_sequence / ensembl_get_xrefs / ensembl_get_homology.
+For a complete gene research workflow, use the ensembl_gene_dossier prompt.
+Override the default GRCh38 endpoint by setting ENSEMBL_BASE_URL (e.g. https://grch37.rest.ensembl.org for GRCh37).`,
+    setup(core) {
+        initEnsemblService(core.config, core.storage);
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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,EAAE,sBAAsB,EAAE,MAAM,wDAAwD,CAAC;AAChG,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,KAAK,EAAE;QACL,kBAAkB;QAClB,iBAAiB;QACjB,kBAAkB;QAClB,kBAAkB;QAClB,qBAAqB;QACrB,kBAAkB;QAClB,eAAe;KAChB;IACD,SAAS,EAAE,CAAC,mBAAmB,EAAE,yBAAyB,EAAE,sBAAsB,CAAC;IACnF,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/prompts/definitions/gene-dossier.prompt.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Prompt for assembling a complete gene profile using the Ensembl tool chain.
+ * @module mcp-server/prompts/definitions/gene-dossier
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const ensemblGeneDossierPrompt: import("@cyanheads/mcp-ts-core").PromptDefinition<z.ZodObject<{
+    gene_symbol: z.ZodString;
+    species: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>>;
+//# sourceMappingURL=gene-dossier.prompt.d.ts.map

package/dist/mcp-server/prompts/definitions/gene-dossier.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gene-dossier.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/gene-dossier.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,eAAO,MAAM,wBAAwB;;;kBA2DnC,CAAC"}

package/dist/mcp-server/prompts/definitions/gene-dossier.prompt.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Prompt for assembling a complete gene profile using the Ensembl tool chain.
+ * @module mcp-server/prompts/definitions/gene-dossier
+ */
+import { prompt, z } from '@cyanheads/mcp-ts-core';
+export const ensemblGeneDossierPrompt = prompt('ensembl_gene_dossier', {
+    description: 'Structured research workflow for assembling a complete gene profile. Guides the agent through ' +
+        'the Ensembl tool chain in order: symbol → ID + location → protein sequence → key variants → ' +
+        'cross-species orthologs → xref IDs for protein and literature follow-up.',
+    args: z.object({
+        gene_symbol: z
+            .string()
+            .describe('Gene symbol to research (e.g. BRCA2, TP53, EGFR). ' +
+            'Case-insensitive; Ensembl will resolve the canonical form.'),
+        species: z
+            .string()
+            .default('homo_sapiens')
+            .describe('Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). ' +
+            'Default is homo_sapiens. Use ensembl_list_species to discover valid values.'),
+    }),
+    generate: (args) => [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: `Assemble a complete gene profile for **${args.gene_symbol}** in **${args.species}** ` +
+                    `using the Ensembl MCP tools. Follow these steps in order:\n\n` +
+                    `1. **Resolve the gene** — call \`ensembl_lookup_gene\` with symbol="${args.gene_symbol}" ` +
+                    `and species="${args.species}", setting expand_transcripts=true. ` +
+                    `Record the stable ID (ENSG…), genomic coordinates (chr:start-end:strand:assembly), ` +
+                    `biotype, and the canonical transcript ID (ENST…).\n\n` +
+                    `2. **Fetch the protein sequence** — call \`ensembl_get_sequence\` with the canonical ` +
+                    `transcript ID from step 1 and type="protein". Record the amino acid sequence and its length.\n\n` +
+                    `3. **Find variants in the locus** — call \`ensembl_query_region\` with ` +
+                    `species="${args.species}", the gene's chromosomal region (chr:start-end from step 1), ` +
+                    `and feature=["variation"]. Identify any HIGH or MODERATE impact variants.\n\n` +
+                    `4. **Predict variant consequences** — for up to 3 high-impact variants found in step 3, ` +
+                    `call \`ensembl_predict_variant\` with the variant ID or HGVS notation. ` +
+                    `Record most_severe_consequence, impact, and clinical significance.\n\n` +
+                    `5. **Find cross-species orthologs** — call \`ensembl_get_homology\` with ` +
+                    `symbol="${args.gene_symbol}", species="${args.species}", and type="orthologues". ` +
+                    `Focus on mammalian orthologs (mouse, rat, zebrafish). Record perc_id for the top 3.\n\n` +
+                    `6. **Get external database IDs** — call \`ensembl_get_xrefs\` with the stable gene ID ` +
+                    `from step 1 (no dbname filter to get all). Record: ` +
+                    `HGNC ID (dbname=HGNC), UniProt accession (dbname=Uniprot_gn), ` +
+                    `NCBI Gene ID (dbname=EntrezGene), and OMIM ID (dbname=MIM_GENE) if present.\n\n` +
+                    `7. **Synthesize the dossier** — compile your findings into a structured report with sections:\n` +
+                    `   - Gene overview (ID, location, biotype, description)\n` +
+                    `   - Protein sequence summary (length, first 50 aa, key domains if known)\n` +
+                    `   - Variant landscape (count, highest-impact findings, clinical significance)\n` +
+                    `   - Conservation across species (ortholog table with perc_id)\n` +
+                    `   - External IDs for follow-up (UniProt → pubchem for structure, ` +
+                    `HGNC/EntrezGene → pubmed for literature, OMIM for disease associations)\n\n` +
+                    `Use the stable IDs and coordinates from each step as inputs to the next — ` +
+                    `the Ensembl tool chain is designed to chain this way.`,
+            },
+        },
+    ],
+});
+//# sourceMappingURL=gene-dossier.prompt.js.map

package/dist/mcp-server/prompts/definitions/gene-dossier.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gene-dossier.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/gene-dossier.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,sBAAsB,EAAE;IACrE,WAAW,EACT,gGAAgG;QAChG,8FAA8F;QAC9F,0EAA0E;IAC5E,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,CACP,oDAAoD;YAClD,4DAA4D,CAC/D;QACH,OAAO,EAAE,CAAC;aACP,MAAM,EAAE;aACR,OAAO,CAAC,cAAc,CAAC;aACvB,QAAQ,CACP,wEAAwE;YACtE,6EAA6E,CAChF;KACJ,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB;YACE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,MAAM;gBACZ,IAAI,EACF,0CAA0C,IAAI,CAAC,WAAW,WAAW,IAAI,CAAC,OAAO,KAAK;oBACtF,+DAA+D;oBAC/D,uEAAuE,IAAI,CAAC,WAAW,IAAI;oBAC3F,gBAAgB,IAAI,CAAC,OAAO,sCAAsC;oBAClE,qFAAqF;oBACrF,uDAAuD;oBACvD,uFAAuF;oBACvF,kGAAkG;oBAClG,yEAAyE;oBACzE,YAAY,IAAI,CAAC,OAAO,gEAAgE;oBACxF,+EAA+E;oBAC/E,0FAA0F;oBAC1F,yEAAyE;oBACzE,wEAAwE;oBACxE,2EAA2E;oBAC3E,WAAW,IAAI,CAAC,WAAW,eAAe,IAAI,CAAC,OAAO,6BAA6B;oBACnF,yFAAyF;oBACzF,wFAAwF;oBACxF,qDAAqD;oBACrD,gEAAgE;oBAChE,iFAAiF;oBACjF,iGAAiG;oBACjG,2DAA2D;oBAC3D,6EAA6E;oBAC7E,kFAAkF;oBAClF,kEAAkE;oBAClE,oEAAoE;oBACpE,6EAA6E;oBAC7E,4EAA4E;oBAC5E,uDAAuD;aAC1D;SACF;KACF;CACF,CAAC,CAAC"}

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

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Resource exposing Ensembl gene records by stable ID.
+ * @module mcp-server/resources/definitions/gene
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const ensemblGeneResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, undefined, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The gene stable ID was not found in Ensembl.";
+    readonly recovery: string;
+}]>;
+//# sourceMappingURL=gene.resource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gene.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gene.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,mBAAmB;;;;;;;GA2D9B,CAAC"}

package/dist/mcp-server/resources/definitions/gene.resource.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Resource exposing Ensembl gene records by stable ID.
+ * @module mcp-server/resources/definitions/gene
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEnsemblService } from '../../../services/ensembl/ensembl-service.js';
+export const ensemblGeneResource = resource('ensembl://gene/{id}', {
+    name: 'Ensembl Gene',
+    description: 'Gene record by Ensembl stable ID (ENSG…). Returns location, biotype, description, and transcript list. ' +
+        'Stable, injectable context for multi-step workflows. ' +
+        'Use ensembl_lookup_gene to resolve a gene symbol to the stable ID first.',
+    mimeType: 'application/json',
+    params: z.object({
+        id: z
+            .string()
+            .describe('Ensembl gene stable ID (ENSG…). ' +
+            'Version suffix is optional — omitting it resolves to the current version. ' +
+            'Example: ENSG00000139618 or ENSG00000139618.7'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The gene stable ID was not found in Ensembl.',
+            recovery: 'Verify the ID format (ENSG followed by 11 digits, optional .version suffix). ' +
+                'Use ensembl_lookup_gene to resolve a symbol to a current stable ID.',
+        },
+    ],
+    async handler(params, ctx) {
+        ctx.log.debug('Fetching gene resource', { id: params.id });
+        const service = getEnsemblService();
+        const gene = await service.lookupGeneById(params.id, true, ctx).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/not found/i.test(msg)) {
+                throw ctx.fail('not_found', `Gene ${params.id} not found in Ensembl.`);
+            }
+            throw err;
+        });
+        return gene;
+    },
+    list: async () => ({
+        resources: [
+            {
+                uri: 'ensembl://gene/ENSG00000139618',
+                name: 'BRCA2 (homo_sapiens)',
+                description: 'Example: BRCA2 breast cancer susceptibility gene',
+                mimeType: 'application/json',
+            },
+            {
+                uri: 'ensembl://gene/ENSG00000141510',
+                name: 'TP53 (homo_sapiens)',
+                description: 'Example: Tumor protein p53',
+                mimeType: 'application/json',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=gene.resource.js.map

package/dist/mcp-server/resources/definitions/gene.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gene.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gene.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC,qBAAqB,EAAE;IACjE,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,yGAAyG;QACzG,uDAAuD;QACvD,0EAA0E;IAC5E,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,EAAE,EAAE,CAAC;aACF,MAAM,EAAE;aACR,QAAQ,CACP,kCAAkC;YAChC,4EAA4E;YAC5E,+CAA+C,CAClD;KACJ,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,WAAW;YACnB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,8CAA8C;YACpD,QAAQ,EACN,+EAA+E;gBAC/E,qEAAqE;SACxE;KACF;IAED,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;QAEpC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACrF,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,MAAM,CAAC,EAAE,wBAAwB,CAAC,CAAC;YACzE,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjB,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,gCAAgC;gBACrC,IAAI,EAAE,sBAAsB;gBAC5B,WAAW,EAAE,kDAAkD;gBAC/D,QAAQ,EAAE,kBAAkB;aAC7B;YACD;gBACE,GAAG,EAAE,gCAAgC;gBACrC,IAAI,EAAE,qBAAqB;gBAC3B,WAAW,EAAE,4BAA4B;gBACzC,QAAQ,EAAE,kBAAkB;aAC7B;SACF;KACF,CAAC;CACH,CAAC,CAAC"}

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

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Resource exposing the Ensembl species catalog.
+ * @module mcp-server/resources/definitions/species
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const ensemblSpeciesResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    division: z.ZodOptional<z.ZodEnum<{
+        EnsemblVertebrates: "EnsemblVertebrates";
+        EnsemblPlants: "EnsemblPlants";
+        EnsemblFungi: "EnsemblFungi";
+        EnsemblMetazoa: "EnsemblMetazoa";
+        EnsemblProtists: "EnsemblProtists";
+    }>>;
+}, z.core.$strip>, undefined, undefined>;
+//# sourceMappingURL=species.resource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"species.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/species.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAWrD,eAAO,MAAM,sBAAsB;;;;;;;;wCAwCjC,CAAC"}

package/dist/mcp-server/resources/definitions/species.resource.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Resource exposing the Ensembl species catalog.
+ * @module mcp-server/resources/definitions/species
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { getEnsemblService } from '../../../services/ensembl/ensembl-service.js';
+const DIVISION_VALUES = [
+    'EnsemblVertebrates',
+    'EnsemblPlants',
+    'EnsemblFungi',
+    'EnsemblMetazoa',
+    'EnsemblProtists',
+];
+export const ensemblSpeciesResource = resource('ensembl://species', {
+    name: 'Ensembl Species',
+    description: 'Complete catalog of Ensembl-supported species with internal name, display name, assembly, ' +
+        'taxon ID, and division. Addressable reference for tool bootstrapping. ' +
+        'Contains ~350 vertebrate species plus additional non-vertebrate divisions. ' +
+        'Use this as stable, injectable context when working with unfamiliar species names.',
+    mimeType: 'application/json',
+    params: z.object({
+        division: z
+            .enum(DIVISION_VALUES)
+            .optional()
+            .describe('Filter to a specific Ensembl division. ' + 'Omit to return species from all divisions.'),
+    }),
+    async handler(params, ctx) {
+        ctx.log.debug('Fetching species resource', { division: params.division });
+        const service = getEnsemblService();
+        const allSpecies = await service.listSpecies(params.division, ctx);
+        allSpecies.sort((a, b) => a.name.localeCompare(b.name));
+        return {
+            species: allSpecies,
+            totalCount: allSpecies.length,
+        };
+    },
+    list: async () => ({
+        resources: [
+            {
+                uri: 'ensembl://species',
+                name: 'All Ensembl Species',
+                description: 'Complete catalog of Ensembl-supported species',
+                mimeType: 'application/json',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=species.resource.js.map

package/dist/mcp-server/resources/definitions/species.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"species.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/species.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,eAAe,GAAG;IACtB,oBAAoB;IACpB,eAAe;IACf,cAAc;IACd,gBAAgB;IAChB,iBAAiB;CACT,CAAC;AAEX,MAAM,CAAC,MAAM,sBAAsB,GAAG,QAAQ,CAAC,mBAAmB,EAAE;IAClE,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,4FAA4F;QAC5F,wEAAwE;QACxE,6EAA6E;QAC7E,oFAAoF;IACtF,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,QAAQ,EAAE,CAAC;aACR,IAAI,CAAC,eAAe,CAAC;aACrB,QAAQ,EAAE;aACV,QAAQ,CACP,yCAAyC,GAAG,4CAA4C,CACzF;KACJ,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,2BAA2B,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1E,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;QAEpC,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACnE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAExD,OAAO;YACL,OAAO,EAAE,UAAU;YACnB,UAAU,EAAE,UAAU,CAAC,MAAM;SAC9B,CAAC;IACJ,CAAC;IAED,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjB,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,mBAAmB;gBACxB,IAAI,EAAE,qBAAqB;gBAC3B,WAAW,EAAE,+CAA+C;gBAC5D,QAAQ,EAAE,kBAAkB;aAC7B;SACF;KACF,CAAC;CACH,CAAC,CAAC"}

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

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Resource exposing Ensembl transcript records by stable ID.
+ * @module mcp-server/resources/definitions/transcript
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const ensemblTranscriptResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, undefined, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The transcript stable ID was not found in Ensembl.";
+    readonly recovery: string;
+}]>;
+//# sourceMappingURL=transcript.resource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/transcript.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,yBAAyB;;;;;;;GAqDpC,CAAC"}

package/dist/mcp-server/resources/definitions/transcript.resource.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Resource exposing Ensembl transcript records by stable ID.
+ * @module mcp-server/resources/definitions/transcript
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEnsemblService } from '../../../services/ensembl/ensembl-service.js';
+export const ensemblTranscriptResource = resource('ensembl://transcript/{id}', {
+    name: 'Ensembl Transcript',
+    description: 'Transcript record by Ensembl stable ID (ENST…). Returns parent gene, location, biotype, ' +
+        'canonical flag, and length. Use ensembl_lookup_gene with expand_transcripts=true to discover ' +
+        'transcript IDs for a given gene, then fetch this resource for stable, injectable context.',
+    mimeType: 'application/json',
+    params: z.object({
+        id: z
+            .string()
+            .describe('Ensembl transcript stable ID (ENST…). ' +
+            'Version suffix is optional — omitting it resolves to the current version. ' +
+            'Example: ENST00000380152 or ENST00000380152.8'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The transcript stable ID was not found in Ensembl.',
+            recovery: 'Verify the ID format (ENST followed by 11 digits, optional .version suffix). ' +
+                'Use ensembl_lookup_gene with expand_transcripts=true to get transcript IDs.',
+        },
+    ],
+    async handler(params, ctx) {
+        ctx.log.debug('Fetching transcript resource', { id: params.id });
+        const service = getEnsemblService();
+        const transcript = await service.lookupTranscript(params.id, ctx).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/not found/i.test(msg)) {
+                throw ctx.fail('not_found', `Transcript ${params.id} not found in Ensembl.`);
+            }
+            throw err;
+        });
+        return transcript;
+    },
+    list: async () => ({
+        resources: [
+            {
+                uri: 'ensembl://transcript/ENST00000380152',
+                name: 'BRCA2-201 canonical transcript (homo_sapiens)',
+                description: 'Example: canonical BRCA2 transcript',
+                mimeType: 'application/json',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=transcript.resource.js.map

package/dist/mcp-server/resources/definitions/transcript.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/transcript.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,CAAC,MAAM,yBAAyB,GAAG,QAAQ,CAAC,2BAA2B,EAAE;IAC7E,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EACT,0FAA0F;QAC1F,+FAA+F;QAC/F,2FAA2F;IAC7F,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,EAAE,EAAE,CAAC;aACF,MAAM,EAAE;aACR,QAAQ,CACP,wCAAwC;YACtC,4EAA4E;YAC5E,+CAA+C,CAClD;KACJ,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,WAAW;YACnB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,oDAAoD;YAC1D,QAAQ,EACN,+EAA+E;gBAC/E,6EAA6E;SAChF;KACF;IAED,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,8BAA8B,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;QAEpC,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACvF,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,MAAM,CAAC,EAAE,wBAAwB,CAAC,CAAC;YAC/E,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjB,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,sCAAsC;gBAC3C,IAAI,EAAE,+CAA+C;gBACrD,WAAW,EAAE,qCAAqC;gBAClD,QAAQ,EAAE,kBAAkB;aAC7B;SACF;KACF,CAAC;CACH,CAAC,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Tool to find orthologs and paralogs of a gene across species.
+ * @module mcp-server/tools/definitions/get-homology
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const ensemblGetHomology: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    symbol: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    species: z.ZodDefault<z.ZodString>;
+    target_species: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodEnum<{
+        orthologues: "orthologues";
+        paralogues: "paralogues";
+        all: "all";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    homologs: z.ZodArray<z.ZodObject<{
+        targetId: z.ZodString;
+        targetSpecies: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        percId: z.ZodOptional<z.ZodNumber>;
+        percPos: z.ZodOptional<z.ZodNumber>;
+        taxonomyLevel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+    queryId: z.ZodString;
+    querySpecies: z.ZodString;
+    queryType: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The gene symbol or stable ID was not found in Ensembl.";
+    readonly recovery: string;
+}, {
+    readonly reason: "no_input";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "Neither symbol nor id was provided.";
+    readonly recovery: "Provide either symbol (with species) or a stable Ensembl gene ID.";
+}], {
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=get-homology.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-homology.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-homology.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA0CjE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyK7B,CAAC"}