Ensembl MCP Server

Instructions

Implementation Reference

• src/handlers/tools.ts:477-487 (handler)

  The handleMeta function executes the core logic for the ensembl_meta tool by normalizing inputs and delegating to the Ensembl API client for metadata retrieval.

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

• src/handlers/tools.ts:115-157 (schema)

  Input schema and metadata definition for the ensembl_meta tool, defining parameters like info_type, species, archive_id.

  {
    name: "ensembl_meta",
    description:
      "Get server metadata, data releases, species info, and system status. Covers /info/* endpoints and /archive/id for version tracking.",
    inputSchema: {
      type: "object",
      properties: {
        info_type: {
          type: "string",
          enum: [
            "ping",
            "rest",
            "software",
            "data",
            "species",
            "divisions",
            "assembly",
            "biotypes",
            "analysis",
            "external_dbs",
            "variation",
          ],
          description: "Type of information to retrieve",
        },
        species: {
          type: "string",
          description:
            "Species name (required for species-specific info) (e.g., 'homo_sapiens', 'mus_musculus', 'drosophila_melanogaster')",
        },
        archive_id: {
          type: "string",
          description:
            "ID to get version information for (alternative to info_type) (e.g., 'ENSG00000141510', 'rs699')",
        },
        division: {
          type: "string",
          description:
            "Ensembl division name (e.g., 'vertebrates', 'plants', 'fungi', 'metazoa')",
        },
      },
      anyOf: [{ required: ["info_type"] }, { required: ["archive_id"] }],
    },
  },

• src/utils/ensembl-api.ts:157-195 (helper)

  Core API client method getMetaInfo that implements the actual Ensembl REST API calls for various metadata endpoints based on info_type.

  async getMetaInfo(args: any): Promise<any> {
    const { info_type, species, archive_id, division } = args;
  
    if (archive_id) {
      return this.makeRequest(`/archive/id/${archive_id}`);
    }
  
    switch (info_type) {
      case "ping":
        return this.makeRequest("/info/ping");
      case "rest":
        return this.makeRequest("/info/rest");
      case "software":
        return this.makeRequest("/info/software");
      case "data":
        return this.makeRequest("/info/data");
      case "species":
        return this.makeRequest("/info/species");
      case "divisions":
        return this.makeRequest("/info/divisions");
      case "assembly":
        if (!species) throw new Error("Species required for assembly info");
        return this.makeRequest(`/info/assembly/${species}`);
      case "biotypes":
        if (!species) throw new Error("Species required for biotypes info");
        return this.makeRequest(`/info/biotypes/${species}`);
      case "analysis":
        if (!species) throw new Error("Species required for analysis info");
        return this.makeRequest(`/info/analysis/${species}`);
      case "external_dbs":
        if (!species) throw new Error("Species required for external_dbs info");
        return this.makeRequest(`/info/external_dbs/${species}`);
      case "variation":
        if (!species) throw new Error("Species required for variation info");
        return this.makeRequest(`/info/variation/${species}`);
      default:
        throw new Error(`Unknown info_type: ${info_type}`);
    }
  }

• index.ts:47-51 (registration)

  Tool list registration handler that returns the ensemblTools array containing the ensembl_meta tool definition.

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

• index.ts:99-107 (registration)

  Dispatch registration in the main CallToolRequest handler that routes ensembl_meta calls to the handleMeta function.

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