AlphaFold MCP Server

Instructions

Implementation Reference

• src/index.ts:996-1053 (handler)

  The handler function that executes the 'analyze_confidence_regions' tool. It fetches AlphaFold prediction data for the given UniProt ID and performs analysis to identify confidence regions (very high, confident, low) with mock data based on sequence length.

  private async handleAnalyzeConfidenceRegions(args: any) {
    if (!isValidConfidenceArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid confidence analysis arguments');
    }
  
    try {
      const response = await this.apiClient.get(`/prediction/${args.uniprotId}`);
      const structures = response.data;
  
      if (!structures || structures.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No structure available for ${args.uniprotId}`,
            },
          ],
        };
      }
  
      const structure = structures[0];
      const sequenceLength = structure.uniprotSequence.length;
  
      // Mock confidence analysis
      const regions = {
        veryHighConfidence: { start: 1, end: Math.floor(sequenceLength * 0.3), avgScore: 95 },
        confident: { start: Math.floor(sequenceLength * 0.3) + 1, end: Math.floor(sequenceLength * 0.7), avgScore: 80 },
        lowConfidence: { start: Math.floor(sequenceLength * 0.7) + 1, end: sequenceLength, avgScore: 60 },
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              uniprotId: args.uniprotId,
              confidenceRegions: regions,
              analysis: {
                highConfidencePercentage: 30,
                mediumConfidencePercentage: 40,
                lowConfidencePercentage: 30,
              },
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error analyzing confidence regions: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:432-442 (schema)

  The input schema definition for the 'analyze_confidence_regions' tool, specifying the required 'uniprotId' parameter.

  {
    name: 'analyze_confidence_regions',
    description: 'Analyze confidence score distribution and identify high/low confidence regions',
    inputSchema: {
      type: 'object',
      properties: {
        uniprotId: { type: 'string', description: 'UniProt accession' },
      },
      required: ['uniprotId'],
    },
  },

• src/index.ts:595-596 (registration)

  The dispatch case in the CallToolRequestSchema handler that routes calls to 'analyze_confidence_regions' to its handler function.

  case 'analyze_confidence_regions':
    return this.handleAnalyzeConfidenceRegions(args);

• src/index.ts:344-572 (registration)

  The tool registration in ListToolsRequestSchema where 'analyze_confidence_regions' is listed among available tools with its schema.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      // Core Structure Tools
      {
        name: 'get_structure',
        description: 'Get AlphaFold structure prediction for a specific UniProt ID',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession (e.g., P21359, Q8N726)' },
            format: { type: 'string', enum: ['pdb', 'cif', 'bcif', 'json'], description: 'Output format (default: json)' },
          },
          required: ['uniprotId'],
        },
      },
      {
        name: 'download_structure',
        description: 'Download AlphaFold structure file in specified format',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession' },
            format: { type: 'string', enum: ['pdb', 'cif', 'bcif'], description: 'File format (default: pdb)' },
          },
          required: ['uniprotId'],
        },
      },
      {
        name: 'check_availability',
        description: 'Check if AlphaFold structure prediction is available for a UniProt ID',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession to check' },
          },
          required: ['uniprotId'],
        },
      },
      // Search & Discovery Tools
      {
        name: 'search_structures',
        description: 'Search for available AlphaFold structures by protein name or gene',
        inputSchema: {
          type: 'object',
          properties: {
            query: { type: 'string', description: 'Search term (protein name, gene name, etc.)' },
            organism: { type: 'string', description: 'Filter by organism (optional)' },
            size: { type: 'number', description: 'Number of results (1-100, default: 25)', minimum: 1, maximum: 100 },
          },
          required: ['query'],
        },
      },
      {
        name: 'list_by_organism',
        description: 'List all available structures for a specific organism',
        inputSchema: {
          type: 'object',
          properties: {
            organism: { type: 'string', description: 'Organism name (e.g., "Homo sapiens", "Escherichia coli")' },
            size: { type: 'number', description: 'Number of results (1-100, default: 50)', minimum: 1, maximum: 100 },
          },
          required: ['organism'],
        },
      },
      {
        name: 'get_organism_stats',
        description: 'Get statistics about AlphaFold coverage for an organism',
        inputSchema: {
          type: 'object',
          properties: {
            organism: { type: 'string', description: 'Organism name' },
          },
          required: ['organism'],
        },
      },
      // Confidence & Quality Tools
      {
        name: 'get_confidence_scores',
        description: 'Get per-residue confidence scores for a structure prediction',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession' },
            threshold: { type: 'number', description: 'Confidence threshold (0-100, optional)', minimum: 0, maximum: 100 },
          },
          required: ['uniprotId'],
        },
      },
      {
        name: 'analyze_confidence_regions',
        description: 'Analyze confidence score distribution and identify high/low confidence regions',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession' },
          },
          required: ['uniprotId'],
        },
      },
      {
        name: 'get_prediction_metadata',
        description: 'Get metadata about the prediction including version, date, and quality metrics',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession' },
          },
          required: ['uniprotId'],
        },
      },
      // Batch Processing Tools
      {
        name: 'batch_structure_info',
        description: 'Get structure information for multiple proteins simultaneously',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotIds: { type: 'array', items: { type: 'string' }, description: 'Array of UniProt accessions (max 50)', minItems: 1, maxItems: 50 },
            format: { type: 'string', enum: ['json', 'summary'], description: 'Output format (default: json)' },
          },
          required: ['uniprotIds'],
        },
      },
      {
        name: 'batch_download',
        description: 'Download multiple structure files',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotIds: { type: 'array', items: { type: 'string' }, description: 'Array of UniProt accessions (max 20)', minItems: 1, maxItems: 20 },
            format: { type: 'string', enum: ['pdb', 'cif'], description: 'File format (default: pdb)' },
          },
          required: ['uniprotIds'],
        },
      },
      {
        name: 'batch_confidence_analysis',
        description: 'Analyze confidence scores for multiple proteins',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotIds: { type: 'array', items: { type: 'string' }, description: 'Array of UniProt accessions (max 30)', minItems: 1, maxItems: 30 },
          },
          required: ['uniprotIds'],
        },
      },
      // Comparative Analysis Tools
      {
        name: 'compare_structures',
        description: 'Compare multiple AlphaFold structures for analysis',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotIds: { type: 'array', items: { type: 'string' }, description: 'Array of UniProt accessions to compare (2-10)', minItems: 2, maxItems: 10 },
          },
          required: ['uniprotIds'],
        },
      },
      {
        name: 'find_similar_structures',
        description: 'Find AlphaFold structures similar to a given protein',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'Reference UniProt accession' },
            organism: { type: 'string', description: 'Filter by organism (optional)' },
          },
          required: ['uniprotId'],
        },
      },
      // Coverage & Completeness Tools
      {
        name: 'get_coverage_info',
        description: 'Get information about sequence coverage in the AlphaFold prediction',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession' },
          },
          required: ['uniprotId'],
        },
      },
      {
        name: 'validate_structure_quality',
        description: 'Validate and assess the overall quality of an AlphaFold prediction',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession' },
          },
          required: ['uniprotId'],
        },
      },
      // Export & Integration Tools
      {
        name: 'export_for_pymol',
        description: 'Export structure data formatted for PyMOL visualization',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession' },
            includeConfidence: { type: 'boolean', description: 'Include confidence score coloring (default: true)' },
          },
          required: ['uniprotId'],
        },
      },
      {
        name: 'export_for_chimerax',
        description: 'Export structure data formatted for ChimeraX visualization',
        inputSchema: {
          type: 'object',
          properties: {
            uniprotId: { type: 'string', description: 'UniProt accession' },
            includeConfidence: { type: 'boolean', description: 'Include confidence score coloring (default: true)' },
          },
          required: ['uniprotId'],
        },
      },
      {
        name: 'get_api_status',
        description: 'Check AlphaFold API status and database statistics',
        inputSchema: {
          type: 'object',
          properties: {},
          required: [],
        },
      },
    ],
  }));

• src/index.ts:122-132 (helper)

  Validation function for confidence-related tool arguments, used by 'analyze_confidence_regions' to validate input parameters.

  const isValidConfidenceArgs = (
    args: any
  ): args is { uniprotId: string; threshold?: number } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.uniprotId === 'string' &&
      args.uniprotId.length > 0 &&
      (args.threshold === undefined || (typeof args.threshold === 'number' && args.threshold >= 0 && args.threshold <= 100))
    );
  };