UniProt MCP Server

Instructions

Implementation Reference

• src/index.ts:1137-1175 (handler)

  The main handler function for the 'get_phylogenetic_info' tool. It validates input, fetches detailed protein information from the UniProt REST API, extracts relevant phylogenetic data (organism, lineage, evolutionary origin, phylogenetic range comments), formats it as JSON, and returns it.
  private async handleGetPhylogeneticInfo(args: any) { if (!isValidProteinInfoArgs(args)) { throw new McpError(ErrorCode.InvalidParams, 'Invalid phylogenetic info arguments'); } try { const response = await this.apiClient.get(`/uniprotkb/${args.accession}`, { params: { format: 'json' }, }); const protein = response.data; const phylogeneticInfo = { accession: protein.primaryAccession, organism: protein.organism, taxonomicLineage: protein.organism?.lineage || [], evolutionaryOrigin: protein.comments?.filter((c: any) => c.commentType === 'EVOLUTIONARY ORIGIN') || [], phylogeneticRange: protein.comments?.filter((c: any) => c.commentType === 'PHYLOGENETIC RANGE') || [], }; return { content: [ { type: 'text', text: JSON.stringify(phylogeneticInfo, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error fetching phylogenetic info: ${error instanceof Error ? error.message : 'Unknown error'}`, }, ], isError: true, }; } }
• src/index.ts:502-510 (schema)

  The tool schema definition including name, description, and input schema (requires UniProt accession). This is returned by the ListTools handler.
  name: 'get_phylogenetic_info', description: 'Retrieve evolutionary relationships and phylogenetic data', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], },
• src/index.ts:744-747 (registration)

  Registration of the tool handler in the CallToolRequestSchema switch statement, mapping the tool name to its handler method.
  return this.handleGetProteinOrthologs(args); case 'get_phylogenetic_info': return this.handleGetPhylogeneticInfo(args); // Structure & Function Analysis Tools
• src/index.ts:79-89 (helper)

  Helper validation function used by the handler to validate input arguments (accession and optional format).
  const isValidProteinInfoArgs = ( args: any ): args is { accession: string; format?: string } => { return ( typeof args === 'object' && args !== null && typeof args.accession === 'string' && args.accession.length > 0 && (args.format === undefined || ['json', 'tsv', 'fasta', 'xml'].includes(args.format)) ); };
• src/index.ts:397-721 (registration)

  Overall tool registration in setupToolHandlers where all tools including get_phylogenetic_info are listed with their schemas for the ListTools endpoint.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ // Original tools { name: 'search_proteins', description: 'Search UniProt database for proteins by name, keyword, or organism', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query (protein name, keyword, or complex search)' }, organism: { type: 'string', description: 'Organism name or taxonomy ID to filter results' }, size: { type: 'number', description: 'Number of results to return (1-500, default: 25)', minimum: 1, maximum: 500 }, format: { type: 'string', enum: ['json', 'tsv', 'fasta', 'xml'], description: 'Output format (default: json)' }, }, required: ['query'], }, }, { name: 'get_protein_info', description: 'Get detailed information for a specific protein by UniProt accession', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number (e.g., P04637)' }, format: { type: 'string', enum: ['json', 'tsv', 'fasta', 'xml'], description: 'Output format (default: json)' }, }, required: ['accession'], }, }, { name: 'search_by_gene', description: 'Search for proteins by gene name or symbol', inputSchema: { type: 'object', properties: { gene: { type: 'string', description: 'Gene name or symbol (e.g., BRCA1, INS)' }, organism: { type: 'string', description: 'Organism name or taxonomy ID to filter results' }, size: { type: 'number', description: 'Number of results to return (1-500, default: 25)', minimum: 1, maximum: 500 }, }, required: ['gene'], }, }, { name: 'get_protein_sequence', description: 'Get the amino acid sequence for a protein', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, format: { type: 'string', enum: ['fasta', 'json'], description: 'Output format (default: fasta)' }, }, required: ['accession'], }, }, { name: 'get_protein_features', description: 'Get functional features and domains for a protein', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, // Comparative & Evolutionary Analysis Tools { name: 'compare_proteins', description: 'Compare multiple proteins side-by-side with sequence and feature comparison', inputSchema: { type: 'object', properties: { accessions: { type: 'array', items: { type: 'string' }, description: 'Array of UniProt accession numbers (2-10)', minItems: 2, maxItems: 10 }, format: { type: 'string', enum: ['json', 'tsv'], description: 'Output format (default: json)' }, }, required: ['accessions'], }, }, { name: 'get_protein_homologs', description: 'Find homologous proteins across different species', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, organism: { type: 'string', description: 'Target organism to find homologs in' }, size: { type: 'number', description: 'Number of results to return (1-100, default: 25)', minimum: 1, maximum: 100 }, }, required: ['accession'], }, }, { name: 'get_protein_orthologs', description: 'Identify orthologous proteins for evolutionary studies', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, organism: { type: 'string', description: 'Target organism to find orthologs in' }, size: { type: 'number', description: 'Number of results to return (1-100, default: 25)', minimum: 1, maximum: 100 }, }, required: ['accession'], }, }, { name: 'get_phylogenetic_info', description: 'Retrieve evolutionary relationships and phylogenetic data', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, // Structure & Function Analysis Tools { name: 'get_protein_structure', description: 'Retrieve 3D structure information from PDB references', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, { name: 'get_protein_domains_detailed', description: 'Enhanced domain analysis with InterPro, Pfam, and SMART annotations', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, { name: 'get_protein_variants', description: 'Disease-associated variants and mutations', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, { name: 'analyze_sequence_composition', description: 'Amino acid composition, hydrophobicity, and other sequence properties', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, // Biological Context Tools { name: 'get_protein_pathways', description: 'Associated biological pathways (KEGG, Reactome)', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, { name: 'get_protein_interactions', description: 'Protein-protein interaction networks', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, { name: 'search_by_function', description: 'Search proteins by GO terms or functional annotations', inputSchema: { type: 'object', properties: { goTerm: { type: 'string', description: 'Gene Ontology term (e.g., GO:0005524)' }, function: { type: 'string', description: 'Functional description or keyword' }, organism: { type: 'string', description: 'Organism name or taxonomy ID to filter results' }, size: { type: 'number', description: 'Number of results to return (1-500, default: 25)', minimum: 1, maximum: 500 }, }, required: [], }, }, { name: 'search_by_localization', description: 'Find proteins by subcellular localization', inputSchema: { type: 'object', properties: { localization: { type: 'string', description: 'Subcellular localization (e.g., nucleus, mitochondria)' }, organism: { type: 'string', description: 'Organism name or taxonomy ID to filter results' }, size: { type: 'number', description: 'Number of results to return (1-500, default: 25)', minimum: 1, maximum: 500 }, }, required: ['localization'], }, }, // Batch Processing & Advanced Search { name: 'batch_protein_lookup', description: 'Process multiple accessions efficiently', inputSchema: { type: 'object', properties: { accessions: { type: 'array', items: { type: 'string' }, description: 'Array of UniProt accession numbers (1-100)', minItems: 1, maxItems: 100 }, format: { type: 'string', enum: ['json', 'tsv', 'fasta'], description: 'Output format (default: json)' }, }, required: ['accessions'], }, }, { name: 'advanced_search', description: 'Complex queries with multiple filters (length, mass, organism, function)', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Base search query' }, organism: { type: 'string', description: 'Organism name or taxonomy ID' }, minLength: { type: 'number', description: 'Minimum sequence length', minimum: 1 }, maxLength: { type: 'number', description: 'Maximum sequence length' }, minMass: { type: 'number', description: 'Minimum molecular mass (Da)', minimum: 1 }, maxMass: { type: 'number', description: 'Maximum molecular mass (Da)' }, keywords: { type: 'array', items: { type: 'string' }, description: 'Array of keywords to include' }, size: { type: 'number', description: 'Number of results to return (1-500, default: 25)', minimum: 1, maximum: 500 }, }, required: [], }, }, { name: 'search_by_taxonomy', description: 'Search by detailed taxonomic classification', inputSchema: { type: 'object', properties: { taxonomyId: { type: 'number', description: 'NCBI taxonomy ID', minimum: 1 }, taxonomyName: { type: 'string', description: 'Taxonomic name (e.g., Mammalia, Bacteria)' }, size: { type: 'number', description: 'Number of results to return (1-500, default: 25)', minimum: 1, maximum: 500 }, }, required: [], }, }, // Cross-Reference & Literature Tools { name: 'get_external_references', description: 'Links to other databases (PDB, EMBL, RefSeq, etc.)', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, { name: 'get_literature_references', description: 'Associated publications and citations', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, { name: 'get_annotation_confidence', description: 'Quality scores for different annotations', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, // Export & Utility Tools { name: 'export_protein_data', description: 'Export data in specialized formats (GFF, GenBank, etc.)', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, format: { type: 'string', enum: ['gff', 'genbank', 'embl', 'xml'], description: 'Export format' }, }, required: ['accession', 'format'], }, }, { name: 'validate_accession', description: 'Check if accession numbers are valid', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number to validate' }, }, required: ['accession'], }, }, { name: 'get_taxonomy_info', description: 'Detailed taxonomic information for organisms', inputSchema: { type: 'object', properties: { accession: { type: 'string', description: 'UniProt accession number' }, }, required: ['accession'], }, }, ], }));