GTEx MCP Server

Instructions

Implementation Reference

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

  Main handler function that fetches median gene expression data for multiple genes and computes pairwise Pearson correlations across common tissues, returning formatted correlation results.
  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:175-190 (schema)

  Input schema defining the parameters for the calculate_expression_correlation tool: array of GENCODE gene IDs (required) and optional datasetId.
  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/index.ts:172-191 (registration)

  Tool registration in the listTools response, including name, description, and input schema.
  { 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/index.ts:657-662 (registration)

  Dispatch logic in CallToolRequest handler that routes calls to the expressionHandlers.calculateExpressionCorrelation method.
  if (name === "calculate_expression_correlation") { return await expressionHandlers.calculateExpressionCorrelation({ geneIds: args?.gencodeIds || [], datasetId: args?.datasetId }); }
• src/handlers/expression-handlers.ts:987-1001 (helper)

  Private helper method that computes the Pearson correlation coefficient between two arrays of expression values.
  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; }