Medical Calculator MCP Server 🏥

A DDD-architected medical calculator service providing clinical scoring tools for AI Agent integration via MCP (Model Context Protocol).

繁體中文版 (Traditional Chinese)

---

📖 Table of Contents

• Features
• Why This Project?
• Research Framework
• Architecture
• Quick Start
• OpenClaw Compatibility
• OpenClaw Registry Guide
• Deployment Modes
• Agent Integration
• Docker Deployment
• HTTPS Deployment
• REST API
• Security
• Tool Discovery
• Available Tools
  • Quick Navigation
  • Anesthesiology
  • Critical Care
  • Pediatrics
  • Nephrology
  • Pulmonology
  • Cardiology
  • Hematology
  • Emergency Medicine
  • Hepatology
  • Acid-Base / Metabolic
  • Discovery Tools
  • Prompts
• Usage Examples
• References
• Development
• Deployment Guide
• Clinical Guidelines Review
• Roadmap

---

🎯 Features

• 🔌 MCP Native Integration: Built with FastMCP SDK for seamless AI agent integration
• 🔍 Intelligent Tool Discovery: Two-level key system + Tool Relation Graph (Hypergraph) for smart tool selection
• 🛡️ Smart Parameter Matching: Alias support, fuzzy matching, and typo tolerance
• ⚠️ Boundary Validation: Literature-backed clinical range checking with automatic warnings
• 🏗️ Clean DDD Architecture: Onion architecture with clear separation of concerns
• 📚 Evidence-Based: All 121 calculators cite peer-reviewed research (100% coverage, Vancouver style)
• 🔒 Type Safe: Full Python type hints with dataclass entities
• 🌐 Bilingual: Chinese/English documentation and tool descriptions

---

🤔 Why This Project?

The Problem

When AI agents (like Claude, GPT) need to perform medical calculations, they face challenges:

1. Hallucination Risk: LLMs may generate incorrect formulas or values
2. Version Confusion: Multiple versions of same calculator (e.g., MELD vs MELD-Na vs MELD 3.0)
3. No Discovery Mechanism: How does an agent know which tool to use for "cardiac risk assessment"?

The Solution

This project provides:

| Feature | Description | |---------|-------------| | Validated Calculators | Peer-reviewed, tested formulas | | Tool Discovery | AI can search by specialty, condition, or clinical question | | MCP Protocol | Standard protocol for AI-tool communication | | Paper References | Every calculator cites original research |

🧪 Development Methodology

We employ a human-in-the-loop, AI-augmented workflow to ensure clinical accuracy:

1. Domain Specification: Human experts define the target medical specialty or clinical domain.
2. AI-Driven Search: AI agents perform comprehensive searches for the latest clinical guidelines and consensus.
3. Guideline Extraction: Systematically identify recommended scoring systems and calculations mentioned in those guidelines.
4. Source Validation: Trace back to original peer-reviewed primary papers to verify exact formulas and coefficients.
5. Implementation: Develop validated calculation tools with precise parameters and evidence-based interpretations.

---

🔬 Research Framework

This project implements a Neuro-Symbolic Framework for reliable medical calculation, combining LLM understanding with validated symbolic computation.

Academic Positioning

| Challenge | Traditional LLM | Our Solution | | --------- | --------------- | ------------ | | Calculation Accuracy | ~50% (MedCalc-Bench) | >95% via validated formulas | | Parameter Extraction | Vocabulary mismatch | ParamMatcher (60+ aliases) | | Safety Guardrails | No clinical constraints | BoundaryValidator (PMID-backed) | | Tool Discovery | Keyword/RAG only | Two-Level Key + Hypergraph |

Three-Module Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                     NEURO-SYMBOLIC MEDICAL REASONING                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌───────────────────┐   ┌───────────────────┐   ┌───────────────────┐     │
│  │  Discovery Engine │ → │ Reasoning Interface│ → │    Safety Layer   │     │
│  │  (Tool Selection) │   │  (Param Matching)  │   │  (Validation)     │     │
│  │                   │   │                    │   │                   │     │
│  │  • High/Low Keys  │   │  • Alias Matching  │   │  • Range Check    │     │
│  │  • Hypergraph     │   │  • Fuzzy Match     │   │  • PMID Citation  │     │
│  │  • Context-Aware  │   │  • Multi-lingual   │   │  • Error Messages │     │
│  └───────────────────┘   └───────────────────┘   └───────────────────┘     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Core Contributions

1. Semantic Parameter Mapping (ParamMatcher): Resolves vocabulary mismatch between clinical text and calculator parameters through alias tables, fuzzy matching, and suffix normalization.

2. Literature-Based Guardrails (BoundaryValidator): Validates input values against clinically impossible ranges derived from peer-reviewed literature (17+ parameters with PMID citations).

3. Context-Aware Tool Discovery: Two-level key system + Clinical Knowledge Graph for intelligent tool recommendation based on clinical context.

🏆 Levels of Academic Value

| Level | Contribution | Scholarly Focus | | ----- | ------------ | --------------- | | L1 | Validated Symbolic Engine | Extends LLM with deterministic precision | | L2 | Hierarchical Tool Discovery | Solves RAG precision in high-stakes domains | | L3 | Robust Semantic Extraction | Resolves the "Vocabulary Mismatch" problem | | L4 | Knowledge-Gated Safety Layer | Unique: Literature-derived constraint verification | | L5 | Clinical Hypergraph Agent | Cross-specialty workflow reasoning |

📄 For detailed research roadmap and benchmark strategy, see ROADMAP.md

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    infrastructure/mcp/                       │
│                (MCP Server, Handlers, Resources)             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  MedicalCalculatorServer                             │    │
│  │  ├── handlers/DiscoveryHandler (discover, list...)   │    │
│  │  ├── handlers/CalculatorHandler (calculate_*)        │    │
│  │  └── resources/CalculatorResourceHandler             │    │
│  └─────────────────────────────────────────────────────┘    │
└──────────────────────────┬──────────────────────────────────┘
                           │ uses
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     application/                             │
│               (Use Cases, DTOs, Validation)                  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  DiscoveryUseCase, CalculateUseCase                  │    │
│  │  DiscoveryRequest/Response, CalculateRequest/Response│    │
│  └─────────────────────────────────────────────────────┘    │
└──────────────────────────┬──────────────────────────────────┘
                           │ depends on
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       domain/                                │
│            (Entities, Services, Value Objects)               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  BaseCalculator, ToolMetadata, ScoreResult          │    │
│  │  LowLevelKey, HighLevelKey, ToolRegistry            │    │
│  └─────────────────────────────────────────────────────┘    │
│                    【Core, Zero Dependencies】                │
└─────────────────────────────────────────────────────────────┘

Key Design Decisions

| Decision | Rationale | |----------|-----------| | DDD Onion | Domain logic isolated from infrastructure | | FastMCP | Native Python MCP SDK, simple decorator-b