AlphaFold MCP Server

Instructions

Implementation Reference

• src/index.ts:633-690 (handler)

  The handler function that implements the get_structure tool. It validates input, fetches structure data from AlphaFold API, handles JSON or file formats (pdb/cif/bcif), and returns appropriate content or error.

  private async handleGetStructure(args: any) {
    if (!isValidUniProtArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid UniProt 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 AlphaFold structure prediction found for ${args.uniprotId}`,
            },
          ],
        };
      }
  
      const structure = structures[0];
      if (args.format === 'json') {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(structure, null, 2),
            },
          ],
        };
      } else {
        // Handle file format downloads
        const url = args.format === 'pdb' ? structure.pdbUrl :
                   args.format === 'cif' ? structure.cifUrl :
                   args.format === 'bcif' ? structure.bcifUrl : structure.pdbUrl;
  
        const fileResponse = await axios.get(url);
        return {
          content: [
            {
              type: 'text',
              text: fileResponse.data,
            },
          ],
        };
      }
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error fetching AlphaFold structure: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:351-357 (schema)

  Input schema definition for the get_structure tool, specifying uniprotId as required and optional format.

    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'],
  },

• src/index.ts:347-358 (registration)

  Tool registration in ListToolsRequestSchema response, defining name, description, and inputSchema.

  {
    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'],
    },
  },

• src/index.ts:579-581 (registration)

  Dispatch in CallToolRequestSchema handler that routes 'get_structure' calls to the handleGetStructure method.

  case 'get_structure':
    return this.handleGetStructure(args);
  case 'download_structure':

• src/index.ts:58-68 (helper)

  Type guard helper function used to validate arguments for get_structure and similar UniProt-based tools.

  const isValidUniProtArgs = (
    args: any
  ): args is { uniprotId: string; format?: 'pdb' | 'cif' | 'bcif' | 'json' } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.uniprotId === 'string' &&
      args.uniprotId.length > 0 &&
      (args.format === undefined || ['pdb', 'cif', 'bcif', 'json'].includes(args.format))
    );
  };