Fitness Agent MCP

A zero-dependency Express API that acts as a universal fitness intelligence layer for AI assistants. Claude, ChatGPT, and GitHub Copilot all share the same state, gamification engine, and data. Claude and Copilot via the built-in MCP server, ChatGPT via OpenAPI Custom Actions.

No OpenAI key. No database server. One deployed URL.

Table of Contents

1. What This Does

2. Architecture

3. Local Setup

4. Deploy to Railway

5. Connecting AI Clients

6. MCP Tools

7. Security Notes

8. Environment Variables

1. What This Does

One server, three AI surfaces:

Features: user profiles · workout + diet plans · calendar scheduling · gamification (XP / streaks / 12 achievements) · paginated history · export (JSON / CSV / interactive HTML) · cron reminders

Design principle: The server is a pure storage layer. The AI client (Claude, GPT-4, Copilot) reads tool descriptions and generates all structured data itself — diet plans, workout schedules, calendar events — then passes them as parameters. No server-side AI calls. No API keys required.

2. Architecture

Claude / Copilot          ChatGPT Custom GPT
    └─ MCP JSON-RPC ──────┐   └─ REST/OpenAPI ──┐
                          ▼                      ▼
              ┌──────────────────────────────────────┐
              │        Express API  (/api/*)         │
              │                                      │
              │  MCP tools (8)     REST routes       │
              │  get_state         /state            │
              │  save_state        /log-completion   │
              │  log_completion    /normalize        │
              │  normalize_user_input /generate-plan │
              │  generate_plan     /schedule-events  │
              │  schedule_events   /export           │
              │  get_history       /progress/history │
              │  export_report     /healthz          │
              │                                      │
              │  Gamification engine + node-cron     │
              └──────────────────┬───────────────────┘
                                 │
                                 ▼
                        ┌────────────────┐
                        │  SQLite (file) │
                        │                │
                        │ user_profiles  │
                        │ diet_plans     │
                        │ workout_plans  │
                        │ schedules      │
                        │ progress       │
                        └────────────────┘

Tables are created automatically on first boot via Drizzle migrations — no manual schema push needed.

3. Local Setup

Prerequisites

• Node.js 20+

• pnpm 9+

Install and run

git clone <your-repo-url>
cd fitness-agent-mcp-v2
pnpm install

Copy the example env file (optional — defaults work out of the box):

cp .env.example .env

Start the server:

pnpm --filter @workspace/api-server run dev

The API is at http://localhost:8080/api. SQLite database is created automatically at ./artifacts/api-server/data/fitness.db.

Verify

curl http://localhost:8080/api/healthz
# → {"status":"ok"}

Run tests

pnpm --filter @workspace/api-server test

4. Deploy to Railway

The railway.toml at the project root configures everything automatically.

Steps

1. Push this repo to GitHub

2. railway.app → New Project → Deploy from GitHub repo → select repo

3. Dashboard → Add Volume → Mount path: /data, Size: 1 GB

4. Service → Variables → add:

5. Deploy — Railway auto-sets RAILWAY_PUBLIC_DOMAIN

Test

curl https://your-app.up.railway.app/api/healthz
# → {"status":"ok"}

List on Smithery (optional)

Smithery.ai is the MCP marketplace — users can find your server and connect it to Claude with one click.

npx smithery mcp publish "https://your-app.up.railway.app/api/mcp" \
  -n yourusername/fitness-agent

5. Connecting AI Clients

Once deployed, get your base URL (https://your-app.up.railway.app).

Claude — claude.ai web

1. Settings → Integrations → Add Custom Integration

2. Paste: https://your-app.up.railway.app/api/mcp

3. Done — syncs to Claude iOS app automatically

Claude Desktop (manual config)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fitness-agent": {
      "url": "https://your-app.up.railway.app/api/mcp",
      "transport": "streamable-http"
    }
  }
}

Restart Claude Desktop completely after saving.

Get the recommended system prompt:

curl https://your-app.up.railway.app/api/system-prompt
# → use the claude.prompt value

GitHub Copilot — VS Code

Update .vscode/mcp.json with your deployed URL:

{
  "servers": {
    "fitness-agent": {
      "url": "https://your-app.up.railway.app/api/mcp",
      "type": "sse"
    }
  }
}

.github/copilot-instructions.md is already in the repo — Copilot Chat reads it automatically for full API context.

ChatGPT — Custom GPT Actions

1. chat.openai.com → profile → My GPTs → Create → Configure → Actions → Add action

2. Schema URL: https://your-app.up.railway.app/api/openapi.json

3. ChatGPT auto-discovers all REST endpoints

4. Paste the chatgpt.prompt value from GET /api/system-prompt as your GPT's System Prompt

6. MCP Tools

All 8 tools are available at POST /api/mcp (JSON-RPC, StreamableHTTP).

For normalize_user_input, generate_plan, and schedule_events: the tool description instructs the AI to generate the structured data itself and pass it as a parameter. The server validates and stores it. No server-side AI call is made.

Discover all tools and their input schemas:

POST /api/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }

7. Security Notes

Current status: safe for personal use and demos.

• No authentication — any userId string can read/write any user's data. For personal use this is fine. For multi-user deployments, add an x-api-key header check before going public.

• Open CORS — app.use(cors()) allows all origins. Restrict to your domain in production.

• No rate limiting — add express-rate-limit if hosting publicly.

• SQL injection — safe, Drizzle ORM uses parameterized queries throughout.

• Secrets — no hardcoded credentials; all config via environment variables.

8. Environment Variables