HevyMCP - AI-Powered Fitness Assistant

🚀 HevyMCP - AI 驱动的健身助手与 MCP 服务

HevyMCP 是面向 Hevy 健身应用的 AI 驱动 Model Context Protocol（MCP）服务。它支持你使用自然语言、网页界面或 Claude 和 ChatGPT 等 AI 助手记录训练、搜索动作、管理训练计划等。

---

🌟 功能

• 使用自然语言记录训练（“卧推 3 组 × 8 次，重量 135 磅”）
• 智能动作匹配（模糊匹配、NLP、用户偏好）
• 训练计划和文件夹管理
• Webhook 订阅
• 现代化网页界面（演示模式和真实模式）
• 面向 AI 助手的 MCP 服务

---

⚡ 快速开始

🎮 在 Playground 中试用（无需安装）

通过我们的 Smithery Playground 即刻体验 HevyMCP：

npx -y @smithery/cli install hevymcp --client claude

或者访问：Smithery MCP Registry，搜索“hevymcp”

📦 本地安装

1. 安装依赖

pip install -r requirements.txt

2. 设置 Hevy API 密钥（用于真实使用）

# Create .env file
echo "HEVY_API_KEY=your_hevy_api_key_here" > .env

3. 运行网页界面

python -m uvicorn app.main:app --reload --port 8000

• 访问：http://localhost:8000

演示模式（无需 API 密钥，仅使用示例数据）：

export DEMO_MODE=true
python -m uvicorn app.main:app --reload --port 8000

---

🖥️ 网页界面

• 立即试用训练记录、搜索和肌群浏览功能。
• **演示模式：**仅供公开演示网站使用。无需 API 密钥，可安全公开使用，仅提供示例数据。
• **真实模式：**供本地安装使用。输入 API 密钥即可真实记录（仅限本地使用，绝不会发送给第三方）。请勿在本地使用演示模式。

---

🛠️ API 端点（面向开发者）

训练计划

• GET /mcp/routines — 列出所有训练计划
• POST /mcp/routines — 创建训练计划
• GET /mcp/routines/{routine_id} — 按 ID 获取训练计划
• PUT /mcp/routines/{routine_id} — 更新训练计划

训练计划文件夹

• GET /mcp/routine-folders — 列出所有文件夹
• POST /mcp/routine-folders — 创建文件夹
• GET /mcp/routine-folders/{folder_id} — 按 ID 获取文件夹

Webhook

• GET /mcp/webhooks — 列出所有 Webhook 订阅
• POST /mcp/webhooks — 创建 Webhook
• DELETE /mcp/webhooks/{webhook_id} — 删除 Webhook

其他端点

• POST /mcp/workout — 记录训练（NLP）
• GET /mcp/workouts — 列出近期训练
• GET /mcp/exercises/search?query=bench — 搜索动作
• GET /mcp/exercises/muscle-groups — 列出肌群

---

🤖 MCP 工具（面向 AI 助手）

训练工具

• log_workout — 使用自然语言记录训练（“卧推 3 组 × 8 次，重量 135 磅”）
• get_workout_history — 分页列出近期训练
• get_workout_count — 获取训练统计总数
• get_workout_events — 获取训练更新/删除事件

动作工具

• search_exercises — 使用模糊匹配按名称搜索动作
• get_muscle_groups — 列出所有可用肌群
• get_exercises_by_muscle_group — 按肌群筛选并获取动作
• update_exercise_template — 修改现有动作模板
• delete_exercise_template — 删除动作模板

训练计划管理

• list_routines — 分页列出所有训练计划
• create_routine — 创建训练计划
• get_routine — 按 ID 获取指定训练计划
• update_routine — 修改现有训练计划
• delete_routine — 删除训练计划

文件夹整理

• list_routine_folders — 列出所有训练计划文件夹
• create_routine_folder — 创建整理用文件夹
• get_routine_folder — 按 ID 获取文件夹详情
• update_routine_folder — 修改文件夹属性
• delete_routine_folder — 删除文件夹

Webhook 集成

• list_webhooks — 列出所有 Webhook 订阅
• create_webhook — 创建实时事件订阅
• delete_webhook — 删除 Webhook 订阅

---

🧩 API 结构（面向贡献者）

• app/integrations/hevy_api.py — Hevy API 客户端（在此添加新端点）
• app/endpoints/ — FastAPI 端点（在此添加新路由）
• app/mcp_server.py — MCP 工具定义和处理程序
• app/web_interface.py — Web UI 逻辑（演示模式和真实模式）

---

🛡️ 安全与隐私

• 演示模式： 无需 API 密钥，不保存数据，适合公开演示。
• 真实模式： API 密钥仅在本地使用，绝不会发送给第三方。
• 切勿在公共或共享服务上输入真实的 API 密钥！

---

🤝 参与贡献

1. Fork 此仓库并将其克隆到本地。
2. 创建虚拟环境：

   python -m venv venv
   source venv/bin/activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 添加新端点/工具：
   • 添加到 hevy_api.py（API 客户端）
   • 添加到 endpoints/（FastAPI）
   • 添加到 mcp_server.py（MCP 工具）
5. 提交拉取请求！

---

💬 有疑问？

• 在 GitHub 上提交议题或发起讨论。
• 欢迎提交 PR 和反馈！