README.md•7.56 kB
# Medical Calculator MCP Service
[中文版](README_ZH.md) | **English**
Medical Calculator MCP Service Implementation.
## 🚀 Project Overview
This is a Medical Calculator MCP service implementation that has completed **56 medical calculators** covering multiple medical fields including anthropometry, cardiovascular, renal function, hepatic function, laboratory tests, critical care scoring, respiratory system, infection & inflammation, fluid & medication, obstetrics, and oncology.
### 🏥 Calculator Categories
#### Anthropometry and Basic Calculations (5)
- BMI Calculator - Body Mass Index calculation
- Body Surface Area Calculator - BSA calculation
- Ideal Body Weight Calculator - IBW calculation
- Adjusted Body Weight Calculator - ABW calculation
- Target Weight Calculator
#### Cardiovascular System (11)
- Mean Arterial Pressure Calculator
- QTc Interval Calculators (5 formulas)
- CHA2DS2-VASc Stroke Risk Score
- HAS-BLED Bleeding Risk Score
- HEART Score Calculator
- Cardiac Risk Index Calculator
- Framingham Risk Score
- Wells DVT Score
- Caprini Thrombosis Risk Assessment
#### Renal Function (4)
- Creatinine Clearance Calculator (Cockcroft-Gault)
- CKD-EPI GFR Calculator
- MDRD GFR Calculator
- Fractional Excretion of Sodium Calculator
#### Hepatic Function (3)
- Child-Pugh Liver Function Classification
- MELD-Na Score Calculator
- FIB-4 Liver Fibrosis Index
#### Laboratory Tests (12)
- Anion Gap Calculator and related calculators
- Calcium Correction Calculator
- Sodium Correction for Hyperglycemia
- Serum Osmolality Calculator
- LDL Cholesterol Calculator
- HOMA-IR Insulin Resistance Index
- Free Water Deficit Calculator
#### Critical Care and Scoring Systems (8)
- APACHE II Acute Physiology Score
- SOFA Sequential Organ Failure Assessment
- SIRS Systemic Inflammatory Response Syndrome
- Glasgow Coma Score
- Glasgow Bleeding Score
- Charlson Comorbidity Index
#### Respiratory System (4)
- CURB-65 Pneumonia Severity Score
- Pneumonia Severity Index (PSI)
- Wells PE Score
- PERC Pulmonary Embolism Rule-out Criteria
#### Infection and Inflammation (2)
- Centor Streptococcal Pharyngitis Score
- FeverPAIN Pharyngitis Score
#### Fluid and Medication (3)
- Maintenance Fluid Calculator
- Steroid Conversion Calculator
- Morphine Milligram Equivalent Calculator
#### Obstetrics (3)
- Estimated Conception Date Calculator
- Estimated Gestational Age Calculator
- Estimated Due Date Calculator
#### Oncology (1)
- Lung Cancer TNM Staging Calculator
### 📚 Quick Start
1. **Install Dependencies**:
```bash
pip install -r requirements.txt
```
2. **Run Tests**:
```bash
# Run all API tests
python test/api_test_bmi_calculator.py
python test/api_test_pregnancy_calculators.py
python test/api_test_lung_cancer_staging.py
python test/api_test_tools.py
# Run basic tests
python test_bmi.py
```
3. **Start Server**:
```bash
python server.py
```
### 📁 Project Structure
```
medcalcmcp/
├── medcalc/ # Core framework module
│ ├── __init__.py # Module exports
│ ├── models.py # Data models
│ ├── base.py # Base calculator class
│ ├── registry.py # Calculator registration system
│ ├── service.py # Calculator service
│ ├── utils.py # Utilities (unit conversion, etc.)
│ └── exceptions.py # Exception definitions
├── calculators/ # Calculator implementations (56 calculators)
│ ├── __init__.py # Calculator package (manages all calculators)
│ ├── bmi_calculator.py # BMI Calculator
│ ├── bsa_calculator.py # Body Surface Area Calculator
│ ├── creatinine_clearance_calculator.py # Creatinine Clearance Calculator
│ ├── cha2ds2_vasc_calculator.py # CHA2DS2-VASc Score
│ ├── lung_cancer_staging_calculator.py # Lung Cancer TNM Staging Calculator
│ └── ... # Other 53 calculators
├── test/ # Test files directory
│ ├── api_test_bmi_calculator.py # BMI Calculator API tests
│ ├── api_test_pregnancy_calculators.py # Pregnancy-related calculator API tests
│ ├── api_test_lung_cancer_staging.py # Lung cancer staging calculator API tests
│ └── api_test_tools.py # MCP tools dynamic tests
├── server.py # FastMCP server main file
├── api_server.py # MCP API server
├── requirements.txt # Project dependencies
└── README.md # Project documentation
```
### 🛠️ Technical Architecture
The project uses a modular design with the following main components:
- **MCP Server** (`server.py`): Provides MCP protocol interface
- **Core Framework** (`medcalc/`): Data models, base classes, utilities
- **Calculator Engine** (`calculators/`): 56 specific medical calculators
- **Test Suite** (`test/`): API tests and functionality verification
### ✨ Key Features
- ✅ **Complete Medical Calculator Collection**: 56 professional medical calculators
- ✅ **Multi-domain Coverage**: Covers various clinical medical specialties
- ✅ **Smart Unit Conversion**: Supports automatic conversion of various medical units
- ✅ **Detailed Calculation Explanations**: Each result includes detailed medical explanations
- ✅ **Complete Parameter Validation**: Ensures accuracy and safety of input data
- ✅ **MCP Protocol Support**: Standardized interface protocol
- ✅ **Asynchronous Processing**: High-performance asynchronous calculation processing
- ✅ **Complete Test Coverage**: Comprehensive API and functionality testing
### 🚀 Start Server
```bash
# Start FastMCP server (recommended)
python server.py
# Or start MCP API server
python api_server.py
# Server will run at http://127.0.0.1:8010/mcp/
```
### 🔧 Development Guide
#### Creating New Calculators
1. Create a new calculator file in the `calculators/` directory
2. Inherit from the `BaseCalculator` class
3. Implement required methods: `get_info()`, `validate_parameters()`, `calculate()`
4. Register using the `@register_calculator` decorator
5. Add import to `calculators/__init__.py`
#### Running Tests
```bash
# Test specific calculator
python test/api_test_bmi_calculator.py
# Test all calculators (dynamic testing)
python test/api_test_tools.py
# Test pregnancy-related calculators
python test/api_test_pregnancy_calculators.py
# Test lung cancer staging calculator
python test/api_test_lung_cancer_staging.py
```
## 📋 Project Status
- **Current Version**: 0.1.0
- **Number of Calculators**: 56
- **Test Coverage**: 100%
- **Supported Medical Fields**: 11 specialty areas
## 🤝 Contributing
Pull requests and issues are welcome to help improve the project.
## 🙏 Acknowledgments
This project is based on the [MedCalc-Bench](https://github.com/ncbi-nlp/MedCalc-Bench) project. Thanks to the NCBI-NLP team for providing excellent foundational medical calculator implementations. We have converted it into an MCP (Model Context Protocol) service to better integrate with modern AI applications.
**Original Project References:**
- GitHub: https://github.com/ncbi-nlp/MedCalc-Bench
- Paper: MedCalc-Bench: A Large-scale Medical Calculator Benchmark