Ensembl MCP Server

Instructions

Implementation Reference

• src/handlers/tools.ts:465-475 (handler)

  Main handler function for 'ensembl_protein_features' tool. Normalizes input arguments and calls EnsemblApiClient.getProteinFeatures, with error handling.

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

• src/handlers/tools.ts:88-113 (schema)

  Tool definition including name, description, and input schema (protein_id required, optional feature_type and species). Used in ensemblTools array for MCP tool listing.

  {
    name: "ensembl_protein_features",
    description:
      "Get protein-level features, domains, and annotations for proteins and translations.",
    inputSchema: {
      type: "object",
      properties: {
        protein_id: {
          type: "string",
          description:
            "Protein/translation ID (e.g., 'ENSP00000288602', 'ENSP00000350283', 'ENSP00000334393')",
        },
        feature_type: {
          type: "string",
          description:
            "Type of protein feature (e.g., 'domain', 'signal_peptide', 'transmembrane', 'low_complexity')",
        },
        species: {
          type: "string",
          description: "Species name (e.g., 'homo_sapiens', 'mus_musculus')",
          default: "homo_sapiens",
        },
      },
      required: ["protein_id"],
    },
  },

• index.ts:85-97 (registration)

  Registration in MCP server CallToolRequest handler: switch case dispatches to handleProteinFeatures and formats response as JSON text content.

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

• src/utils/ensembl-api.ts:135-154 (helper)

  Core helper method in EnsemblApiClient: queries Ensembl REST API `/overlap/translation/{protein_id}` endpoint with optional 'type' parameter for feature filtering, includes species validation and rate limiting.

  async getProteinFeatures(args: any): Promise<any> {
    const { protein_id, feature_type, species = "homo_sapiens" } = args;
  
    if (!protein_id) {
      throw new Error("protein_id is required");
    }
  
    // Validate species if provided and not default
    if (species && species !== "homo_sapiens") {
      await this.validateSpecies(species);
    }
  
    const params: Record<string, string> = {};
  
    if (feature_type) {
      params.type = feature_type;
    }
  
    return this.makeRequest(`/overlap/translation/${protein_id}`, params);
  }