Fitness Coach MCP

🚀 健康与健身教练MCP 💪

健康与健身教练MCP是一款全面的AI健身追踪应用程序，它通过模型上下文协议（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桌面版配置

{
  "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集成

本项目由两个主要组件构成：

1. 🌐 Web应用程序：一个现代的Next.js健身仪表盘，用于记录活动和跟踪进度。
2. 🤖 MCP服务器：一个符合协议的服务器，使AI工具（如Cursor、Claude Desktop等）能够智能地与您的健身数据进行交互。

系统架构如下：

┌─────────────────────────────────────────────────────────────────────────────┐
│                    健康与健身教练生态系统                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────┐  │
│  │   🌐 WEB应用        │    │   🤖 MCP服务器      │    │  🧠 AI客户端    │  │
│  │   (Next.js)         │    │   (协议层)          │    │  (Cursor/Claude) │  │
│  │                     │    │                     │    │                 │  │
│  │ • 健身仪表盘        │◄──►│ • 7个智能工具      │◄──►│ • 自然语言交互  │  │
│  │ • 活动记录          │    │ • 数据处理          │    │ • 上下文感知    │  │
│  │ • 进度跟踪          │    │ • 上下文分析        │    │ • 计划生成      │  │
│  │ • 计划可视化        │    │ • API集成           │    │ • 智能查询      │  │
│  │ • 实时更新          │    │ • 协议合规性        │    │ • 工具调用      │  │
│  └─────────────────────┘    └─────────────────────┘    └─────────────────┘  │
│           │                           │                           │          │
│           └───────────────────────────┼───────────────────────────┘          │
│                                       │                                      │
│  ┌─────────────────────────────────────▼─────────────────────────────────────┐ │
│  │                     📊 统一数据层                                       │ │
│  │                                                                         │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │ │
│  │  │ 🏋️ 锻炼记录 │  │ 🍎 营养记录 │  │ 📋 计划记录 │  │ 💭 反馈记录 │   │ │
│  │  │ • 锻炼时段  │  │ • 餐食信息  │  │ • AI生成计划 │  │ • 进度反馈  │   │ │
│  │  │ • 持续时间  │  │ • 卡路里摄入 │  │ • 每周计划  │  │ • 笔记信息  │   │ │
│  │  │ • 锻炼类型  │  │ • 食物项目  │  │ • 每日计划  │  │ • 洞察分析  │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │ │
│  └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

MCP服务器的作用

模型上下文协议（MCP） 是AI应用程序连接外部数据源和工具的标准化方式。我们的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分钟的俯卧撑锻炼。您今日的锻炼目标已完成15/60分钟。” │
└─────────────────────────────────────────────────────────────────────────────┘

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应用而言

• 🧠 专业领域知识：具备专业的健身知识和数据处理能力。
• 📋 结构化数据：提供干净、有组织的健身信息，便于分析。
• ⚡ 实时更新：实时同步数据，确保信息的及时性。
• 🎨 丰富的响应：提供上下文相关的个性化健身教练响应。

🔧 技术细节

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)

🚀 部署选项

本地开发

• 运行 npm run dev 启动开发服务器。
• MCP服务器可通过 http://localhost:3000/mcp 访问。
• Web界面可通过 http://localhost:3000 访问。

生产部署

• 一键部署到Vercel。
• 配置环境变量（OPENAI_API_KEY）。
• MCP服务器将自动在您的域名下可用。

自定义部署

• 支持Docker容器化部署。
• 可通过环境变量配置不同的部署设置。
• 具有可扩展的架构，适用于多用户场景。

🔧 环境配置

必需的变量

# 用于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智能与现实世界的健身数据相连接