atc_classify

Instructions

Implementation Reference

• src/tools/atc.ts:87-130 (handler)

  The main handler function for the atc_classify tool. Parses input via ATCClassifyParamsSchema, calls getRxNormClient().getATCByDrugName(params.drug_name) to query the NLM RxClass API, and formats the results as a markdown table with structured content.

  async function handleATCClassify(args: Record<string, unknown>): Promise<CallToolResult> {
    try {
      const params = ATCClassifyParamsSchema.parse(args);
      const client = getRxNormClient();
      const matches = await client.getATCByDrugName(params.drug_name);
  
      const structured: ATCClassifyOutput = {
        drug_name: params.drug_name,
        matches,
      };
  
      if (matches.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No ATC classification found for "${params.drug_name}". The drug may be unknown to RxNorm or have no ATC mapping.`,
            },
          ],
          structuredContent: structured,
        };
      }
  
      const lines: string[] = [];
      lines.push(`# ATC classification for "${params.drug_name}"`);
      lines.push('');
      lines.push(`Found ${matches.length} ATC code${matches.length === 1 ? '' : 's'}:`);
      lines.push('');
      lines.push('| ATC code | Class name | Drug (RxNorm) | TTY |');
      lines.push('|----------|------------|---------------|-----|');
      for (const m of matches) {
        lines.push(
          `| ${m.atc_code} | ${m.atc_name} | ${m.drug_name} | ${m.tty} |`,
        );
      }
  
      return {
        content: [{ type: 'text', text: lines.join('\n') }],
        structuredContent: structured,
      };
    } catch (error) {
      return handleToolError(error);
    }
  }

• src/types/index.ts:639-644 (schema)

  Input schema for atc_classify: defines the drug_name parameter (string, min length 1).

  export const ATCClassifyParamsSchema = z.object({
    drug_name: z
      .string()
      .min(1)
      .describe('Drug name to classify (brand or generic, e.g., "metformin")'),
  });

• src/types/index.ts:668-680 (schema)

  Output schema for atc_classify: specifies the structure including drug_name and matches array (each with rxcui, drug_name, tty, atc_code, atc_name, atc_level_type).

  export const ATCClassifyOutputSchema = z.object({
    drug_name: z.string(),
    matches: z.array(
      z.object({
        rxcui: z.string(),
        drug_name: z.string(),
        tty: z.string(),
        atc_code: z.string(),
        atc_name: z.string(),
        atc_level_type: z.string(),
      }),
    ),
  });

• src/tools/atc.ts:220-220 (registration)

  Registration of the atc_classify tool in the toolRegistry with its handler function handleATCClassify.

  toolRegistry.register(atcClassifyTool, handleATCClassify);

• src/clients/rxnorm-client.ts:394-418 (helper)

  The RxNormClient.getATCByDrugName method that actually calls the RxClass API endpoint /rxclass/class/byDrugName.json with the drug name and 'ATC' as the source, then maps the response to RxNormATCMatch objects.

  async getATCByDrugName(drugName: string): Promise<RxNormATCMatch[]> {
    const cacheKey = `atc:bydrug:${drugName.toLowerCase()}`;
  
    return cache.getOrSet(
      CACHE_PREFIX.RXNORM,
      cacheKey,
      async () => {
        const response = await this.request<RxClassResponse>(
          '/rxclass/class/byDrugName.json',
          { drugName, relaSource: 'ATC' },
        );
  
        const list = response.rxclassDrugInfoList?.rxclassDrugInfo ?? [];
        return list.map((info) => ({
          rxcui: info.minConcept?.rxcui ?? '',
          drug_name: info.minConcept?.name ?? '',
          tty: info.minConcept?.tty ?? '',
          atc_code: info.rxclassMinConceptItem.classId,
          atc_name: info.rxclassMinConceptItem.className,
          atc_level_type: info.rxclassMinConceptItem.classType,
        }));
      },
      DEFAULT_TTL.LOOKUP,
    );
  }