使用说明

个人健康MCP系统

一个模块化的本地优先系统，使用MCP接口记录、分析和预测个人健康相关性。
重点：食物、酒精、压力、睡眠和症状跟踪。

请注意，此项目用于教育目的，而非生产用途。

个人健康MCP系统

1.目标

使本地或基于代理的系统能够：

通过受控的MCP呼叫记录健康和生活方式数据。
查询摘要、相关性和预测。
作为机器学习驱动的个人洞察力的数据支柱。

2.架构概述

数据库层： SQLite用于结构化健康日志。
MCP服务器： FastAPI应用程序公开标准化方法。
发动机型号： 随机森林回归器（scikit-learn）用于疼痛预测。
代理接口： 本地LLM或使用MCP API的自动化客户端。

┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│ User Input   │──────▶│ MCP Server   │──────▶│ SQLite / ML  │
│ (Agent)   │       │ (FastAPI)    │       │ Engine       │
└──────────────┘       └──────────────┘       └──────────────┘

看 docs/architecture.md 查看详细的架构图和组件描述。

3.文件夹布局

personal-health-mcp-system/
├── pyproject.toml                      # Python project settings and dependencies
├── README.md                           # Project documentation
├── uv.lock                             # UV lockfile
├── configs/                            # Configuration files
│   ├── personal_health.yaml            # Default application configuration
│   └── environments/                   # Environment-specific configs
│       ├── dev.yaml
│       └── prod.yaml
├── data/                               # Runtime data (gitignored except structure)
│   ├── health.db                       # SQLite database
│   ├── model_v1.pkl                    # Trained ML model
│   └── logs/                           # Application logs
│       └── personal_health.log
├── docs/                               # Documentation
│   └── phases.md                       # Project phases and roadmap
├── scripts/                            # Utility scripts (see scripts/README.md)
│   ├── __init__.py
│   ├── README.md                       # Scripts documentation
│   ├── export_sqlite_to_csv.py         # Export database to CSV
│   ├── import_csv_to_sqlite.py         # Import CSV to database
│   ├── init_db.py                      # Initialize database schema
│   ├── train_model.py                  # Train ML model
│   ├── find_duplicate_ids.py           # Find duplicate entries
│   └── shell/                          # Shell scripts
│       ├── run_http.sh                 # Start HTTP server (local dev)
│       ├── run_https.sh                # Start HTTPS server (external access)
│       ├── setup_chatgpt_mcp.sh        # Configure ChatGPT integration
│       └── setup_claude_mcp.sh         # Configure Claude Desktop integration
├── src/                                # Source code
│   └── personal_health/
│       ├── __init__.py
│       ├── core.py                     # FastAPI app with mounted MCP
│       ├── config.py                   # Configuration handling;`
│       ├── logging_config.py           # Logging configuration
│       ├── exceptions.py               # Custom exceptions
│       ├── utils.py                    # Utility functions
│       ├── py.typed                    # PEP 561 type marker
│       ├── api/                        # API module
│       │   ├── __init__.py
│       │   ├── routes.py               # HTTP endpoints
│       │   ├── schemas.py              # Pydantic models
│       │   ├── operation_ids.py        # Operation ID constants
│       │   └── analysis.py             # Analysis logic
│       ├── db/                         # Database module
│       │   ├── __init__.py
│       │   ├── manager.py              # Database manager class
│       │   └── schema.sql              # SQLite schema
│       └── ml/                         # Machine learning module
│           ├── __init__.py
│           ├── features.py             # Feature engineering for ML model
│           └── predictor.py            # Model inference
└── tests/                              # Test suite
    ├── __init__.py
    ├── conftest.py                     # Pytest fixtures
    ├── resources/                      # Test resources
    │   └── test_data.yaml
    └── unit/                           # Unit tests
        ├── __init__.py
        ├── test_analysis.py
        ├── test_mcp_integration.py
        └── test_routes.py

4.数据库模式

CREATE TABLE entries (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    meal TEXT,
    alcohol TEXT,
    stress INTEGER,
    sleep_hours REAL,
    pain_level INTEGER,
    notes TEXT
);

5.入门

安装

# Clone and navigate to the repo
cd personal-health-mcp-system

# Use uv to sync dependencies
uv sync

数据库设置

初始化SQLite数据库：

uv run init-db

这创造了 data/health.db 根据上面的模式。

运行服务器

有关所有可用脚本的信息，请参阅 scripts/README.md.

HTTP（开发）：

scripts/shell/run_http.sh

HTTPS（外部访问）：

scripts/shell/run_https.sh

API将在以下网址提供：

HTTP： http://localhost:8080
HTTPS： https://localhost:8443
OpenAPI文档： /docs
MCP端点： /mcp （SSE协议）

运行测试

uv run pytest tests/ -v

代码质量

预提交钩子在提交时自动运行：

uv run pre-commit run --all-files

6.MCP集成

概述

该系统公开了一个 模型上下文协议（MCP） 端点位于 /mcp 用于AI代理集成。MCP层用JSON-RPC 2.0兼容的发现和调用封装REST端点。

ChatGPT快速入门

启动HTTPS服务器：
```
./scripts/run_https.sh
```
通过ngrok曝光：
```
ngrok http https://localhost:8443
```
配置ChatGPT：
- 订阅Plus或更高版本，请访问chat.openai.com
- 前往设置→ 应用程序和连接器，然后选择创建
- 使用ngrok HTTPS URL完成表单操作
使用自然语言：
- “添加今天的健康条目：披萨、2瓶啤酒、压力4、睡眠7.5小时”
- “显示我上周的健康记录”
- “总结我过去7天的健康数据”

幂等性

具有相同值的重复条目 所有领域 （日期、用餐、酒精、压力、睡眠小时数、疼痛程度、笔记）被删除：

相同的字段值→ same entry_id （确定性哈希）
未创建重复的数据库行
使用现有ID始终返回200 OK

要更新上下文，请执行以下操作： 使用 update_entry 在不创建新条目的情况下修改特定字段（例如notes、pain_level）的操作。

文档

OpenAPI/Swagger用户界面： 访问 http://localhost:8080/docs 当服务器正在运行包含模式和示例的完整API文档时
重新记录： 替代文件位于 http://localhost:8080/redoc

7.管道模型

功能工程：
- 将分类文本（膳食、酒精）转换为二元特征。
- 添加滞后特征（前一天饮酒、平均滚动压力）。
- 计算汇总统计数据。
培训：
```
uv run train-model --db data/health.db
```
- 输出：model.pkl
预测服务：
- 服务器启动时加载模型。
- predict_next_day 电话 predictor.py

模型选择

随机森林回归器因其鲁棒性、处理非线性关系的能力、抗过拟合性和处理缺失数据而被选为疼痛预测模型。健康数据很少遵循线性模式，因此该模型有助于捕捉膳食、酒精、压力、睡眠时间和疼痛水平等特征之间的复杂相互作用。此外，随机森林不需要对数字特征进行缩放，该模型可以提供特征重要性见解，这对于理解哪些因素对疼痛水平影响最大非常有价值。

特征工程

为疼痛预测模型设计了以下功能：

滞后特征： 回顾窗口使用前7天的压力、睡眠时间和疼痛水平（例如。， stress_d7, sleep_d7, pain_d7).
- 这些捕获了数据中的时间模式和趋势，使模型能够从最近的历史中学习。
- 零填充允许一些缺失的条目，生成滞后特征至少需要3天的时间。
- 例如，如果用户在过去一周内压力很大，或者睡眠时间不好，模型可能会学会将这些模式与第二天更高的疼痛水平联系起来。
星期几编码： 表示一周中的某一天（例如，星期一、星期二）的分类特征，以捕获健康数据中的每周模式。
- 例如，与周末相比，工作日的压力水平可能更高，或者睡眠模式可能因一周中的不同而不同。
汇总统计信息： 过去一周的平均/最大压力、睡眠和疼痛水平，以捕捉整体趋势。
- 这些功能总结了用户最近的健康状况，可以帮助模型识别可能影响疼痛水平的总体模式。

使用的指标

以下指标用于评估疼痛预测模型的性能：

平均绝对误差（MAE）：
- 测量原始单位的平均预测误差（痛点）
- 示例：MAE为1.5意味着预测平均偏离±1.5个痛点
- 为什么：对健康背景的直观解释
均方根误差（RMSE）：
- 比MAE更能惩罚较大的错误，从而洞察偶尔的重大失误
- 示例：RMSE为2.0表示预测精度的方差
- 原因：有助于识别模型是否偶尔出现大失误，还是持续出现小错误
R平方分数（决定系数）：
- 衡量模型对疼痛水平的解释程度（0.0到1.0）
- 示例：R平方为0.75表示模型解释了疼痛水平75%的方差
- 原因：表明整体预测能力和实用性

R平方分数历史

最初的训练忽略了饮食和酒精特征，导致R平方分数为负。我们也可能一直在预测平均疼痛水平。

该分数首次表明模型表现不佳，并导致人们意识到模型中缺少关键的生活方式因素（饮食和酒精）。在包含这些特性之后。..将继续。..>.

扩展学习技巧

目前，该项目主要旨在通过实践提供学习，而不是在真实数据集上实现生产就绪模型或现实预测。初始模型是在一个小的、部分策划的数据集上训练的，该数据集不代表现实世界数据的复杂性或大小。事实上，该模型可能无法很好地推广到现实世界的数据。

未来的增强工作应包括扩展数据集，扩展特征集，以包括膳食类型、酒精类型、其他物质类型、其他生活方式因素、食品成分和已知过敏原的向量。将膳食和酒精分为更颗粒的类型（如辛辣食物、红酒）可能有助于识别疼痛触发模式。特征之间的相互作用也可能很重要，例如压力x睡眠相互作用，或饮食x酒精相互作用。

不同型号

考虑到简单而小的数据集，线性回归模型可能更适合项目的初始版本。

扩展评分技术

除了标准回归指标（MAE、RMSE、R平方）外，还应实施额外的评分技术，以便更好地评估性能，因为引入了额外的特征，并在更大的数据集上训练了模型。这些可能包括：

列车与测试
- 有助于了解是否需要更多数据来避免过拟合。
- 原因：较大的差距表明过拟合。
平均绝对百分比误差（MAPE）：
- 测量预测误差占实际值的百分比
- 示例：MAPE为20%意味着预测平均偏差为20%
- 原因：有助于理解健康背景下的相对误差，特别是当疼痛水平在个体之间可能存在很大差异时。1点误差可能更为显著
绝对误差中位数（MedAE）：
- 测量绝对误差的中位数，提供对不受异常值影响的典型误差的洞察。
- 示例：如果MAE=0.83，但MedAE=0.5，则存在一些较大的失误。
- 为什么：比MAE更强大。在健康数据中，异常值可能是由于异常事件（例如，特别紧张的一天或睡眠不佳的一晚）造成的，MedAE可以提供更具代表性的典型模型性能指标。
最大误差：
- 测量预测中最大的单一误差。
- 示例：最大误差为5意味着至少有一个预测偏离了5个痛点。
- 原因：确定最坏的情况，这可能会发现其他表现良好的模型中的失误。在健康背景下，大误差可能表明严重的错误预测，可能需要进一步调查或模型改进。
分箱将疼痛水平分为类别（例如，低、中、高）并评估这些类别的分类指标（准确性、精确度、召回率），可以提供更多关于模型在预测临床相关疼痛阈值方面表现如何的见解。

8.工作流程示例

# Add new entry
curl -X POST localhost:8080/add_entry \
     -H "Content-Type: application/json" \
     -d '{"meal":"tacos","alcohol":"beer","stress":4,"pain_level":6,"notes":"felt bloated"}'

# Get week summary
curl localhost:8080/summarize_recent?window_days=7

# Run next-day prediction
curl localhost:8080/predict_next_day?date=2025-10-24

9.可选集成

•Apple Health/Fitbit：用于睡眠、步数、心率的REST或CSV导入。 •电子邮件/Slack摘要：通过webhook提交每日或每周健康报告。 •MLflow或DVC：模型版本跟踪和实验记录。

10.下一步

看相位.md 了解详细的后续步骤。

[x] 使用上述架构构建FastAPI项目。
[x] 实现/add_entry和/get_entries。
[]为相关性可视化构建培训笔记本（笔记本/eda.ipynb）。
[x] 训练基线逻辑回归模型。
[x] 添加/prict_next_day端点。
[x] 扩展到MCP兼容规范（可调用函数的JSON模式）。