README.md•23.6 kB
# Health & Fitness Coach MCP 💪
[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fyour-username%2Fhealth-fitness-coach-mcp&env=OPENAI_API_KEY)
<a href="https://cursor.com/install-mcp?name=health-fitness-coach&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAvc3NlIn0="><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add Health & Fitness Coach MCP server to Cursor" height="32" /></a>
## 🎯 What is this Project?
**Health & Fitness Coach MCP** is a comprehensive AI-powered fitness tracking application that bridges the gap between traditional fitness apps and intelligent AI assistance through the **Model Context Protocol (MCP)**.
This project consists of two main components:
1. **🌐 Web Application**: A modern Next.js fitness dashboard for logging activities and tracking progress
2. **🤖 MCP Server**: A protocol-compliant server that enables AI tools (Cursor, Claude Desktop, etc.) to interact with your fitness data intelligently
## 🏗️ System Architecture & MCP Integration
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ HEALTH & FITNESS COACH ECOSYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────┐ │
│ │ 🌐 WEB APP │ │ 🤖 MCP SERVER │ │ 🧠 AI CLIENTS │ │
│ │ (Next.js) │ │ (Protocol Layer) │ │ (Cursor/Claude) │ │
│ │ │ │ │ │ │ │
│ │ • Fitness Dashboard │◄──►│ • 7 Smart Tools │◄──►│ • Natural Lang │ │
│ │ • Activity Logging │ │ • Data Processing │ │ • Context Aware │ │
│ │ • Progress Tracking │ │ • Context Analysis │ │ • Plan Generate │ │
│ │ • Plan Visualization│ │ • API Integration │ │ • Smart Queries │ │
│ │ • Real-time Updates │ │ • Protocol Compliance│ │ • Tool Calling │ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ └───────────────────────────┼───────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────▼─────────────────────────────────────┐ │
│ │ 📊 UNIFIED DATA LAYER │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 🏋️ Workouts │ │ 🍎 Nutrition │ │ 📋 Plans │ │ 💭 Feedback │ │ │
│ │ │ • Sessions │ │ • Meals │ │ • AI-Gen │ │ • Progress │ │ │
│ │ │ • Duration │ │ • Calories │ │ • Weekly │ │ • Notes │ │ │
│ │ │ • Types │ │ • Items │ │ • Daily │ │ • Insights │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
```
## 🤖 What is the MCP Server and Why It Matters?
### **Model Context Protocol (MCP) Explained**
The **Model Context Protocol** is a standardized way for AI applications to connect to external data sources and tools. Think of it as a universal translator that allows AI assistants like Claude Desktop or Cursor to understand and interact with your fitness data.
### **MCP Server Role in This Application**
Our MCP server acts as an **intelligent fitness data gateway** that:
1. **🔗 Bridges AI and Fitness Data**
- Translates natural language fitness queries into structured data operations
- Enables AI tools to read, write, and analyze your fitness information
- Provides context-aware responses based on your actual fitness history
2. **🧠 Enables Intelligent Coaching**
- AI can ask: "What workouts did I do this week?" → MCP fetches and analyzes your data
- AI can suggest: "Create a workout plan" → MCP generates personalized routines
- AI can track: "Log my 30-minute run" → MCP stores and updates your progress
3. **📊 Provides Rich Context**
- When you ask AI for fitness advice, it has access to your complete history
- AI can identify patterns, suggest improvements, and track long-term progress
- Enables personalized coaching based on your actual performance data
## 🛠️ MCP Server Tools & Capabilities
The MCP server exposes **7 intelligent tools** that transform how AI interacts with fitness data:
### **Core Logging Tools**
#### `log-workout` - Exercise Session Tracking
```typescript
// What it does: Records workout sessions with intelligent categorization
{
tool: "log-workout",
parameters: {
userId: "user123",
date: "2025-01-07",
type: "strength training", // Auto-categorized: cardio, strength, flexibility
duration: 45, // Minutes of activity
distance: 0 // Optional for cardio workouts
}
}
// AI Context: "I did 45 minutes of strength training today"
```
#### `log-nutrition` - Meal & Calorie Tracking
```typescript
// What it does: Logs meals with smart nutritional analysis
{
tool: "log-nutrition",
parameters: {
userId: "user123",
date: "2025-01-07",
meal: "breakfast", // Auto-detected: breakfast/lunch/dinner/snack
items: ["oatmeal", "banana", "almonds"], // Natural language food items
calories: 350 // Calculated or estimated
}
}
// AI Context: "I had oatmeal with banana and almonds for breakfast"
```
#### `log-feedback` - Progress & Motivation Tracking
```typescript
// What it does: Captures subjective fitness experiences and progress notes
{
tool: "log-feedback",
parameters: {
userId: "user123",
date: "2025-01-07",
notes: "Feeling stronger after consistent workouts. Ready for heavier weights!"
}
}
// AI Context: Tracks motivation, energy levels, and subjective progress
```
### **Intelligence & Planning Tools**
#### `generate-plan` - AI-Powered Fitness Planning
```typescript
// What it does: Creates personalized workout and nutrition plans
{
tool: "generate-plan",
parameters: {
userId: "user123"
}
}
// AI Magic: Analyzes your history, preferences, and goals to create:
// - Tomorrow's workout routine
// - Weekly exercise schedule
// - Meal recommendations
// - Progressive difficulty adjustments
```
#### `view-context` - Comprehensive Fitness Analysis
```typescript
// What it does: Provides complete fitness profile for AI decision-making
{
tool: "view-context",
parameters: {
userId: "user123"
}
}
// Returns: Complete fitness history, patterns, goals, and insights
// Enables AI to make informed coaching decisions
```
#### `set-weekly-target` - Goal Setting & Tracking
```typescript
// What it does: Establishes and tracks fitness goals
{
tool: "set-weekly-target",
parameters: {
userId: "user123",
weekStart: "2025-01-06",
targetRuns: 3, // Weekly cardio goal
calorieBudget: 2000 // Daily calorie target
}
}
// AI Context: Enables goal-oriented coaching and progress tracking
```
### **Utility Tools**
#### `echo` - System Health & Testing
```typescript
// What it does: Tests MCP connectivity and system health
{
tool: "echo",
parameters: {
message: "Testing MCP connection"
}
}
// Usage: Debugging and ensuring MCP server is responsive
```
## 🔄 MCP Data Flow & AI Integration
### **How AI Queries Become Fitness Actions**
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ MCP DATA FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ User in AI Tool: "I did 20 push-ups for 15 minutes today" │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────┐ │
│ │ 🧠 AI PROCESSING │ │ 🤖 MCP PROTOCOL │ │ 📊 DATA STORE │ │
│ │ │ │ │ │ │ │
│ │ • Parse intent │───►│ • Tool selection │───►│ • Store workout │ │
│ │ • Extract data │ │ • Parameter mapping │ │ • Update stats │ │
│ │ • Choose action │ │ • Execute tool call │ │ • Calculate │ │
│ │ • Format response │◄───│ • Return results │◄───│ progress │ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ AI Response: "Great! I've logged your 15-minute push-up session. │
│ You're at 15/60 minutes for your daily workout goal." │
└─────────────────────────────────────────────────────────────────────────────┘
```
### **Web App ↔ MCP Server Integration**
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ DUAL-INTERFACE SYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ 🌐 WEB INTERFACE │ │ 🤖 AI INTERFACE │ │
│ │ │ │ │ │
│ │ • Visual dashboard │ │ • Natural language │ │
│ │ • Click logging │ │ • Context queries │ │
│ │ • Progress charts │ │ • Smart planning │ │
│ │ • Plan display │ │ • Pattern analysis │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 🔄 MCP SERVER CORE │ │
│ │ │ │
│ │ • Unified data access for both interfaces │ │
│ │ • Consistent business logic and validation │ │
│ │ • Real-time synchronization between web and AI │ │
│ │ • Intelligent caching and performance optimization │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
```
## 🎯 Real-World Usage Scenarios
### **Scenario 1: Daily Workout Logging**
```
👤 User in Cursor: "I just finished a 30-minute HIIT workout"
🤖 AI + MCP Process:
1. AI recognizes workout logging intent
2. MCP calls `log-workout` tool
3. Stores: type="HIIT", duration=30, date=today
4. Updates daily progress counters
5. AI responds with encouragement and progress update
📱 Web App: Automatically shows updated workout minutes and exercise completion
```
### **Scenario 2: Intelligent Plan Generation**
```
👤 User in Claude: "Create a workout plan for tomorrow based on what I did this week"
🤖 AI + MCP Process:
1. MCP calls `view-context` to analyze week's activities
2. AI identifies patterns: mostly upper body, low cardio
3. MCP calls `generate-plan` with context
4. Creates balanced plan emphasizing legs and cardio
5. Stores plan for tomorrow
📱 Web App: Tomorrow's workout section populates with AI-generated exercises
```
### **Scenario 3: Nutrition Guidance**
```
👤 User in AI: "I'm trying to eat healthier, what should I have for lunch?"
�� AI + MCP Process:
1. MCP calls `view-context` to check today's meals and calorie goals
2. AI analyzes nutritional gaps and calorie budget
3. Suggests specific meal with calorie count
4. User confirms: "I'll have the grilled chicken salad"
5. MCP calls `log-nutrition` to record the meal
📱 Web App: Updates nutrition progress and meal history
```
## 🌟 Key Benefits of MCP Integration
### **For Users**
- **🎯 Personalized AI Coaching**: AI has complete context of your fitness journey
- **💬 Natural Interaction**: Talk to AI in plain English about fitness goals
- **📊 Intelligent Insights**: AI can identify patterns and suggest improvements
- **🔄 Seamless Experience**: Data syncs between web app and AI tools automatically
### **For Developers**
- **🔌 Protocol Compliance**: Standard MCP implementation works with any MCP client
- **🛠️ Extensible Architecture**: Easy to add new tools and capabilities
- **📈 Rich Context**: AI tools get comprehensive fitness data for better decisions
- **🔧 Flexible Deployment**: Works with Cursor, Claude Desktop, or custom AI tools
### **For AI Applications**
- **🧠 Domain Expertise**: Specialized fitness knowledge and data processing
- **📋 Structured Data**: Clean, organized fitness information for analysis
- **⚡ Real-time Updates**: Live data synchronization for current information
- **🎨 Rich Responses**: Contextual, personalized fitness coaching responses
## 🚀 Quick Start Guide
### **1. Set Up the MCP Server**
```bash
git clone https://github.com/your-username/health-fitness-coach-mcp.git
cd health-fitness-coach-mcp
npm install
cp env.example .env.local
# Add OPENAI_API_KEY for AI-generated plans
npm run dev
```
### **2. Connect to AI Tools**
#### **Cursor Configuration**
```json
{
"mcpServers": {
"health-fitness-coach": {
"url": "http://localhost:3000/sse"
}
}
}
```
#### **Claude Desktop Configuration**
```json
{
"mcpServers": {
"health-fitness-coach": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
}
}
}
```
### **3. Test the Integration**
```bash
# Test MCP tools directly
npm run test:fitness
# Test specific endpoints
curl http://localhost:3000/api/context?userId=default-user
```
### **4. Start Using**
- **Web App**: Visit `http://localhost:3000` for visual fitness tracking
- **AI Integration**: Ask your AI assistant fitness-related questions
- **Natural Language**: "Log my workout", "Create a plan", "How am I doing?"
## 🔧 Technical Implementation Details
### **MCP Protocol Compliance**
```typescript
// MCP-compliant tool definition
export const logWorkoutTool = {
name: "log-workout",
description: "Log a workout session with type, duration, and optional distance",
inputSchema: {
type: "object",
properties: {
userId: { type: "string", description: "Unique user identifier" },
date: { type: "string", description: "Date in YYYY-MM-DD format" },
type: { type: "string", description: "Workout type (e.g., 'running', 'strength')" },
duration: { type: "number", description: "Duration in minutes" },
distance: { type: "number", description: "Distance in kilometers (optional)" }
},
required: ["userId", "date", "type", "duration"]
}
}
```
### **Data Storage & Retrieval**
```typescript
// In-memory stores with persistence hooks
export const workoutStore = createInMemoryStore<WorkoutEntry>()
export const nutritionStore = createInMemoryStore<NutritionEntry>()
export const planStore = createInMemoryStore<PlanEntry>()
// MCP tool implementation
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 Integration Layer**
```typescript
// Chat interface with MCP integration
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 })
}
}
```
## 🧪 Testing & Development
### **Available Test Scripts**
```bash
# Test all MCP tools
npm run test:fitness
# Test HTTP transport
npm run test:http
# Test MCP integration
npm run test:mcp
# Debug tool functionality
npm run debug:tools
```
### **MCP Tool Testing**
```javascript
// Test workout logging
const result = await mcpClient.callTool('log-workout', {
userId: 'test-user',
date: '2025-01-07',
type: 'running',
duration: 30,
distance: 5.0
})
console.log('Workout logged:', result)
```
## 🚀 Deployment Options
### **Local Development**
- Run `npm run dev` for development server
- MCP server available at `http://localhost:3000/mcp`
- Web interface at `http://localhost:3000`
### **Production Deployment**
- Deploy to Vercel with one-click button
- Configure environment variables (OPENAI_API_KEY)
- MCP server automatically available at your domain
### **Custom Deployment**
- Docker support for containerized deployment
- Environment variable configuration for different setups
- Scalable architecture for multiple users
## 🔧 Environment Configuration
### **Required Variables**
```env
# OpenAI API key for AI-generated fitness plans
OPENAI_API_KEY=your_openai_api_key_here
# Optional Redis for enhanced performance
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token
```
### **Optional Configuration**
```env
# Custom user ID for single-user setups
DEFAULT_USER_ID=my-fitness-journey
# Logging level for debugging
LOG_LEVEL=debug
# Custom port for development
PORT=3000
```
## 🤝 Contributing & Extending
### **Adding New MCP Tools**
```typescript
// Create new tool in tools/ directory
export const myCustomTool = {
name: "my-custom-tool",
description: "Description of what this tool does",
inputSchema: {
// Define parameters
},
handler: async (params) => {
// Implementation
}
}
// Register in tools/index.ts
export const tools = [
// ... existing tools
myCustomTool
]
```
### **Extending the Web Interface**
- Add new components in `components/` directory
- Create API routes in `app/api/` for new functionality
- Update the main dashboard in `app/page.tsx`
### **Custom AI Integrations**
- Implement additional MCP clients
- Add support for other AI platforms
- Create custom query processing logic
## 📄 License & Usage
**MIT License** - Feel free to use this project as a foundation for your own MCP servers and fitness applications.
This project demonstrates how to build production-ready MCP servers that bridge AI tools with domain-specific applications, providing a template for similar integrations in other domains.
---
**🤖 Powered by Model Context Protocol**
*Bridging AI intelligence with real-world fitness data*