@cyanheads/ensembl-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/predict-variant.tool.js

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview Tool to predict functional consequences of sequence variants using Ensembl VEP.
+ * @module mcp-server/tools/definitions/predict-variant
+ */
+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 TranscriptConsequenceSchema = z.object({
+    transcriptId: z
+        .string()
+        .optional()
+        .describe('Ensembl transcript ID (ENST…) affected by this variant.'),
+    geneId: z
+        .string()
+        .optional()
+        .describe('Ensembl gene ID (ENSG…) harboring the affected transcript.'),
+    geneSymbol: z.string().optional().describe('Gene symbol (e.g. BRCA2, TP53).'),
+    consequenceTerms: z
+        .array(z
+        .string()
+        .describe('A Sequence Ontology consequence term (e.g. missense_variant, stop_gained).'))
+        .describe('Sequence Ontology consequence terms for this transcript.'),
+    impact: z
+        .string()
+        .optional()
+        .describe('Impact level: HIGH (frameshift, stop_gained), MODERATE (missense), LOW (synonymous), or MODIFIER.'),
+    biotype: z.string().optional().describe('Transcript biotype (e.g. protein_coding).'),
+    hgvsc: z.string().optional().describe('HGVS notation at the cDNA level (e.g. c.2T>A).'),
+    hgvsp: z.string().optional().describe('HGVS notation at the protein level (e.g. p.Met1Thr).'),
+    aminoAcids: z
+        .string()
+        .optional()
+        .describe('Reference/alternate amino acids separated by "/" (e.g. M/T).'),
+    sift: z
+        .object({
+        prediction: z.string().describe('SIFT prediction: deleterious or tolerated.'),
+        score: z
+            .number()
+            .describe('SIFT score (0-1). Lower scores indicate more deleterious variants.'),
+    })
+        .optional()
+        .describe('SIFT pathogenicity prediction for missense variants. Omitted when not applicable.'),
+    polyphen: z
+        .object({
+        prediction: z
+            .string()
+            .describe('PolyPhen prediction: probably_damaging, possibly_damaging, or benign.'),
+        score: z
+            .number()
+            .describe('PolyPhen score (0-1). Higher scores indicate more damaging variants.'),
+    })
+        .optional()
+        .describe('PolyPhen pathogenicity prediction for missense variants. Omitted when not applicable.'),
+});
+const ColocatedVariantSchema = z.object({
+    id: z.string().optional().describe('Known variant ID (e.g. rs1234567 for dbSNP entries).'),
+    alleleString: z
+        .string()
+        .optional()
+        .describe('Allele string showing reference/alternate (e.g. A/T).'),
+    clinicalSignificance: z
+        .array(z.string().describe('A clinical significance term for this colocated known variant.'))
+        .optional()
+        .describe('Clinical significance terms from ClinVar (e.g. pathogenic, benign).'),
+    pubmed: z
+        .array(z.number().describe('A PubMed ID for literature citing this variant.'))
+        .optional()
+        .describe('PubMed IDs for literature associated with this variant.'),
+});
+const VepResultSchema = z.object({
+    input: z.string().optional().describe('The input variant notation as submitted to VEP.'),
+    chromosome: z.string().optional().describe('Chromosome the variant is on.'),
+    start: z.number().optional().describe('Variant start position (1-based).'),
+    end: z.number().optional().describe('Variant end position (1-based).'),
+    assemblyName: z.string().optional().describe('Genome assembly name (e.g. GRCh38).'),
+    mostSevereConsequence: z
+        .string()
+        .optional()
+        .describe('Most severe Sequence Ontology consequence term across all transcripts ' +
+        '(e.g. stop_gained, missense_variant, synonymous_variant).'),
+    transcriptConsequences: z
+        .array(TranscriptConsequenceSchema.describe('Consequence details for one affected transcript, including impact, HGVS notation, and pathogenicity scores.'))
+        .describe('Per-transcript consequence details. High-impact variants may affect many transcripts; ' +
+        'focus on canonical transcripts (isCanonical from ensembl_lookup_gene) for primary effect.'),
+    colocatedVariants: z
+        .array(ColocatedVariantSchema.describe('A known variant at the same genomic position from public databases (dbSNP, ClinVar).'))
+        .describe('Known variants at the same position from public databases (dbSNP, ClinVar). ' +
+        'Empty when the variant is novel.'),
+});
+export const ensemblPredictVariant = tool('ensembl_predict_variant', {
+    title: 'Predict Variant Effect',
+    description: 'Predict the functional consequences of a sequence variant using the Ensembl Variant Effect Predictor (VEP). ' +
+        'Accepts HGVS notation (transcript-relative, e.g. ENST00000380152.8:c.2T>A, or genomic, ' +
+        'e.g. 13:g.32316462T>A) and also region+allele format (chr:start:end:strand/allele, ' +
+        'e.g. 1:65568:65568:1/T). Returns the most severe consequence term, affected transcripts and genes, ' +
+        'impact level (HIGH/MODERATE/LOW/MODIFIER), and any colocated known variants with clinical significance. ' +
+        'HGVS input: provide the full notation including transcript version for best results. ' +
+        'Region+allele input: use Ensembl chromosome naming (no chr prefix for vertebrates).',
+    annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+    input: z.object({
+        variant: z
+            .string()
+            .describe('Variant in one of two formats: ' +
+            '(1) HGVS notation — transcript-relative: ENST00000380152.8:c.2T>A; ' +
+            'genomic: 13:g.32316462T>A; ' +
+            '(2) Region+allele: chr:start:end:strand/allele — e.g. 1:65568:65568:1/T. ' +
+            'For region+allele, strand is 1 (forward) or -1 (reverse); ' +
+            'chromosome names use no "chr" prefix for vertebrates.'),
+        species: z
+            .string()
+            .default('homo_sapiens')
+            .describe('Species in Ensembl internal format. Default is homo_sapiens. ' +
+            'For non-human variants, set the appropriate species ' +
+            '(e.g. mus_musculus for mouse). Use ensembl_list_species to discover valid values.'),
+    }),
+    output: z.object({
+        results: z
+            .array(VepResultSchema.describe('VEP consequence record for one genomic position, with transcript consequences and colocated known variants.'))
+            .describe('VEP consequence records — typically one per input variant. ' +
+            'Multiple records appear when a single notation matches multiple genomic positions.'),
+        totalCount: z.number().describe('Number of VEP consequence records returned.'),
+    }),
+    enrichment: {
+        notice: z.string().optional().describe('Guidance when no results are returned.'),
+    },
+    errors: [
+        {
+            reason: 'invalid_notation',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The variant notation is malformed or cannot be parsed by VEP.',
+            recovery: 'Check HGVS format: transcript-relative uses ENST…:c.POSREF>ALT; ' +
+                'genomic uses CHR:g.POSREF>ALT. ' +
+                'Region+allele format is chr:start:end:strand/allele. ' +
+                'Verify the transcript version matches the current Ensembl release.',
+        },
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The variant location falls outside any known transcript or assembly region.',
+            recovery: 'Verify the chromosome and position are within the target assembly bounds. ' +
+                'Use ensembl_query_region to confirm the genomic context around the position.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Predicting variant effect', { variant: input.variant, species: input.species });
+        const service = getEnsemblService();
+        // Detect region+allele format: chr:start:end:strand/allele
+        const regionAllelePattern = /^([^:]+):(\d+):(\d+):(-?1)\/(.+)$/;
+        const regionMatch = input.variant.match(regionAllelePattern);
+        let results;
+        if (regionMatch) {
+            const [, chr, start, end, strand, allele] = regionMatch;
+            results = await service
+                .predictVariantRegion(chr, Number(start), Number(end), Number(strand), allele, input.species, ctx)
+                .catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/invalid|unrecognized|parse|malformed/i.test(msg)) {
+                    throw ctx.fail('invalid_notation', `Invalid region+allele notation "${input.variant}": ${msg}`);
+                }
+                if (/not found|outside/i.test(msg)) {
+                    throw ctx.fail('not_found', `Variant location not found: ${msg}`);
+                }
+                throw err;
+            });
+        }
+        else {
+            results = await service
+                .predictVariantHgvs(input.variant, input.species, ctx)
+                .catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/invalid|unrecognized|parse|malformed|hgvs/i.test(msg)) {
+                    throw ctx.fail('invalid_notation', `Invalid HGVS notation "${input.variant}": ${msg}`);
+                }
+                if (/not found/i.test(msg)) {
+                    throw ctx.fail('not_found', `Variant ${input.variant} not found.`);
+                }
+                throw err;
+            });
+        }
+        if (results.length === 0) {
+            ctx.enrich.notice(`No VEP results for "${input.variant}". ` +
+                'Verify the notation format and that the position falls within an annotated region.');
+        }
+        ctx.enrich.total(results.length);
+        return { results, totalCount: results.length };
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`## VEP Results (${result.totalCount} record${result.totalCount !== 1 ? 's' : ''})`);
+        if (result.results.length === 0) {
+            lines.push('No VEP results returned for this variant.');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        for (const r of result.results) {
+            lines.push(`\n### Variant: ${r.input ?? 'unknown'}`);
+            if (r.chromosome && r.start != null) {
+                lines.push(`**Location:** ${r.chromosome}:${r.start}${r.end !== r.start ? `-${r.end}` : ''}${r.assemblyName ? ` [${r.assemblyName}]` : ''}`);
+            }
+            if (r.mostSevereConsequence) {
+                lines.push(`**Most severe consequence:** ${r.mostSevereConsequence}`);
+            }
+            if (r.colocatedVariants.length > 0) {
+                lines.push(`\n**Known colocated variants:**`);
+                for (const cv of r.colocatedVariants) {
+                    let cvLine = `- ${cv.id ?? 'novel'}`;
+                    if (cv.alleleString)
+                        cvLine += ` (${cv.alleleString})`;
+                    if (cv.clinicalSignificance?.length) {
+                        cvLine += ` — ${cv.clinicalSignificance.join(', ')}`;
+                    }
+                    if (cv.pubmed?.length) {
+                        cvLine += ` | PubMed: ${cv.pubmed.join(', ')}`;
+                    }
+                    lines.push(cvLine);
+                }
+            }
+            if (r.transcriptConsequences.length > 0) {
+                lines.push(`\n**Transcript consequences (${r.transcriptConsequences.length}):**`);
+                for (const tc of r.transcriptConsequences) {
+                    const geneLabel = tc.geneSymbol ?? tc.geneId ?? 'unknown';
+                    lines.push(`\n#### ${geneLabel} — ${tc.transcriptId ?? 'unknown'}`);
+                    if (tc.geneId && tc.geneSymbol)
+                        lines.push(`**Gene ID:** ${tc.geneId}`);
+                    lines.push(`**Impact:** ${tc.impact ?? 'UNKNOWN'} | **Consequence:** ${tc.consequenceTerms.join(', ')}`);
+                    if (tc.biotype)
+                        lines.push(`**Biotype:** ${tc.biotype}`);
+                    if (tc.hgvsc)
+                        lines.push(`**HGVSc:** ${tc.hgvsc}`);
+                    if (tc.hgvsp)
+                        lines.push(`**HGVSp:** ${tc.hgvsp}`);
+                    if (tc.aminoAcids)
+                        lines.push(`**Amino acids:** ${tc.aminoAcids}`);
+                    if (tc.sift) {
+                        lines.push(`**SIFT:** ${tc.sift.prediction} (score: ${tc.sift.score.toFixed(3)})`);
+                    }
+                    if (tc.polyphen) {
+                        lines.push(`**PolyPhen:** ${tc.polyphen.prediction} (score: ${tc.polyphen.score.toFixed(3)})`);
+                    }
+                }
+            }
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=predict-variant.tool.js.map

package/dist/mcp-server/tools/definitions/predict-variant.tool.js.map

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

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

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Tool to find genomic features overlapping a chromosomal region.
+ * @module mcp-server/tools/definitions/query-region
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const ensemblQueryRegion: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    species: z.ZodString;
+    region: z.ZodString;
+    feature: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        gene: "gene";
+        transcript: "transcript";
+        variation: "variation";
+        regulatory: "regulatory";
+        exon: "exon";
+    }>>>;
+    biotype: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    features: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        featureType: z.ZodString;
+        biotype: z.ZodOptional<z.ZodString>;
+        chromosome: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        strand: z.ZodOptional<z.ZodNumber>;
+        description: z.ZodOptional<z.ZodString>;
+        consequenceType: z.ZodOptional<z.ZodString>;
+        clinicalSignificance: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+    region: z.ZodString;
+    species: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "invalid_region";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The region string could not be parsed or contains invalid coordinates.";
+    readonly recovery: string;
+}, {
+    readonly reason: "invalid_species";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The species string was not recognized by Ensembl.";
+    readonly recovery: "Call ensembl_list_species to discover valid species names in lowercase_underscore format.";
+}], {
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=query-region.tool.d.ts.map

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

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

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

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Tool to find genomic features overlapping a chromosomal region.
+ * @module mcp-server/tools/definitions/query-region
+ */
+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 FEATURE_TYPES = ['gene', 'transcript', 'variation', 'regulatory', 'exon'];
+const FeatureSchema = z.object({
+    id: z.string().optional().describe('Ensembl stable ID for this feature (e.g. ENSG…, rs…).'),
+    name: z.string().optional().describe('External name or symbol for this feature.'),
+    featureType: z
+        .string()
+        .describe('Feature type: gene, transcript, variation, regulatory, or exon.'),
+    biotype: z
+        .string()
+        .optional()
+        .describe('Biotype of the feature (e.g. protein_coding, lncRNA, SNV).'),
+    chromosome: z.string().describe('Chromosome or sequence region name.'),
+    start: z.number().describe('Start position on the chromosome (1-based).'),
+    end: z.number().describe('End position on the chromosome (1-based).'),
+    strand: z.number().optional().describe('Strand: 1 for forward, -1 for reverse.'),
+    description: z.string().optional().describe('Feature description when provided.'),
+    consequenceType: z
+        .string()
+        .optional()
+        .describe('Most severe consequence type for variation features.'),
+    clinicalSignificance: z
+        .array(z.string().describe('A clinical significance term for this variant.'))
+        .optional()
+        .describe('Clinical significance terms for variation features (e.g. pathogenic, benign).'),
+});
+export const ensemblQueryRegion = tool('ensembl_query_region', {
+    title: 'Query Genomic Region',
+    description: 'Find genomic features overlapping a chromosomal region: genes, transcripts, variants, regulatory ' +
+        'elements, or exons. Returns each feature with its stable ID, type, location, biotype, and name. ' +
+        'Useful for "what\'s in this locus?" and for seeding follow-up lookups. Region format is chr:start-end ' +
+        '(e.g. 13:32315086-32400268 for the BRCA2 locus). Chromosome names use Ensembl format — no "chr" ' +
+        'prefix for vertebrates (use 13 not chr13). The feature parameter defaults to gene only to prevent ' +
+        'overwhelming returns — requesting variation in an 85 kb region returns 44,000+ entries. Explicitly ' +
+        'include variation, regulatory, transcript, or exon only when needed.',
+    annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+    input: z.object({
+        species: z
+            .string()
+            .describe('Species in Ensembl internal format (e.g. homo_sapiens, mus_musculus). ' +
+            'Use ensembl_list_species to discover valid values.'),
+        region: z
+            .string()
+            .describe('Genomic region in chr:start-end format (e.g. 13:32315086-32400268). ' +
+            'Chromosome names use Ensembl format — no "chr" prefix for vertebrates (13, not chr13). ' +
+            'For large regions (>100 kb), limit to gene feature type to avoid overwhelming results.'),
+        feature: z
+            .array(z
+            .enum(FEATURE_TYPES)
+            .describe('A feature type to retrieve: gene, transcript, variation, regulatory, or exon.'))
+            .default(['gene'])
+            .describe('Feature types to retrieve. Default is gene only. ' +
+            'Requesting variation in a large region can return tens of thousands of features. ' +
+            'Include variation only for targeted small regions (single gene loci or smaller).'),
+        biotype: z
+            .string()
+            .optional()
+            .describe('Optional biotype filter (e.g. protein_coding, lncRNA, SNV). ' +
+            'Applied server-side by Ensembl. Not all feature types support biotype filtering.'),
+    }),
+    output: z.object({
+        features: z
+            .array(FeatureSchema.describe('A single genomic feature overlapping the queried region.'))
+            .describe('Genomic features found in the requested region.'),
+        totalCount: z
+            .number()
+            .describe('Number of features returned. Note: very large regions may return truncated results.'),
+        region: z.string().describe('The region queried, as provided.'),
+        species: z.string().describe('The species queried.'),
+    }),
+    enrichment: {
+        notice: z.string().optional().describe('Warning or guidance about the result set.'),
+    },
+    errors: [
+        {
+            reason: 'invalid_region',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The region string could not be parsed or contains invalid coordinates.',
+            recovery: 'Use the format chr:start-end (e.g. 13:32315086-32400268). ' +
+                'Chromosome names use Ensembl format with no "chr" prefix for vertebrates. ' +
+                'Verify coordinates are within the chromosome bounds for the target assembly.',
+        },
+        {
+            reason: 'invalid_species',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The species string was not recognized by Ensembl.',
+            recovery: 'Call ensembl_list_species to discover valid species names in lowercase_underscore format.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Querying region', {
+            species: input.species,
+            region: input.region,
+            features: input.feature,
+            biotype: input.biotype,
+        });
+        const service = getEnsemblService();
+        const features = await service
+            .queryRegion(input.species, input.region, input.feature, input.biotype, ctx)
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/invalid.*region|coordinate|parse/i.test(msg) ||
+                /is not a valid start|is not a valid end|is not a valid chr/i.test(msg)) {
+                throw ctx.fail('invalid_region', `Invalid region "${input.region}": ${msg}`);
+            }
+            if (/species|invalid|unrecognized/i.test(msg)) {
+                throw ctx.fail('invalid_species', `Species "${input.species}" not recognized.`);
+            }
+            throw err;
+        });
+        if (features.length === 0) {
+            ctx.enrich.notice(`No ${input.feature.join(', ')} features found in ${input.region} for ${input.species}. ` +
+                'The region may be intergenic or use a different chromosome naming convention.');
+        }
+        else if (features.length > 1000) {
+            ctx.enrich.notice(`Large result set (${features.length} features). ` +
+                'Consider narrowing the region or filtering by biotype to reduce context usage.');
+        }
+        ctx.enrich.total(features.length);
+        return {
+            features,
+            totalCount: features.length,
+            region: input.region,
+            species: input.species,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`## Genomic Region: ${result.species} ${result.region}`);
+        lines.push(`**Features found:** ${result.totalCount}\n`);
+        if (result.features.length === 0) {
+            lines.push('No features found in this region.');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        for (const f of result.features) {
+            const label = f.name ?? f.id ?? f.featureType;
+            lines.push(`### ${label}`);
+            if (f.id)
+                lines.push(`**ID:** ${f.id}`);
+            lines.push(`**Type:** ${f.featureType}`);
+            if (f.biotype)
+                lines.push(`**Biotype:** ${f.biotype}`);
+            lines.push(`**Location:** ${f.chromosome}:${f.start}-${f.end}${f.strand != null ? ` strand:${f.strand} (${f.strand === -1 ? '-' : '+'})` : ''}`);
+            if (f.description)
+                lines.push(`**Description:** ${f.description}`);
+            if (f.consequenceType)
+                lines.push(`**Consequence:** ${f.consequenceType}`);
+            if (f.clinicalSignificance?.length) {
+                lines.push(`**Clinical significance:** ${f.clinicalSignificance.join(', ')}`);
+            }
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=query-region.tool.js.map

package/dist/mcp-server/tools/definitions/query-region.tool.js.map

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

package/dist/services/ensembl/ensembl-service.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Ensembl REST API service — HTTP client, rate-limit-aware retry,
+ * error normalization, and typed methods per endpoint family.
+ * @module services/ensembl/ensembl-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { GeneRecord, HomologyEntry, OverlapFeature, SequenceRecord, SpeciesInfo, TranscriptRecord, VepRecord, XrefEntry } from './types.js';
+export declare class EnsemblService {
+    private readonly baseUrl;
+    constructor(_config: AppConfig, _storage: StorageService);
+    private fetchJson;
+    private fetchWithRetry;
+    lookupGene(symbol: string, species: string, expandTranscripts: boolean, ctx: Context): Promise<GeneRecord>;
+    lookupGeneById(id: string, expandTranscripts: boolean, ctx: Context): Promise<GeneRecord>;
+    lookupGenesBatch(ids: string[], expandTranscripts: boolean, ctx: Context): Promise<Map<string, GeneRecord>>;
+    lookupSymbolsBatch(symbols: string[], species: string, expandTranscripts: boolean, ctx: Context): Promise<Map<string, GeneRecord>>;
+    lookupTranscript(id: string, ctx: Context): Promise<TranscriptRecord>;
+    getSequenceById(id: string, type: string, ctx: Context): Promise<SequenceRecord>;
+    getSequenceByRegion(species: string, region: string, expand5prime: number, expand3prime: number, ctx: Context): Promise<SequenceRecord>;
+    queryRegion(species: string, region: string, features: string[], biotype: string | undefined, ctx: Context): Promise<OverlapFeature[]>;
+    predictVariantHgvs(notation: string, species: string, ctx: Context): Promise<VepRecord[]>;
+    predictVariantRegion(chr: string, start: number, end: number, strand: number, allele: string, species: string, ctx: Context): Promise<VepRecord[]>;
+    getHomologyBySymbol(symbol: string, species: string, type: string, targetSpecies: string | undefined, ctx: Context): Promise<HomologyEntry[]>;
+    getHomologyById(id: string, species: string, type: string, targetSpecies: string | undefined, ctx: Context): Promise<HomologyEntry[]>;
+    getXrefsById(id: string, dbname: string | undefined, ctx: Context): Promise<XrefEntry[]>;
+    listSpecies(division: string | undefined, ctx: Context): Promise<SpeciesInfo[]>;
+}
+export declare function initEnsemblService(config: AppConfig, storage: StorageService): void;
+export declare function getEnsemblService(): EnsemblService;
+//# sourceMappingURL=ensembl-service.d.ts.map

package/dist/services/ensembl/ensembl-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensembl-service.d.ts","sourceRoot":"","sources":["../../../src/services/ensembl/ensembl-service.ts"],"names":[],"mappings":"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"}