get_chemical_frequency
Analyze frequency statistics of specific chemicals across the SureChEMBL patent database to assess their 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)Main handler function that fetches chemical information from the SureChEMBL API using the provided chemical_id, extracts global frequency data, categorizes the frequency, calculates a rarity score, 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 definition for the tool, specifying that a 'chemical_id' string is required.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 ListToolsRequestSchema response, defining 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)Switch case in CallToolRequestSchema handler that routes tool calls to the specific handler method.case 'get_chemical_frequency': return await this.handleGetChemicalFrequency(args);
- src/index.ts:1232-1240 (helper)Helper method used by the handler to categorize the chemical's global frequency into descriptive categories.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'; }
- src/index.ts:1242-1247 (helper)Helper method used by the handler to compute a numerical rarity score based on logarithmic scaling of frequency.private calculateRarityScore(frequency: number): number { if (frequency === 0) return 0; if (frequency === 1) return 1.0; // Logarithmic scale for rarity (higher frequency = lower rarity) return Math.max(0, 1 - Math.log10(frequency) / 6); }