get_chemical_frequency
Retrieve patent frequency statistics for a chemical using its SureChEMBL ID to analyze its prevalence in patent documents.
Instructions
Get frequency statistics for chemicals across the patent database
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chemical_id | Yes | SureChEMBL chemical ID |
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'; }