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智能與現實世界的健身數據連接起來