GTEx MCP Server

Instructions

Implementation Reference

• src/handlers/reference-handlers.ts:1162-1239 (handler)

  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
    });
  }

• src/handlers/reference-handlers.ts:1322-1338 (helper)

  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;
    }
  }