Ensembl MCP Server

Instructions

Implementation Reference

• src/handlers/tools.ts:513-523 (handler)

  The main handler function for the 'ensembl_mapping' tool. It normalizes the input arguments and calls the EnsemblApiClient's mapCoordinates method to perform the coordinate mapping.

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

• src/handlers/tools.ts:237-277 (schema)

  Tool schema definition including name, description, and detailed inputSchema for validation of parameters like coordinates, feature_id, mapping_type, assemblies, and species.

  {
    name: "ensembl_mapping",
    description:
      "Map coordinates between different coordinate systems (genomic ↔ cDNA/CDS/protein) and between genome assemblies. Covers /map/* endpoints.",
    inputSchema: {
      type: "object",
      properties: {
        coordinates: {
          type: "string",
          description:
            "Coordinates to map: '100..200' for cDNA/CDS coords, or 'chr:start-end' for genomic (e.g., '100..300', '1..150', '17:7565096-7590856', 'X:1000000-2000000')",
        },
        feature_id: {
          type: "string",
          description:
            "Feature ID (transcript/translation) for coordinate mapping (e.g., 'ENST00000288602', 'ENSP00000288602')",
        },
        mapping_type: {
          type: "string",
          enum: ["cdna", "cds", "translation", "assembly"],
          description: "Type of coordinate mapping",
        },
        source_assembly: {
          type: "string",
          description:
            "Source assembly name (for assembly mapping) (e.g., 'GRCh37', 'GRCh38')",
        },
        target_assembly: {
          type: "string",
          description:
            "Target assembly name (for assembly mapping) (e.g., 'GRCh38', 'GRCh37')",
        },
        species: {
          type: "string",
          description: "Species name (e.g., 'homo_sapiens', 'mus_musculus')",
          default: "homo_sapiens",
        },
      },
      required: ["coordinates", "mapping_type"],
    },
  },

• index.ts:129-137 (registration)

  Registration in the main server request handler switch statement that dispatches 'ensembl_mapping' tool calls to the handleMapping function.

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

• src/utils/ensembl-api.ts:267-303 (helper)

  Core helper method in EnsemblApiClient that performs the actual API calls to Ensembl REST /map endpoints based on the mapping_type (cdna, cds, translation, assembly).

  async mapCoordinates(args: any): Promise<any> {
    const {
      coordinates,
      feature_id,
      mapping_type,
      source_assembly,
      target_assembly,
      species = "homo_sapiens",
    } = args;
  
    switch (mapping_type) {
      case "cdna":
        if (!feature_id)
          throw new Error("feature_id required for cDNA mapping");
        return this.makeRequest(`/map/cdna/${feature_id}/${coordinates}`);
      case "cds":
        if (!feature_id) throw new Error("feature_id required for CDS mapping");
        return this.makeRequest(`/map/cds/${feature_id}/${coordinates}`);
      case "translation":
        if (!feature_id)
          throw new Error("feature_id required for translation mapping");
        return this.makeRequest(
          `/map/translation/${feature_id}/${coordinates}`
        );
      case "assembly":
        if (!source_assembly || !target_assembly) {
          throw new Error(
            "source_assembly and target_assembly required for assembly mapping"
          );
        }
        return this.makeRequest(
          `/map/${species}/${source_assembly}/${coordinates}/${target_assembly}`
        );
      default:
        throw new Error(`Unknown mapping_type: ${mapping_type}`);
    }
  }