lookup_meddra
Look up MedDRA Preferred Terms to identify System Organ Class, hierarchy level, and synonyms. Essential for adverse event coding and pharmacovigilance.
Instructions
Look up a MedDRA Preferred Term (PT), identify its System Organ Class (SOC), hierarchy level, and related terms. Critical for adverse event coding, pharmacovigilance, and regulatory submissions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | MedDRA term to look up (e.g. 'nausea', 'qt prolongation', 'suicidal ideation') | |
| include_synonyms | No | Include US/UK spelling variants and common synonyms |
Implementation Reference
- index.js:169-254 (registration)The tool 'lookup_meddra' is registered using server.tool() from the MCP SDK at line 169. It accepts 'term' (string) and 'include_synonyms' (boolean, default true) and returns formatted MedDRA classification info.
server.tool( "lookup_meddra", "Look up a MedDRA Preferred Term (PT), identify its System Organ Class (SOC), hierarchy level, and related terms. Critical for adverse event coding, pharmacovigilance, and regulatory submissions.", { term: z .string() .describe("MedDRA term to look up (e.g. 'nausea', 'qt prolongation', 'suicidal ideation')"), include_synonyms: z .boolean() .default(true) .describe("Include US/UK spelling variants and common synonyms"), }, async ({ term, include_synonyms }) => { const normalized = term.toLowerCase().trim(); // Direct match let soc = MEDDRA_PT_SOC[normalized]; // Partial match fallback if (!soc) { const partialKey = Object.keys(MEDDRA_PT_SOC).find( k => k.includes(normalized) || normalized.includes(k) ); if (partialKey) soc = MEDDRA_PT_SOC[partialKey]; } // MedDRA hierarchy levels explanation const hierarchy = [ "**SOC** (System Organ Class) — highest level, 27 categories", "**HLGT** (High Level Group Term) — groups related HLTs", "**HLT** (High Level Term) — groups related PTs", "**PT** (Preferred Term) — single medical concept, used in labels & FAERS", "**LLT** (Lowest Level Term) — synonyms/variants that map to a PT", ]; // Common synonyms for known terms const synonymMap = { "nausea": ["nausea", "feeling sick", "queasy"], "diarrhoea": ["diarrhoea", "diarrhea", "loose stools", "frequent bowel movements"], "dizziness": ["dizziness", "vertigo", "lightheadedness", "giddiness"], "dyspnoea": ["dyspnoea", "dyspnea", "shortness of breath", "breathlessness", "SOB"], "oedema": ["oedema", "edema", "swelling", "fluid retention"], "anaemia": ["anaemia", "anemia", "low hemoglobin", "low haemoglobin"], "pyrexia": ["pyrexia", "fever", "febrile", "high temperature", "hyperthermia"], "pruritus": ["pruritus", "itching", "itch", "itchiness"], "somnolence": ["somnolence", "drowsiness", "sleepiness", "sedation"], "alopecia": ["alopecia", "hair loss", "hair thinning", "baldness"], }; const synonyms = synonymMap[normalized] || []; let text = `## MedDRA Term: "${term}"\n\n`; if (soc) { text += `### Classification\n`; text += `- **Preferred Term (PT):** ${term.charAt(0).toUpperCase() + term.slice(1)}\n`; text += `- **System Organ Class (SOC):** ${soc}\n`; text += `- **Hierarchy Level:** PT (Preferred Term)\n\n`; } else { text += `> ⚠️ Term not found in curated PT index. May be an LLT, HLGT, or HLT — verify in official MedDRA browser.\n\n`; } text += `### MedDRA Hierarchy (5 Levels)\n`; text += hierarchy.map(h => `- ${h}`).join("\n") + "\n\n"; if (include_synonyms && synonyms.length > 0) { text += `### LLT Synonyms / Coding Variants\n`; text += `These LLTs map to the same PT:\n`; text += synonyms.map(s => `- ${s}`).join("\n") + "\n\n"; } text += `### Regulatory Context\n`; text += `- PTs are used in **FDA FAERS** adverse event reporting\n`; text += `- PTs appear in **clinical trial** adverse event tables\n`; text += `- Drug labels use PTs in **Adverse Reactions** section (≥1% frequency threshold)\n`; text += `- **ICH E2B** submissions use MedDRA PTs for individual case safety reports (ICSRs)\n\n`; text += `### All 27 SOCs (for context)\n`; text += Object.values(MEDDRA_SOC).map(s => `- ${s}`).join("\n") + "\n\n"; text += `_Source: MedDRA hierarchy documentation (v26.0). Full term browser at meddra.org (subscription required)._\n`; text += `_⚠️ Always verify PT assignments in official MedDRA browser before regulatory submission._`; return { content: [{ type: "text", text }] }; } ); - index.js:181-253 (handler)The handler function normalizes the input term, looks it up in MEDDRA_PT_SOC (with partial match fallback), builds the hierarchy info, includes LLT synonyms if requested, and returns formatted text with SOC classification and regulatory context.
async ({ term, include_synonyms }) => { const normalized = term.toLowerCase().trim(); // Direct match let soc = MEDDRA_PT_SOC[normalized]; // Partial match fallback if (!soc) { const partialKey = Object.keys(MEDDRA_PT_SOC).find( k => k.includes(normalized) || normalized.includes(k) ); if (partialKey) soc = MEDDRA_PT_SOC[partialKey]; } // MedDRA hierarchy levels explanation const hierarchy = [ "**SOC** (System Organ Class) — highest level, 27 categories", "**HLGT** (High Level Group Term) — groups related HLTs", "**HLT** (High Level Term) — groups related PTs", "**PT** (Preferred Term) — single medical concept, used in labels & FAERS", "**LLT** (Lowest Level Term) — synonyms/variants that map to a PT", ]; // Common synonyms for known terms const synonymMap = { "nausea": ["nausea", "feeling sick", "queasy"], "diarrhoea": ["diarrhoea", "diarrhea", "loose stools", "frequent bowel movements"], "dizziness": ["dizziness", "vertigo", "lightheadedness", "giddiness"], "dyspnoea": ["dyspnoea", "dyspnea", "shortness of breath", "breathlessness", "SOB"], "oedema": ["oedema", "edema", "swelling", "fluid retention"], "anaemia": ["anaemia", "anemia", "low hemoglobin", "low haemoglobin"], "pyrexia": ["pyrexia", "fever", "febrile", "high temperature", "hyperthermia"], "pruritus": ["pruritus", "itching", "itch", "itchiness"], "somnolence": ["somnolence", "drowsiness", "sleepiness", "sedation"], "alopecia": ["alopecia", "hair loss", "hair thinning", "baldness"], }; const synonyms = synonymMap[normalized] || []; let text = `## MedDRA Term: "${term}"\n\n`; if (soc) { text += `### Classification\n`; text += `- **Preferred Term (PT):** ${term.charAt(0).toUpperCase() + term.slice(1)}\n`; text += `- **System Organ Class (SOC):** ${soc}\n`; text += `- **Hierarchy Level:** PT (Preferred Term)\n\n`; } else { text += `> ⚠️ Term not found in curated PT index. May be an LLT, HLGT, or HLT — verify in official MedDRA browser.\n\n`; } text += `### MedDRA Hierarchy (5 Levels)\n`; text += hierarchy.map(h => `- ${h}`).join("\n") + "\n\n"; if (include_synonyms && synonyms.length > 0) { text += `### LLT Synonyms / Coding Variants\n`; text += `These LLTs map to the same PT:\n`; text += synonyms.map(s => `- ${s}`).join("\n") + "\n\n"; } text += `### Regulatory Context\n`; text += `- PTs are used in **FDA FAERS** adverse event reporting\n`; text += `- PTs appear in **clinical trial** adverse event tables\n`; text += `- Drug labels use PTs in **Adverse Reactions** section (≥1% frequency threshold)\n`; text += `- **ICH E2B** submissions use MedDRA PTs for individual case safety reports (ICSRs)\n\n`; text += `### All 27 SOCs (for context)\n`; text += Object.values(MEDDRA_SOC).map(s => `- ${s}`).join("\n") + "\n\n"; text += `_Source: MedDRA hierarchy documentation (v26.0). Full term browser at meddra.org (subscription required)._\n`; text += `_⚠️ Always verify PT assignments in official MedDRA browser before regulatory submission._`; return { content: [{ type: "text", text }] }; } - index.js:69-116 (helper)Curated dataset mapping MedDRA Preferred Terms (PTs) to their System Organ Class (SOC) for fast lookup. Also includes a synonymMap (lines 205-216) with US/UK spelling variants.
// Common MedDRA PT → SOC mappings for fast lookup (curated subset) const MEDDRA_PT_SOC = { "nausea": "Gastrointestinal disorders", "vomiting": "Gastrointestinal disorders", "diarrhoea": "Gastrointestinal disorders", "diarrhea": "Gastrointestinal disorders", "constipation": "Gastrointestinal disorders", "abdominal pain": "Gastrointestinal disorders", "headache": "Nervous system disorders", "dizziness": "Nervous system disorders", "tremor": "Nervous system disorders", "somnolence": "Nervous system disorders", "seizure": "Nervous system disorders", "insomnia": "Psychiatric disorders", "depression": "Psychiatric disorders", "anxiety": "Psychiatric disorders", "agitation": "Psychiatric disorders", "hallucination": "Psychiatric disorders", "suicidal ideation": "Psychiatric disorders", "rash": "Skin and subcutaneous tissue disorders", "pruritus": "Skin and subcutaneous tissue disorders", "alopecia": "Skin and subcutaneous tissue disorders", "fatigue": "General disorders and administration site conditions", "pyrexia": "General disorders and administration site conditions", "oedema": "General disorders and administration site conditions", "edema": "General disorders and administration site conditions", "dyspnoea": "Respiratory, thoracic and mediastinal disorders", "dyspnea": "Respiratory, thoracic and mediastinal disorders", "cough": "Respiratory, thoracic and mediastinal disorders", "pneumonia": "Infections and infestations", "neutropenia": "Blood and lymphatic system disorders", "thrombocytopenia": "Blood and lymphatic system disorders", "anaemia": "Blood and lymphatic system disorders", "anemia": "Blood and lymphatic system disorders", "hypertension": "Vascular disorders", "hypotension": "Vascular disorders", "tachycardia": "Cardiac disorders", "qt prolongation": "Cardiac disorders", "myocardial infarction": "Cardiac disorders", "alanine aminotransferase increased": "Investigations", "aspartate aminotransferase increased": "Investigations", "weight decreased": "Investigations", "weight increased": "Investigations", "creatinine increased": "Investigations", "renal failure": "Renal and urinary disorders", "hepatotoxicity": "Hepatobiliary disorders", "liver injury": "Hepatobiliary disorders", }; - index.js:40-67 (helper)All 27 MedDRA SOC (System Organ Class) codes and names, used for providing SOC context in the output.
const MEDDRA_SOC = { "10001316": "Blood and lymphatic system disorders", "10005329": "Cardiac disorders", "10007541": "Congenital, familial and genetic disorders", "10010331": "Ear and labyrinth disorders", "10014698": "Endocrine disorders", "10015919": "Eye disorders", "10017947": "Gastrointestinal disorders", "10018065": "General disorders and administration site conditions", "10019805": "Hepatobiliary disorders", "10021428": "Immune system disorders", "10021881": "Infections and infestations", "10022117": "Injury, poisoning and procedural complications", "10022891": "Investigations", "10027433": "Metabolism and nutrition disorders", "10028395": "Musculoskeletal and connective tissue disorders", "10029205": "Neoplasms benign, malignant and unspecified", "10029999": "Nervous system disorders", "10033371": "Pregnancy, puerperium and perinatal conditions", "10036585": "Psychiatric disorders", "10038359": "Renal and urinary disorders", "10038604": "Reproductive system and breast disorders", "10038738": "Respiratory, thoracic and mediastinal disorders", "10040785": "Skin and subcutaneous tissue disorders", "10041244": "Social circumstances", "10042613": "Surgical and medical procedures", "10047065": "Vascular disorders", };