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