@cyanheads/ensembl-mcp-server 0.1.1

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

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview Tool to find orthologs and paralogs of a gene across species.
+ * @module mcp-server/tools/definitions/get-homology
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEnsemblService } from '../../../services/ensembl/ensembl-service.js';
+const HOMOLOGY_TYPES = ['orthologues', 'paralogues', 'all'];
+const HomologyEntrySchema = z.object({
+    targetId: z.string().describe('Ensembl stable ID of the homologous gene in the target species.'),
+    targetSpecies: z
+        .string()
+        .optional()
+        .describe('Target species in Ensembl internal format (e.g. mus_musculus).'),
+    type: z
+        .string()
+        .optional()
+        .describe('Homology type: ortholog_one2one, ortholog_one2many, ortholog_many2many, ' +
+        'paralog_many2many, within_species_paralog, or similar.'),
+    percId: z
+        .number()
+        .optional()
+        .describe('Percent identity between the query and target gene sequences (0-100). ' +
+        'Higher values indicate more conserved sequences.'),
+    percPos: z
+        .number()
+        .optional()
+        .describe('Percent positive (similar) positions in the alignment (0-100). ' +
+        'Includes conservative substitutions as well as identical residues.'),
+    taxonomyLevel: z
+        .string()
+        .optional()
+        .describe('Last common ancestor taxonomic level for this homology relationship ' +
+        '(e.g. Amniota, Vertebrata, Bilateria).'),
+});
+export const ensemblGetHomology = tool('ensembl_get_homology', {
+    title: 'Get Gene Homologs',
+    description: "Find orthologs and/or paralogs of a gene across species. Returns each homolog's stable ID, species, " +
+        'homology type (ortholog_one2one, ortholog_one2many, paralog_many2many, etc.), perc_id (percent identity), ' +
+        'perc_pos (percent positives), and taxonomy level. Essential for cross-species research — for example, ' +
+        '"what is the mouse equivalent of human TP53?" or "how conserved is BRCA2 across mammals?". ' +
+        'Provide either symbol + species or a stable gene ID. Target species can be filtered to a single species ' +
+        'or left open to return all available homologs.',
+    annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+    input: z.object({
+        symbol: z
+            .string()
+            .optional()
+            .describe('Gene symbol in the source species (e.g. BRCA2, TP53). ' +
+            'Requires species to be set. Cannot be used together with id.'),
+        id: z
+            .string()
+            .optional()
+            .describe('Ensembl stable gene ID (e.g. ENSG00000139618). ' +
+            'Use ensembl_lookup_gene to get the stable ID from a symbol. ' +
+            'Cannot be used together with symbol.'),
+        species: z
+            .string()
+            .default('homo_sapiens')
+            .describe('Source species (the species the query gene belongs to) in Ensembl internal format. ' +
+            'Default is homo_sapiens. Use ensembl_list_species to discover valid values.'),
+        target_species: z
+            .string()
+            .optional()
+            .describe('Filter to homologs in a single target species (e.g. mus_musculus for mouse). ' +
+            'Omit to return homologs across all available species. ' +
+            'Use ensembl_list_species to discover valid values.'),
+        type: z
+            .enum(HOMOLOGY_TYPES)
+            .default('orthologues')
+            .describe('Type of homologs to return. ' +
+            'orthologues: genes related by speciation (cross-species equivalents). ' +
+            'paralogues: genes related by duplication (within or across species). ' +
+            'all: both orthologs and paralogs.'),
+    }),
+    output: z.object({
+        homologs: z
+            .array(HomologyEntrySchema.describe('A single homologous gene with its stable ID, species, homology type, and sequence identity metrics.'))
+            .describe('Homologous genes found for the query gene.'),
+        totalCount: z.number().describe('Total number of homologs returned.'),
+        queryId: z.string().describe('The resolved Ensembl gene ID used for the homology query.'),
+        querySpecies: z.string().describe('The source species used for the query.'),
+        queryType: z.string().describe('The homology type queried (orthologues, paralogues, or all).'),
+    }),
+    enrichment: {
+        notice: z.string().optional().describe('Guidance when no homologs are found.'),
+    },
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The gene symbol or stable ID was not found in Ensembl.',
+            recovery: 'Verify the symbol spelling or use ensembl_lookup_gene to get the stable ID first. ' +
+                'Confirm the species is correct with ensembl_list_species.',
+        },
+        {
+            reason: 'no_input',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'Neither symbol nor id was provided.',
+            recovery: 'Provide either symbol (with species) or a stable Ensembl gene ID.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Getting homologs', {
+            symbol: input.symbol,
+            id: input.id,
+            species: input.species,
+            targetSpecies: input.target_species,
+            type: input.type,
+        });
+        const service = getEnsemblService();
+        if (!input.symbol?.trim() && !input.id?.trim()) {
+            throw ctx.fail('no_input', 'Provide either symbol (with species) or a stable gene ID.');
+        }
+        const idTrimmed = input.id?.trim();
+        const symbolTrimmed = input.symbol?.trim();
+        let queryId;
+        let homologs;
+        if (idTrimmed) {
+            queryId = idTrimmed;
+            homologs = await service
+                .getHomologyById(queryId, input.species, input.type, input.target_species, ctx)
+                .catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/not found|no valid lookup|page not found/i.test(msg)) {
+                    throw ctx.fail('not_found', `Gene ID "${queryId}" not found in Ensembl.`);
+                }
+                throw err;
+            });
+        }
+        else {
+            queryId = symbolTrimmed ?? '';
+            homologs = await service
+                .getHomologyBySymbol(queryId, input.species, input.type, input.target_species, ctx)
+                .catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                // Ensembl returns {"error":"<species_name>"} for invalid gene symbols in homology endpoint
+                if (/not found|no valid lookup/i.test(msg) || msg === input.species) {
+                    throw ctx.fail('not_found', `Gene symbol "${queryId}" not found in ${input.species}.`);
+                }
+                throw err;
+            });
+        }
+        if (homologs.length === 0) {
+            ctx.enrich.notice(`No ${input.type} found for "${queryId}" in ${input.species}` +
+                (input.target_species ? ` targeting ${input.target_species}` : '') +
+                '. Try type=all or remove the target_species filter.');
+        }
+        ctx.enrich.total(homologs.length);
+        return {
+            homologs,
+            totalCount: homologs.length,
+            queryId,
+            querySpecies: input.species,
+            queryType: input.type,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`## Homologs of ${result.queryId} (${result.querySpecies})`);
+        lines.push(`**Type:** ${result.queryType} | **Found:** ${result.totalCount}\n`);
+        if (result.homologs.length === 0) {
+            lines.push('No homologs found. Try type=all or remove the target_species filter.');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        for (const h of result.homologs) {
+            lines.push(`### ${h.targetId}`);
+            if (h.targetSpecies)
+                lines.push(`**Species:** ${h.targetSpecies}`);
+            if (h.type)
+                lines.push(`**Homology type:** ${h.type}`);
+            if (h.percId != null)
+                lines.push(`**Percent identity:** ${h.percId.toFixed(1)}%`);
+            if (h.percPos != null)
+                lines.push(`**Percent positives:** ${h.percPos.toFixed(1)}%`);
+            if (h.taxonomyLevel)
+                lines.push(`**Last common ancestor:** ${h.taxonomyLevel}`);
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-homology.tool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-homology.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-homology.tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Tool to fetch DNA, cDNA, CDS, or protein sequences for Ensembl IDs or genomic regions.
+ * @module mcp-server/tools/definitions/get-sequence
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+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";
+        protein: "protein";
+    }>>;
+    species: z.ZodOptional<z.ZodString>;
+    expand_5prime: z.ZodDefault<z.ZodNumber>;
+    expand_3prime: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    seq: z.ZodString;
+    lengthInBp: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The stable ID or region was not found in Ensembl.";
+    readonly recovery: string;
+}, {
+    readonly reason: "type_mismatch";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The requested sequence type is incompatible with the provided ID type.";
+    readonly recovery: string;
+}], undefined>;
+//# sourceMappingURL=get-sequence.tool.d.ts.map

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

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

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

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Tool to fetch DNA, cDNA, CDS, or protein sequences for Ensembl IDs or genomic regions.
+ * @module mcp-server/tools/definitions/get-sequence
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEnsemblService } from '../../../services/ensembl/ensembl-service.js';
+const SEQUENCE_TYPES = ['genomic', 'cdna', 'cds', 'protein'];
+export const ensemblGetSequence = tool('ensembl_get_sequence', {
+    title: 'Get Sequence',
+    description: 'Fetch the DNA, cDNA, CDS, or protein sequence for a gene, transcript, protein, or genomic region. ' +
+        'Returns the sequence with its stable ID, molecule type, and character count — large sequences are ' +
+        'returned in full but the length is stated so callers can budget context. The type parameter selects ' +
+        'which sequence is fetched: genomic (default, includes introns), cdna (spliced transcript), ' +
+        'cds (coding sequence only), protein. For region mode, set id to the format species:chr:start-end ' +
+        '(e.g. homo_sapiens:13:32315086-32400268) and set species. Protein sequences require a transcript or ' +
+        'protein stable ID (ENST…/ENSP…), not a gene ID — use ensembl_lookup_gene with expand_transcripts=true ' +
+        'to get the canonical transcript ID first.',
+    annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+    input: z.object({
+        id: z
+            .string()
+            .describe('Ensembl stable ID (ENSG…, ENST…, ENSP…) or region in the format ' +
+            'species:chr:start-end (e.g. homo_sapiens:13:32315086-32400268) for region mode. ' +
+            'For genomic region queries, species is also required.'),
+        type: z
+            .enum(SEQUENCE_TYPES)
+            .default('genomic')
+            .describe('Sequence type to retrieve. ' +
+            'genomic: full genomic DNA including introns (default). ' +
+            'cdna: spliced transcript sequence (requires ENST… ID). ' +
+            'cds: coding sequence only, no UTRs (requires ENST… ID with coding transcript). ' +
+            'protein: amino acid sequence (requires ENST… or ENSP… ID).'),
+        species: z
+            .string()
+            .optional()
+            .describe('Species in Ensembl internal format (e.g. homo_sapiens). ' +
+            'Required for region mode (when id is a species:chr:start-end string). ' +
+            'Optional for stable ID lookups — Ensembl infers species from the ID prefix.'),
+        expand_5prime: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Number of base pairs to extend upstream (5' direction) of the requested feature. " +
+            'Default 0. Only applies to genomic sequences and region queries.'),
+        expand_3prime: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Number of base pairs to extend downstream (3' direction) of the requested feature. " +
+            'Default 0. Only applies to genomic sequences and region queries.'),
+    }),
+    output: z.object({
+        id: z.string().describe('The stable ID or region used for the lookup.'),
+        type: z.string().describe('Sequence type returned (genomic, cdna, cds, or protein).'),
+        seq: z
+            .string()
+            .describe('The full sequence. DNA sequences use IUPAC nucleotide codes (ACGT + ambiguity codes). ' +
+            'Protein sequences use single-letter amino acid codes. ' +
+            'Large genomic sequences (e.g. 85 kb for BRCA2) are returned in full.'),
+        lengthInBp: z
+            .number()
+            .describe('Sequence length in characters (nucleotides or amino acids). ' +
+            'Use this to budget context window usage before processing the sequence.'),
+        description: z.string().optional().describe('Sequence description from Ensembl, if provided.'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The stable ID or region was not found in Ensembl.',
+            recovery: 'Verify the ID format (ENSG…, ENST…, ENSP…) or region coordinates. ' +
+                'Use ensembl_lookup_gene to get valid stable IDs first.',
+        },
+        {
+            reason: 'type_mismatch',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The requested sequence type is incompatible with the provided ID type.',
+            recovery: 'protein and cds sequences require a transcript ID (ENST…) or protein ID (ENSP…), not a gene ID. ' +
+                'Use ensembl_lookup_gene with expand_transcripts=true to find the canonical transcript ID, ' +
+                'then request the protein or cds sequence from that transcript ID.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Fetching sequence', { id: input.id, type: input.type });
+        const service = getEnsemblService();
+        // Detect region mode: contains ":" after optional species prefix.
+        // Scaffold/patch names carry dots (e.g. GL000220.1), so the chromosome
+        // segment allows "." in addition to word characters.
+        const regionPattern = /^[a-z_]+:[\w.]+:\d+-\d+$/i;
+        const isRegion = regionPattern.test(input.id);
+        if (isRegion) {
+            // Parse "species:chr:start-end"
+            const parts = input.id.split(':');
+            if (parts.length !== 3) {
+                throw ctx.fail('not_found', `Region format should be species:chr:start-end, got: ${input.id}`);
+            }
+            const [speciesFromId, chr, range] = parts;
+            const speciesStr = input.species?.trim() || speciesFromId;
+            const region = `${chr}:${range}`;
+            const seq = await service
+                .getSequenceByRegion(speciesStr, region, input.expand_5prime, input.expand_3prime, ctx)
+                .catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/not found|invalid|no stable id/i.test(msg)) {
+                    throw ctx.fail('not_found', `Region ${input.id} not found: ${msg}`);
+                }
+                throw err;
+            });
+            return seq;
+        }
+        // Stable ID mode
+        const seq = await service
+            .getSequenceById(input.id.trim(), input.type, ctx)
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/protein.*gene|cds.*gene|type.*mismatch|incompatible/i.test(msg) ||
+                /requesting a gene and type not equal/i.test(msg) ||
+                /multiple sequences detected/i.test(msg)) {
+                throw ctx.fail('type_mismatch', `Cannot request type "${input.type}" from a gene ID — use a transcript or protein stable ID instead. ` +
+                    `Call ensembl_lookup_gene with expand_transcripts=true to get transcript IDs.`);
+            }
+            if (/not found|no stable id/i.test(msg)) {
+                throw ctx.fail('not_found', `ID ${input.id} not found in Ensembl.`);
+            }
+            throw err;
+        });
+        return seq;
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`## Sequence: ${result.id}`);
+        lines.push(`**Type:** ${result.type} | **Length:** ${result.lengthInBp.toLocaleString()} bp/aa`);
+        if (result.description)
+            lines.push(`**Description:** ${result.description}`);
+        lines.push('');
+        // Show first 200 chars + truncation note for large sequences
+        if (result.seq.length > 200) {
+            lines.push('```');
+            lines.push(result.seq.slice(0, 200));
+            lines.push(`… (${result.lengthInBp.toLocaleString()} total characters)`);
+            lines.push('```');
+        }
+        else {
+            lines.push('```');
+            lines.push(result.seq);
+            lines.push('```');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-sequence.tool.js.map

package/dist/mcp-server/tools/definitions/get-sequence.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-sequence.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-sequence.tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Tool to retrieve cross-database references for Ensembl genes and features.
+ * @module mcp-server/tools/definitions/get-xrefs
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const ensemblGetXrefs: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    id: z.ZodString;
+    dbname: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    xrefs: z.ZodArray<z.ZodObject<{
+        dbname: z.ZodOptional<z.ZodString>;
+        dbDisplayName: z.ZodOptional<z.ZodString>;
+        primaryId: z.ZodOptional<z.ZodString>;
+        displayId: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+    queriedId: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The Ensembl stable ID was not found or has no cross-references.";
+    readonly recovery: string;
+}], {
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=get-xrefs.tool.d.ts.map

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

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

package/dist/mcp-server/tools/definitions/get-xrefs.tool.js

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Tool to retrieve cross-database references for Ensembl genes and features.
+ * @module mcp-server/tools/definitions/get-xrefs
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEnsemblService } from '../../../services/ensembl/ensembl-service.js';
+const XrefEntrySchema = z.object({
+    dbname: z
+        .string()
+        .optional()
+        .describe('Database name in Ensembl internal format (e.g. HGNC, Uniprot_gn, EntrezGene, MIM_GENE, RefSeq_mRNA).'),
+    dbDisplayName: z.string().optional().describe('Human-readable database display name.'),
+    primaryId: z
+        .string()
+        .optional()
+        .describe('Primary identifier in the external database (e.g. HGNC:1101 for BRCA2 in HGNC, ' +
+        'P51587 for BRCA2 in UniProt).'),
+    displayId: z
+        .string()
+        .optional()
+        .describe('Display identifier — often the same as primaryId but may be a formatted accession.'),
+    description: z.string().optional().describe('Description of the cross-reference entry.'),
+});
+export const ensemblGetXrefs = tool('ensembl_get_xrefs', {
+    title: 'Get Cross-Database References',
+    description: 'Retrieve cross-database references for a gene or feature — HGNC, UniProt, EntrezGene, OMIM, ' +
+        'RefSeq, Reactome, and others. Returns each xref with its database name, primary ID, display ID, ' +
+        'and description. The dbname filter narrows to specific databases; omit to return all xrefs. ' +
+        'IDs returned here chain to protein (pubchem via UniProt), literature (pubmed via PubMed IDs), ' +
+        'disease (OMIM via MIM_GENE), and pathway (Reactome) resources. ' +
+        'Requires an Ensembl stable ID — use ensembl_lookup_gene to get the ENSG… ID first. ' +
+        'Common dbname values: HGNC, Uniprot_gn, EntrezGene, MIM_GENE, RefSeq_mRNA, RefSeq_peptide, ' +
+        'Reactome, GO (Gene Ontology), ChEMBL.',
+    annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+    input: z.object({
+        id: z
+            .string()
+            .describe('Ensembl stable gene ID (ENSG…) or transcript ID (ENST…). ' +
+            'Use ensembl_lookup_gene to get the stable ID from a gene symbol. ' +
+            'xrefs/id returns the full cross-reference set (56+ entries for well-annotated genes like BRCA2).'),
+        dbname: z
+            .string()
+            .optional()
+            .describe('Filter to a specific external database by its Ensembl internal name. ' +
+            'Examples: HGNC (HGNC gene ID), Uniprot_gn (UniProt gene name), ' +
+            'EntrezGene (NCBI Gene ID), MIM_GENE (OMIM disease gene), ' +
+            'RefSeq_mRNA (NCBI RefSeq transcript), Reactome (pathway IDs), ' +
+            'GO (Gene Ontology terms). Omit to return all available xrefs.'),
+    }),
+    output: z.object({
+        xrefs: z
+            .array(XrefEntrySchema.describe('A single cross-database reference entry with database name, primary ID, and description.'))
+            .describe('Cross-database references for the queried Ensembl ID.'),
+        totalCount: z.number().describe('Total number of cross-references returned.'),
+        queriedId: z.string().describe('The Ensembl stable ID that was queried.'),
+    }),
+    enrichment: {
+        notice: z.string().optional().describe('Guidance when no cross-references are found.'),
+    },
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The Ensembl stable ID was not found or has no cross-references.',
+            recovery: 'Use ensembl_lookup_gene to verify the stable ID is current and valid. ' +
+                'Versioned IDs (ENSG00000139618.7) should work with or without the version suffix.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Getting xrefs', { id: input.id, dbname: input.dbname });
+        const service = getEnsemblService();
+        const xrefs = await service
+            .getXrefsById(input.id.trim(), input.dbname?.trim() || undefined, ctx)
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/not found/i.test(msg)) {
+                throw ctx.fail('not_found', `ID "${input.id}" not found in Ensembl.`);
+            }
+            throw err;
+        });
+        if (xrefs.length === 0) {
+            const filterNote = input.dbname ? ` with dbname filter "${input.dbname}"` : '';
+            ctx.enrich.notice(`No cross-references found for ${input.id}${filterNote}. ` +
+                'Try without the dbname filter to see all available databases.');
+        }
+        ctx.enrich.total(xrefs.length);
+        return { xrefs, totalCount: xrefs.length, queriedId: input.id };
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`## Cross-References for ${result.queriedId}`);
+        lines.push(`**Total:** ${result.totalCount}\n`);
+        if (result.xrefs.length === 0) {
+            lines.push('No cross-references found.');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        // Group by database for readability
+        const byDb = new Map();
+        for (const x of result.xrefs) {
+            const db = x.dbname ?? 'Unknown';
+            if (!byDb.has(db))
+                byDb.set(db, []);
+            byDb.get(db)?.push(x);
+        }
+        for (const [db, entries] of byDb) {
+            const displayName = entries[0]?.dbDisplayName;
+            lines.push(`### ${displayName ?? db}${displayName && displayName !== db ? ` (${db})` : ''}`);
+            for (const x of entries) {
+                let line = `- **${x.primaryId ?? x.displayId ?? 'unknown'}**`;
+                if (x.displayId && x.displayId !== x.primaryId)
+                    line += ` (${x.displayId})`;
+                if (x.description)
+                    line += `: ${x.description}`;
+                lines.push(line);
+            }
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-xrefs.tool.js.map

package/dist/mcp-server/tools/definitions/get-xrefs.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-xrefs.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-xrefs.tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Tool to list Ensembl-supported species with display names, assemblies, and taxon IDs.
+ * @module mcp-server/tools/definitions/list-species
+ */
+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";
+        EnsemblProtists: "EnsemblProtists";
+    }>>;
+    nameContains: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    species: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        commonName: z.ZodOptional<z.ZodString>;
+        taxonId: z.ZodOptional<z.ZodString>;
+        assembly: z.ZodOptional<z.ZodString>;
+        division: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+}, z.core.$strip>, undefined, {
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=list-species.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list-species.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/list-species.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AA+BjD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAkF7B,CAAC"}