sisrun-mcp

# sisrun-mcp

<!-- mcp-name: io.github.cdutr/sisrun-mcp -->

🇧🇷 [Versão em português abaixo](#em-português-pt-br)

Unofficial [MCP](https://modelcontextprotocol.io) server that exposes your **SisRUN** ([appsisrun.com.br](https://appsisrun.com.br)) training plan to AI assistants like Claude, so you can ask "what did my coach prescribe this week?" and get a structured answer.

SisRUN has no public API, so this reads the same web pages you see in your browser, with your own credentials, and parses them into structured workout data. It is read-only: it never writes anything to SisRUN.

## Tools

| Tool | What it returns |
|---|---|
| `get_current_week()` | Every workout row of the current week |
| `get_week(date)` | The week containing an ISO date (`YYYY-MM-DD`) |
| `get_upcoming(weeks_ahead=1)` | Prescribed-but-not-done workouts from today forward |

Each workout row carries: date, status (`Proposto` = prescribed, `Feito` = done, `Feito Avulso` = auto-imported, not prescribed), modality, prescribed distance, pace and HR windows, the coach's structured session (warm-up, repeats, recoveries), the coach's note, and what SisRUN matched as delivered (date, distance, time, avg HR, kcal; SisRUN auto-imports your Garmin/Strava activities).

**`planned_km` vs `distance_km`:** SisRUN's own `Distância` field is empty for every interval, hill and time-based session, and on interval days it counts the reps only. Summing that column undercounts the real prescription by ~35% (SisRUN's own "Evolução Semanal" panel has the same bug). `planned_km` derives the honest number from the coach's structured session, expanding `Repetir Nx` blocks; `planned_km_is_est: "yes"` marks rows where a timed step had to be converted at an assumed pace.

## Install

```bash
uvx sisrun-mcp            # zero-install run from PyPI
# or
pipx install sisrun-mcp
# or straight from GitHub
uvx --from git+https://github.com/cdutr/sisrun-mcp sisrun-mcp
```

## Credentials

Your own SisRUN login (the one your coach gave you). Either environment variables:

```bash
export SISRUN_EMAIL=you@example.com
export SISRUN_PASSWORD=yourpassword
```

or a credentials file:

```bash
mkdir -p ~/.sisrun
cat > ~/.sisrun/credentials <<'EOF'
email=you@example.com
password=yourpassword
EOF
chmod 600 ~/.sisrun/credentials
```

⚠️ **The password is stored in plain text.** SisRUN offers no token or OAuth mechanism, so there is no better option. Keep the file `chmod 600`, and never commit it.

## Claude Desktop / Claude Code config

```json
{
  "mcpServers": {
    "sisrun": {
      "command": "uvx",
      "args": ["sisrun-mcp"]
    }
  }
}
```

## Debugging

Fetch and print your current week without any MCP client:

```bash
python -m sisrun_mcp selftest
```

If a result ever contains a `warning` about missing detail panels, the JSF form-state accumulation regressed. Please open an issue with the output (it contains no credentials).

## How it works (for the curious)

SisRUN is JSF + PrimeFaces 8.0. Every request carries a `javax.faces.ViewState` token, and all widget ids are server-generated: they change on any redeploy, so nothing here hardcodes them. Buttons are located by their stable, human-authored `title` attributes, and the ViewState is re-read from every response. The non-obvious part is that the day detail panels are accordions the server only renders when the request carries their expanded state, **accumulated across navigation hops**, together with `javax.faces.partial.execute=@all`. Without that you silently get summary rows with no prescriptions. See the comments in `client.py`.

The client is deliberately polite: one week per request, spaced 0.6 s apart, and week HTML is cached per process.

## Contributing

Bug reports, feature suggestions and PRs are welcome, in English or Portuguese. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Status & disclaimers

- **Unofficial.** Not affiliated with, endorsed by, or supported by SisRUN. It may break whenever SisRUN changes their site; issues and PRs welcome.
- **Your data only.** This accesses your own training plan with your own credentials, the same data portability the LGPD grants you. Don't use it against accounts that aren't yours, and respect SisRUN's terms of service.
- Tested against real accounts since 2026-07. Python ≥ 3.10, single dependency (`mcp`).

## Em português (pt-BR)

Servidor [MCP](https://modelcontextprotocol.io) **não oficial** que expõe sua planilha de treinos do **SisRUN** ([appsisrun.com.br](https://appsisrun.com.br)) para assistentes de IA como o Claude. Com ele você pergunta "o que o treinador prescreveu essa semana?" e recebe os treinos estruturados: status (Proposto / Feito / Feito Avulso), distância, faixas de ritmo e FC, a estrutura da sessão (aquecimento, tiros, recuperações), a observação do treinador e o que o SisRUN associou como realizado (o SisRUN importa suas atividades do Garmin/Strava automaticamente).

O SisRUN não tem API pública, então o servidor lê as mesmas páginas que você vê no navegador, com as suas próprias credenciais. É somente leitura: nunca escreve nada no SisRUN.

**Ferramentas:** `get_current_week()` (semana atual), `get_week(date)` (semana de uma data), `get_upcoming(weeks_ahead)` (treinos propostos daqui pra frente).

**Instalação:**

```bash
uvx sisrun-mcp
# ou
pipx install sisrun-mcp
```

**Credenciais:** seu próprio login do SisRUN, por variáveis de ambiente (`SISRUN_EMAIL` / `SISRUN_PASSWORD`) ou pelo arquivo `~/.sisrun/credentials`:

```
email=voce@exemplo.com
password=suasenha
```

```bash
chmod 600 ~/.sisrun/credentials
```

⚠️ **A senha fica em texto puro.** O SisRUN não oferece token nem OAuth, então não existe opção melhor. Mantenha o arquivo com `chmod 600` e nunca faça commit dele.

**Sobre `planned_km`:** o campo `Distância` do próprio SisRUN fica vazio em todo treino intervalado, de subida ou por tempo, e em dias de tiro conta só as repetições. Somar essa coluna subestima a prescrição real em ~35% (o painel "Evolução Semanal" do próprio SisRUN tem esse mesmo bug). O `planned_km` deriva o número honesto a partir da sessão estruturada do treinador, expandindo os blocos `Repetir Nx`.

**Avisos:** projeto não afiliado, não endossado e não suportado pelo SisRUN. Pode quebrar quando o site mudar (issues e PRs são bem-vindos). Ele acessa apenas os seus dados, com as suas credenciais, a mesma portabilidade de dados que a LGPD garante a você. Não use contra contas que não são suas e respeite os termos de uso do SisRUN.

Para depurar sem cliente MCP: `python -m sisrun_mcp selftest` imprime a semana atual em JSON.

## License

MIT