ensembl_mapping
Convert genomic coordinates between different systems (e.g., cDNA, CDS, protein, assemblies) using specified feature IDs and mapping types. Supports multiple species and assembly conversions for precise genomic data analysis.
Instructions
Map coordinates between different coordinate systems (genomic ↔ cDNA/CDS/protein) and between genome assemblies. Covers /map/* endpoints.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| coordinates | Yes | 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 | No | Feature ID (transcript/translation) for coordinate mapping (e.g., 'ENST00000288602', 'ENSP00000288602') | |
| mapping_type | Yes | Type of coordinate mapping | |
| source_assembly | No | Source assembly name (for assembly mapping) (e.g., 'GRCh37', 'GRCh38') | |
| species | No | Species name (e.g., 'homo_sapiens', 'mus_musculus') | homo_sapiens |
| target_assembly | No | Target assembly name (for assembly mapping) (e.g., 'GRCh38', 'GRCh37') |
Implementation Reference
- src/utils/ensembl-api.ts:267-303 (handler)Core implementation of ensembl_mapping tool. Handles different mapping types (cdna, cds, translation, assembly) by constructing and calling appropriate Ensembl REST API /map/* endpoints.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}`); } }
- src/handlers/tools.ts:241-276 (schema)Input schema definition for the ensembl_mapping tool, defining parameters, types, descriptions, and validation rules.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 switch statement that dispatches calls to the 'ensembl_mapping' tool to the handleMapping function.case "ensembl_mapping": return { content: [ { type: "text", text: JSON.stringify(await handleMapping(args), null, 2), }, ], };
- src/handlers/tools.ts:237-277 (registration)Tool definition and registration in the ensemblTools array used for listing available tools. Includes name, description, and schema.{ 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"], }, },
- src/handlers/tools.ts:513-523 (helper)Wrapper handler function that normalizes inputs and calls the core EnsemblApiClient.mapCoordinates, with error handling.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, }; } }