convert_coordinates
Convert genomic coordinates between hg19 and hg38 genome builds for accurate cross-study data analysis and integration.
Instructions
Convert between different genomic coordinate systems
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chr | Yes | Chromosome (e.g., chr1, chr2, chrX) | |
| position | Yes | Genomic position to convert | |
| fromBuild | No | Source genome build (default: hg38) | hg38 |
| toBuild | No | Target genome build (default: hg19) | hg19 |
Implementation Reference
- Main handler function for the convert_coordinates tool. Performs input validation, approximate coordinate conversion between hg19/hg38 using helper offsets, generates detailed output with warnings and recommendations for accurate tools.async convertCoordinates(args: any) { if (!args.chr || !args.position) { throw new Error('chr and position parameters are required'); } if (typeof args.position !== 'number') { throw new Error('position parameter must be a number'); } const fromBuild = args.fromBuild || 'hg38'; const toBuild = args.toBuild || 'hg19'; // Validate genome builds const validBuilds = ['hg19', 'hg38']; if (!validBuilds.includes(fromBuild) || !validBuilds.includes(toBuild)) { throw new Error('Genome builds must be either "hg19" or "hg38"'); } if (fromBuild === toBuild) { return { content: [{ type: "text", text: `No conversion needed: ${args.chr}:${args.position.toLocaleString()} (${fromBuild} → ${toBuild})` }] }; } let output = `**Genomic Coordinate Conversion**\n`; output += `Input: ${args.chr}:${args.position.toLocaleString()} (${fromBuild})\n`; output += `Target: ${toBuild}\n\n`; // Note: This is a simplified coordinate conversion // Real coordinate conversion requires liftOver tools or chain files // Provide approximate conversion based on known differences let convertedPosition = args.position; let conversionNote = ''; if (fromBuild === 'hg19' && toBuild === 'hg38') { // Very rough approximation - real conversion needs liftOver // Most positions shift by small amounts, some by larger amounts const roughOffset = this.getApproximateHg19ToHg38Offset(args.chr, args.position); convertedPosition = args.position + roughOffset; conversionNote = 'hg19 to hg38 conversion (approximate)'; } else if (fromBuild === 'hg38' && toBuild === 'hg19') { // Reverse conversion const roughOffset = this.getApproximateHg38ToHg19Offset(args.chr, args.position); convertedPosition = args.position + roughOffset; conversionNote = 'hg38 to hg19 conversion (approximate)'; } output += `**Converted Coordinates:**\n`; output += `• **${toBuild}**: ${args.chr}:${convertedPosition.toLocaleString()}\n`; output += `• **Offset**: ${(convertedPosition - args.position).toLocaleString()} bp\n\n`; output += `**Conversion Details:**\n`; output += `• Method: ${conversionNote}\n`; output += `• Chromosome: ${args.chr}\n`; output += `• Region type: ${this.getRegionType(args.chr, args.position)}\n\n`; output += `**⚠️ Important Limitations:**\n`; output += `• This is an APPROXIMATE conversion for demonstration purposes\n`; output += `• Real coordinate conversion requires UCSC liftOver tools\n`; output += `• Some positions may not have direct equivalents between builds\n`; output += `• Insertions/deletions between builds can affect accuracy\n\n`; output += `**Recommended Tools for Accurate Conversion:**\n`; output += `• UCSC Genome Browser LiftOver: https://genome.ucsc.edu/cgi-bin/hgLiftOver\n`; output += `• Ensembl Assembly Converter: https://www.ensembl.org/Homo_sapiens/Tools/AssemblyConverter\n`; output += `• NCBI Remap: https://www.ncbi.nlm.nih.gov/genome/tools/remap\n`; return { content: [{ type: "text", text: output }] }; }
- src/index.ts:583-612 (schema)MCP tool schema definition including input parameters, types, descriptions, defaults, and required fields for convert_coordinates.{ name: "convert_coordinates", description: "Convert between different genomic coordinate systems", inputSchema: { type: "object", properties: { chr: { type: "string", description: "Chromosome (e.g., chr1, chr2, chrX)" }, position: { type: "integer", description: "Genomic position to convert" }, fromBuild: { type: "string", description: "Source genome build (default: hg38)", enum: ["hg19", "hg38"], default: "hg38" }, toBuild: { type: "string", description: "Target genome build (default: hg19)", enum: ["hg19", "hg38"], default: "hg19" } }, required: ["chr", "position"] } }
- src/index.ts:779-786 (registration)Tool call dispatcher that maps convert_coordinates requests to the referenceHandlers.convertCoordinates implementation, passing parsed arguments.if (name === "convert_coordinates") { return await referenceHandlers.convertCoordinates({ chr: args?.chr, position: args?.position, fromBuild: args?.fromBuild, toBuild: args?.toBuild }); }
- Private helper method providing chromosome-specific approximate offsets for hg19 to hg38 coordinate conversion, used by the main handler.private getApproximateHg19ToHg38Offset(chr: string, position: number): number { // This is a very simplified approximation // Real conversion requires comprehensive chain files // Most positions have small positive offsets in hg38 // This is just for demonstration purposes const baseOffset = Math.floor(position * 0.0001); // Very rough approximation // Some chromosomes have different patterns switch (chr.toLowerCase()) { case 'chr1': return baseOffset + 100; case 'chr2': return baseOffset - 50; case 'chrx': return baseOffset + 200; case 'chry': return baseOffset - 100; default: return baseOffset; } }