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

User Isolation (RLS): Normal MCP tools are restricted by PostgreSQL Row Level Security, scoped to the user authenticated by the API key. The AI can only see data belonging to that user.
Admin-Only Dev Tools: A small set of optional developer/debugging tools is off by default. They are enabled only when DEV_TOOLS_ENABLED=true and the request uses an admin API key. These tools intentionally run with elevated database access (the owner pool, bypassing Row Level Security), so leave them disabled unless you are actively debugging.
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

The MCP server is now served in-process by the main SparkyFitness server at POST /mcp. There is no separate MCP service to run.

1. Generate an API Key

Go to Profile → Personal API Key in the web UI and generate a key (or call POST /identity/user/generate-api-key). You'll pass this as a Bearer Token in the Authorization header.

2. Find Your MCP Endpoint

Production: https://<your-host>/mcp (the production nginx config proxies /mcp to the server).
Local dev: http://localhost:8080/mcp — the frontend Vite dev proxy forwards /mcp to the server. Hitting the server port directly at http://localhost:3010/mcp also works.

3. Configure Your Client

HTTP / remote-capable clients (Cursor and other clients that support streamable HTTP) point directly at /mcp with an Authorization: Bearer <API_KEY> header:

{
  "mcpServers": {
    "sparky-fitness": {
      "url": "https://<your-host>/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

stdio-only clients (such as the classic Claude Desktop config) can't talk HTTP directly. Use the off-the-shelf mcp-remote bridge. The key goes in an env block, and the header uses the no-space Authorization:${AUTH_HEADER} form — mcp-remote's documented workaround for clients that mangle spaces in header arguments (e.g. Claude Desktop on Windows, Cursor):

{ "mcpServers": { "sparky-fitness": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://<your-host>/mcp",
             "--header", "Authorization:${AUTH_HEADER}"],
    "env": { "AUTH_HEADER": "Bearer <API_KEY>" } } } }

Note: for a local-dev server over plain HTTP, add --allow-http to the args and use http://localhost:8080/mcp (or http://localhost:3010/mcp to hit the server directly) — mcp-remote refuses non-HTTPS URLs otherwise.

FeaturesMeasurements

FeaturesPeriod & Cycle Hub