GTEx MCP Server

Instructions

Implementation Reference

• src/handlers/reference-handlers.ts:88-160 (handler)

  Main handler function for get_gene_info tool. Validates input geneIds array (up to 50), calls apiClient.getGenes(), processes results into formatted markdown output with genomic locations, annotations, and descriptions for each gene.

  async getGeneInfo(args: any) {
    if (!args.geneIds || !Array.isArray(args.geneIds) || args.geneIds.length === 0) {
      throw new Error('geneIds parameter is required and must be a non-empty array of gene IDs');
    }
  
    if (args.geneIds.length > 50) {
      return {
        content: [{
          type: "text",
          text: "Maximum 50 genes can be processed at once. Please reduce the number of genes."
        }]
      };
    }
  
    const result = await this.apiClient.getGenes(
      args.geneIds,
      args.gencodeVersion || 'v26',
      args.genomeBuild || 'GRCh38/hg38'
    );
  
    if (result.error) {
      return {
        content: [{
          type: "text",
          text: `Error retrieving gene information: ${result.error}`
        }],
        isError: true
      };
    }
  
    const genes = result.data || [];
    if (genes.length === 0) {
      return {
        content: [{
          type: "text",
          text: `No genes found for the specified IDs: ${args.geneIds.join(', ')}`
        }]
      };
    }
  
    let output = `**Gene Information (${genes.length} genes)**\n`;
    output += `Genome: ${genes[0]?.genomeBuild}, GENCODE: ${genes[0]?.gencodeVersion}\n\n`;
  
    genes.forEach((gene, index) => {
      output += `### ${index + 1}. ${gene.geneSymbol} (${gene.gencodeId})\n`;
      output += `**Genomic Location:**\n`;
      output += `  • Chromosome: ${gene.chromosome}\n`;
      output += `  • Position: ${gene.start.toLocaleString()} - ${gene.end.toLocaleString()}\n`;
      output += `  • Strand: ${gene.strand}\n`;
      output += `  • Length: ${(gene.end - gene.start + 1).toLocaleString()} bp\n`;
      output += `  • TSS: ${gene.tss.toLocaleString()}\n\n`;
  
      output += `**Gene Annotation:**\n`;
      output += `  • Type: ${gene.geneType}\n`;
      output += `  • Status: ${gene.geneStatus}\n`;
      output += `  • Source: ${gene.dataSource}\n`;
      if (gene.entrezGeneId) {
        output += `  • Entrez Gene ID: ${gene.entrezGeneId}\n`;
      }
      
      if (gene.description) {
        output += `\n**Description:**\n${gene.description}\n`;
      }
      output += '\n';
    });
  
    return {
      content: [{
        type: "text",
        text: output.trim()
      }]
    };
  }

• src/index.ts:722-726 (registration)

  Tool dispatch/registration in the main CallToolRequestSchema handler. Routes 'get_gene_info' calls to referenceHandlers.getGeneInfo, mapping input args.gencodeId or geneSymbol to geneIds array.

  if (name === "get_gene_info") {
    return await referenceHandlers.getGeneInfo({
      geneIds: args?.gencodeId ? [args.gencodeId] : (args?.geneSymbol ? [args.geneSymbol] : [])
    });
  }

• src/index.ts:404-419 (schema)

  Tool schema definition in ListToolsRequestSchema response. Specifies name, description, and inputSchema accepting optional gencodeId or geneSymbol (no required fields listed, but handler expects one).

    name: "get_gene_info",
    description: "Get detailed information about a specific gene",
    inputSchema: {
      type: "object",
      properties: {
        gencodeId: {
          type: "string",
          description: "GENCODE gene ID (e.g., ENSG00000223972.5)"
        },
        geneSymbol: {
          type: "string",
          description: "Gene symbol (alternative to gencodeId)"
        }
      }
    }
  },