ChEMBL MCP Server

Instructions

Implementation Reference

• src/index.ts:1913-1961 (handler)

  The main handler function for the 'advanced_search' tool. It validates input arguments using isValidPropertyFilterArgs, constructs a filter query for molecular properties (MW, LogP, HBD, HBA), queries the ChEMBL molecule endpoint, and returns the filtered results.

  private async handleAdvancedSearch(args: any) {
    if (!isValidPropertyFilterArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid advanced search arguments');
    }
  
    try {
      // Build filter query for ChEMBL API
      const filters: string[] = [];
  
      if (args.min_mw !== undefined) {
        filters.push(`molecule_properties__mw_freebase__gte=${args.min_mw}`);
      }
      if (args.max_mw !== undefined) {
        filters.push(`molecule_properties__mw_freebase__lte=${args.max_mw}`);
      }
      if (args.min_logp !== undefined) {
        filters.push(`molecule_properties__alogp__gte=${args.min_logp}`);
      }
      if (args.max_logp !== undefined) {
        filters.push(`molecule_properties__alogp__lte=${args.max_logp}`);
      }
      if (args.max_hbd !== undefined) {
        filters.push(`molecule_properties__hbd__lte=${args.max_hbd}`);
      }
      if (args.max_hba !== undefined) {
        filters.push(`molecule_properties__hba__lte=${args.max_hba}`);
      }
  
      const filterString = filters.join('&');
      const response = await this.apiClient.get(`/molecule.json?${filterString}&limit=${args.limit || 25}`);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              filters: args,
              results: response.data,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to perform advanced search: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/index.ts:720-735 (registration)

  Registration of the 'advanced_search' tool in the ListToolsRequestSchema handler, including name, description, and input schema definition.

    name: 'advanced_search',
    description: 'Complex queries with multiple chemical and biological filters',
    inputSchema: {
      type: 'object',
      properties: {
        min_mw: { type: 'number', description: 'Minimum molecular weight (Da)', minimum: 0 },
        max_mw: { type: 'number', description: 'Maximum molecular weight (Da)', minimum: 0 },
        min_logp: { type: 'number', description: 'Minimum LogP value' },
        max_logp: { type: 'number', description: 'Maximum LogP value' },
        max_hbd: { type: 'number', description: 'Maximum hydrogen bond donors', minimum: 0 },
        max_hba: { type: 'number', description: 'Maximum hydrogen bond acceptors', minimum: 0 },
        limit: { type: 'number', description: 'Number of results to return (1-1000, default: 25)', minimum: 1, maximum: 1000 },
      },
      required: [],
    },
  },

• src/index.ts:802-803 (registration)

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

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

• src/index.ts:141-163 (schema)

  Type guard and validation function for 'advanced_search' input parameters, ensuring proper types and ranges for molecular property filters.

  const isValidPropertyFilterArgs = (
    args: any
  ): args is {
      min_mw?: number;
      max_mw?: number;
      min_logp?: number;
      max_logp?: number;
      max_hbd?: number;
      max_hba?: number;
      limit?: number
    } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      (args.min_mw === undefined || (typeof args.min_mw === 'number' && args.min_mw >= 0)) &&
      (args.max_mw === undefined || (typeof args.max_mw === 'number' && args.max_mw >= 0)) &&
      (args.min_logp === undefined || typeof args.min_logp === 'number') &&
      (args.max_logp === undefined || typeof args.max_logp === 'number') &&
      (args.max_hbd === undefined || (typeof args.max_hbd === 'number' && args.max_hbd >= 0)) &&
      (args.max_hba === undefined || (typeof args.max_hba === 'number' && args.max_hba >= 0)) &&
      (args.limit === undefined || (typeof args.limit === 'number' && args.limit > 0 && args.limit <= 1000))
    );
  };