@spotfitr/mcp 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# @spotfitr/mcp
+
+MCP server that exposes the Spotfitr API as tools for Claude. Allows trainers and clients to manage sessions, bookings, and clients directly from Claude Desktop or any MCP-compatible AI client.
+
+## Architecture decisions
+
+**Transport: stdio (local)**
+
+The server runs as a local subprocess of the AI client (Claude Desktop). Each user runs their own isolated process — there is no shared state between users, no open network port, and credentials never leave the user's machine except when calling the Spotfitr API.
+
+This was chosen over an HTTP remote server because:
+- No infrastructure required (no always-on server, no TLS setup)
+- Security model is trivial: one process = one user, fully isolated auth state
+- The target users (fitness professionals) use Claude Desktop, so npm install is feasible
+- A remote HTTP server would require rewriting the auth state model to be per-session, adding OAuth, rate limiting, and ongoing hosting costs — complexity that adds no real value for this use case
+
+**Authentication: environment variables only**
+
+Credentials are passed exclusively via `SPOTFITR_EMAIL` and `SPOTFITR_PASSWORD` environment variables, set in the Claude Desktop config file. A `login` tool that accepted credentials as parameters was considered and rejected: tool parameters appear in Claude's conversation context and tool call logs, which would expose the password to the model and any logging infrastructure.
+
+**Authorization: delegated to the API**
+
+The MCP server does not enforce any role-based access control itself. It passes the JWT from the Spotfitr API to every request and lets the API enforce permissions (OWNER vs CLIENT). Tool descriptions document which role each tool requires, but enforcement happens server-side.
+
+**Error handling: sanitized**
+
+API errors are filtered before being returned to the LLM. Only the API's own `error` field is forwarded (e.g. "Session is full"), never raw stack traces or internal error details. This prevents leaking implementation details through the model context.
+
+**URL security: HTTPS enforced at startup**
+
+If `SPOTFITR_API_URL` is set to a non-HTTPS URL (and is not localhost), the server refuses to start. This prevents the JWT from being transmitted in plaintext by misconfiguration.
+
+## Installation
+
+Requires Node.js 18 or later.
+
+The package is published to npm as `@spotfitr/mcp`. Users do not need to install it manually — `npx` handles it automatically.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "spotfitr": {
+      "command": "npx",
+      "args": ["-y", "@spotfitr/mcp"],
+      "env": {
+        "SPOTFITR_EMAIL": "your-email@example.com",
+        "SPOTFITR_PASSWORD": "your-password",
+        "SPOTFITR_API_URL": "https://api.spotfitr.com/api"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving. Claude will have access to all Spotfitr tools automatically.
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add spotfitr \
+  -e SPOTFITR_EMAIL=your-email@example.com \
+  -e SPOTFITR_PASSWORD=your-password \
+  -e SPOTFITR_API_URL=https://api.spotfitr.com/api \
+  -- npx -y @spotfitr/mcp
+```
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SPOTFITR_EMAIL` | Yes | — | Spotfitr account email |
+| `SPOTFITR_PASSWORD` | Yes | — | Spotfitr account password |
+| `SPOTFITR_API_URL` | No | `http://localhost:3001/api` | Spotfitr API base URL. Must be HTTPS for non-localhost URLs. |
+
+If `SPOTFITR_EMAIL` or `SPOTFITR_PASSWORD` are missing, the server starts but all tool calls will fail until credentials are provided. Auto-login errors are non-fatal and logged to stderr.
+
+## Available tools
+
+### Auth
+| Tool | Role | Description |
+|------|------|-------------|
+| `get_current_user` | Any | Get the profile of the authenticated user |
+| `get_auth_status` | Any | Check if the server is authenticated and see basic user info |
+
+### Sessions
+| Tool | Role | Description |
+|------|------|-------------|
+| `list_sessions` | Any | List sessions within an optional date range |
+| `create_session` | OWNER | Create a new individual training session |
+| `update_session` | OWNER | Update date, times, capacity, or cancel a session |
+| `delete_session` | OWNER | Permanently delete a session |
+| `get_session_bookings` | OWNER | List all confirmed bookings for a session (with client details) |
+| `get_session_attendees` | CLIENT | List names and profile pictures of confirmed attendees |
+
+### Session types
+| Tool | Role | Description |
+|------|------|-------------|
+| `list_session_types` | Any | List all workout types (e.g. CrossFit, Yoga, HIIT) |
+| `create_session_type` | OWNER | Create a new workout type with name, description, and color |
+| `update_session_type` | OWNER | Update name, description, or color of a workout type |
+| `delete_session_type` | OWNER | Delete a workout type (fails if sessions are using it) |
+
+### Recurrence rules
+| Tool | Role | Description |
+|------|------|-------------|
+| `list_recurrence_rules` | OWNER | List all recurring session rules |
+| `create_recurrence_rule` | OWNER | Create a recurring rule that auto-generates sessions |
+| `delete_recurrence_rule` | OWNER | Delete a rule and its future unbooked sessions |
+
+### Clients
+| Tool | Role | Description |
+|------|------|-------------|
+| `list_clients` | OWNER | List all active clients with their monthly booking count |
+| `list_archived_clients` | OWNER | List archived (inactive) clients |
+| `create_client` | OWNER | Add a new client and send them an invitation email |
+| `update_client` | OWNER | Update name, email, or monthly session limit |
+| `delete_client` | OWNER | Delete a client (fails if they have any bookings) |
+| `archive_client` | OWNER | Deactivate a client without deleting them |
+| `unarchive_client` | OWNER | Reactivate an archived client |
+
+### Bookings
+| Tool | Role | Description |
+|------|------|-------------|
+| `list_my_bookings` | CLIENT | List upcoming confirmed bookings |
+| `get_my_usage` | CLIENT | Get booking usage for the current month vs the session limit |
+| `book_session` | CLIENT | Book a spot in a session |
+| `cancel_booking` | CLIENT | Cancel a booking (subject to cancellation window) |
+
+### Waitlist
+| Tool | Role | Description |
+|------|------|-------------|
+| `list_my_waitlist` | CLIENT | List sessions you are on the waitlist for |
+| `join_waitlist` | CLIENT | Join the waitlist for a full session |
+| `leave_waitlist` | CLIENT | Remove yourself from the waitlist |
+
+### Subscription
+| Tool | Role | Description |
+|------|------|-------------|
+| `get_subscription_info` | OWNER | Get plan (FREE/PRO), status, and client usage vs limit |
+
+## Local development
+
+```bash
+cd mcp
+npm install
+cp .env.example .env   # fill in your credentials
+npm run dev
+```
+
+The dev script uses `tsx --watch` for hot reload.
+
+To test with Claude Code locally before publishing:
+
+```bash
+npm run build
+claude mcp add spotfitr-local \
+  -e SPOTFITR_EMAIL=your-email@example.com \
+  -e SPOTFITR_PASSWORD=your-password \
+  -e SPOTFITR_API_URL=http://localhost:3001/api \
+  -- node /absolute/path/to/spotfitr/mcp/dist/index.js
+```
+
+## Publishing
+
+The package is published to npm under the `@spotfitr` org scope.
+
+```bash
+cd mcp
+npm version patch   # or minor / major
+npm publish         # runs build automatically via prepublishOnly
+```
+
+Requires npm login with an account that has publish access to the `@spotfitr` org.

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { autoLogin } from "./auth.js";
+import { registerAllTools } from "./tools/index.js";
+async function main() {
+  const server = new McpServer({
+    name: "spotfitr",
+    version: "0.1.0"
+  });
+  registerAllTools(server);
+  const email = process.env.SPOTFITR_EMAIL;
+  const password = process.env.SPOTFITR_PASSWORD;
+  const baseUrl = process.env.SPOTFITR_API_URL ?? "http://localhost:3001/api";
+  if (email && password) {
+    try {
+      await autoLogin(baseUrl, email, password);
+    } catch (err) {
+      process.stderr.write(`[spotfitr-mcp] Auto-login failed: ${err.message}
+`);
+    }
+  } else {
+    process.stderr.write("[spotfitr-mcp] No credentials provided. Call the login tool to authenticate.\n");
+  }
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("[spotfitr-mcp] Server running on stdio\n");
+}
+main().catch((err) => {
+  process.stderr.write(`[spotfitr-mcp] Fatal error: ${err.message}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@spotfitr/mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing the Spotfitr fitness API as tools for Claude",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "spotfitr-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx --watch src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}