ensembl_feature_overlap
Identify genomic features overlapping a specified region or feature in Ensembl, handling assembly variations and supporting multiple species and feature types.
Instructions
Find genomic features (genes, transcripts, regulatory elements) that overlap with a genomic region or specific feature. Automatically handles assembly-specific format variations (GRCh38/hg38, chromosome naming conventions, coordinate systems). Covers /overlap/region and /overlap/id endpoints.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | Genomic region in format 'chromosome:start-end' (e.g., '17:7565096-7590856', 'X:1000000-2000000', '1:100000-200000'). Use this OR feature_id, not both. | |
| feature_id | No | Feature ID (gene, transcript, etc.) to find overlapping features for (e.g., 'ENSG00000141510', 'ENST00000288602', 'BRCA1'). Use this OR region, not both. | |
| species | No | Species name (e.g., 'homo_sapiens', 'mus_musculus', 'danio_rerio') | homo_sapiens |
| feature_types | No | Types of features to include (e.g., ['gene', 'transcript', 'exon'], ['regulatory', 'enhancer']) | |
| biotype | No | Filter by biotype (e.g., 'protein_coding', 'lncRNA', 'miRNA', 'pseudogene') |
Implementation Reference
- src/handlers/tools.ts:436-451 (handler)Primary handler function that normalizes input arguments and calls the Ensembl API client methods for feature overlap queries based on region or feature ID.export async function handleFeatureOverlap(args: any) { try { const normalizedArgs = normalizeEnsemblInputs(args); if (normalizedArgs.region) { return await ensemblClient.getOverlapByRegion(normalizedArgs); } else if (normalizedArgs.feature_id) { return await ensemblClient.getOverlapById(normalizedArgs); } throw new Error("Either region or feature_id must be provided"); } catch (error) { return { error: error instanceof Error ? error.message : "Unknown error", success: false, }; } }
- src/utils/ensembl-api.ts:75-98 (helper)EnsemblApiClient methods that perform the actual REST API requests to Ensembl's /overlap/region and /overlap/id endpoints.async getOverlapByRegion(args: any): Promise<any> { const { region, species = "homo_sapiens", feature_types, biotype } = args; const params: Record<string, string> = {}; if (feature_types && feature_types.length > 0) { params.feature = feature_types.join(","); } if (biotype) { params.biotype = biotype; } return this.makeRequest(`/overlap/region/${species}/${region}`, params); } async getOverlapById(args: any): Promise<any> { const { feature_id, species = "homo_sapiens", feature_types } = args; const params: Record<string, string> = {}; if (feature_types && feature_types.length > 0) { params.feature = feature_types.join(","); } return this.makeRequest(`/overlap/id/${feature_id}`, params); }
- src/handlers/tools.ts:12-43 (schema)JSON schema for tool inputs, including properties, descriptions, defaults, and validation requiring either 'region' or 'feature_id'.inputSchema: { type: "object", properties: { region: { type: "string", description: "Genomic region in format 'chromosome:start-end' (e.g., '17:7565096-7590856', 'X:1000000-2000000', '1:100000-200000'). Use this OR feature_id, not both.", }, feature_id: { type: "string", description: "Feature ID (gene, transcript, etc.) to find overlapping features for (e.g., 'ENSG00000141510', 'ENST00000288602', 'BRCA1'). Use this OR region, not both.", }, species: { type: "string", description: "Species name (e.g., 'homo_sapiens', 'mus_musculus', 'danio_rerio')", default: "homo_sapiens", }, feature_types: { type: "array", items: { type: "string" }, description: "Types of features to include (e.g., ['gene', 'transcript', 'exon'], ['regulatory', 'enhancer'])", }, biotype: { type: "string", description: "Filter by biotype (e.g., 'protein_coding', 'lncRNA', 'miRNA', 'pseudogene')", }, }, oneOf: [{ required: ["region"] }, { required: ["feature_id"] }],
- index.ts:47-51 (registration)MCP server handler for listing tools, which returns the ensemblTools array containing the 'ensembl_feature_overlap' tool definition.this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: ensemblTools, }; });
- index.ts:61-73 (registration)Dispatch case in MCP CallToolRequest handler that invokes the tool's handler function when 'ensembl_feature_overlap' is called.case "ensembl_feature_overlap": return { content: [ { type: "text", text: JSON.stringify( await handleFeatureOverlap(args), null, 2 ), }, ], };