SureChEMBL MCP Server

Instructions

Implementation Reference

• src/index.ts:1018-1061 (handler)

  The main handler function that implements the tool logic: validates input, fetches chemical data from SureChEMBL API using chemical ID, extracts global_frequency, computes category and rarity score using helpers, and returns formatted statistics.

  private async handleGetChemicalFrequency(args: any) {
    if (!args || typeof args.chemical_id !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid chemical ID');
    }
  
    try {
      const response = await this.apiClient.get(`/chemical/id/${args.chemical_id}`);
      const chemical = response.data.data?.[0];
  
      if (!chemical) {
        throw new Error('Chemical not found');
      }
  
      const frequencyStats = {
        chemical_id: args.chemical_id,
        name: chemical.name,
        global_frequency: chemical.global_frequency || 0,
        frequency_analysis: {
          total_occurrences: chemical.global_frequency || 0,
          frequency_category: this.categorizeFrequency(chemical.global_frequency || 0),
          rarity_score: this.calculateRarityScore(chemical.global_frequency || 0)
        },
        chemical_info: {
          smiles: chemical.smiles,
          molecular_weight: chemical.mol_weight,
          inchi_key: chemical.inchi_key
        }
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(frequencyStats, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to get chemical frequency: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/index.ts:502-508 (schema)

  Input schema defining the required 'chemical_id' parameter as a string.

  inputSchema: {
    type: 'object',
    properties: {
      chemical_id: { type: 'string', description: 'SureChEMBL chemical ID' },
    },
    required: ['chemical_id'],
  },

• src/index.ts:499-509 (registration)

  Tool registration in the ListTools response, including name, description, and input schema.

  {
    name: 'get_chemical_frequency',
    description: 'Get frequency statistics for chemicals across the patent database',
    inputSchema: {
      type: 'object',
      properties: {
        chemical_id: { type: 'string', description: 'SureChEMBL chemical ID' },
      },
      required: ['chemical_id'],
    },
  },

• src/index.ts:572-573 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement, routing calls to the handler.

  case 'get_chemical_frequency':
    return await this.handleGetChemicalFrequency(args);

• src/index.ts:1232-1240 (helper)

  Helper function to categorize the global frequency into descriptive buckets, used in the handler.

  private categorizeFrequency(frequency: number): string {
    if (frequency === 0) return 'Not found';
    if (frequency === 1) return 'Unique';
    if (frequency <= 10) return 'Very rare';
    if (frequency <= 100) return 'Rare';
    if (frequency <= 1000) return 'Uncommon';
    if (frequency <= 10000) return 'Common';
    return 'Very common';
  }