GTEx MCP Server

Instructions

Implementation Reference

• src/handlers/expression-handlers.ts:751-853 (handler)

  The main handler function that fetches median gene expression data from GTEx API, organizes it by gene and tissue, finds common tissues across genes, computes pairwise Pearson correlations, and formats the results with strength classifications.
  async calculateExpressionCorrelation(args: any) { if (!args.geneIds || !Array.isArray(args.geneIds) || args.geneIds.length < 2) { throw new Error('geneIds parameter is required and must contain at least 2 gene IDs for correlation analysis'); } if (args.geneIds.length > 10) { return { content: [{ type: "text", text: "Maximum 10 genes can be processed for correlation analysis." }] }; } // Get median expression for all genes const result = await this.apiClient.getMedianGeneExpression( args.geneIds, args.datasetId || 'gtex_v8' ); if (result.error) { return { content: [{ type: "text", text: `Error calculating expression correlation: ${result.error}` }], isError: true }; } const expressions = result.data || []; if (expressions.length === 0) { return { content: [{ type: "text", text: "No expression data found for correlation analysis." }] }; } // Organize by gene and tissue const geneData: { [gene: string]: { [tissue: string]: number } } = {}; const geneNames: { [gene: string]: string } = {}; expressions.forEach(expr => { const geneKey = expr.gencodeId; geneNames[geneKey] = expr.geneSymbol; if (!geneData[geneKey]) { geneData[geneKey] = {}; } geneData[geneKey][expr.tissueSiteDetailId] = expr.median; }); // Find common tissues const genes = Object.keys(geneData); const commonTissues = Object.keys(geneData[genes[0]] || {}); // Calculate pairwise correlations let output = `**Gene Expression Correlation Analysis**\n`; output += `Genes: ${genes.length}\n`; output += `Common tissues: ${commonTissues.length}\n`; output += `Dataset: ${expressions[0]?.datasetId}\n\n`; if (commonTissues.length < 5) { output += `⚠️ **Warning**: Only ${commonTissues.length} common tissues found. Correlation analysis requires more data points for reliability.\n\n`; } output += `**Pairwise Correlations:**\n`; for (let i = 0; i < genes.length; i++) { for (let j = i + 1; j < genes.length; j++) { const gene1 = genes[i]; const gene2 = genes[j]; // Calculate Pearson correlation const values1 = commonTissues.map(t => geneData[gene1][t]).filter(v => v !== undefined); const values2 = commonTissues.map(t => geneData[gene2][t]).filter(v => v !== undefined); if (values1.length !== values2.length || values1.length < 3) { output += `• **${geneNames[gene1]}** vs **${geneNames[gene2]}**: Insufficient data\n`; continue; } const correlation = this.calculatePearsonCorrelation(values1, values2); const strength = Math.abs(correlation) > 0.7 ? "Strong" : Math.abs(correlation) > 0.4 ? "Moderate" : "Weak"; output += `• **${geneNames[gene1]}** vs **${geneNames[gene2]}**: r = ${correlation.toFixed(3)} (${strength})\n`; } } output += `\n**Analysis Notes:**\n`; output += `- Correlations calculated using median expression across tissues\n`; output += `- |r| > 0.7: Strong correlation, |r| > 0.4: Moderate correlation\n`; output += `- Based on ${commonTissues.length} tissue samples\n`; return { content: [{ type: "text", text: output }] }; }
• src/index.ts:657-662 (registration)

  Dispatches tool calls to the calculateExpressionCorrelation handler method in the ExpressionHandlers class.
  if (name === "calculate_expression_correlation") { return await expressionHandlers.calculateExpressionCorrelation({ geneIds: args?.gencodeIds || [], datasetId: args?.datasetId }); }
• src/index.ts:173-191 (schema)

  Defines the tool schema including name, description, and input parameters for the ListTools response.
  name: "calculate_expression_correlation", description: "Calculate expression correlation between genes across tissues", inputSchema: { type: "object", properties: { gencodeIds: { type: "array", items: { type: "string" }, description: "Array of GENCODE gene IDs to compare" }, datasetId: { type: "string", description: "GTEx dataset ID (default: gtex_v8)", default: "gtex_v8" } }, required: ["gencodeIds"] } },
• src/handlers/expression-handlers.ts:987-1001 (helper)

  Helper function that computes the Pearson correlation coefficient between two arrays of expression values, used in pairwise comparisons.
  private calculatePearsonCorrelation(x: number[], y: number[]): number { const n = x.length; if (n !== y.length || n === 0) return 0; const sumX = x.reduce((sum, val) => sum + val, 0); const sumY = y.reduce((sum, val) => sum + val, 0); const sumXY = x.reduce((sum, val, i) => sum + val * y[i], 0); const sumX2 = x.reduce((sum, val) => sum + val * val, 0); const sumY2 = y.reduce((sum, val) => sum + val * val, 0); const numerator = n * sumXY - sumX * sumY; const denominator = Math.sqrt((n * sumX2 - sumX * sumX) * (n * sumY2 - sumY * sumY)); return denominator === 0 ? 0 : numerator / denominator; }