icuvisor

README

icuvisor is an open-source, local-first Model Context Protocol server for intervals.icu, shipped as a single signed Go binary so athletes and coaches can talk to their training data from Claude, ChatGPT, Pi, Cursor, and other MCP-compatible clients. Your intervals.icu API key stays in the OS keychain, not in an icuvisor cloud service or MCP tool argument. There is no icuvisor-hosted account, onboarding credit, SaaS quota, or subscription gate. Usage limits from your AI client or model provider, GitHub/package downloads, and intervals.icu account are separate. End-user docs live at https://icuvisor.app.

For users

Why icuvisor

icuvisor is designed to keep training-data access simple, local, and easy for an AI assistant to use correctly:

• Local-first by default: your intervals.icu API key is read by the local icuvisor process from the OS keychain or an explicit headless fallback, not passed as an MCP tool argument.
• One binary to install: the server ships as a Go binary with shell installers and package-manager paths, so setup does not depend on a language runtime in the user's AI chat.
• Structured, terse responses: read tools return compact JSON-shaped results by default, with fuller payloads behind explicit include_full options for cases such as raw streams.
• Units and scales are explicit: distances, paces, wellness scales, and related fields use unit-labelled names or _meta legends so the model does not have to infer whether a value is kilometres, miles, or a 1-5 rating.
• Delete safety is outside the model's reach: destructive tools are registered only when the process-level ICUVISOR_DELETE_MODE allows them; there is no per-call confirm argument for the assistant to invent.

The fastest path on Linux, macOS (without Homebrew), WSL, and CI is the shell installer:

curl -fsSL https://icuvisor.app/install.sh | sh

On native Windows / PowerShell:

iwr -useb https://icuvisor.app/install.ps1 | iex

See SECURITY.md for installer signature verification and in-place update behaviour.

Prefer a package manager? brew install ricardocabral/icuvisor/icuvisor, scoop install icuvisor, or download the .dmg / .msi from the releases page.

Learn more on how to connect your AI assistant, read the tool catalog, and troubleshoot stale conversations or cached tool catalogs at https://icuvisor.app.

For developers

Build from source

git clone https://github.com/ricardocabral/icuvisor.git
cd icuvisor
make build
./bin/icuvisor version

Project layout

cmd/icuvisor/             Binary entrypoint
internal/app/             CLI dispatch, startup wiring, `setup` / `diagnostics` commands
internal/cli/prompt/      Terminal prompting (masked input) for first-run setup
internal/config/          Config load/validate/write, athlete-ID/timezone normalization, HTTP bind, dotenv, redaction
internal/credstore/       OS keychain wrapper (macOS Keychain, Windows Credential Manager, libsecret)
internal/diagnostics/     Redacted runtime/config snapshot for `icuvisor diagnostics`
internal/intervals/       intervals.icu API client (Basic Auth, retries, structured errors)
internal/clients/         Shared typed client interfaces (athlete profile, etc.)
internal/mcp/             MCP server + stdio/Streamable HTTP transports, schema, recovery
internal/tools/           Tool implementations (registered via `tools.Catalog()`)
internal/toolcatalog/     Catalog hashing and stale-catalog CI guard surface
internal/toolchecks/      Cross-tool invariants (delete-mode gating, examples, schema snapshots)
internal/coach/           Coach-mode roster and per-athlete tool ACLs
internal/safety/          Delete-mode resolution and registration-time gating
internal/response/        Terse/full response shaping and `_meta` plumbing
internal/analysis/        Deterministic analyzer math + interval-source / auto-lap classifier
internal/prompts/         Curated MCP prompt registry
internal/resources/       MCP Resources (workout syntax, event categories, schemas, analysis formulas, athlete profile)
internal/athleteprofile/  Athlete profile read shaping shared by tool + resource
internal/workoutdoc/      WorkoutDoc Parse/Serialize for the upstream description DSL
internal/customitemschemas/ Custom-item content schema samples used by write validation
internal/units/           Unit enum parsing + preferred-unit conversion
internal/streams/         Canonical stream key normalization
docs/                     PRD, roadmap, design notes

Development

Requires Go 1.25+ and (optionally) golangci-lint and goreleaser.

make build       # build ./bin/icuvisor
make test        # unit tests
make test-race   # tests with the race detector
make lint        # golangci-lint
make check       # fmt-check + vet + lint + test-race (run before pushing)
make snapshot    # local goreleaser snapshot
make docs-tools  # regenerate website tool catalog data
make help        # list all targets

See CONTRIBUTING.md, SECURITY.md, and the PRD.

License

MIT.