# Sport Health MCP

一个本地优先的华为运动健康分析 MCP Server。用户只需提供一次
`HUAWEI_HEALTH_*` 个人数据导出包，Agent 即可读取运动表现、运动内生理指标、
运动前后健康背景，并按需补充历史天气与空气质量。

> 本项目用于运动复盘，不提供医疗诊断或治疗建议。

## 当前能力

- 识别华为个人数据导出目录及核心 JSON 文件。
- 容错解析华为非标准 JSON 数字键。
- 解析运动摘要、GPS 轨迹、心率、步频、速度、海拔和训练负荷。
- 聚合运动前一天、当天、后一天的心率、静息心率、HRV、压力、血氧和睡眠阶段。
- 调用 Open-Meteo 历史天气与空气质量 API，并在本地缓存响应。
- 通过 MCP 提供分页数据工具和报告证据包。

## 安装

建议使用 Python 3.11 或更新版本，并在项目目录创建虚拟环境：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
```

华为导出包不会被打包或提交，`.gitignore` 默认忽略所有 `HUAWEI_HEALTH_*` 目录。

## 本地检查

项目目录中只有一个 `HUAWEI_HEALTH_*` 文件夹时会自动识别：

```powershell
sport-health-inspect inspect
sport-health-inspect list
```

也可以显式指定：

```powershell
sport-health-inspect --export-dir "D:\HealthData\HUAWEI_HEALTH_xxx" list
```

## 启动 MCP Server

本地 Agent 推荐使用 `stdio`：

```powershell
$env:SPORT_HEALTH_EXPORT_DIR="D:\HealthData\HUAWEI_HEALTH_xxx"
sport-health-mcp
```

MCP 客户端配置的核心形式如下，实际字段名以客户端为准：

```json
{
  "mcpServers": {
    "sport-health": {
      "command": "C:\\sport-health-mcp\\.venv\\Scripts\\sport-health-mcp.exe",
      "env": {
        "SPORT_HEALTH_EXPORT_DIR": "D:\\HealthData\\HUAWEI_HEALTH_xxx"
      }
    }
  }
}
```

### 注册到 MCP 客户端

在支持 MCP `stdio` 的客户端中添加前述 `command` 和 `env` 配置，保存后重启客户端。
不同客户端的配置文件位置和外层字段名称可能不同，请以对应客户端文档为准。

### 在不同 Agent 中使用

- 同一台电脑：每个支持 MCP `stdio` 的 Agent 都可以启动同一个 Server，但需要按该
  Agent 的配置格式注册一次。
- 其他用户的电脑：安装本项目、导出自己的 `HUAWEI_HEALTH_*` 数据包，并把配置中的
  命令和数据目录替换为自己的绝对路径。

项目不会共享作者的华为数据包。MCP Server 是通用程序，每位用户的数据仍保存在其本机。

## MCP 工具

- `inspect_huawei_export`: 检查数据包完整性。
- `list_activities`: 列出运动。
- `get_activity_summary`: 查询单次运动摘要。
- `get_activity_track`: 分页查询 GPS 轨迹。
- `get_activity_samples`: 分页查询心率、步频、速度和海拔样本。
- `get_health_context`: 查询运动前后多日健康背景。
- `get_activity_environment`: 获取并缓存历史环境数据。
- `get_report_evidence_pack`: 生成供 Agent 写报告的确定性证据包。
- `get_report_contract`: 获取固定的报告章节、篇幅和写作约束。

建议 Agent 先调用 `list_activities`，选定 `activity_id` 后优先调用
`get_report_evidence_pack`，并严格按照返回的 `report_contract` 输出报告。固定格式只保留
核心判断、表现分析、身体反应和训练建议，避免复述设备应用已经展示的完整指标。
只有需要查看原始曲线或轨迹时，才调用分页明细工具。

## 测试

无需安装测试框架也可运行标准库测试：

```powershell
$env:PYTHONPATH="src"
python -m unittest discover -s tests -v
```

测试只使用代码生成的合成运动记录，不依赖或包含任何个人导出数据。

## 隐私边界

- 原始健康数据默认仅在本机读取。
- 只有环境增强工具会访问网络，仅发送路线中心点、日期和小时范围。
- MCP 工具只读，不修改华为导出文件。
- 对外分享日志或问题报告前，应移除坐标、时间、设备标识和健康指标。
- 发布源码前不要直接压缩整个工作目录；应使用版本控制导出或发布构建产物，避免把已忽略的个人数据目录一并打包。

## 开源许可

本项目采用 [MIT License](LICENSE)。提交安全问题前请阅读 [SECURITY.md](SECURITY.md)，
不要在公开 Issue 中上传真实健康数据、GPS轨迹、环境缓存或包含本地路径的日志。

## 第三方服务与商标

- 环境数据由 [Open-Meteo](https://open-meteo.com/) 提供，数据采用
  [CC BY 4.0](https://open-meteo.com/en/license)，展示时必须保留来源和许可信息。
- Open-Meteo免费API仅限非商业用途并受调用配额约束。商业使用应采用其商业接口或按
  官方许可自行部署，详见 [Open-Meteo Terms](https://open-meteo.com/en/terms)。
- 本项目是独立社区项目，与华为官方不存在隶属、授权或背书关系。相关产品名称和商标归各自权利人所有。