Ensembl MCP Server

Instructions

Implementation Reference

• src/handlers/tools.ts:525-535 (handler)

  Direct handler function for the 'ensembl_compara' tool. Normalizes input arguments and calls the EnsemblApiClient's getComparativeData method to execute the comparative genomics logic.

  export async function handleCompara(args: any) {
    try {
      const normalizedArgs = normalizeEnsemblInputs(args);
      return await ensemblClient.getComparativeData(normalizedArgs);
    } catch (error) {
      return {
        error: error instanceof Error ? error.message : "Unknown error",
        success: false,
      };
    }
  }

• src/handlers/tools.ts:279-335 (schema)

  Input schema definition for the 'ensembl_compara' tool, including parameters like gene_id, analysis_type (homology, genetree, etc.), species, and validation rules.

  {
    name: "ensembl_compara",
    description:
      "Comparative genomics: gene trees, homology, species alignments, and evolutionary analysis. Covers /genetree/*, /homology/*, /alignment/* endpoints.",
    inputSchema: {
      type: "object",
      properties: {
        gene_id: {
          type: "string",
          description:
            "Gene ID for homology/gene tree analysis (e.g., 'ENSG00000141510', 'ENSG00000012048')",
        },
        gene_symbol: {
          type: "string",
          description:
            "Gene symbol (alternative to gene_id) (e.g., 'BRCA1', 'TP53', 'EGFR')",
        },
        region: {
          type: "string",
          description:
            "Genomic region for alignments in format 'chr:start-end' (e.g., '17:7565096-7590856', 'X:1000000-2000000', '6:25000000-35000000')",
        },
        analysis_type: {
          type: "string",
          enum: ["homology", "genetree", "cafe_tree", "alignment"],
          description: "Type of comparative analysis",
        },
        species: {
          type: "string",
          description:
            "Species name (e.g., 'homo_sapiens', 'mus_musculus', 'pan_troglodytes')",
          default: "homo_sapiens",
        },
        target_species: {
          type: "string",
          description:
            "Target species for homology search (e.g., 'mus_musculus', 'pan_troglodytes', 'rattus_norvegicus')",
        },
        homology_type: {
          type: "string",
          enum: ["orthologues", "paralogues", "all"],
          description: "Type of homology to retrieve",
          default: "all",
        },
        aligned: {
          type: "boolean",
          description: "Include aligned sequences",
          default: false,
        },
      },
      anyOf: [
        { required: ["gene_id", "analysis_type"] },
        { required: ["gene_symbol", "analysis_type"] },
        { required: ["region", "analysis_type"] },
      ],
    },
  },

• index.ts:139-147 (registration)

  MCP tool execution registration: switch case in CallToolRequestSchema handler that dispatches 'ensembl_compara' calls to the handleCompara function.

  case "ensembl_compara":
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(await handleCompara(args), null, 2),
        },
      ],
    };

• src/utils/ensembl-api.ts:305-373 (helper)

  Core helper method implementing the comparative genomics functionality by routing to appropriate Ensembl REST API endpoints based on analysis_type (homology, genetree, alignment, etc.).

  // Comparative genomics
  async getComparativeData(args: any): Promise<any> {
    const {
      gene_id,
      gene_symbol,
      region,
      analysis_type,
      species = "homo_sapiens",
      target_species,
      homology_type = "all",
      aligned,
    } = args;
    const params: Record<string, string> = {};
  
    if (aligned !== undefined) {
      params.aligned = aligned.toString();
    }
    if (target_species) {
      params.target_species = target_species;
    }
    if (homology_type !== "all") {
      params.type = homology_type;
    }
  
    switch (analysis_type) {
      case "homology":
        if (gene_id) {
          return this.makeRequest(`/homology/id/${species}/${gene_id}`, params);
        } else if (gene_symbol) {
          return this.makeRequest(
            `/homology/symbol/${species}/${gene_symbol}`,
            params
          );
        }
        throw new Error("Either gene_id or gene_symbol required for homology");
  
      case "genetree":
        if (gene_id) {
          return this.makeRequest(`/genetree/id/${gene_id}`, params);
        } else if (gene_symbol) {
          return this.makeRequest(
            `/genetree/member/symbol/${species}/${gene_symbol}`,
            params
          );
        }
        throw new Error("Either gene_id or gene_symbol required for gene tree");
  
      case "cafe_tree":
        if (gene_id) {
          return this.makeRequest(`/cafe/genetree/id/${gene_id}`, params);
        } else if (gene_symbol) {
          return this.makeRequest(
            `/cafe/genetree/member/symbol/${species}/${gene_symbol}`,
            params
          );
        }
        throw new Error("Either gene_id or gene_symbol required for cafe tree");
  
      case "alignment":
        if (!region) throw new Error("region required for alignment");
        return this.makeRequest(
          `/alignment/region/${species}/${region}`,
          params
        );
  
      default:
        throw new Error(`Unknown analysis_type: ${analysis_type}`);
    }
  }

• index.ts:47-50 (registration)

  MCP tool listing registration: handler for ListToolsRequestSchema that returns the ensemblTools array, making 'ensembl_compara' discoverable.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: ensemblTools,
    };