AlphaGenome MCP Server

Instructions

Implementation Reference

• src/index.ts:130-143 (handler)

  MCP CallTool request handler case for 'batch_score_variants': validates input using batchScoreSchema, calls AlphaGenomeClient.batchScore(), formats result with formatBatchResult() and returns as text content.

  case 'batch_score_variants': {
    const params = validateInput(batchScoreSchema, args) as BatchScoreParams;
    const result = await getClient().batchScore(params);
    const formatted = formatBatchResult(result);
  
    return {
      content: [
        {
          type: 'text',
          text: formatted,
        },
      ],
    };

• src/alphagenome-client.ts:218-233 (handler)

  AlphaGenomeClient.batchScore method: core execution logic that invokes Python bridge with action 'batch_score', passing variants and scoring parameters, handles errors.

  async batchScore(params: BatchScoreParams): Promise<BatchResult> {
    try {
      const result = await this.callPythonBridge<BatchResult>('batch_score', {
        variants: params.variants,
        scoring_metric: params.scoring_metric,
        top_n: params.top_n,
      });
  
      return result;
    } catch (error) {
      if (error instanceof ApiError) {
        throw error;
      }
      throw new ApiError(`Batch scoring failed: ${error}`, 500);
    }
  }

• src/tools.ts:74-148 (schema)

  Tool object definition for 'batch_score_variants' including name, description, and detailed inputSchema for MCP tool listing and validation.

  export const BATCH_SCORE_TOOL: Tool = {
    name: 'batch_score_variants',
    description: `Score and prioritize multiple genetic variants using AlphaGenome AI.
  
  Powered by Google DeepMind's AlphaGenome model for high-throughput variant scoring.
  
  Analyzes up to 100 variants simultaneously and ranks them by regulatory impact.
  
  Scoring metrics:
  - rna_seq: Gene expression changes
  - splice: Splicing alterations
  - regulatory_impact: Combined regulatory score
  - combined: All metrics weighted
  
  Perfect for: GWAS post-analysis, VCF filtering, variant prioritization.
  
  Example: "Score these 50 variants and show me the top 10 by regulatory impact"`,
    inputSchema: {
      type: 'object',
      properties: {
        variants: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              chromosome: {
                type: 'string',
                description: 'Chromosome',
                pattern: '^chr([1-9]|1[0-9]|2[0-2]|X|Y)$',
              },
              position: {
                type: 'number',
                description: 'Position',
                minimum: 1,
              },
              ref: {
                type: 'string',
                description: 'Reference allele',
                pattern: '^[ATGCatgc]+$',
              },
              alt: {
                type: 'string',
                description: 'Alternate allele',
                pattern: '^[ATGCatgc]+$',
              },
              variant_id: {
                type: 'string',
                description: 'Optional: variant identifier (e.g., rs number)',
              },
            },
            required: ['chromosome', 'position', 'ref', 'alt'],
          },
          description: 'List of variants to analyze (1-100)',
          minItems: 1,
          maxItems: 100,
        },
        scoring_metric: {
          type: 'string',
          enum: ['rna_seq', 'splice', 'regulatory_impact', 'combined'],
          description: 'Metric to use for scoring and ranking',
        },
        top_n: {
          type: 'number',
          description: 'Number of top variants to return (default: 10, max: 100)',
          minimum: 1,
          maximum: 100,
        },
        include_interpretation: {
          type: 'boolean',
          description: 'Include detailed clinical interpretation (default: false)',
        },
      },
      required: ['variants', 'scoring_metric'],
    },
  };

• src/utils/validation.ts:88-104 (schema)

  Zod schema 'batchScoreSchema' for runtime input validation of batch_score_variants parameters, used in the handler.

  export const batchScoreSchema = z.object({
    variants: z
      .array(
        z.object({
          chromosome: chromosomeSchema,
          position: positiveIntSchema,
          ref: nucleotideSchema,
          alt: nucleotideSchema,
          variant_id: z.string().optional(),
        })
      )
      .min(1, 'At least one variant is required')
      .max(100, 'Maximum 100 variants allowed'),
    scoring_metric: z.enum(['rna_seq', 'splice', 'regulatory_impact', 'combined']),
    top_n: z.number().int().min(1).max(100).optional().default(10),
    include_interpretation: z.boolean().optional().default(false),
  });

• src/utils/formatting.ts:213-266 (helper)

  formatBatchResult helper: formats the BatchResult from client into human-readable Markdown output with top variants table, impact distribution, and disclaimers.

  export function formatBatchResult(result: BatchResult): string {
    const date = new Date().toISOString().split('T')[0];
    const time = new Date().toISOString().split('T')[1].split('.')[0];
  
    let output = `# 📊 AlphaGenome Batch Variant Analysis\n\n`;
    output += `**Total Variants Analyzed**: ${result.total_analyzed}\n`;
    output += `**Analysis Date**: ${date} ${time} UTC\n\n`;
    output += `---\n\n`;
  
    output += `## 🏆 Top Variants by Impact\n\n`;
    output += `| Rank | Variant ID | Location | Impact Score | Impact Level | Key Effect |\n`;
    output += `|------|------------|----------|--------------|--------------|------------|\n`;
  
    result.variants.forEach((v) => {
      const badge =
        v.impact_level === 'high'
          ? '🔴 High'
          : v.impact_level === 'moderate'
            ? '🟡 Moderate'
            : '🟢 Low';
      const varId = v.variant_id || '-';
      const keyEffect = v.key_effect || 'Regulatory element';
      output += `| ${v.rank} | ${varId} | ${v.variant} | ${v.score.toFixed(
        2
      )} | ${badge} | ${keyEffect} |\n`;
    });
  
    output += `\n---\n\n`;
  
    output += `## 📈 Impact Distribution\n\n`;
    output += `\`\`\`\n`;
    output += `Impact Level    | Count | Percentage\n`;
    output += `----------------|-------|------------\n`;
    for (const [level, count] of Object.entries(result.distribution)) {
      const pct = ((count / result.total_analyzed) * 100).toFixed(1);
      const emoji = level === 'high' ? '🔴' : level === 'moderate' ? '🟡' : '🟢';
      output += `${emoji} ${level.padEnd(13)} | ${String(count).padStart(5)} | ${pct.padStart(5)}%\n`;
    }
    output += `----------------|-------|------------\n`;
    output += `Total           | ${String(result.total_analyzed).padStart(5)} | 100.0%\n`;
    output += `\`\`\`\n\n`;
  
    output += `---\n\n`;
    output += `## ⚠️ Important Disclaimer\n\n`;
    output += `**For Research Use Only**\n\n`;
    output += `- ⚠️ NOT for clinical use or diagnosis\n`;
    output += `- ✅ Powered by AlphaGenome AI predictions\n`;
    output += `- 📋 Validate with experimental data\n\n`;
    output += `---\n\n`;
    output += `*AlphaGenome MCP Server v0.1.0*\n`;
    output += `*GitHub: https://github.com/taehojo/alphagenome-mcp*\n`;
  
    return output;
  }