# Strength Training MCP Server

[![PyPI](https://img.shields.io/pypi/v/strength-training-mcp)](https://pypi.org/project/strength-training-mcp/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-2025--11--25-green)]()

A stateless MCP server exposing 8 tools for evidence-based strength training. Encodes classical powerlifting programs (5/3/1, Texas Method, Madcow, GZCLP, nSuns CAP3, Coan-Philippi, Smolov Jr), the Banister fitness-fatigue model, RPE-based autoregulation, and an adjustment policy engine.

**No user data is stored on the server.** All state lives in the calling agent. The server is a pure function: same inputs → same outputs.

## Supported Transports

| Transport | Support | Entry Point | Use Case |
|---|---|---|---|
| **Stdio** | ✅ | `strength-training-mcp` | Claude Desktop, Claude Code, Cursor |
| **Streamable HTTP** | ✅ | `strength-training-mcp-http` / `POST /mcp` | ModelScope, Aura, remote agents |
| **SSE** | ❌ | — | Not implemented (use Streamable HTTP instead) |

## Quick Start

### Stdio (local clients)

```bash
uvx --from strength-training-mcp strength-training-mcp
```

### HTTP server (remote / cloud)

```bash
uvx --from strength-training-mcp strength-training-mcp-http --port 8080
```

Test:

```bash
curl http://localhost:8080/health
# → {"status":"ok","version":"0.1.1"}
```

For MCP calls over HTTP, use any MCP client (e.g., `fastmcp.Client`, Claude Desktop, or ModelScope) pointing at `http://localhost:8080/mcp`.

## Deploy on ModelScope

This package is published to PyPI as `strength-training-mcp`. ModelScope can deploy it directly via `uvx`.

### Step 1 — Choose transport

In ModelScope MCP deployment console, select **Stdio** or **Streamable HTTP**.

> **Recommendation**: Use **Stdio** for the simplest one-click deployment.

### Step 2 — Fill service config

#### Option A — Stdio (recommended)

```json
{
  "mcpServers": {
    "strength-training": {
      "command": "uvx",
      "args": [
        "--from",
        "strength-training-mcp",
        "strength-training-mcp"
      ],
      "env": {}
    }
  }
}
```

#### Option B — Streamable HTTP

Deploy the HTTP server first (see [Self-Host](#self-host) below), then fill your public URL:

```json
{
  "mcpServers": {
    "strength-training": {
      "type": "http",
      "url": "https://your-domain.com/mcp"
    }
  }
}
```

### Step 3 — No parameters required

This server requires **no API keys, no environment variables, and no database**. Leave parameter config empty.

### Step 4 — Verify

After deployment, test:

```bash
curl https://your-deployment-url/health
# → {"status":"ok","version":"0.1.1"}
```

---

## Self-Host

See [docs/selfhost.md](docs/selfhost.md) for:

- systemd service setup
- nginx reverse proxy (hide application port)
- Caddy + HTTPS
- Docker deployment

Minimal production setup:

```bash
# Install
uv tool install strength-training-mcp

# Run behind nginx on port 80
strength-training-mcp-http --host 127.0.0.1 --port 3492
```

Then configure nginx to proxy `80` → `127.0.0.1:3492`.

---

## Tools

| Tool | Purpose |
|------|---------|
| `list_training_templates` | Browse the built-in program library |
| `get_template_plan` | Get a specific week's prescribed sessions |
| `lookup_exercise_form` | Get form cues + alternatives for an exercise |
| `explain_principle` | Explain a training science principle with citation |
| `calculate_fatigue_score` | Compute Banister CTL/ATL/TSB from training history |
| `suggest_session_modification` | Get adjustment recommendations based on fatigue + actual |
| `apply_plan_adjustment` | Apply aggregate adjustments to a week (deload, etc.) |
| `recommend_session_for_today` | Compose today's session with rationale |

See [docs/api.md](docs/api.md) for full tool reference, input schemas, and error codes.

---

## Agent Integration

- [Claude Desktop](docs/agent-integration/claude-desktop.md)
- [Aura](docs/agent-integration/aura.md)
- [Cursor](docs/agent-integration/cursor.md)
- [Custom Agent (Python SDK)](docs/agent-integration/custom-agent.md)

### Claude Desktop example

```json
{
  "mcpServers": {
    "strength-training": {
      "command": "uvx",
      "args": [
        "--from",
        "strength-training-mcp",
        "strength-training-mcp"
      ]
    }
  }
}
```

---

## Development

```bash
uv sync --all-extras
uv run pytest tests/unit        # unit tests
uv run pytest tests/integration # E2E tests
uv run pytest --cov=src/strength_training_mcp
```

## Knowledge Sources

All templates and principles cite their original public sources. See [docs/rts-principles.md](docs/rts-principles.md) for citations.

## License

MIT