UniProt MCP Server

Instructions

Implementation Reference

• src/index.ts:1035-1084 (handler)

  Implements the core logic for the get_protein_homologs tool. Fetches protein details by accession, constructs a search query using the protein name and optional organism filter (excluding the original protein), queries UniProt search API for homologs, and returns JSON results.

  private async handleGetProteinHomologs(args: any) {
    if (!isValidHomologArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid homolog search arguments');
    }
  
    try {
      // Get the protein info first to build a homology search
      const proteinResponse = await this.apiClient.get(`/uniprotkb/${args.accession}`, {
        params: { format: 'json' },
      });
      const protein = proteinResponse.data;
  
      // Build search query for homologs
      let query = `reviewed:true`;
      if (protein.proteinDescription?.recommendedName?.fullName?.value) {
        query += ` AND (${protein.proteinDescription.recommendedName.fullName.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 homologs: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:478-486 (schema)

  JSON schema defining the input parameters for the get_protein_homologs tool, including accession (required), optional organism, and size limits.

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

• src/index.ts:741-742 (registration)

  Registers the handler function for the get_protein_homologs tool in the CallToolRequestSchema switch statement.

  case 'get_protein_homologs':
    return this.handleGetProteinHomologs(args);

• src/index.ts:476-487 (registration)

  Registers the tool metadata, name, description, and schema in the ListToolsRequestSchema response.

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

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

  Type guard function for validating input arguments to the get_protein_homologs handler.

  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))
    );
  };