ensembl_variation
Analyze genomic variants to predict functional consequences, find linked variants, map phenotypes, and examine haplotypes using Ensembl's variant data across species.
Instructions
Variant analysis: VEP consequence prediction, variant lookup, LD analysis, phenotype mapping, haplotypes. Covers /variation/, /vep/, /ld/, /phenotype/ endpoints.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| variant_id | No | Variant ID (e.g., 'rs699', 'rs1042779', 'COSM476') or HGVS notation (e.g., '17:g.7579472G>C') | |
| region | No | Genomic region in format 'chr:start-end' for variant search (e.g., '17:7565096-7590856', 'X:1000000-2000000', '1:100000-200000') | |
| hgvs_notation | No | HGVS notation for VEP analysis (e.g., '17:g.7579472G>C', 'ENST00000288602.6:c.1799T>A', 'NM_007294.3:c.1799T>A') | |
| analysis_type | No | Type of variant analysis | |
| species | No | Species name (e.g., 'homo_sapiens', 'mus_musculus') | homo_sapiens |
| consequence_type | No | Filter by consequence type (e.g., 'missense_variant', 'stop_gained', 'splice_donor_variant') | |
| population | No | Population for LD analysis (e.g., '1000GENOMES:phase_3:EUR', '1000GENOMES:phase_3:AFR', '1000GENOMES:phase_3:ASN') | |
| transcript_id | No | Transcript ID for haplotype analysis (e.g., 'ENST00000288602', 'ENST00000350283') |
Implementation Reference
- src/handlers/tools.ts:537-547 (handler)The primary handler function that executes the 'ensembl_variation' tool. It normalizes the input arguments and calls the EnsemblApiClient's getVariationData method to perform the actual API requests.
export async function handleVariation(args: any) { try { const normalizedArgs = normalizeEnsemblInputs(args); return await ensemblClient.getVariationData(normalizedArgs); } catch (error) { return { error: error instanceof Error ? error.message : "Unknown error", success: false, }; } } - src/handlers/tools.ts:337-392 (schema)Defines the tool schema including name, description, and inputSchema validation for 'ensembl_variation' within the ensemblTools array used for tool listing.
{ name: "ensembl_variation", description: "Variant analysis: VEP consequence prediction, variant lookup, LD analysis, phenotype mapping, haplotypes. Covers /variation/*, /vep/*, /ld/*, /phenotype/* endpoints.", inputSchema: { type: "object", properties: { variant_id: { type: "string", description: "Variant ID (e.g., 'rs699', 'rs1042779', 'COSM476') or HGVS notation (e.g., '17:g.7579472G>C')", }, region: { type: "string", description: "Genomic region in format 'chr:start-end' for variant search (e.g., '17:7565096-7590856', 'X:1000000-2000000', '1:100000-200000')", }, hgvs_notation: { type: "string", description: "HGVS notation for VEP analysis (e.g., '17:g.7579472G>C', 'ENST00000288602.6:c.1799T>A', 'NM_007294.3:c.1799T>A')", }, analysis_type: { type: "string", enum: ["variant_info", "vep", "ld", "phenotype", "haplotypes"], description: "Type of variant analysis", }, species: { type: "string", description: "Species name (e.g., 'homo_sapiens', 'mus_musculus')", default: "homo_sapiens", }, consequence_type: { type: "string", description: "Filter by consequence type (e.g., 'missense_variant', 'stop_gained', 'splice_donor_variant')", }, population: { type: "string", description: "Population for LD analysis (e.g., '1000GENOMES:phase_3:EUR', '1000GENOMES:phase_3:AFR', '1000GENOMES:phase_3:ASN')", }, transcript_id: { type: "string", description: "Transcript ID for haplotype analysis (e.g., 'ENST00000288602', 'ENST00000350283')", }, }, anyOf: [ { required: ["variant_id"] }, { required: ["region"] }, { required: ["hgvs_notation"] }, ], }, }, - index.ts:149-157 (registration)Registers the 'ensembl_variation' tool in the MCP server's request handler switch statement, dispatching calls to handleVariation.
case "ensembl_variation": return { content: [ { type: "text", text: JSON.stringify(await handleVariation(args), null, 2), }, ], }; - src/utils/ensembl-api.ts:376-461 (helper)Core helper function in EnsemblApiClient that implements the variant analysis logic by routing to specific Ensembl REST API endpoints based on the analysis_type.
async getVariationData(args: any): Promise<any> { const { variant_id, region, hgvs_notation, analysis_type, species = "homo_sapiens", consequence_type, population, transcript_id, } = args; const params: Record<string, string> = {}; if (consequence_type) { params.consequence_type = consequence_type; } if (population) { params.population_name = population; } switch (analysis_type) { case "variant_info": if (variant_id) { return this.makeRequest( `/variation/${species}/${variant_id}`, params ); } else if (region) { return this.makeRequest(`/overlap/region/${species}/${region}`, { ...params, feature: "variation", }); } throw new Error( "Either variant_id or region required for variant info" ); case "vep": if (hgvs_notation) { return this.makeRequest( `/vep/${species}/hgvs/${hgvs_notation}`, params ); } else if (variant_id) { return this.makeRequest(`/vep/${species}/id/${variant_id}`, params); } else if (region) { // For region-based VEP, we need allele info - this is simplified return this.makeRequest(`/vep/${species}/region/${region}/1`, params); } throw new Error( "Either hgvs_notation, variant_id, or region required for VEP" ); case "ld": if (!variant_id) throw new Error("variant_id required for LD analysis"); return this.makeRequest( `/ld/${species}/${variant_id}/1000GENOMES:phase_3:EUR`, params ); case "phenotype": if (variant_id) { return this.makeRequest( `/phenotype/variant/${species}/${variant_id}`, params ); } else if (region) { return this.makeRequest( `/phenotype/region/${species}/${region}`, params ); } throw new Error("Either variant_id or region required for phenotype"); case "haplotypes": if (!transcript_id) throw new Error("transcript_id required for haplotype analysis"); return this.makeRequest( `/transcript_haplotypes/${species}/${transcript_id}`, params ); default: throw new Error(`Unknown analysis_type: ${analysis_type}`); } } - Supporting utility that normalizes tool inputs for Ensembl API compatibility, used by all handlers including handleVariation.
export function normalizeEnsemblInputs(inputs: any): any { const normalized = { ...inputs }; // Normalize assembly first as it affects other normalizations if (normalized.assembly) { normalized.assembly = normalizeAssemblyName(normalized.assembly); } // Normalize species with assembly context if (normalized.species) { normalized.species = normalizeSpeciesName( normalized.species, normalized.assembly ); } // Normalize genomic regions with assembly context if (normalized.region) { normalized.region = normalizeGenomicRegion( normalized.region, normalized.assembly ); } // Normalize cDNA coordinates if (normalized.cdna_coords) { normalized.cdna_coords = normalizeCdnaCoordinates(normalized.cdna_coords); } // Normalize gene identifiers if (normalized.gene_id || normalized.feature_id) { const geneField = normalized.gene_id ? "gene_id" : "feature_id"; normalized[geneField] = normalizeGeneIdentifier( normalized[geneField], normalized.assembly ); } // Normalize HGVS notation if (normalized.hgvs) { normalized.hgvs = normalizeHgvsNotation( normalized.hgvs, normalized.assembly ); } // Normalize scaffold names if (normalized.scaffold) { normalized.scaffold = normalizeScaffoldName( normalized.scaffold, normalized.assembly ); } // Handle coordinate system normalization if specified if (normalized.start && normalized.end && normalized.coordinate_system) { const coords = normalizeCoordinateSystem( Number(normalized.start), Number(normalized.end), normalized.coordinate_system ); normalized.start = coords.start; normalized.end = coords.end; delete normalized.coordinate_system; // Remove the hint after using it } return normalized; }