search_compounds

Instructions

Implementation Reference

• src/index.ts:832-880 (handler)

  The handler function that executes the search_compounds tool. Validates input, queries PubChem API for compound CIDs by various search types, fetches details for top results, and returns formatted JSON response.

  private async handleSearchCompounds(args: any) {
    if (!isValidCompoundSearchArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid compound search arguments');
    }
  
    try {
      const searchType = args.search_type || 'name';
      const maxRecords = args.max_records || 100;
  
      const response = await this.apiClient.get(`/compound/${searchType}/${encodeURIComponent(args.query)}/cids/JSON`, {
        params: {
          MaxRecords: maxRecords,
        },
      });
  
      if (response.data?.IdentifierList?.CID?.length > 0) {
        const cids = response.data.IdentifierList.CID.slice(0, 10);
        const detailsResponse = await this.apiClient.get(`/compound/cid/${cids.join(',')}/property/MolecularFormula,MolecularWeight,CanonicalSMILES,IUPACName/JSON`);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                query: args.query,
                search_type: searchType,
                total_found: response.data.IdentifierList.CID.length,
                details: detailsResponse.data,
              }, null, 2),
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ message: 'No compounds found', query: args.query }, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to search compounds: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/index.ts:373-381 (schema)

  Input schema defining parameters for search_compounds: query (required string), search_type (enum), max_records (number 1-10000).

  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query (compound name, CAS, formula, or identifier)' },
      search_type: { type: 'string', enum: ['name', 'smiles', 'inchi', 'sdf', 'cid', 'formula'], description: 'Type of search to perform (default: name)' },
      max_records: { type: 'number', description: 'Maximum number of results (1-10000, default: 100)', minimum: 1, maximum: 10000 },
    },
    required: ['query'],
  },

• src/index.ts:370-382 (registration)

  Registration of search_compounds tool in the ListTools response, including name, description, and input schema.

  {
    name: 'search_compounds',
    description: 'Search PubChem database for compounds by name, CAS number, formula, or identifier',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query (compound name, CAS, formula, or identifier)' },
        search_type: { type: 'string', enum: ['name', 'smiles', 'inchi', 'sdf', 'cid', 'formula'], description: 'Type of search to perform (default: name)' },
        max_records: { type: 'number', description: 'Maximum number of results (1-10000, default: 100)', minimum: 1, maximum: 10000 },
      },
      required: ['query'],
    },
  },

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

  Dispatcher case in CallToolRequest handler that routes search_compounds calls to the handleSearchCompounds method.

  case 'search_compounds':
    return await this.handleSearchCompounds(args);

• src/index.ts:52-63 (helper)

  Type guard function for validating input arguments to search_compounds handler.

  const isValidCompoundSearchArgs = (
    args: any
  ): args is { query: string; search_type?: string; max_records?: number } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.query === 'string' &&
      args.query.length > 0 &&
      (args.search_type === undefined || ['name', 'smiles', 'inchi', 'sdf', 'cid', 'formula'].includes(args.search_type)) &&
      (args.max_records === undefined || (typeof args.max_records === 'number' && args.max_records > 0 && args.max_records <= 10000))
    );
  };