血液检测MCP服务器
一个全面的健康指导系统，将血液检测分析与循证营养治疗建议相结合，由检索增强生成（RAG）技术提供支持。
🔗 实时端点:
- 主要的，重要的 https://supplement-therapy.up.railway.app （活动）
- 新域名： https://bloodtest-mcp.up.railway.app （正在配置）
目录
- 入门指南 - Claude桌面集成 - 使用健康教练 - 可用的MCP工具
- 先决条件 - 安装 - 开发设置 - API文档 - 测试 - 部署 - 项目结构
概述
主要特点
- 血液检测分析：基于功能医学，获得8+关键健康标志物的最佳范围
- 个性化推荐：来自德国医学文献的循证补充和生活方式建议
- RAG知识库：使用FAISS矢量数据库搜索索引医学文本
- MCP协议支持：与Claude Desktop和其他MCP兼容客户端集成
- 多格式支持：以PDF、图像和文本格式处理血液检测结果
- RESTful API：以编程方式访问血液检测参考值
- 健康指导工作流程：综合评估和建议生成
技术栈
- 框架：集成了FastAPI的FastMCP
- AI/ML：LangChain，句子转换器，FAISS
- 文件处理：PyPDF，python多部分
- 配置：基于YAML的工作流定义
- 部署：Docker与铁路云部署
- 语言：Python 3.12+
用户手册
入门指南
- 访问生产系统
当前活动端点:
- Web界面： https://supplement-therapy.up.railway.app - API基本URL: https://supplement-therapy.up.railway.app - MCP SSE端点： https://supplement-therapy.up.railway.app/sse - 健康检查： https://supplement-therapy.up.railway.app/health
新建端点 （正在配置中）：
- https://bloodtest-mcp.up.railway.app -铁路配置完成后即可使用
- 认证
- 目前，公共端点不需要身份验证 - 对于生产使用，实现承载令牌身份验证
Claude桌面集成
要将此MCP服务器与Claude Desktop一起使用：
- 打开Claude桌面配置
- 点击 克劳德 菜单（macOS）或 文件 菜单（Windows） - 选择 设置 → 开发者 → 编辑配置
- 添加服务器配置
将以下内容添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"bloodtest-health-coach": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sse",
"https://supplement-therapy.up.railway.app/sse"
],
"env": {}
}
}
}备注：一次 bloodtest-mcp.up.railway.app 处于活动状态，请将URL更新为 https://bloodtest-mcp.up.railway.app/sse
- 保存并重新启动Claude Desktop
- 保存配置文件 - 完全退出并重新启动Claude Desktop - 健康教练工具现在应该出现在Claude中
配置文件位置：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json - Linux：
~/.config/Claude/claude_desktop_config.json
使用健康教练
- 上传血液检测结果
- 支持的格式：PDF、JPG、PNG - 德国实验室报告会自动解析 - 将最佳范围与您的结果进行比较
- 完整的健康评估
- 提供人口统计信息 - 描述当前的症状和健康问题 - 设定你的健康目标和优先事项
- 接收个性化推荐
- 补充特定剂量和时间的方案 - 根据你的缺陷调整饮食 - 最佳健康生活方式干预 - 所有建议均引用了医学文献
可用的MCP工具
get_book_info
- 返回有关加载的医学书籍和RAG状态的元数据 - 显示可用的工作流和系统功能
list_workflows
- 列出所有可用的健康指导工作流程 - 每个工作流都有一个特定的重点领域
supplement_therapy
- 主要健康指导工作流程 - 提供全面的补充建议 - 需要患者评估数据
search_book_knowledge
- 在索引的医学知识库中搜索 - 返回带有页面引用的相关段落 - 示例：“女性的最佳铁蛋白水平”
sequential_thinking
- 复杂健康分析的多步推理 - 可用于鉴别诊断和复杂病例
开发者手册
先决条件
- Python 3.12或更高版本
- Docker（可选，用于容器化部署）
- Git
安装
- 克隆存储库
git clone https://github.com/longevitycoach/bloodtest-mcp-server.git
cd bloodtest-mcp-server- 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate- 再进行
pip install -r requirements.txt开发设置
- 初始化RAG知识库
# Place PDF files in resources/books directory
INDEX_NAME="supplement-therapy" PDF_DIRECTORY="resources/books" python scripts/init_rag.py- 配置应用程序
- 编辑 resources/structure.yaml 自定义工作流 - 确保 rag.config.index_name 匹配您的INDEX_NAME
- 运行开发服务器
# Run MCP server with SSE transport
python server.py --host 0.0.0.0 --port 8000
# Or run integrated server (MCP + API)
python integrated_server.py --host 0.0.0.0 --port 8000
# Or run just the FastAPI server
python main.pyAPI文档
基本端点
GET /-API信息和可用端点GET /health-健康检查端点GET /parameters-列出所有血液检测参数GET /reference/{parameter}-获取参数的参考范围GET /sse-MCP服务器发送事件端点
API使用示例
import requests
# Get all available parameters
response = requests.get("https://supplement-therapy.up.railway.app/parameters")
print("Available parameters:", response.json()["parameters"])
# Get reference range for ferritin
response = requests.get(
"https://supplement-therapy.up.railway.app/reference/ferritin",
params={"sex": "female"}
)
print("Ferritin reference:", response.json())支持的血液检测参数
| 参数 | 单位 | 说明 |
|---|---|---|
| 铁蛋白 | ng/ml | 铁储存蛋白 |
| tsh | mIU/l | 促甲状腺激素 |
| 维生素d | ng/ml | 25-OH维生素d |
| 维生素b12 | pmol/l | 维生素b12（Holo-TC） |
| 叶酸_rbc | ng/ml | 红细胞叶酸 |
| 锌 | mg/l | 必需矿物质 |
| 镁 | mmol/l | 全血镁 |
| 硒 | µg/l | 抗氧化矿物质 |
测试
# Run all tests with coverage
pytest tests/ -v --cov=bloodtest_tools --cov-report=term-missing
# Run specific test file
pytest tests/test_api_endpoints.py -v
# Run with Makefile
make test
# Run MCP Integration Tests
python tests/test_mcp_client.py测试组织
tests/test_api_endpoints.py-API终点测试tests/test_bloodtest_tools.py-核心功能测试tests/test_edge_cases.py-边缘案例处理tests/test_integration.py-集成测试tests/test_mcp_client.py-MCP SSE协议测试tests/test_mcp_integration.py-全面的MCP集成测试testdata/-全面的测试场景和数据
MCP集成测试
MCP集成测试验证了服务器的SSE（服务器发送事件）协议实现和知识库功能：
阳性测试用例（10个测试）：
- 健康检查 -验证服务器运行状况端点
- SSE 连接 -测试SSE端点连接
- 铁蛋白知识查询 -验证最佳范围信息
- 维生素D查询 -测试缺陷症状搜索
- 镁补充剂 -验证剂量指南
- TSH解读 -测试甲状腺值解释
- B12全胸苷 -验证B12信息检索
- 硒免疫系统 -测试矿物质免疫连接
- 锌铜比 -验证补充余额信息
- 叶酸要求 -检测叶酸参考信息
阴性测试用例（10个测试）：
- 端点无效 -404响应不存在的路径
- 错误的HTTP方法 拒绝SSE终端上的POST
- 健康方法无效 -拒绝健康端点上的POST
- API路径无效 -正确处理/api/无效
- 测试路径 -拒绝/测试终点
- 管理员路径 -拒绝/管理员访问
- 路径遍历 -块/。./etc/passwd尝试
- 健康路径遍历 -区块/健康/。./../
- SSE子路径 -拒绝/sse/无效
- 空路径 -句柄/空端点
在本地运行集成测试：
# Build and run Docker container
docker build -t bloodtest-mcp-server:local -f Dockerfile.optimized .
docker run -d --name bloodtest-local -p 8001:8000 bloodtest-mcp-server:local
# Run integration tests
python tests/test_mcp_client.py
# Check health endpoint
curl http://localhost:8001/health
# Clean up
docker stop bloodtest-local && docker rm bloodtest-local测试报告
MCP集成测试套件验证服务器的功能、安全性和性能。以下是最新执行的综合测试报告：
📊 总体结果
- 总测试：37（20 MCP+17参考值）
- 通过: 37/37 (100%)
- 失败: 0
- 执行时间：\100 pmol/l |每日舌下含1000 mcg |✅ 通过|
|4 |锌|6-7mg/l |每天15-30mg|✅ 通过| |5 |镁| 0.85-1.0毫摩尔/升|每天300-600毫克|✅ 通过| |6 | Omega-3指数|>8%|每天2-4g EPA/DHA |✅ 通过| |7 |睾酮|男性：8-30 pg/ml |维生素D、锌、镁|✅ 通过| |8 |雌二醇|男性：20-25 pg/ml | DIM，d-葡萄糖酸钙|✅ 通过| |9|hs CRP |\20 ng/ml红细胞|5-MTHF（甲基叶酸）|✅ 通过| |17 |硒| 120-150微克/升|每天200微克|✅ 通过|
✅ 总结
所有37个集成测试均成功通过，证明：
- 稳健的健康监测
- 正确实施SSE协议
- 全面的错误处理
- 针对常见攻击的强大安全措施
- 性能卓越，响应时间低于2ms
- RAG系统为医学知识查询做好准备
- 全面覆盖所有血液检测参考值
- 循证补充建议
服务器已准备好生产，所有安全措施到位，性能特征最佳，对血液检测参数和补充指导有全面的了解。
部署
铁路（生产）
该应用程序部署在铁路上：
- 连接存储库
- 将GitHub存储库连接到Railway - 推送到主分支时自动部署
- 环境变量
PORT=8000
ENV=production
PDF_DIRECTORY=/app/resources/books
INDEX_DIRECTORY=/app/faiss_index
INDEX_NAME=supplement-therapy- 监控
- 健康检查：https://supplement-therapy.up.railway.app/health - 在铁路仪表板中查看日志 - 当前端点：https://supplement-therapy.up.railway.app - 新端点（待定）：https://bloodtest-mcp.up.railway.app
码头工人
# Build and run with Docker
docker build -t bloodtest-mcp-server -f Dockerfile.optimized .
docker run -p 8000:8000 bloodtest-mcp-server
# Or use Docker Compose
docker-compose up --build项目结构
bloodtest-mcp-server/
├── bloodtest_tools/ # Core blood test functionality
│ ├── api.py # FastAPI endpoints
│ ├── reference_values.py # Medical reference ranges
│ └── mcp_tool.py # MCP tool wrappers
├── utils/ # Utility modules
│ ├── rag_system.py # FAISS RAG implementation
│ └── sequential_thinking.py # Reasoning tool
├── resources/ # Configuration and books
│ ├── structure.yaml # Workflow definitions
│ └── books/ # PDF medical texts
├── scripts/ # Utility scripts
│ └── init_rag.py # RAG initialization
├── tests/ # Test suite
├── server.py # Main MCP server
├── integrated_server.py # Combined MCP + API server
└── main.py # FastAPI entry point高级主题
RAG系统架构
- 文档处理
- PDF被分成块（1000个字符，200个重叠） - 使用句子转换器嵌入文本 - 存储在FAISS索引中的向量
- 查询流程
- 嵌入用户查询 - 检索到前k个类似文档 - 上下文传递给LLM以生成响应
- 配置
rag:
enabled: true
config:
index_name: "supplement-therapy"
index_directory: "./faiss_index"
chunk_size: 1000
chunk_overlap: 200工作流配置
工作流在中定义 resources/structure.yaml:
workflows:
- name: "Supplement Therapy"
description: "Personalized supplement recommendations"
prompt: |
Based on the blood test results and health assessment,
provide evidence-based supplement recommendations...故障排除
常见问题
- 未找到FAISS索引
- 确保环境中的INDEX_NAME与structure.yaml匹配 - 跑 python scripts/init_rag.py 创建索引
- 与Claude Desktop的连接问题
- 验证服务器是否正在运行：检查/健康终结点 - 确保配置JSON有效 - 完全重新启动克劳德桌面
- Docker构建失败
- 检查Python版本兼容性 - 确保所有文件都包含在构建上下文中 - 验证Docker镜像中是否存在FAISS索引
贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
该项目根据MIT许可证获得许可。看 许可证 文件以获取详细信息。
致谢
- 基于Ulrich Strunz博士和Helena Orfanos Boeckel博士工作的医学参考值
- 基于FastMCP、FastAPI和LangChain构建
- 部署在铁路云平台上