Medical Calc MCP

医疗计算器MCP服务器🏥

DDD架构的医疗计算器服务，通过MCP（模型上下文协议）为AI Agent集成提供临床评分工具。

繁体中文版（Traditional Chinese）

         

______________________________________________________________________

📖 目录

• 特性
• 为什么是这个项目？
• 研究框架
• 建筑
• 快速开始
• OpenClaw兼容性
• OpenClaw注册指南
• 部署模式
• 代理集成
• HTTPS部署
• REST API
• 安全
• 工具发现
• 可用工具

- 快速导航 - 麻醉学 - 重症监护 - 儿科学 - 肾脏病学 - 呼吸病学 - 心脏病学 - 血液学 - 急诊医学 - 肝脏病学 - 酸碱/代谢 - 发现工具 - 提示

• 用法示例
• 基准指南
• 参考文献
• 发展
• 部署指南
• 临床指南审查
• 路线图

______________________________________________________________________

🎯 特性

• 🔌 MCP本地集成：内置FastMCP SDK，实现无缝AI代理集成
• 🔍 智能工具发现：两级按键系统+刀具关系图（Hypergraph），用于智能刀具选择
• 🛡️ 智能参数匹配：别名支持、模糊匹配和拼写错误容忍度
• ⚠️ 边界验证：文献支持的临床范围检查，带有自动警告
• 🏗️ 干净的DDD架构：洋葱架构，关注点明确分离
• 📚 基于证据的：所有152个计算器都引用了同行评审的研究（100%覆盖，温哥华风格）
• 🔒 类型安全：带有数据类实体的完整Python类型提示
• 🌐 双语：中英文文档和工具说明

______________________________________________________________________

🤔 为什么是这个项目？

问题

当AI代理（如Claude、GPT）需要执行医疗计算时，他们面临着挑战：

1. 幻觉风险：LLM可能生成不正确的公式或值
2. 版本混淆：同一计算器的多个版本（例如，MELD vs MELD Na vs MELD 3.0）
3. 无发现机制：代理人如何知道使用哪种工具进行“心脏风险评估”？

解决方案

该项目提供：

🧪 开发方法学

我们采用人工参与、人工智能增强的工作流程来确保临床准确性：

1. 领域规范：人类专家定义目标医学专业或临床领域。
2. 人工智能驱动搜索：AI代理对最新的临床指南和共识进行全面搜索。
3. 指南提取：系统地确定这些准则中提到的推荐评分系统和计算方法。
4. 源验证：追溯到原始同行评审的主要论文，以验证确切的公式和系数。
5. 实施开发具有精确参数和循证解释的经过验证的计算工具。

______________________________________________________________________

🔬 研究框架

该项目实现了 神经符号框架 为了获得可靠的医学计算，将LLM理解与经过验证的符号计算相结合。

学术定位

战略下一步

• 代理临床决策支持差距和突破计划
• Agent决策支持端到端基准测试
• 基准使用指南

三模块架构

┌─────────────────────────────────────────────────────────────────────────────┐
│                     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 │     │
│  └───────────────────┘   └───────────────────┘   └───────────────────┘     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

核心贡献

1. 语义参数映射 （ParamMatcher）：通过别名表、模糊匹配和后缀规范化解决临床文本和计算器参数之间的词汇不匹配问题。

1. 基于文献的护栏 （BoundaryValidator）：根据同行评审文献中得出的临床不可能范围（17个以上参数被PMID引用）验证输入值。

1. 上下文感知工具发现：两级密钥系统+临床知识图谱，用于基于临床背景的智能工具推荐。

🏆 学术价值水平

📄 有关详细的研究路线图和基准策略，请参阅 ROADMAP.md

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────────────────────────┐
│                    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】                │
└─────────────────────────────────────────────────────────────┘

关键设计决策

验证架构

┌─────────────────────────────────────────────────────────────┐
│  Layer 1: MCP (Infrastructure)                               │
│  └── Pydantic + JSON Schema: Type validation                │
│      (Automatic from Annotated[type, Field(description)])   │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Application (Use Case)                             │
│  ├── ParamMatcher: Intelligent parameter matching           │
│  │   (Alias, fuzzy, suffix matching with typo tolerance)    │
│  └── BoundaryValidator: Clinical range validation           │
│      (Literature-backed warnings for extreme values)        │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: Domain (Calculator)                                │
│  └── ParameterValidator: Medical logic validation           │
│      (22 parameter specs with valid ranges)                 │
└─────────────────────────────────────────────────────────────┘

域验证模块 (src/domain/validation/):

• rules.py：基类（RangeRule、EnumRule、TypeRule、CustomRule）
• parameter_specs.py：22个医疗参数规格
• validators.py：参数验证器 validate_params() 功能
• boundaries.py：BoundarySpec与文献支持的临床范围

参数匹配 (src/domain/services/param_matcher.py):

• 别名匹配： cr → serum_creatinine, hr → heart_rate
• 模糊匹配： creatnine → creatinine （拼写错误容忍度）
• 删除后缀： creatinine_mg_dl → creatinine

______________________________________________________________________

🚀 快速开始

先决条件

• Python 3.11+（MCP SDK要求）
• 紫外线 包管理器（推荐）- 安装uv

安装

# Clone repository
git clone https://github.com/u9401066/medical-calc-mcp.git
cd medical-calc-mcp

# Install uv (if not already installed)
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Sync dependencies (creates .venv automatically)
uv sync

运行MCP服务器

# Start MCP server (stdio transport)
uv run python -m src.main

# Or with MCP development inspector
uv run mcp dev src/main.py

OpenClaw兼容性

这个存储库是有意构建的，因此OpenClaw风格的爬虫、MCP注册表和自主编码代理可以在最少的猜测下发现、安装和安全操作它。

发现关键字

• MCP服务器
• 医用计算器MCP
• FastMCP
• stdio MCP服务器
• SSE MCP服务器
• 循证医学评分
• AI代理临床工具
• 模式优先计算
• 安全重试指南

为什么这次回购对OpenClaw友好

• 清晰的规范工作流程： discover(...) -> get_tool_schema(tool_id) -> calculate(tool_id, params)
• 从这里开始，多个MCP表面都有指导：

- 提示： tool_usage_playbook() - 资源： guide://tool-usage-playbook - 指标： calculator://list

• 智能解析器处理跨工具和资源的模糊工具ID和专业名称
• 失败的调用返回重试友好字段，例如 guidance, suggestions, resolved_value，以及 param_template
• 支持本地 stdio 并主持 sse / http 运输

最小安装

git clone https://github.com/u9401066/medical-calc-mcp.git
cd medical-calc-mcp
uv sync
uv run python -m src.main

OpenClaw推荐的第一步行动

1. Read resource: guide://tool-usage-playbook
2. Read resource: calculator://list
3. Call tool: discover(by="keyword", value="clinical problem")
4. Call tool: get_tool_schema("tool_id")
5. Call tool: calculate("tool_id", {...})

MCP客户端配置示例

{
  "mcpServers": {
    "medical-calc": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.main"],
      "cwd": "/path/to/medical-calc-mcp"
    }
  }
}

远程爬网程序/代理的托管模式

uv run python -m src.main --mode sse
# or
uv run python -m src.main --mode http

如果您的OpenClaw部署根据安装清晰度和MCP准备情况对存储库进行排名，则此存储库现在公开了一个直接安装路径、显式传输模式和一个旨在减少代理滥用的模式优先SOP。

配置VS代码副本⭐ 新

该项目包括 .vscode/mcp.json 用于无缝VS Code Copilot集成的配置文件。

自动设置：

只需在VS Code中打开此项目，MCP服务器将被自动发现！

// .vscode/mcp.json (included in repo)
{
  "servers": {
    "medical-calc-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "src.main"]
    }
  }
}

在VS代码中启用MCP：

1. 打开VS代码设置（Ctrl+，）
2. 搜索 chat.mcp
3. 启用 Chat: Mcp Discovery Enabled
4. 重新启动VS代码

用途：

在GitHub Copilot聊天中，使用 @medical-calc-mcp 要访问计算器：

@medical-calc-mcp Calculate SOFA score with PaO2/FiO2=200, platelets=80...

使用Claude Desktop进行配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "medical-calc": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.main"],
      "cwd": "/path/to/medical-calc-mcp"
    }
  }
}

______________________________________________________________________

🚀 部署模式⭐ 新

此项目支持不同用例的多种部署模式：

┌─────────────────────────────────────────────────────────────────────┐
│                        Deployment Options                            │
├─────────────────┬─────────────────┬─────────────────────────────────┤
│   REST API      │   MCP SSE       │   MCP stdio                     │
│   (Port 8080)   │   (Port 8000)   │   (Local)                       │
├─────────────────┼─────────────────┼─────────────────────────────────┤
│ ✅ Any HTTP     │ ✅ MCP Clients  │ ✅ Claude Desktop               │
│    client       │    (remote)     │ ✅ VS Code Copilot              │
│ ✅ Custom Agent │ ✅ Docker/Cloud │ ✅ MCP Inspector                │
│ ✅ Web Apps     │                 │                                 │
│ ✅ Python/JS    │                 │                                 │
└─────────────────┴─────────────────┴─────────────────────────────────┘

📘 有关详细的部署说明，请参阅 文档/部署.md

______________________________________________________________________

🤖 代理集成⭐ 新

Python代理示例

import requests

class MedicalCalculatorClient:
    def __init__(self, base_url: str = "http://localhost:8080"):
        self.api_url = f"{base_url}/api/v1"

    def search(self, query: str) -> list:
        r = requests.get(f"{self.api_url}/search", params={"q": query})
        return r.json()

    def calculate(self, tool_id: str, params: dict) -> dict:
        r = requests.post(f"{self.api_url}/calculate/{tool_id}", json={"params": params})
        return r.json()

# Usage
client = MedicalCalculatorClient()

# Search for sepsis calculators
results = client.search("sepsis")

# Calculate SOFA score
result = client.calculate("sofa", {
    "pao2_fio2_ratio": 200,
    "platelets": 100,
    "bilirubin": 2.0,
    "gcs_score": 13,
    "creatinine": 2.5
})
print(f"SOFA Score: {result['result']['value']}")

LangChain/OpenAI函数调用

看 文档/部署.md LangChain和OpenAI集成示例。

API快速测试

# Start API server
uv run python src/main.py --mode api --port 8080

# Test endpoints
curl http://localhost:8080/health
curl "http://localhost:8080/api/v1/search?q=sepsis"
curl -X POST "http://localhost:8080/api/v1/calculate/gcs" \
  -H "Content-Type: application/json" \
  -d '{"params": {"eye_response": 4, "verbal_response": 5, "motor_response": 6}}'

______________________________________________________________________

🐳 Docker部署⭐ 新

MCP服务器可以作为 远程SSE（服务器发送事件）服务器 通过Docker，启用：

• 🌐 从任何兼容MCP的客户端进行远程访问
• ☁️ 云部署（AWS、GCP、Azure等）
• 🔄 使用Docker Compose或Kubernetes轻松扩展

Docker快速入门

# Build and run
docker-compose up -d

# Or build manually
docker build -t medical-calc-mcp .
docker run -p 8000:8000 medical-calc-mcp

# Check service is running
curl -sf http://localhost:8000/sse -o /dev/null && echo "OK"

运输方式

⚠️ 重要：SSE/HTTP模式绑定到 0.0.0.0 默认情况下用于远程访问。

快速启动命令

# 1. STDIO Mode - For Claude Desktop (local)
uv run python -m src.main

# 2. SSE Mode - For remote agents (Docker/Cloud)
uv run python -m src.main --mode sse
uv run python -m src.main --mode sse --host 0.0.0.0 --port 9000  # Custom port

# 3. HTTP Mode - Streamable HTTP transport
uv run python -m src.main --mode http

远程MCP客户端配置

克劳德桌面（远程SSE）：

{
  "mcpServers": {
    "medical-calc": {
      "url": "http://localhost:8000/sse"
    }
  }
}

对于云部署，请替换 localhost 使用您的服务器地址：

{
  "mcpServers": {
    "medical-calc": {
      "url": "https://your-server.example.com/sse"
    }
  }
}

API终点

⚠️ FastMCP SSE模式仅提供以下端点：

环境变量

Docker编写示例

version: '3.8'
services:
  # MCP Server (SSE mode)
  medical-calc-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - MCP_MODE=sse

  # REST API Server (FastAPI)
  medical-calc-api:
    build: .
    ports:
      - "8080:8080"
    command: ["python", "src/main.py", "--mode", "api", "--port", "8080"]

______________________________________________________________________

🔒 HTTPS部署⭐ 新

启用HTTPS，以便在具有灵活证书配置的生产环境中进行安全通信。

建筑

┌─────────────────────────────────────────────────────────────────────┐
│                        HTTPS Deployment                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────────┐                                                   │
│   │   Client    │                                                   │
│   │ (Browser/   │                                                   │
│   │  AI Agent)  │                                                   │
│   └──────┬──────┘                                                   │
│          │ HTTPS (TLS 1.2/1.3)                                      │
│          ▼                                                          │
│   ┌──────────────────────────────────────────────────────────┐      │
│   │                    Nginx Reverse Proxy                    │      │
│   │  ┌─────────────────────────────────────────────────────┐ │      │
│   │  │ • TLS Termination (SSL Certificates)                │ │      │
│   │  │ • Rate Limiting (30/60 req/s)                       │ │      │
│   │  │ • Security Headers (XSS, CSRF protection)           │ │      │
│   │  │ • SSE Optimization (long-lived connections)         │ │      │
│   │  └─────────────────────────────────────────────────────┘ │      │
│   └──────────────┬───────────────────────┬───────────────────┘      │
│                  │ HTTP (internal)        │ HTTP (internal)         │
│                  ▼                        ▼                         │
│   ┌──────────────────────┐    ┌──────────────────────┐              │
│   │   MCP SSE Server     │    │   REST API Server    │              │
│   │   (Port 8000)        │    │   (Port 8080)        │              │
│   │                      │    │                      │              │
│   │ • /sse               │    │ • /api/v1/*          │              │
│   │ • /messages          │    │ • /docs (Swagger)    │              │
│   │ • /health            │    │ • /health            │              │
│   └──────────────────────┘    └──────────────────────┘              │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

External Endpoints (HTTPS):
├── https://localhost/        → MCP SSE (via Nginx :443)
├── https://localhost/sse     → SSE Connection
├── https://localhost:8443/   → REST API (via Nginx :8443)
└── https://localhost:8443/docs → Swagger UI

Internal (HTTP, Docker network only):
├── http://medical-calc-mcp:8000  → MCP Server
└── http://medical-calc-api:8080  → API Server

SSL环境变量

选项1:Docker部署（推荐）

最适合生产和团队环境。

# Step 1: Generate SSL certificates
chmod +x scripts/generate-ssl-certs.sh
./scripts/generate-ssl-certs.sh

# Step 2: Start HTTPS services
./scripts/start-https-docker.sh up

# Other commands
./scripts/start-https-docker.sh down     # Stop services
./scripts/start-https-docker.sh logs     # View logs
./scripts/start-https-docker.sh restart  # Restart
./scripts/start-https-docker.sh status   # Check status

自定义证书（Docker）：

# Use custom certificate directory
SSL_DIR=/path/to/your/certs docker-compose -f docker-compose.https.yml up -d

# Use Let's Encrypt certificates
SSL_DIR=/etc/letsencrypt/live/example.com docker-compose -f docker-compose.https.yml up -d

终点：

选项2：本地开发（无Docker）

使用Python/Uvicorn原生SSL支持进行快速本地测试。

# Step 1: Generate SSL certificates (or use your own)
./scripts/generate-ssl-certs.sh

# Step 2: Start HTTPS services
./scripts/start-https-local.sh          # Start both MCP and API
./scripts/start-https-local.sh sse      # Start MCP SSE only
./scripts/start-https-local.sh api      # Start REST API only

自定义证书（本地）：

# Use custom certificate paths via environment variables
SSL_KEYFILE=/path/to/server.key \
SSL_CERTFILE=/path/to/server.crt \
./scripts/start-https-local.sh

# Custom ports
SSL_KEYFILE=/certs/key.pem SSL_CERTFILE=/certs/cert.pem \
MCP_PORT=9000 API_PORT=9001 \
./scripts/start-https-local.sh

# Direct command with CLI arguments
python -m src.main --mode sse --port 8443 \
    --ssl-keyfile /path/to/server.key \
    --ssl-certfile /path/to/server.crt

终点：

选项3：使用Let’s Encrypt进行生产

适用于具有免费可信证书的真实域名。

# 1. Edit nginx/nginx.conf, uncomment these lines:
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

# 2. Use certbot to obtain certificates:
sudo certbot certonly --webroot -w /var/www/certbot \
  -d your-domain.com -d api.your-domain.com

# 3. Start services with Let's Encrypt certs
SSL_DIR=/etc/letsencrypt/live/your-domain.com \
docker-compose -f docker-compose.https.yml up -d

信任自签名证书

为了避免在开发过程中出现浏览器警告：

Linux（Ubuntu/Debian）：

sudo cp nginx/ssl/ca.crt /usr/local/share/ca-certificates/medical-calc-dev.crt
sudo update-ca-certificates

macOS：

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain nginx/ssl/ca.crt

窗户：

1. Double-click nginx/ssl/ca.crt
2. Install Certificate → Local Machine
3. Place in "Trusted Root Certification Authorities"

Claude桌面配置（HTTPS）

{
  "mcpServers": {
    "medical-calc": {
      "url": "https://localhost/sse"
    }
  }
}

对于具有真实域的生产：

{
  "mcpServers": {
    "medical-calc": {
      "url": "https://mcp.your-domain.com/sse"
    }
  }
}

文件概述

SSL配置参考

故障排除

证书不受信任：

# Regenerate certificates
rm -rf nginx/ssl/*
./scripts/generate-ssl-certs.sh

# Then re-add to system trust store (see above)

端口已在使用中：

# Check what's using the port
sudo lsof -i :443
sudo lsof -i :8443

# Kill the process or use different ports

Docker容器未启动：

# Check logs
docker-compose -f docker-compose.https.yml logs nginx
docker-compose -f docker-compose.https.yml logs medical-calc-mcp

# Rebuild
docker-compose -f docker-compose.https.yml up -d --build

SSE连接超时：

# Nginx is configured for 24h timeout, but if issues persist:
# Check nginx/nginx.conf has these settings:
proxy_read_timeout 24h;
proxy_send_timeout 24h;
proxy_buffering off;

______________________________________________________________________

🌐 REST API⭐ 新

除了MCP协议，服务器还提供 独立REST API 用于直接HTTP访问。

快速开始

# Start API server
uv run python src/main.py --mode api --port 8080

# With uvicorn (production)
uv run uvicorn src.infrastructure.api.server:app --host 0.0.0.0 --port 8080

API文档

跑步后，请访问：

• Swagger用户界面:
• ReDoc:
• OpenAPI JSON:

REST API端点

示例：计算CKD-EPI

# Using curl
curl -X POST "http://localhost:8080/api/v1/calculate/ckd_epi_2021" \
  -H "Content-Type: application/json" \
  -d '{"params": {"serum_creatinine": 1.2, "age": 65, "sex": "female"}}'

答复：

{
  "success": true,
  "calculator": "ckd_epi_2021",
  "result": {
    "score_name": "CKD-EPI 2021",
    "value": 49.2,
    "unit": "mL/min/1.73m²",
    "interpretation": {
      "summary": "G3a: Mildly to moderately decreased",
      "severity": "moderate"
    }
  }
}

快速计算端点

一些计算器具有带有查询参数的专用端点：

# CKD-EPI (Query parameters)
curl "http://localhost:8080/api/v1/ckd-epi?serum_creatinine=1.2&age=65&sex=female"

# SOFA Score
curl -X POST "http://localhost:8080/api/v1/sofa?pao2_fio2_ratio=200&platelets=100&bilirubin=2.0&cardiovascular=dopamine_lte_5&gcs_score=13&creatinine=2.5"

______________________________________________________________________

🔐 安全⭐ 新

安全特性

此项目实现了多个安全层：

📖 有关HTTPS部署的详细说明，请参阅 HTTPS部署.

🔑 可选安全功能

所有可选的安全功能都是 默认情况下禁用.通过环境变量启用：

速率限制（应用级别）

# Enable rate limiting
SECURITY_RATE_LIMIT_ENABLED=true   # Default: false
SECURITY_RATE_LIMIT_RPM=60         # Requests per minute (default: 60)
SECURITY_RATE_LIMIT_BURST=10       # Burst size (default: 10)
SECURITY_RATE_LIMIT_BY_IP=true     # Per-IP rate limiting (default: true)

API密钥验证

# Enable API authentication
SECURITY_AUTH_ENABLED=true         # Default: false
SECURITY_API_KEYS=key1,key2,key3   # Comma-separated API keys (min 8 chars each)
SECURITY_AUTH_HEADER=X-API-Key     # Header name (default: X-API-Key)
SECURITY_AUTH_PARAM=api_key        # Query param name (default: api_key)

使用示例：

# With header
curl -H "X-API-Key: your-api-key" http://localhost:8000/sse

# With query parameter
curl "http://localhost:8000/sse?api_key=your-api-key"

# With Bearer token
curl -H "Authorization: Bearer your-api-key" http://localhost:8000/sse

安全场景

配置

CORS配置：

# Development (default) - Allow all origins
CORS_ORIGINS="*"

# Production - Restrict to specific domains
CORS_ORIGINS="https://your-app.com,https://api.your-app.com"

其他安全设置：

# API Server
API_HOST=0.0.0.0   # Use 127.0.0.1 for local only
API_PORT=8080

# MCP Server
MCP_HOST=0.0.0.0   # Use 127.0.0.1 for local only
MCP_PORT=8000

生产建议

依赖安全

# Check for known vulnerabilities
uv run pip-audit --strict

# Upgrade all packages
uv sync --upgrade

# Lock dependencies
uv lock

安全审计结果（2025-06）

✅ 通过检查：

• 无SQL/命令注入漏洞
• 没有硬编码的秘密或凭据
• 错误消息中没有敏感数据泄露
• 所有层的输入验证
• 依赖关系已更新（无已知CVE）

⚠️ 笔记：

• 默认CORS是允许的(*)-配置生产
• 无内置身份验证-必要时在基础架构层添加
• 医疗计算仅供参考，不用于临床决策

______________________________________________________________________

🔍 工具发现

这 两级密钥系统 结合 刀具关系图 是本项目的核心创新：

发现哲学

当AI代理需要医疗计算器时，它使用 统一发现:

┌─────────────────────────────────────────────────────────────┐
│  discover() - Unified Entry Point (v3.0)                     │
├─────────────────────────────────────────────────────────────┤
│  Path A: Explore All Categories                              │
│  ① discover() → {specialties: [...], contexts: [...]}       │
│  ② discover(by="specialty", value="critical_care")          │
│  ③ get_tool_schema("sofa_score") → params, references       │
│  ④ calculate("sofa_score", {...params})                      │
├─────────────────────────────────────────────────────────────┤
│  Path B: Context-based                                       │
│  ① discover(by="context", value="preoperative_assessment")  │
│  ② get_tool_schema("rcri") → params, param_sources          │
│  ③ calculate("rcri", {...params})                            │
├─────────────────────────────────────────────────────────────┤
│  Path C: Keyword Search                                      │
│  ① discover(by="keyword", value="sepsis")                    │
│  ② get_tool_schema("qsofa_score")                            │
│  ③ calculate("qsofa_score", {...params})                     │
├─────────────────────────────────────────────────────────────┤
│  Path D: Graph-based Discovery                               │
│  ① get_related_tools("sofa_score") → [qsofa, apache_ii...]  │
│  ② find_tools_by_params(["creatinine", "age"]) → [tools...] │
└─────────────────────────────────────────────────────────────┘

每一步都会回来 next_step 提示，所以特工永远不会迷路！

工具关系图（Hypergraph）

这 工具关系图 基于以下内容连接工具：

# Find related tools via graph traversal
get_related_tools("sofa_score")
# → [{"tool_id": "qsofa_score", "similarity": 0.85},
#    {"tool_id": "apache_ii", "similarity": 0.72}, ...]

# Reverse lookup: "I have these values, what can I calculate?"
find_tools_by_params(["creatinine", "bilirubin", "inr"])
# → [meld_score, child_pugh, ...]

统一计算接口（v2.0）

我们提供了一个 单一统一 calculate() 工具:

# Old approach (deprecated):
# calculate_sofa(pao2_fio2=300, platelets=150, ...)

# New approach (v2.0):
calculate(
    tool_id="sofa_score",
    params={
        "pao2_fio2_ratio": 300,
        "platelets": 150,
        "bilirubin": 1.2,
        # ... other params
    }
)

优点：

• 🎯 代币高效：上下文中只有6个工具，而不是75个以上
• 🔍 发现第一：使用discover（）查找正确的计算器
• 📖 自我记录: get_tool_schema() 显示所需的确切参数

低级键（精确选择）

对于 精确刀具选择 当你确切地知道你需要什么时：

LowLevelKey(
    tool_id="ckd_epi_2021",           # Unique identifier
    name="CKD-EPI 2021",              # Human-readable name
    purpose="Calculate eGFR",          # What it does
    input_params=["age", "sex", "creatinine"],  # Required inputs
    output_type="eGFR with CKD staging"         # Output format
)

高级钥匙（智能发现）

对于 智能发现 在探索选项时：

HighLevelKey(
    specialties=(Specialty.NEPHROLOGY, Specialty.INTERNAL_MEDICINE),
    conditions=("chronic kidney disease", "CKD", "renal impairment"),
    clinical_contexts=(ClinicalContext.STAGING, ClinicalContext.DRUG_DOSING),
    clinical_questions=(
        "What is the patient's kidney function?",
        "Should I adjust drug dosage for renal function?",
    ),
    icd10_codes=("N18", "N19"),
    keywords=("eGFR", "GFR", "creatinine", "kidney function")
)

🔑 主要特点：多专业工具

一个工具可以属于多个高级类别！

示例：SOFA分数属于：

这意味着：

• 搜索“败血症”→ 返回SOFA、qSOFA、新闻。..
• 搜索“重症监护”→ 返回SOFA、APACHE II、RASS、GCS、CAM-ICU。..
• 搜索“器官功能障碍”→ 返回SOFA。..

整合MCP工具（v3.0）

总计：6个工具 （从v2.0中的12合并而来）

示例：AI代理工作流

User: "I need to assess this patient's cardiac risk before surgery"

# Step 1: Agent uses hierarchical navigation
Agent: list_contexts()
       → Returns: [..., "preoperative_assessment", ...]
       → next_step: "list_by_context('preoperative_assessment')"

# Step 2: Filter by context
Agent: list_by_context("preoperative_assessment")
       → Returns: [rcri, asa_physical_status, mallampati_score, ...]
       → next_step: "get_calculator_info('rcri')"

# Step 3: Get tool details
Agent: get_calculator_info("rcri")
       → Returns: Full metadata with input params, references
       → next_step: "calculate_rcri(...)"

# Step 4: Calculate
Agent: calculate_rcri(high_risk_surgery=True, ischemic_heart_disease=True, ...)
       → Returns: Score, risk percentage, recommendations

示例：重症监护室败血症检查

User: "Evaluate this ICU patient for sepsis"

Agent: search_calculators("sepsis")
       → Returns: SOFA, qSOFA, NEWS2, APACHE II

# Per Sepsis-3 guidelines:

Agent: calculate_qsofa(respiratory_rate=24, systolic_bp=95, altered_mentation=True)
       → qSOFA = 3 (High risk, prompt evaluation needed)

Agent: calculate_sofa(pao2_fio2_ratio=200, platelets=80, bilirubin=2.5, ...)
       → SOFA = 8 (Sepsis confirmed if infection suspected, ≥2 point increase)

______________________________________________________________________

🔧 可用工具

质量快照：2095个已收集的测试|287个PMID|245个DOI|100%的引用覆盖率 📋 查看完整路线图→ | 贡献指南→

📑 快速导航

此自述文件不再包含手工维护的计算器清单。现在，相同的生成源为存储库文档和MkDocs页面提供数据。

注册表快照：31个专业的152台计算器

• 完整的计算器目录
• 繁体中文目录
• 网站计算器目录
• 网站版繁中总览
• 在本地重新生成 uv run python scripts/generate_tool_catalog_docs.py

您仍然可以通过以下方式检查实时注册表 python scripts/count_tools.py, calculator://list，或 list_calculators() 来自您的MCP客户。

______________________________________________________________________

生成的计算器目录

完整的工具清单和专业摘要直接从注册表中生成，以消除README漂移风险。

• 完整的计算器目录
• 繁体中文目录
• 在本地重新生成 uv run python scripts/generate_tool_catalog_docs.py

______________________________________________________________________

🔍 发现工具

第一步：入口点

步骤2：按类别筛选

步骤3：获取详细信息

步骤4：执行计算

↑ 返回导航

______________________________________________________________________

📦 资源

______________________________________________________________________

📝 提示

提示为常见临床场景提供了指导性的多工具工作流程：

用途：

# In MCP client, request a prompt:
prompt: sepsis_evaluation
→ Returns structured workflow with step-by-step guidance

↑ 返回导航

______________________________________________________________________

📖 用法示例

Python示例⭐ 新

该项目在 examples/ 文件夹：

# Basic usage examples
uv run python examples/basic_usage.py

# Clinical workflow examples
uv run python examples/clinical_workflows.py

可用示例：

示例1:CKD-EPI 2021（eGFR）

输入：

{
  "serum_creatinine": 1.2,
  "age": 65,
  "sex": "female"
}

输出：

{
  "score_name": "CKD-EPI 2021",
  "result": 67.1,
  "unit": "mL/min/1.73m²",
  "interpretation": {
    "summary": "Mildly decreased kidney function (G2)",
    "stage": "G2",
    "recommendation": "Monitor kidney function annually; adjust renally-excreted drugs"
  },
  "references": [{
    "citation": "Inker LA, et al. N Engl J Med. 2021;385(19):1737-1749.",
    "doi": "10.1056/NEJMoa2102953"
  }]
}

示例2：工具发现

查询： search_calculators("airway")

输出：

{
  "keyword": "airway",
  "count": 1,
  "tools": [{
    "tool_id": "mallampati_score",
    "name": "Modified Mallampati Classification",
    "purpose": "Predict difficult intubation based on oropharyngeal visualization",
    "specialties": ["anesthesiology", "emergency_medicine"],
    "input_params": ["mallampati_class"]
  }]
}

示例3:RCRI心脏风险

输入：

{
  "high_risk_surgery": true,
  "ischemic_heart_disease": true,
  "heart_failure": false,
  "cerebrovascular_disease": false,
  "insulin_diabetes": true,
  "creatinine_above_2": false
}

输出：

{
  "score_name": "Revised Cardiac Risk Index",
  "result": 3,
  "interpretation": {
    "summary": "RCRI Class III - Elevated cardiac risk",
    "risk_percentage": "6.6%",
    "recommendation": "Consider cardiology consultation; optimize medical therapy"
  }
}

______________________________________________________________________

📜 参考文献

所有计算器都引用了原始的同行评审研究。看 参考文献/README.md 完整的引用。

📋 指南映射

我们系统地将计算器映射到临床指南：

我们系统地将我们的计算器映射到主要的临床指南审查中，此概述来自文档和网站使用的相同来源。

跟踪覆盖范围： 65/65 推荐的工具 16 域。

• 生成的指南覆盖范围摘要
• 网站指南覆盖页面
• 2023-2025详细指南审查
• 2020-2025年历史指南回顾

引文格式

我们使用 温哥华风格 引用：

Inker LA, Eneanya ND, Coresh J, et al. New Creatinine- and Cystatin C-Based
Equations to Estimate GFR without Race. N Engl J Med. 2021;385(19):1737-1749.
doi:10.1056/NEJMoa2102953

______________________________________________________________________

👨‍💻 发展

项目状态

快速入门（开发人员）

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Setup environment and install dependencies
uv sync

# CI-parity install using the lock file
uv sync --frozen --extra dev --group dev

# 3. Run tests
uv run pytest

# 4. Run MCP server in dev mode
uv run mcp dev src/main.py

______________________________________________________________________

🧪 测试

测试策略

我们通过以下方式维护高质量的代码库 2019年收集的测试 以及CI中的自动覆盖报告。

┌─────────────────────────────────────────────────────────────────┐
│                        Testing Pyramid                          │
├─────────────────────────────────────────────────────────────────┤
│                     E2E Tests (MCP Protocol)                     │
│                    (700+ tests covering all tools)               │
│                               ╱  ╲                               │
│           Integration Tests              MCP Inspector           │
│          (Use Cases + Registry)          (Manual Testing)        │
│                  ╱              ╲                                │
│      Unit Tests (Domain)    Validation Tests                     │
│      (940+ tests for logic) (Parameter constraints)              │
└─────────────────────────────────────────────────────────────────┘

运行测试

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Run specific layer tests
uv run pytest tests/test_acid_base.py -v

# Run with verbose output
uv run pytest -v --tb=short

类型安全

该项目执行 严格类型检查 在整个代码库中。

# Run strict type check
uv run mypy --no-incremental --strict src tests

# Run linter
uv run ruff check src tests

# Auto-fix linting issues
uv run ruff check --fix src tests

API合同

REST API OpenAPI契约作为生成的工件进行跟踪，因此在下游客户端中断之前，在CI中捕获模式漂移。

# Refresh the generated OpenAPI snapshot
uv run python scripts/generate_openapi_spec.py

# Refresh the generated REST API reference
uv run python scripts/generate_rest_api_docs.py

# Verify generated docs and API contract are current
uv run python scripts/check_project_consistency.py --check-tests

依赖升级策略记录在 docs/DEPENDENCY_UPGRADE_PLAYBOOK.md.

CI/CD管道

该项目使用GitHub Actions与以下功能进行持续集成：

┌─────────────────────────────────────────────────────────────┐
│                    Push to develop                          │
├─────────────────────────────────────────────────────────────┤
│  auto-fix:                                                  │
│    • ruff check --fix (auto-fix linting)                    │
│    • ruff format (auto-format code)                         │
│    • uv lock (update dependency lock)                       │
│    • Auto-commit back to develop [skip ci]                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                    test (3.11, 3.12, 3.13)                  │
├─────────────────────────────────────────────────────────────┤
│    • ruff check (lint)                                      │
│    • ruff format --check (format check)                     │
│    • mypy (type check)                                      │
│    • pytest (tests + coverage ≥90%)                         │
└─────────────────────────────────────────────────────────────┘
                            ↓ (main only)
┌─────────────────────────────────────────────────────────────┐
│                    docker + release                         │
├─────────────────────────────────────────────────────────────┤
│    • Build & test Docker image (/health endpoint)           │
│    • Auto-create GitHub Release when version changes        │
└─────────────────────────────────────────────────────────────┘

______________________________________________________________________

🛠️ 需求

• Python 3.11+
• 紫外线 -快速Python包管理器（必需）
• MCP-SDK （FastMCP）-通过自动安装 uv sync

______________________________________________________________________

路线图

📋 查看完整路线图→ 详细的实施计划

2025 Q4 (Current)                2026 Q1                          2026 Q2
───────────────────────────────────────────────────────────────────────────────
Phase 8: ✅ Complete             Phase 9-10: Acid-Base/Cardio    Phase 11-14: Complete
├── ✅ HAS-BLED (2024 ESC)       ├── Anion Gap, Delta Ratio      ├── Resp/Oxygenation
├── ✅ Child-Pugh               ├── Corrected QT, Shock Index    ├── Neuro/Sedation
└── ✅ KDIGO AKI                └── A-a Gradient, IBW           ├── Infectious Disease
                                                                 └── Common Utilities
Phase 9: ✅ Complete
├── ✅ Anion Gap
├── ✅ Delta Ratio
├── ✅ Corrected Sodium
├── ✅ Winter's Formula
├── ✅ Osmolar Gap
└── ✅ Free Water Deficit

最近添加的计算器（第13阶段完成✅)

______________________________________________________________________

📄 许可证

Apache 2.0-请参阅 许可证

______________________________________________________________________

🙏 致谢

• 模型上下文协议 -人工智能工具通信的Anthropic开放协议
• FastMCP -MCP的Python SDK
• 所有引用的医学计算器和评分系统的原始作者