Ensembl MCP Server

Instructions

Implementation Reference

• src/index.ts:1362-1416 (handler)

  The handler function that executes the get_regulatory_features tool. It validates input, queries the Ensembl REST API overlap endpoint for regulatory features in the specified genomic region, with fallback to other features if not found.

  private async handleGetRegulatoryFeatures(args: any) {
    if (!isValidRegulatoryArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid regulatory feature arguments');
    }
  
    try {
      const species = this.getDefaultSpecies(args.species);
      const region = this.formatGenomicRegion(args.region);
  
      // Try overlap endpoint for regulatory features
      try {
        const response = await this.apiClient.get(`/overlap/region/${species}/${region}`, {
          params: { feature: 'regulatory' }
        });
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(response.data, null, 2),
            },
          ],
        };
      } catch (overlapError) {
        // Alternative: try the overlap endpoint with different feature types
        const features = ['gene', 'transcript'];
        const results = [];
  
        for (const feature of features) {
          try {
            const response = await this.apiClient.get(`/overlap/region/${species}/${region}`, {
              params: { feature }
            });
            results.push({ feature, data: response.data });
          } catch (e) {
            // Continue to next feature
          }
        }
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                message: 'Regulatory features not available, showing overlapping genomic features',
                features: results
              }, null, 2),
            },
          ],
        };
      }
    } catch (error) {
      return this.handleError(error, 'fetching regulatory features');
    }
  }

• src/index.ts:710-722 (schema)

  The tool schema definition in the listTools response, specifying name, description, and input schema for validation.

  {
    name: 'get_regulatory_features',
    description: 'Get regulatory elements (enhancers, promoters, TFBS) in genomic region',
    inputSchema: {
      type: 'object',
      properties: {
        region: { type: 'string', description: 'Genomic region (chr:start-end)' },
        species: { type: 'string', description: 'Species name (default: homo_sapiens)' },
        feature_type: { type: 'string', description: 'Regulatory feature type (optional)' },
        cell_type: { type: 'string', description: 'Cell type context (optional)' },
      },
      required: ['region'],
    },

• src/index.ts:859-860 (registration)

  Registration of the tool handler in the CallToolRequestSchema switch statement.

  case 'get_regulatory_features':
    return this.handleGetRegulatoryFeatures(args);

• src/index.ts:229-241 (helper)

  Type guard function for validating input arguments to the get_regulatory_features tool.

  const isValidRegulatoryArgs = (
    args: any
  ): args is { region: string; species?: string; feature_type?: string; cell_type?: string } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.region === 'string' &&
      args.region.length > 0 &&
      (args.species === undefined || typeof args.species === 'string') &&
      (args.feature_type === undefined || typeof args.feature_type === 'string') &&
      (args.cell_type === undefined || typeof args.cell_type === 'string')
    );
  };

• src/index.ts:95-106 (schema)

  TypeScript interface defining the structure of Ensembl regulatory feature data.

  interface EnsemblRegulatoryFeature {
    id: string;
    feature_type: string;
    start: number;
    end: number;
    strand: number;
    bound_start: number;
    bound_end: number;
    description: string;
    cell_type?: string[];
    activity?: string;
  }