Ensembl MCP Server

Instructions

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}`);
    }
  }

• src/utils/input-normalizer.ts:250-317 (helper)

  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;
  }