血液分析健康指导系统

血液检测MCP服务器

一个全面的健康指导系统，将血液检测分析与循证营养治疗建议相结合，由检索增强生成（RAG）技术提供支持。

🔗 实时端点:

• 主要的，重要的 https://supplement-therapy.up.railway.app （活动）
• 新域名： https://bloodtest-mcp.up.railway.app （正在配置）

目录

• 概述
  • 主要特点
  • 技术栈
• 用户手册
  • 入门指南
  • Claude桌面集成
  • 使用健康教练
  • 可用的MCP工具
• 开发者手册
  • 先决条件
  • 安装
  • 开发设置
  • API文档
  • 测试
  • 部署
  • 项目结构
• 高级主题
  • RAG系统架构
  • 工作流配置
  • 故障排除
• 贡献
• 许可证

概述

主要特点

• 血液检测分析：基于功能医学，获得8+关键健康标志物的最佳范围
• 个性化推荐：来自德国医学文献的循证补充和生活方式建议
• RAG知识库：使用FAISS矢量数据库搜索索引医学文本
• MCP协议支持：与Claude Desktop和其他MCP兼容客户端集成
• 多格式支持：以PDF、图像和文本格式处理血液检测结果
• RESTful API：以编程方式访问血液检测参考值
• 健康指导工作流程：综合评估和建议生成

技术栈

• 框架：集成了FastAPI的FastMCP
• AI/ML：LangChain，句子转换器，FAISS
• 文件处理：PyPDF，python多部分
• 配置：基于YAML的工作流定义
• 部署：Docker与铁路云部署
• 语言：Python 3.12+

用户手册

入门指南

1. 访问生产系统

   当前活动端点:

   • 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 -铁路配置完成后即可使用

2. 认证

   • 目前，公共端点不需要身份验证
   • 对于生产使用，实现承载令牌身份验证

Claude桌面集成

要将此MCP服务器与Claude Desktop一起使用：

1. 打开Claude桌面配置

   • 点击 克劳德 菜单（macOS）或 文件 菜单（Windows）
   • 选择 设置 → 开发者 → 编辑配置

2. 添加服务器配置 将以下内容添加到您的 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

3. 保存并重新启动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

使用健康教练

1. 上传血液检测结果

   • 支持的格式：PDF、JPG、PNG
   • 德国实验室报告会自动解析
   • 将最佳范围与您的结果进行比较

2. 完整的健康评估

   • 提供人口统计信息
   • 描述当前的症状和健康问题
   • 设定你的健康目标和优先事项

3. 接收个性化推荐

   • 补充特定剂量和时间的方案
   • 根据你的缺陷调整饮食
   • 最佳健康生活方式干预
   • 所有建议均引用了医学文献

可用的MCP工具

1. get_book_info

   • 返回有关加载的医学书籍和RAG状态的元数据
   • 显示可用的工作流和系统功能

2. list_workflows

   • 列出所有可用的健康指导工作流程
   • 每个工作流都有一个特定的重点领域

3. supplement_therapy

   • 主要健康指导工作流程
   • 提供全面的补充建议
   • 需要患者评估数据

4. search_book_knowledge

   • 在索引的医学知识库中搜索
   • 返回带有页面引用的相关段落
   • 示例：“女性的最佳铁蛋白水平”

5. sequential_thinking

   • 复杂健康分析的多步推理
   • 可用于鉴别诊断和复杂病例

开发者手册

先决条件

• Python 3.12或更高版本
• Docker（可选，用于容器化部署）
• Git

安装

1. 克隆存储库

   复制

   git clone https://github.com/longevitycoach/bloodtest-mcp-server.git
   cd bloodtest-mcp-server
   

2. 创建虚拟环境

   复制

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 再进行

   复制

   pip install -r requirements.txt
   

开发设置

1. 初始化RAG知识库

   复制

   # Place PDF files in resources/books directory
   INDEX_NAME="supplement-therapy" PDF_DIRECTORY="resources/books" python scripts/init_rag.py
   

2. 配置应用程序

   • 编辑 resources/structure.yaml 自定义工作流
   • 确保 rag.config.index_name 匹配您的INDEX_NAME

3. 运行开发服务器

   复制

   # 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.py
   

API文档

基本端点

• 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())

支持的血液检测参数

测试

# 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个测试）：

1. 健康检查 -验证服务器运行状况端点
2. SSE 连接 -测试SSE端点连接
3. 铁蛋白知识查询 -验证最佳范围信息
4. 维生素D查询 -测试缺陷症状搜索
5. 镁补充剂 -验证剂量指南
6. TSH解读 -测试甲状腺值解释
7. B12全胸苷 -验证B12信息检索
8. 硒免疫系统 -测试矿物质免疫连接
9. 锌铜比 -验证补充余额信息
10. 叶酸要求 -检测叶酸参考信息

阴性测试用例（10个测试）：

1. 端点无效 -404响应不存在的路径
2. 错误的HTTP方法 拒绝SSE终端上的POST
3. 健康方法无效 -拒绝健康端点上的POST
4. API路径无效 -正确处理/api/无效
5. 测试路径 -拒绝/测试终点
6. 管理员路径 -拒绝/管理员访问
7. 路径遍历 -块/。./etc/passwd尝试
8. 健康路径遍历 -区块/健康/。./../
9. SSE子路径 -拒绝/sse/无效
10. 空路径 -句柄/空端点

在本地运行集成测试：

# 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
• 执行时间：<45秒

🏥 健康检查测试（4/4通过）

📚 积极的知识库测试（10/10通过）

🛡️ 安全和错误处理测试（10/10通过）

🚀 性能指标

• Docker构建时间：~5秒
• 服务器启动时间：约10秒
• 健康检查响应：平均1.36ms
• SSE连接时间：<5ms
• 错误响应时间：<2ms

🔧 测试环境

• Docker镜像: bloodtest-mcp-server:local
• 集装箱港口：8001（映射到内部8000）
• 测试框架：Python请求+自定义MCP客户端
• 执行日期：最新CI/CD运行

📋 参考值测试（17/17通过）

✅ 总结

所有37个集成测试均成功通过，证明：

• 稳健的健康监测
• 正确实施SSE协议
• 全面的错误处理
• 针对常见攻击的强大安全措施
• 性能卓越，响应时间低于2ms
• RAG系统为医学知识查询做好准备
• 全面覆盖所有血液检测参考值
• 循证补充建议

服务器已准备好生产，所有安全措施到位，性能特征最佳，对血液检测参数和补充指导有全面的了解。

部署

铁路（生产）

该应用程序部署在铁路上：

1. 连接存储库

   • 将GitHub存储库连接到Railway
   • 推送到主分支时自动部署

2. 环境变量

   复制

   PORT=8000
   ENV=production
   PDF_DIRECTORY=/app/resources/books
   INDEX_DIRECTORY=/app/faiss_index
   INDEX_NAME=supplement-therapy
   

3. 监控

   • 健康检查：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系统架构

1. 文档处理

   • PDF被分成块（1000个字符，200个重叠）
   • 使用句子转换器嵌入文本
   • 存储在FAISS索引中的向量

2. 查询流程

   • 嵌入用户查询
   • 检索到前k个类似文档
   • 上下文传递给LLM以生成响应

3. 配置

   复制

   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...

故障排除

常见问题

1. 未找到FAISS索引

   • 确保环境中的INDEX_NAME与structure.yaml匹配
   • 跑 python scripts/init_rag.py 创建索引

2. 与Claude Desktop的连接问题

   • 验证服务器是否正在运行：检查/健康终结点
   • 确保配置JSON有效
   • 完全重新启动克劳德桌面

3. Docker构建失败

   • 检查Python版本兼容性
   • 确保所有文件都包含在构建上下文中
   • 验证Docker镜像中是否存在FAISS索引

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

该项目根据MIT许可证获得许可。看 许可证 文件以获取详细信息。

致谢

• 基于Ulrich Strunz博士和Helena Orfanos Boeckel博士工作的医学参考值
• 基于FastMCP、FastAPI和LangChain构建
• 部署在铁路云平台上