Fitness Coach MCP

🚀 健康与健身教练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服务器充当一个智能健身数据网关，具有以下功能：

1. 🔗 连接AI与健身数据
   • 将自然语言的健身查询转换为结构化的数据操作。
   • 使AI工具能够读取、写入和分析你的健身信息。
   • 根据你的实际健身历史提供上下文感知的响应。
2. 🧠 实现智能教练功能
   • AI可以询问：“我本周做了哪些锻炼？” → MCP获取并分析你的数据。
   • AI可以建议：“创建一个锻炼计划” → MCP生成个性化的锻炼例程。
   • AI可以跟踪：“记录我30分钟的跑步” → MCP存储并更新你的进度。
3. 📊 提供丰富的上下文信息
   • 当你向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智能与现实世界的健身数据连接起来