Scan to contactarticle
README
🚀 健康与健身教练MCP 💪
健康与健身教练MCP是一款由人工智能驱动的综合健身跟踪应用程序，它通过模型上下文协议（MCP） ，弥合了传统健身应用与智能AI辅助之间的差距。
🚀 快速开始
1. 设置MCP服务器
git clone https://github.com/your-username/health-fitness-coach-mcp.git
cd health-fitness-coach-mcp
npm install
cp env.example .env.local
# 添加用于AI生成计划的OPENAI_API_KEY
npm run dev
2. 连接到AI工具
Cursor配置
{
"mcpServers": {
"health-fitness-coach": {
"url": "http://localhost:3000/sse"
}
}
}
Claude Desktop配置
{
"mcpServers": {
"health-fitness-coach": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
}
}
}
3. 测试集成
# 直接测试MCP工具
npm run test:fitness
# 测试特定端点
curl http://localhost:3000/api/context?userId=default-user
4. 开始使用
- Web应用：访问
http://localhost:3000进行可视化健身跟踪 - AI集成：向你的AI助手询问与健身相关的问题
- 自然语言交互：例如 “记录我的锻炼”、“创建一个计划”、“我目前的情况如何？”
✨ 主要特性
系统架构与MCP集成
┌─────────────────────────────────────────────────────────────────────────────┐
│ 健康与健身教练生态系统 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────┐ │
│ │ 🌐 Web应用 │ │ 🤖 MCP服务器 │ │ 🧠 AI客户端 │ │
│ │ (Next.js) │ │ (协议层) │ │ (Cursor/Claude) │ │
│ │ │ │ │ │ │ │
│ │ • 健身仪表盘 │◄──►│ • 7个智能工具 │◄──►│ • 自然语言交互 │ │
│ │ • 活动记录 │ │ • 数据处理 │ │ • 上下文感知 │ │
│ │ • 进度跟踪 │ │ • 上下文分析 │ │ • 计划生成 │ │
│ │ • 计划可视化 │ │ • API集成 │ │ • 智能查询 │ │
│ │ • 实时更新 │ │ • 协议合规性 │ │ • 工具调用 │ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ └───────────────────────────┼───────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────▼─────────────────────────────────────┐ │
│ │ 📊 统一数据层 │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 🏋️ 锻炼记录 │ │ 🍎 营养记录 │ │ 📋 计划记录 │ │ 💭 反馈记录 │ │ │
│ │ │ • 锻炼会话 │ │ • 饮食记录 │ │ • AI生成计划 │ │ • 进度记录 │ │ │
│ │ │ • 持续时间 │ │ • 卡路里摄入│ │ • 每周计划 │ │ • 笔记记录 │ │ │
│ │ │ • 锻炼类型 │ │ • 食物项目 │ │ • 每日计划 │ │ • 洞察记录 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
MCP服务器的作用
模型上下文协议（MCP）解释
模型上下文协议（MCP） 是AI应用程序连接到外部数据源和工具的标准化方式。可以将其视为一个通用翻译器，使Claude Desktop或Cursor等AI助手能够理解和与你的健身数据进行交互。
MCP服务器在本应用中的角色
我们的MCP服务器充当一个智能健身数据网关，具有以下功能：
- 🔗 连接AI与健身数据
- 将自然语言的健身查询转换为结构化的数据操作。
- 使AI工具能够读取、写入和分析你的健身信息。
- 根据你的实际健身历史提供上下文感知的响应。
- 🧠 实现智能教练功能
- AI可以询问：“我本周做了哪些锻炼？” → MCP获取并分析你的数据。
- AI可以建议：“创建一个锻炼计划” → MCP生成个性化的锻炼例程。
- AI可以跟踪：“记录我30分钟的跑步” → MCP存储并更新你的进度。
- 📊 提供丰富的上下文信息
- 当你向AI寻求健身建议时，它可以访问你的完整历史记录。
- AI可以识别模式、提出改进建议并跟踪长期进展。
- 根据你的实际表现数据提供个性化的教练服务。
MCP服务器工具与功能
MCP服务器提供了7个智能工具，改变了AI与健身数据的交互方式：
核心记录工具
log-workout - 锻炼会话跟踪
// 功能：使用智能分类记录锻炼会话
{
tool: "log-workout",
parameters: {
userId: "user123",
date: "2025-01-07",
type: "strength training", // 自动分类：有氧运动、力量训练、柔韧性训练
duration: 45, // 活动持续时间（分钟）
distance: 0 // 有氧运动可选参数
}
}
// AI上下文：“我今天进行了45分钟的力量训练”
log-nutrition - 饮食与卡路里跟踪
// 功能：使用智能营养分析记录饮食
{
tool: "log-nutrition",
parameters: {
userId: "user123",
date: "2025-01-07",
meal: "breakfast", // 自动检测：早餐/午餐/晚餐/零食
items: ["oatmeal", "banana", "almonds"], // 自然语言描述的食物项目
calories: 350 // 计算或估算的卡路里
}
}
// AI上下文：“我早餐吃了燕麦片、香蕉和杏仁”
log-feedback - 进度与动力跟踪
// 功能：捕获主观的健身体验和进度笔记
{
tool: "log-feedback",
parameters: {
userId: "user123",
date: "2025-01-07",
notes: "经过持续锻炼，感觉更强壮了。准备挑战更重的重量！"
}
}
// AI上下文：跟踪动力、能量水平和主观进度
智能与规划工具
generate-plan - AI驱动的健身规划
// 功能：创建个性化的锻炼和营养计划
{
tool: "generate-plan",
parameters: {
userId: "user123"
}
}
// AI魔法：分析你的历史记录、偏好和目标，创建：
// - 明天的锻炼例程
// - 每周锻炼计划
// - 饮食建议
// - 逐步增加难度的调整
view-context - 全面的健身分析
// 功能：为AI决策提供完整的健身资料
{
tool: "view-context",
parameters: {
userId: "user123"
}
}
// 返回：完整的健身历史记录、模式、目标和洞察信息
// 使AI能够做出明智的教练决策
set-weekly-target - 目标设定与跟踪
// 功能：设定和跟踪健身目标
{
tool: "set-weekly-target",
parameters: {
userId: "user123",
weekStart: "2025-01-06",
targetRuns: 3, // 每周有氧运动目标
calorieBudget: 2000 // 每日卡路里目标
}
}
// AI上下文：实现以目标为导向的教练服务和进度跟踪
实用工具
echo - 系统健康与测试
// 功能：测试MCP连接和系统健康状况
{
tool: "echo",
parameters: {
message: "Testing MCP connection"
}
}
// 使用场景：调试和确保MCP服务器响应正常
MCP数据流与AI集成
AI查询如何转化为健身行动
┌─────────────────────────────────────────────────────────────────────────────┐
│ MCP数据流 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ AI工具中的用户：“我今天做了20个俯卧撑，持续了15分钟” │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────┐ │
│ │ 🧠 AI处理 │ │ 🤖 MCP协议层 │ │ 📊 数据存储 │ │
│ │ │ │ │ │ │ │
│ │ • 解析意图 │───►│ • 工具选择 │───►│ • 存储锻炼记录 │ │
│ │ • 提取数据 │ │ • 参数映射 │ │ • 更新统计信息 │ │
│ │ • 选择操作 │ │ • 执行工具调用 │ │ • 计算进度 │ │
│ │ • 格式化响应 │◄───│ • 返回结果 │◄───│ │ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ AI响应：“太棒了！我已经记录了你15分钟的俯卧撑锻炼。你今天的锻炼目标是60分钟，目前已完成15分钟。” │
└─────────────────────────────────────────────────────────────────────────────┘
Web应用与MCP服务器集成
┌─────────────────────────────────────────────────────────────────────────────┐
│ 双接口系统 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ 🌐 Web界面 │ │ 🤖 AI界面 │ │
│ │ │ │ │ │
│ │ • 可视化仪表盘 │ │ • 自然语言交互 │ │
│ │ • 点击记录功能 │ │ • 上下文查询 │ │
│ │ • 进度图表展示 │ │ • 智能规划 │ │
│ │ • 计划显示功能 │ │ • 模式分析 │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 🔄 MCP服务器核心 │ │
│ │ │ │
│ │ • 为两个接口提供统一的数据访问 │ │
│ │ • 一致的业务逻辑和验证机制 │ │
│ │ • Web和AI之间的实时同步 │ │
│ │ • 智能缓存和性能优化 │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
实际使用场景
场景1：每日锻炼记录
👤 Cursor中的用户：“我刚刚完成了30分钟的HIIT锻炼”
🤖 AI + MCP处理流程：
1. AI识别锻炼记录意图
2. MCP调用 `log-workout` 工具
3. 存储：锻炼类型="HIIT"，持续时间=30，日期=今天
4. 更新每日进度计数器
5. AI回复鼓励信息并更新进度
📱 Web应用：自动显示更新后的锻炼时长和锻炼完成情况
场景2：智能计划生成
👤 Claude中的用户：“根据我本周的锻炼情况，为我创建一个明天的锻炼计划”
🤖 AI + MCP处理流程：
1. MCP调用 `view-context` 分析本周的锻炼活动
2. AI识别模式：主要是上肢锻炼，有氧运动较少
3. MCP调用 `generate-plan` 并提供上下文信息
4. 创建一个强调腿部锻炼和有氧运动的平衡计划
5. 存储明天的锻炼计划
📱 Web应用：明天的锻炼部分会填充AI生成的锻炼项目
场景3：营养指导
👤 AI工具中的用户：“我想吃得更健康，午餐应该吃什么？”
🤖 AI + MCP处理流程：
1. MCP调用 `view-context` 检查今天的饮食和卡路里目标
2. AI分析营养缺口和卡路里预算
3. 建议具体的饮食并提供卡路里计数
4. 用户确认：“我要吃烤鸡肉沙拉”
5. MCP调用 `log-nutrition` 记录饮食
📱 Web应用：更新营养进度和饮食历史记录
MCP集成的主要优势
对用户而言
- 🎯 个性化AI教练：AI可以全面了解你的健身历程
- 💬 自然交互：用简单的英语与AI交流健身目标
- 📊 智能洞察：AI可以识别模式并提出改进建议
- 🔄 无缝体验：数据在Web应用和AI工具之间自动同步
对开发者而言
- 🔌 协议合规性：标准的MCP实现可以与任何MCP客户端配合使用
- 🛠️ 可扩展架构：易于添加新的工具和功能
- 📈 丰富的上下文信息：AI工具可以获取全面的健身数据，以便做出更好的决策
- 🔧 灵活部署：可以与Cursor、Claude Desktop或自定义AI工具配合使用
对AI应用而言
- 🧠 领域专业知识：具备专业的健身知识和数据处理能力
- 📋 结构化数据：干净、有组织的健身信息，便于分析
- ⚡ 实时更新：实时数据同步，提供最新信息
- 🎨 丰富的响应：基于上下文的个性化健身教练响应
📦 安装指南
本地开发
- 运行
npm run dev启动开发服务器 - MCP服务器可通过
http://localhost:3000/mcp访问 - Web界面可通过
http://localhost:3000访问
生产部署
- 点击一键按钮部署到Vercel
- 配置环境变量（OPENAI_API_KEY）
- MCP服务器将自动在你的域名下可用
自定义部署
- 支持使用Docker进行容器化部署
- 可根据不同的设置配置环境变量
- 可扩展的架构，适用于多用户场景
💻 使用示例
基础用法
// 使用log-workout工具记录锻炼
{
tool: "log-workout",
parameters: {
userId: "user123",
date: "2025-01-07",
type: "strength training",
duration: 45,
distance: 0
}
}
高级用法
// 使用generate-plan工具生成个性化锻炼计划
{
tool: "generate-plan",
parameters: {
userId: "user123"
}
}
🔧 技术细节
MCP协议合规性
// 符合MCP的工具定义
export const logWorkoutTool = {
name: "log-workout",
description: "记录锻炼会话，包括锻炼类型、持续时间和可选的距离",
inputSchema: {
type: "object",
properties: {
userId: { type: "string", description: "唯一的用户标识符" },
date: { type: "string", description: "日期，格式为YYYY-MM-DD" },
type: { type: "string", description: "锻炼类型（例如，'跑步'、'力量训练'）" },
duration: { type: "number", description: "持续时间（分钟）" },
distance: { type: "number", description: "距离（公里，可选）" }
},
required: ["userId", "date", "type", "duration"]
}
}
数据存储与检索
// 带有持久化钩子的内存存储
export const workoutStore = createInMemoryStore<WorkoutEntry>()
export const nutritionStore = createInMemoryStore<NutritionEntry>()
export const planStore = createInMemoryStore<PlanEntry>()
// MCP工具实现
export async function logWorkout(params: LogWorkoutParams) {
const entry: WorkoutEntry = {
id: generateId(),
userId: params.userId,
date: params.date,
type: params.type,
duration: params.duration,
distance: params.distance,
timestamp: new Date().toISOString()
}
workoutStore.set(entry.id, entry)
return { success: true, entry }
}
AI集成层
// 与MCP集成的聊天接口
export async function processFitnessQuery(message: string, userId: string) {
const intent = detectIntent(message)
switch (intent.type) {
case 'log_workout':
return await callMCPTool('log-workout', {
userId,
date: intent.date,
type: intent.workoutType,
duration: intent.duration
})
case 'generate_plan':
return await callMCPTool('generate-plan', { userId })
case 'view_progress':
return await callMCPTool('view-context', { userId })
}
}
🧪 测试与开发
可用的测试脚本
# 测试所有MCP工具
npm run test:fitness
# 测试HTTP传输
npm run test:http
# 测试MCP集成
npm run test:mcp
# 调试工具功能
npm run debug:tools
MCP工具测试
// 测试锻炼记录
const result = await mcpClient.callTool('log-workout', {
userId: 'test-user',
date: '2025-01-07',
type: 'running',
duration: 30,
distance: 5.0
})
console.log('锻炼记录成功:', result)
🔧 环境配置
必需变量
# 用于AI生成健身计划的OpenAI API密钥
OPENAI_API_KEY=your_openai_api_key_here
# 可选的Redis，用于提高性能
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token
可选配置
# 单用户设置的自定义用户ID
DEFAULT_USER_ID=my-fitness-journey
# 调试日志级别
LOG_LEVEL=debug
# 开发用的自定义端口
PORT=3000
🤝 贡献与扩展
添加新的MCP工具
// 在tools/目录下创建新工具
export const myCustomTool = {
name: "my-custom-tool",
description: "此工具的功能描述",
inputSchema: {
// 定义参数
},
handler: async (params) => {
// 实现逻辑
}
}
// 在tools/index.ts中注册
export const tools = [
// ... 现有工具
myCustomTool
]
扩展Web界面
- 在
components/目录下添加新组件 - 在
app/api/中创建新功能的API路由 - 在
app/page.tsx中更新主仪表盘
自定义AI集成
- 实现额外的MCP客户端
- 添加对其他AI平台的支持
- 创建自定义查询处理逻辑
📄 许可证
MIT许可证 - 你可以自由使用此项目作为自己的MCP服务器和健身应用的基础。
本项目展示了如何构建生产就绪的MCP服务器，将AI工具与特定领域的应用程序连接起来，为其他领域的类似集成提供了模板。
🤖 由模型上下文协议提供支持
将AI智能与现实世界的健身数据连接起来