AI Assistant & MCP Server

SparkyFitness includes a powerful Model Context Protocol (MCP) server. This allows you to connect advanced AI assistants (like Claude Desktop, Cursor, or custom AI clients) directly to your personal health data securely.

When you enable the MCP Server, your AI assistant transforms into a Personal Health Intelligence layer that can read your health logs, track your progress, and provide hyper-personalized coaching based on your actual data.

🛠 Available Tools & Capabilities

The AI assistant can perform the following actions across different health domains. All tools automatically respect your Unit Preferences (e.g., converting lbs to kg or kcal to kJ).

🥗 Nutrition & Food

Track your diet, manage meals, and analyze your nutritional intake.

Feature	Tool Action	Example Prompt
Log Food	`log_food`	"I just had a 250g steak and a salad."
Meal Templates	`log_meal`	"Log my 'Standard Breakfast' for today."
Water Tracking	`log_water`	"I drank 500ml of water."
Daily Diary	`list_diary`	"What have I eaten today?"
Copy Entries	`copy_from_yesterday`	"Copy my breakfast from yesterday to today."
Nutrition Analysis	`get_nutritional_summary`	"Give me a breakdown of my macros for the last 7 days."

🏋️ Exercise & Fitness

Manage your workouts, track strength progress, and use presets.

Feature	Tool Action	Example Prompt
Log Workout	`log_exercise`	"Log 3 sets of Bench Press at 80kg for 10 reps."
Workout Presets	`log_workout_preset`	"Start my 'Leg Day' workout."
Exercise Details	`get_exercise_details`	"How do I perform a Bulgarian Split Squat?"
Progress Tracking	`get_exercise_progress`	"Show me my Bench Press progress over the last month."
Search Library	`search_exercises`	"Find some advanced chest exercises using dumbbells."

📈 Biometrics & Check-ins

Monitor your weight, sleep, mood, and daily habits.

Feature	Tool Action	Example Prompt
Daily Wizard	`sparky_daily_checkin_wizard`	"I'm ready for my daily check-in."
Weight & Body	`log_biometrics`	"My weight is 185 lbs today."
Sleep & Mood	`log_sleep`, `log_mood`	"I slept 7 hours and feel like an 8/10."
Fasting Status	`get_fasting_status`	"Am I still in my fasting window?"
Weight History	`get_biometrics_history`	"Show me my weight trend for the last 30 days."
Custom Metrics	`log_custom_metric`	"My blood pressure was 120/80 today."

📋 Goals, Habits & Reports

Set targets and get consolidated performance reviews.

Habit Tracking (sparky_manage_habits): "Did I take my vitamins today?"
Goal Management (sparky_manage_goals): "Set a new weight goal of 175 lbs by July."
Weekly Reports (sparky_get_report): "Give me a weekly performance summary."
Profile Settings (sparky_manage_profile): "Change my energy unit to kJ."

🕵️ AI Personalization (The "Health Detective")

Because the AI has access to all these tools, it can do things a standard app cannot:

Correlation Detection: "I noticed your sleep quality is 20% better on days you finish your last meal before 7 PM."
Smart Planning: "Based on your current weight trend and yesterday's activity, I recommend increasing your protein by 20g today."
Inventory Logic: "You've logged Greek Yogurt 5 times this week. Should I add it to your high-protein shopping list?"

🔐 Security & Privacy

Isolated Connection: The MCP server uses a dedicated application pool. It cannot perform admin-level database operations.
User Isolation (RLS): The AI is physically restricted by PostgreSQL Row Level Security. It can only see data belonging to the user authenticated by the API key.
Local First: If you run SparkyFitness locally, your data never leaves your infrastructure until you send it to your chosen AI provider (e.g., Anthropic or OpenAI).

🚀 Getting Started

Generate API Key: Go to your User Profile in SparkyFitness and generate a Personal API Key.
Configure Client: Add the SparkyFitness MCP server to your AI client (Claude Desktop, Cursor, etc.).
Authentication: Pass your API key as a Bearer Token in the Authorization header.

Example Config (Claude Desktop)

{
  "mcpServers": {
    "sparky-fitness": {
      "serverURL": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SPARKY_FITNESS_API_KEY"
      }
    }
  }
}

Note: If running via Docker, use the HTTP transport URL as described in the Docker Compose Guide.

FeaturesMeasurements

Features Overview