Bloodtest MCP Server

血液检测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 -铁路配置完成后即可使用

1. 认证

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

Claude桌面集成

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

1. 打开Claude桌面配置

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

1. 添加服务器配置

将以下内容添加到您的 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

1. 保存并重新启动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 - 德国实验室报告会自动解析 - 将最佳范围与您的结果进行比较

1. 完整的健康评估

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

1. 接收个性化推荐

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

可用的MCP工具

1. get_book_info

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

1. list_workflows

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

1. supplement_therapy

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

1. search_book_knowledge

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

1. sequential_thinking

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

开发者手册

先决条件

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

安装

1. 克隆存储库

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

1. 创建虚拟环境

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

1. 再进行

   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

1. 配置应用程序

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

1. 运行开发服务器

   # 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
• 执行时间：\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系统为医学知识查询做好准备
• 全面覆盖所有血液检测参考值
• 循证补充建议

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

部署

铁路（生产）

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

1. 连接存储库

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

1. 环境变量

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

1. 监控

- 健康检查：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索引中的向量

1. 查询流程

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

1. 配置

   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 创建索引

1. 与Claude Desktop的连接问题

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

1. 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构建
• 部署在铁路云平台上