GTEx MCP Server

Instructions

Implementation Reference

• src/handlers/association-handlers.ts:410-489 (handler)

  Main handler function that executes the get_sqtl_results tool. Calls GTEx API for sQTL genes (sGenes) by tissue, processes results, sorts by q-value, groups by tissue, and formats a detailed Markdown summary of top sGenes with statistics.

  async getSQTLGenes(args: any) {
    const result = await this.apiClient.getSQTLGenes(
      args.tissueIds,
      args.datasetId || 'gtex_v8'
    );
  
    if (result.error) {
      return {
        content: [{
          type: "text",
          text: `Error retrieving sQTL genes: ${result.error}`
        }],
        isError: true
      };
    }
  
    const sqtlGenes = result.data || [];
    if (sqtlGenes.length === 0) {
      return {
        content: [{
          type: "text",
          text: `No sQTL genes found${args.tissueIds ? ` for tissues: ${args.tissueIds.join(', ')}` : ''}`
        }]
      };
    }
  
    // Group by tissue
    const tissueGroups: { [key: string]: any[] } = {};
    sqtlGenes.forEach(gene => {
      if (!tissueGroups[gene.tissueSiteDetailId]) {
        tissueGroups[gene.tissueSiteDetailId] = [];
      }
      tissueGroups[gene.tissueSiteDetailId].push(gene);
    });
  
    let output = `**sQTL Genes (${sqtlGenes.length} results)**\n`;
    output += `Dataset: ${sqtlGenes[0]?.datasetId}\n`;
    output += `Tissues: ${Object.keys(tissueGroups).length}\n\n`;
  
    Object.entries(tissueGroups).forEach(([tissueId, genes]) => {
      const tissueDisplayName = this.getTissueDisplayName(tissueId);
      output += `### ${tissueDisplayName} (${genes.length} sGenes)\n`;
  
      // Sort by significance
      const sortedGenes = genes.sort((a, b) => a.qValue - b.qValue);
      
      const topCount = Math.min(10, sortedGenes.length);
      sortedGenes.slice(0, topCount).forEach((gene, index) => {
        output += `${(index + 1).toString().padStart(2)}. **${gene.geneSymbol}** (${gene.gencodeId})\n`;
        output += `    • Phenotype: ${gene.phenotypeId}\n`;
        output += `    • p-value: ${gene.pValue.toExponential(2)}\n`;
        output += `    • q-value: ${gene.qValue.toFixed(4)}\n`;
        output += `    • Empirical p-value: ${gene.empiricalPValue.toExponential(2)}\n`;
        output += `    • # Phenotypes tested: ${gene.nPhenotypes}\n`;
        output += `    • p-value threshold: ${gene.pValueThreshold.toExponential(2)}\n`;
      });
  
      if (sortedGenes.length > topCount) {
        output += `    ... and ${sortedGenes.length - topCount} more sGenes\n`;
      }
  
      // Tissue summary
      const qValues = sortedGenes.map(g => g.qValue);
      output += `\n**Tissue Summary:**\n`;
      output += `  • Total sGenes: ${genes.length}\n`;
      output += `  • Most significant q-value: ${Math.min(...qValues).toExponential(2)}\n`;
      output += `  • Mean phenotypes per gene: ${(genes.reduce((sum, g) => sum + g.nPhenotypes, 0) / genes.length).toFixed(1)}\n\n`;
    });
  
    if (result.paging_info && result.paging_info.totalNumberOfItems > sqtlGenes.length) {
      output += `**Note:** Showing ${sqtlGenes.length} of ${result.paging_info.totalNumberOfItems} total results.\n`;
    }
  
    return {
      content: [{
        type: "text",
        text: output.trim()
      }]
    };
  }

• src/index.ts:319-341 (schema)

  Tool schema definition in ListTools response, specifying input parameters: gencodeId (required), tissueSiteDetailId (optional), datasetId (optional). Note: gencodeId is required in schema but not used in handler implementation.

  {
    name: "get_sqtl_results",
    description: "Get splicing QTL (sQTL) results for a gene",
    inputSchema: {
      type: "object",
      properties: {
        gencodeId: {
          type: "string",
          description: "GENCODE gene ID (e.g., ENSG00000223972.5)"
        },
        tissueSiteDetailId: {
          type: "string",
          description: "Tissue site detail ID (optional, for tissue-specific results)"
        },
        datasetId: {
          type: "string",
          description: "GTEx dataset ID (default: gtex_v8)",
          default: "gtex_v8"
        }
      },
      required: ["gencodeId"]
    }
  },

• src/index.ts:699-704 (registration)

  Dispatch logic in CallToolRequestSchema handler that routes 'get_sqtl_results' calls to AssociationHandlers.getSQTLGenes, mapping tool args to handler parameters (ignores gencodeId).

  if (name === "get_sqtl_results") {
    return await associationHandlers.getSQTLGenes({
      tissueIds: args?.tissueSiteDetailId ? [args.tissueSiteDetailId] : undefined,
      datasetId: args?.datasetId
    });
  }