UniProt MCP Server

Instructions

Implementation Reference

• src/index.ts:1086-1135 (handler)

  The handler function that executes the tool logic: validates input, fetches the source protein details, constructs a UniProt search query using the gene name in the target organism, retrieves matching proteins, and returns the results as JSON.

  private async handleGetProteinOrthologs(args: any) {
    if (!isValidHomologArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid ortholog search arguments');
    }
  
    try {
      // Get the protein info first
      const proteinResponse = await this.apiClient.get(`/uniprotkb/${args.accession}`, {
        params: { format: 'json' },
      });
      const protein = proteinResponse.data;
  
      // Build ortholog search (similar function, different organism)
      let query = `reviewed:true`;
      if (protein.genes?.[0]?.geneName?.value) {
        query += ` AND gene:"${protein.genes[0].geneName.value}"`;
      }
      if (args.organism) {
        query += ` AND organism_name:"${args.organism}"`;
      }
      query += ` NOT accession:"${args.accession}"`;
  
      const response = await this.apiClient.get('/uniprotkb/search', {
        params: {
          query: query,
          format: 'json',
          size: args.size || 25,
        },
      });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error finding orthologs: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:489-500 (registration)

  Tool registration in the list of available tools, including name, description, and input schema definition.

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

• src/index.ts:743-744 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement, mapping the tool name to its handler.

  case 'get_protein_orthologs':
    return this.handleGetProteinOrthologs(args);

• src/index.ts:491-499 (schema)

  Input schema definition for the get_protein_orthologs tool, specifying parameters and validation rules.

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

• src/index.ts:130-141 (helper)

  Validation helper function used by the orthologs handler to check input arguments.

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