UniProt MCP Server

Instructions

Implementation Reference

• src/index.ts:1580-1649 (handler)

  The main handler function for the 'advanced_search' tool. It validates input, constructs a complex UniProt search query using filters like length, mass, organism, keywords, executes the API call, and returns the results.

  private async handleAdvancedSearch(args: any) {
    if (!isValidAdvancedSearchArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid advanced search arguments');
    }
  
    try {
      let query = 'reviewed:true';
  
      if (args.query) {
        query += ` AND (${args.query})`;
      }
  
      if (args.organism) {
        query += ` AND organism_name:"${args.organism}"`;
      }
  
      if (args.minLength || args.maxLength) {
        if (args.minLength && args.maxLength) {
          query += ` AND length:[${args.minLength} TO ${args.maxLength}]`;
        } else if (args.minLength) {
          query += ` AND length:[${args.minLength} TO *]`;
        } else if (args.maxLength) {
          query += ` AND length:[* TO ${args.maxLength}]`;
        }
      }
  
      if (args.minMass || args.maxMass) {
        if (args.minMass && args.maxMass) {
          query += ` AND mass:[${args.minMass} TO ${args.maxMass}]`;
        } else if (args.minMass) {
          query += ` AND mass:[${args.minMass} TO *]`;
        } else if (args.maxMass) {
          query += ` AND mass:[* TO ${args.maxMass}]`;
        }
      }
  
      if (args.keywords) {
        for (const keyword of args.keywords) {
          query += ` AND keyword:"${keyword}"`;
        }
      }
  
      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 in advanced search: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:623-636 (schema)

  The input schema definition for the 'advanced_search' tool, specifying parameters like query, organism filters, length/mass ranges, keywords, and result size.

  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: [],
  },

• src/index.ts:621-637 (registration)

  Registration of the 'advanced_search' tool in the ListToolsRequestSchema handler's tools array.

    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: [],
    },
  },

• src/index.ts:768-769 (registration)

  Registration of the handler dispatch in the CallToolRequestSchema switch statement.

  case 'advanced_search':
    return this.handleAdvancedSearch(args);

• src/index.ts:157-181 (helper)

  Type guard function for validating input arguments to the 'advanced_search' tool.

  const isValidAdvancedSearchArgs = (
    args: any
  ): args is {
      query?: string;
      organism?: string;
      minLength?: number;
      maxLength?: number;
      minMass?: number;
      maxMass?: number;
      keywords?: string[];
      size?: number
    } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      (args.query === undefined || typeof args.query === 'string') &&
      (args.organism === undefined || typeof args.organism === 'string') &&
      (args.minLength === undefined || (typeof args.minLength === 'number' && args.minLength > 0)) &&
      (args.maxLength === undefined || (typeof args.maxLength === 'number' && args.maxLength > 0)) &&
      (args.minMass === undefined || (typeof args.minMass === 'number' && args.minMass > 0)) &&
      (args.maxMass === undefined || (typeof args.maxMass === 'number' && args.maxMass > 0)) &&
      (args.keywords === undefined || (Array.isArray(args.keywords) && args.keywords.every((k: any) => typeof k === 'string'))) &&
      (args.size === undefined || (typeof args.size === 'number' && args.size > 0 && args.size <= 500))
    );
  };