Sport Health MCP

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

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

当前能力

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

安装

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

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

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

本地检查

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

sport-health-inspect inspect
sport-health-inspect list

也可以显式指定：

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

启动 MCP Server

本地 Agent 推荐使用 stdio：

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

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

{
  "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_* 数据包，并把配置中的 命令和数据目录替换为自己的绝对路径。
• 网页端或云端 Agent：无法访问用户电脑上的本地 stdio 进程。若要支持这类客户端， 需要另行提供带认证的 Streamable HTTP 部署，并设计加密上传、用户隔离、数据删除和 隐私合规机制。

项目不会共享作者的华为数据包。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 输出报告。固定格式只保留 核心判断、表现分析、身体反应和训练建议，避免复述设备应用已经展示的完整指标。 只有需要查看原始曲线或轨迹时，才调用分页明细工具。

测试

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

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

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

隐私边界

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

开源许可

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

第三方服务与商标

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