fitro-mcp 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fitro_mcp-1.0.0/.env.example +4 -0
- fitro_mcp-1.0.0/.github/workflows/ci.yml +48 -0
- fitro_mcp-1.0.0/.gitignore +14 -0
- fitro_mcp-1.0.0/.pre-commit-config.yaml +13 -0
- fitro_mcp-1.0.0/AGENTS.md +89 -0
- fitro_mcp-1.0.0/CHANGELOG.md +31 -0
- fitro_mcp-1.0.0/CONTRIBUTING.md +38 -0
- fitro_mcp-1.0.0/LICENSE +21 -0
- fitro_mcp-1.0.0/PKG-INFO +361 -0
- fitro_mcp-1.0.0/README.md +331 -0
- fitro_mcp-1.0.0/SECURITY.md +19 -0
- fitro_mcp-1.0.0/docs/architecture.md +65 -0
- fitro_mcp-1.0.0/docs/authentication.md +58 -0
- fitro_mcp-1.0.0/docs/code-reference.md +116 -0
- fitro_mcp-1.0.0/docs/publishing.md +88 -0
- fitro_mcp-1.0.0/docs/verification.md +46 -0
- fitro_mcp-1.0.0/examples/codex.toml +10 -0
- fitro_mcp-1.0.0/pyproject.toml +74 -0
- fitro_mcp-1.0.0/scripts/publish.py +69 -0
- fitro_mcp-1.0.0/scripts/smoke_test.py +110 -0
- fitro_mcp-1.0.0/src/fitro_mcp/__init__.py +3 -0
- fitro_mcp-1.0.0/src/fitro_mcp/__main__.py +43 -0
- fitro_mcp-1.0.0/src/fitro_mcp/authentication.py +49 -0
- fitro_mcp-1.0.0/src/fitro_mcp/catalog.py +55 -0
- fitro_mcp-1.0.0/src/fitro_mcp/client.py +143 -0
- fitro_mcp-1.0.0/src/fitro_mcp/config.py +51 -0
- fitro_mcp-1.0.0/src/fitro_mcp/data/operations.json +937 -0
- fitro_mcp-1.0.0/src/fitro_mcp/diagnostics.py +167 -0
- fitro_mcp-1.0.0/src/fitro_mcp/discovery.py +178 -0
- fitro_mcp-1.0.0/src/fitro_mcp/errors.py +5 -0
- fitro_mcp-1.0.0/src/fitro_mcp/py.typed +0 -0
- fitro_mcp-1.0.0/src/fitro_mcp/resources.py +97 -0
- fitro_mcp-1.0.0/src/fitro_mcp/server.py +139 -0
- fitro_mcp-1.0.0/tests/test_authentication.py +96 -0
- fitro_mcp-1.0.0/tests/test_cli.py +72 -0
- fitro_mcp-1.0.0/tests/test_client.py +207 -0
- fitro_mcp-1.0.0/tests/test_diagnostics.py +199 -0
- fitro_mcp-1.0.0/tests/test_discovery.py +75 -0
- fitro_mcp-1.0.0/tests/test_publishing.py +77 -0
- fitro_mcp-1.0.0/tests/test_server.py +190 -0
- fitro_mcp-1.0.0/uv.lock +2427 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
name: Verify
|
|
2
|
+
on:
|
|
3
|
+
push:
|
|
4
|
+
pull_request:
|
|
5
|
+
workflow_dispatch:
|
|
6
|
+
permissions:
|
|
7
|
+
contents: read
|
|
8
|
+
jobs:
|
|
9
|
+
quality:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ['3.11', '3.12', '3.13', '3.14']
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
with:
|
|
17
|
+
persist-credentials: false
|
|
18
|
+
- uses: astral-sh/setup-uv@v6
|
|
19
|
+
with:
|
|
20
|
+
enable-cache: true
|
|
21
|
+
python-version: ${{ matrix.python }}
|
|
22
|
+
- run: uv sync --locked
|
|
23
|
+
- run: uv run ruff check .
|
|
24
|
+
- run: uv run ruff format --check .
|
|
25
|
+
- run: uv run mypy
|
|
26
|
+
- run: uv run pytest
|
|
27
|
+
- run: uv build
|
|
28
|
+
- run: uv run twine check dist/*
|
|
29
|
+
- name: Smoke-test installed wheel
|
|
30
|
+
run: uv run --isolated --no-project --with dist/*.whl scripts/smoke_test.py
|
|
31
|
+
- name: Smoke-test installed source distribution
|
|
32
|
+
run: uv run --isolated --no-project --with dist/*.tar.gz scripts/smoke_test.py
|
|
33
|
+
- uses: actions/upload-artifact@v4
|
|
34
|
+
if: matrix.python == '3.14'
|
|
35
|
+
with:
|
|
36
|
+
name: distributions
|
|
37
|
+
path: dist/
|
|
38
|
+
audit:
|
|
39
|
+
runs-on: ubuntu-latest
|
|
40
|
+
steps:
|
|
41
|
+
- uses: actions/checkout@v4
|
|
42
|
+
with:
|
|
43
|
+
persist-credentials: false
|
|
44
|
+
- uses: astral-sh/setup-uv@v6
|
|
45
|
+
with:
|
|
46
|
+
python-version: '3.14'
|
|
47
|
+
- run: uv sync --locked
|
|
48
|
+
- run: uv run pip-audit
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
repos:
|
|
2
|
+
- repo: local
|
|
3
|
+
hooks:
|
|
4
|
+
- id: ruff-check
|
|
5
|
+
name: Ruff lint and security rules
|
|
6
|
+
entry: uv run --locked ruff check
|
|
7
|
+
language: system
|
|
8
|
+
types: [python]
|
|
9
|
+
- id: ruff-format
|
|
10
|
+
name: Ruff formatting
|
|
11
|
+
entry: uv run --locked ruff format --check
|
|
12
|
+
language: system
|
|
13
|
+
types: [python]
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Agent guide
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
Fitro MCP is a Python 3.11+ stdio MCP server for an individual user's Garmin
|
|
6
|
+
Connect Personal API. It exchanges a personal API key for a bearer token, then
|
|
7
|
+
exposes five public tools over reviewed GET operations. Keep the neutral package name
|
|
8
|
+
`fitro-mcp` and the import namespace `fitro_mcp` consistent.
|
|
9
|
+
|
|
10
|
+
## Repo map
|
|
11
|
+
|
|
12
|
+
- `src/fitro_mcp/__main__.py`: console entry, sanitized startup, stdio only.
|
|
13
|
+
- `config.py`: validated environment settings and fixed regional HTTPS hosts.
|
|
14
|
+
- `catalog.py`: input validation and endpoint binding.
|
|
15
|
+
- `discovery.py`: domain boundaries, compact tool contracts and offline discovery.
|
|
16
|
+
- `resources.py`: offline MCP documentation resources/templates and completion.
|
|
17
|
+
- `diagnostics.py`: allowlisted private rotating log events and correlation context.
|
|
18
|
+
- `data/operations.json`: reviewed endpoint allowlist and public input schemas.
|
|
19
|
+
- `client.py`: HTTP lifecycle, size limits, token cache and renewal.
|
|
20
|
+
- `authentication.py`: private token response parsing (plain JWT and compatible JSON).
|
|
21
|
+
- `server.py`: MCP listing, dispatch, error and binary serialization.
|
|
22
|
+
- `errors.py`: safe public errors; `__init__.py`: package version.
|
|
23
|
+
- `tests/`: mocked HTTP security/behavior checks and a real stdio MCP handshake.
|
|
24
|
+
- `docs/`: authentication assumptions, architecture, publishing.
|
|
25
|
+
- `pyproject.toml`, `uv.lock`: metadata, tooling configuration, reproducible development.
|
|
26
|
+
- `scripts/smoke_test.py`: installed-wheel/source archive protocol verification.
|
|
27
|
+
- `scripts/publish.py`: exact-artifact PyPI upload with local credential handling.
|
|
28
|
+
- `examples/codex.toml`: versioned end-user Codex setup.
|
|
29
|
+
- `.github/workflows/`: quality, dependency audit and package build checks.
|
|
30
|
+
|
|
31
|
+
## Build instructions
|
|
32
|
+
|
|
33
|
+
Use uv. Run `uv sync --locked` on an unchanged checkout. After intentional
|
|
34
|
+
dependency changes, run `uv lock` and review the diff, then sync. Never install
|
|
35
|
+
project tooling into the system Python. Build with `uv build`; check distribution
|
|
36
|
+
metadata using `uv run twine check dist/*`. Entry points are `uv run
|
|
37
|
+
fitro-mcp` and `uv run python -m fitro_mcp`.
|
|
38
|
+
|
|
39
|
+
## Design and security rules
|
|
40
|
+
|
|
41
|
+
- Keep the protocol layer thin and HTTP independently testable through injected transports.
|
|
42
|
+
- Keep all operations read-only. New endpoints need reviewed documentation and tests.
|
|
43
|
+
- Expose only activity, health (including women's health), wellness, profile and discover.
|
|
44
|
+
- Keep resource contracts, discovery and tool validation backed by the same catalog.
|
|
45
|
+
- Region defaults to global; --debug enables local diagnostics in ~/.starbridge.
|
|
46
|
+
- Cap each log at 1,000,000 bytes with three backups; use private permissions.
|
|
47
|
+
- Log only fixed generic events, random request IDs, status codes and timings.
|
|
48
|
+
Exclude arguments, dates, domains/operations, health content and exception text.
|
|
49
|
+
- Never accept arbitrary upstream URLs, origins, headers, or methods from tool input.
|
|
50
|
+
- Never return/log credentials, upstream error bodies, raw validation exceptions,
|
|
51
|
+
request URLs, or health data in diagnostic messages.
|
|
52
|
+
- Do not print non-protocol output to stdout. Do not persist tokens or health data.
|
|
53
|
+
- Retain verified TLS, no redirects, bounded response reads, and timeouts.
|
|
54
|
+
- Validate inputs before authentication; schemas reject unknown keys and malformed dates.
|
|
55
|
+
- Preserve the local stdio boundary. Remote hosting/auth is a separate design task.
|
|
56
|
+
- Update documentation when tool contracts, settings or authentication change.
|
|
57
|
+
- Avoid live API calls in automated checks. Use synthetic credentials and transport mocks.
|
|
58
|
+
|
|
59
|
+
## Verification
|
|
60
|
+
|
|
61
|
+
Run from the repository root:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
uv run ruff check .
|
|
65
|
+
uv run ruff format --check .
|
|
66
|
+
uv run mypy
|
|
67
|
+
uv run pytest
|
|
68
|
+
uv run pip-audit
|
|
69
|
+
uv build
|
|
70
|
+
uv run twine check dist/*
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Pytest enforces at least 85% coverage. Check that wheel contents include
|
|
74
|
+
`data/operations.json`, `py.typed`, and license metadata. Install the wheel in a
|
|
75
|
+
clean environment and run `scripts/smoke_test.py` for metadata, CLI version,
|
|
76
|
+
MCP initialize/tools-list (five tools), offline resources and completions.
|
|
77
|
+
CI tests all supported Python minor versions. Audit findings require remediation
|
|
78
|
+
or a documented, narrowly justified exception; never silently suppress them.
|
|
79
|
+
|
|
80
|
+
## Definition of done
|
|
81
|
+
|
|
82
|
+
- The intended behavior works through MCP, with discoverable accurate tool schemas.
|
|
83
|
+
- Positive, invalid-input, upstream-error, and credential-redaction paths are covered.
|
|
84
|
+
- Required verification passes and distribution artifacts build and install.
|
|
85
|
+
- README, agent guide, and relevant design/assumption docs reflect the implementation.
|
|
86
|
+
- No secrets, local environments, generated distributions or personal data are committed.
|
|
87
|
+
- Verification reports distinguish mocked protocol/API tests from live upstream tests.
|
|
88
|
+
- Publishing needs the owner's registry identity/name checks; do not claim a release
|
|
89
|
+
or legal clearance that has not happened.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.0 — 2026-11-20
|
|
4
|
+
|
|
5
|
+
First stable release using the new **Fitro MCP** identity.
|
|
6
|
+
|
|
7
|
+
- Five read-only tools: Activity, Health (including women's health), Wellness,
|
|
8
|
+
Profile and Discover, covering 28 documented Personal API operations.
|
|
9
|
+
- Progressive offline discovery with exact schemas and examples on demand.
|
|
10
|
+
- MCP guide/domain/operation resources, resource templates, completion,
|
|
11
|
+
server instructions and structured results with diagnostic request IDs.
|
|
12
|
+
- Official API-key exchange, plain-text JWT response support, memory-only caching,
|
|
13
|
+
synchronized renewal and a single retry after bearer rejection.
|
|
14
|
+
- Fixed verified HTTPS origins, strict input validation, timeouts, bounded response
|
|
15
|
+
reads and sanitized failures.
|
|
16
|
+
- `--debug` with private, process-coordinated rotating diagnostics: 1 MB per file
|
|
17
|
+
and three backups, excluding health data and credentials.
|
|
18
|
+
- Versioned PyPI installation and Codex TOML/CLI setup, simple prompts, contributor
|
|
19
|
+
guidance, architecture/API notes, packaging smoke checks and security checks.
|
|
20
|
+
|
|
21
|
+
### Migration from the development checkout
|
|
22
|
+
|
|
23
|
+
The unreleased `stridebridge-mcp` / `stridebridge_mcp` names become `fitro-mcp` /
|
|
24
|
+
`fitro_mcp`. The Codex server entry is `fitro`. Configuration variables use `FITRO_`
|
|
25
|
+
instead of `STRIDGEBRIDGE_`; `GARMIN_PERSONAL_API_KEY` is unchanged. Resource URIs
|
|
26
|
+
use `fitro://`.
|
|
27
|
+
|
|
28
|
+
The requested `~/.starbridge/` directory stays in place. New logs are named
|
|
29
|
+
`fitro.log` through `fitro.log.3`; earlier development logs are left untouched.
|
|
30
|
+
The original one-tool-per-endpoint interface is replaced by domain tools with
|
|
31
|
+
`operation` and `parameters` arguments.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Read [AGENTS.md](AGENTS.md) for the repository map, constraints and definition of done.
|
|
4
|
+
The project uses uv, a `src/` layout, the official MCP Python SDK and strict mypy.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
uv sync --locked
|
|
8
|
+
uv run pre-commit install # Optional; requires a Git checkout.
|
|
9
|
+
uv run ruff check .
|
|
10
|
+
uv run ruff format --check .
|
|
11
|
+
uv run mypy
|
|
12
|
+
uv run pytest
|
|
13
|
+
uv run pip-audit
|
|
14
|
+
uv build
|
|
15
|
+
uv run twine check dist/*
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Run `uv lock` only for intentional metadata/dependency changes. Keep supported Python
|
|
19
|
+
versions installable from the same lockfile. Tests use synthetic tokens and HTTPX
|
|
20
|
+
transports; no real API key or health account is needed.
|
|
21
|
+
|
|
22
|
+
To add a documented GET endpoint, follow the worked extension procedure in
|
|
23
|
+
[architecture](docs/architecture.md) and [code reference](docs/code-reference.md).
|
|
24
|
+
Assign it exactly one domain, preserve upstream parameter names and units, update
|
|
25
|
+
its closed input schema, and test positive/invalid inputs and cross-domain rejection.
|
|
26
|
+
Do not expand the public tool count to mirror endpoint count.
|
|
27
|
+
|
|
28
|
+
Keep docstrings focused on contracts, side effects, errors and resource ownership.
|
|
29
|
+
Explain security-sensitive choices where they occur. Never add payload logging,
|
|
30
|
+
credential fixtures, arbitrary URL access or live API calls to automated checks.
|
|
31
|
+
|
|
32
|
+
Before a release, check both built distributions using `scripts/smoke_test.py` in
|
|
33
|
+
an isolated environment. See [publishing](docs/publishing.md) for exact commands.
|
|
34
|
+
Tests do not establish that every upstream endpoint or account region works live;
|
|
35
|
+
report manual verification separately and without saving data.
|
|
36
|
+
|
|
37
|
+
For security issues, follow [SECURITY.md](SECURITY.md). No public issue should
|
|
38
|
+
include an API key, access token, upstream error body or personal health payload.
|
fitro_mcp-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Fitro MCP contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
fitro_mcp-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: fitro-mcp
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: A local, read-only MCP bridge to personal fitness and wellness data
|
|
5
|
+
Project-URL: Homepage, https://github.com/phanijapps/fitro-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/phanijapps/fitro-mcp
|
|
7
|
+
Project-URL: Documentation, https://github.com/phanijapps/fitro-mcp#readme
|
|
8
|
+
Project-URL: Issues, https://github.com/phanijapps/fitro-mcp/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/phanijapps/fitro-mcp/blob/main/CHANGELOG.md
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: fitness,mcp,personal-api,wellness
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Operating System :: MacOS
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.11
|
|
24
|
+
Requires-Dist: filelock<5,>=3.20
|
|
25
|
+
Requires-Dist: httpx<1,>=0.28.1
|
|
26
|
+
Requires-Dist: jsonschema[format]<5,>=4.23
|
|
27
|
+
Requires-Dist: mcp<2,>=1.30.0
|
|
28
|
+
Requires-Dist: pydantic<3,>=2.12
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# Fitro MCP
|
|
32
|
+
|
|
33
|
+
Your fitness and wellness data, available to an MCP-compatible assistant through
|
|
34
|
+
**five focused tools**: Activity, Health (including women's health), Wellness,
|
|
35
|
+
Profile, and Discover. Uses the official Garmin Connect Personal API, with all
|
|
36
|
+
28 reviewed read-only operations available through progressive discovery.
|
|
37
|
+
|
|
38
|
+
**Version 1.0.0 · Python 3.11–3.14 · MIT · Local stdio MCP**
|
|
39
|
+
|
|
40
|
+
[Source](https://github.com/phanijapps/fitro-mcp) ·
|
|
41
|
+
[PyPI](https://pypi.org/project/fitro-mcp/) ·
|
|
42
|
+
[Changelog](https://github.com/phanijapps/fitro-mcp/blob/main/CHANGELOG.md)
|
|
43
|
+
|
|
44
|
+
## Try a simple prompt
|
|
45
|
+
|
|
46
|
+
After connecting Fitro to Codex, ask:
|
|
47
|
+
|
|
48
|
+
> Use Fitro to show my steps and sleep for yesterday. Discover the operations you
|
|
49
|
+
> need first, and tell me if any data is unavailable.
|
|
50
|
+
|
|
51
|
+
For a connection check that does not request personal health data:
|
|
52
|
+
|
|
53
|
+
> Use Fitro to list the available activity types.
|
|
54
|
+
|
|
55
|
+
Other examples: “Find my five most recent running activities,” or “Compare my
|
|
56
|
+
sleep over the last seven days.” Fitro retrieves data; your assistant writes the
|
|
57
|
+
explanation. Missing measurements should be reported as unavailable.
|
|
58
|
+
|
|
59
|
+
## Install
|
|
60
|
+
|
|
61
|
+
You need Python 3.11+, [uv](https://docs.astral.sh/uv/getting-started/installation/),
|
|
62
|
+
and a **Garmin Connect Personal API key**. A Garmin login/password alone is not
|
|
63
|
+
enough. Create your key using the official
|
|
64
|
+
[Personal API key setup page](https://developer.garmin.com/gc-developer-program/personal/personal-api/).
|
|
65
|
+
Sign in to Garmin Connect, open Personal API Key, select **Create Key**, accept
|
|
66
|
+
the terms, choose an expiry and save the key when it is shown. Fitro exchanges
|
|
67
|
+
that key for a bearer token automatically.
|
|
68
|
+
|
|
69
|
+
Run the versioned PyPI package without managing an environment:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
uvx fitro-mcp@1.0.0 --version
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Or install with pip inside a virtual environment:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
python -m venv .venv
|
|
79
|
+
source .venv/bin/activate
|
|
80
|
+
python -m pip install fitro-mcp==1.0.0
|
|
81
|
+
fitro-mcp --version
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Fitro runs as an MCP stdio process. Starting it without a client waits for protocol
|
|
85
|
+
messages on stdin; it does not open a web page or interactive shell. Linux is tested.
|
|
86
|
+
macOS uses the same POSIX file-permission model but has not been tested locally.
|
|
87
|
+
Native Windows is not supported in 1.0.0; use WSL for a Linux environment.
|
|
88
|
+
|
|
89
|
+
## Add to Codex
|
|
90
|
+
|
|
91
|
+
Add this block to `~/.codex/config.toml` (or edit an existing `fitro` entry):
|
|
92
|
+
|
|
93
|
+
```toml
|
|
94
|
+
[mcp_servers.fitro]
|
|
95
|
+
command = "uvx"
|
|
96
|
+
args = ["fitro-mcp@1.0.0"]
|
|
97
|
+
startup_timeout_sec = 60
|
|
98
|
+
|
|
99
|
+
[mcp_servers.fitro.env]
|
|
100
|
+
GARMIN_PERSONAL_API_KEY = "PASTE_YOUR_PERSONAL_API_KEY_HERE"
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Replace the placeholder locally. Keep the key out of chat and source control.
|
|
104
|
+
Global is the default region. For China-region accounts, add
|
|
105
|
+
`FITRO_REGION = "china"` under the environment table. For debug logging, use
|
|
106
|
+
`args = ["fitro-mcp@1.0.0", "--debug"]`.
|
|
107
|
+
|
|
108
|
+
Alternatively, register a placeholder with the Codex CLI, then edit the key in the
|
|
109
|
+
configuration file:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
codex mcp add fitro --env GARMIN_PERSONAL_API_KEY=PASTE_YOUR_PERSONAL_API_KEY_HERE -- uvx fitro-mcp@1.0.0
|
|
113
|
+
codex mcp list
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
If your Codex launcher supplies the key from its environment, use the following
|
|
117
|
+
instead of the `[mcp_servers.fitro.env]` table:
|
|
118
|
+
|
|
119
|
+
```toml
|
|
120
|
+
# Inside [mcp_servers.fitro]
|
|
121
|
+
env_vars = ["GARMIN_PERSONAL_API_KEY"]
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Do not configure both approaches with a placeholder that overrides the real key.
|
|
125
|
+
If `uvx` is not on your launcher's PATH, set `command` to its absolute path. Allow
|
|
126
|
+
extra startup time for the initial package download. Restart Codex or reconnect its
|
|
127
|
+
MCP server after changing configuration; verify Fitro is connected, then try the
|
|
128
|
+
prompt above. See the [official Codex MCP guide](https://developers.openai.com/codex/mcp).
|
|
129
|
+
|
|
130
|
+
### Run from this checkout
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
uv sync --locked
|
|
134
|
+
uv run fitro-mcp --version
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
For Codex, replace the PyPI entry's command and arguments with:
|
|
138
|
+
|
|
139
|
+
```toml
|
|
140
|
+
[mcp_servers.fitro]
|
|
141
|
+
command = "uv"
|
|
142
|
+
args = ["--directory", "/absolute/path/to/gc-gather-mcp", "run", "--locked", "fitro-mcp"]
|
|
143
|
+
startup_timeout_sec = 60
|
|
144
|
+
|
|
145
|
+
[mcp_servers.fitro.env]
|
|
146
|
+
GARMIN_PERSONAL_API_KEY = "PASTE_YOUR_PERSONAL_API_KEY_HERE"
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
A direct local run can take the key from your shell. Bash example:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
read -rsp 'Personal API key: ' GARMIN_PERSONAL_API_KEY; echo
|
|
153
|
+
export GARMIN_PERSONAL_API_KEY
|
|
154
|
+
uv run fitro-mcp
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
No `.env` file is loaded automatically. Keys are never accepted as command-line
|
|
158
|
+
arguments. Store client configuration with user-only permissions, such as `0600`
|
|
159
|
+
on POSIX systems.
|
|
160
|
+
|
|
161
|
+
### Other MCP clients
|
|
162
|
+
|
|
163
|
+
Clients using the `mcpServers` JSON format can use:
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{
|
|
167
|
+
"mcpServers": {
|
|
168
|
+
"fitro": {
|
|
169
|
+
"command": "uvx",
|
|
170
|
+
"args": ["fitro-mcp@1.0.0"],
|
|
171
|
+
"env": {"GARMIN_PERSONAL_API_KEY": "PASTE_YOUR_PERSONAL_API_KEY_HERE"}
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## What Fitro provides
|
|
178
|
+
|
|
179
|
+
- Five domain/discovery tools with about 77% smaller advertised definitions than
|
|
180
|
+
the original 28-tool interface (serialized JSON size, not a model token benchmark).
|
|
181
|
+
- Offline documentation resources, URI templates and resource argument completion.
|
|
182
|
+
- Validated input schemas, bounded responses, explicit pagination and structured errors.
|
|
183
|
+
- API-key exchange for a bearer token, memory-only caching and one renewal after a 401.
|
|
184
|
+
- Private rotating diagnostics with `--debug`; stdout is reserved for MCP.
|
|
185
|
+
- Typed modular Python code, uv lockfile, Ruff security rules, strict mypy,
|
|
186
|
+
synthetic tests, dependency auditing, package smoke checks and CI.
|
|
187
|
+
|
|
188
|
+
Live token exchange and activity-types retrieval have been verified on the global
|
|
189
|
+
region. Individual health endpoints and China-region authentication are not fully
|
|
190
|
+
verified live. See [authentication](docs/authentication.md) and
|
|
191
|
+
[verification](docs/verification.md) for the precise scope.
|
|
192
|
+
|
|
193
|
+
**Independent project. Not affiliated with, endorsed by, or sponsored by Garmin.**
|
|
194
|
+
Garmin and Garmin Connect are trademarks of Garmin Ltd. or its subsidiaries.
|
|
195
|
+
The [Personal API FAQ](https://developer.garmin.com/gc-developer-program/personal/personal-faq/)
|
|
196
|
+
limits the Personal API to an individual's own data and excludes commercial
|
|
197
|
+
applications serving multiple users. Installing this MIT-licensed client does not
|
|
198
|
+
grant rights to upstream services. The Fitro name has not received trademark clearance.
|
|
199
|
+
|
|
200
|
+
## Domain tools and discovery
|
|
201
|
+
|
|
202
|
+
Only five tools appear in `tools/list`. API endpoints are internal operations,
|
|
203
|
+
not separate tools:
|
|
204
|
+
|
|
205
|
+
| Tool | Operations |
|
|
206
|
+
| --- | --- |
|
|
207
|
+
| `activity` | `activity_types`, `activity`, `activity_workouts`, `search_activities`, `download_activity`, `wellness_activity_range` |
|
|
208
|
+
| `health` | `heart_rate`, `heart_rate_zones`, `hrv`, `hrv_range`, `vo2_max_range`, `fitness_age`, `spo2`, `weight_measurements`, `weight_range`, `weight_goals`, `menstrual_cycle_summary`, `menstrual_cycle_day` |
|
|
209
|
+
| `wellness` | `daily_summary`, `daily_summaries`, `steps_range`, `stress_range`, `hydration_range`, `body_battery`, `sleep`, `sleep_range`, `food_logs` |
|
|
210
|
+
| `profile` | `user_settings` |
|
|
211
|
+
| `discover` | Offline domain browsing, operation search, and exact schemas/examples |
|
|
212
|
+
|
|
213
|
+
Women's health is included in `health`. Each execution tool accepts `operation`
|
|
214
|
+
and `parameters`, enforces its domain boundary, and validates the exact operation
|
|
215
|
+
schema before any authentication or data request.
|
|
216
|
+
|
|
217
|
+
An assistant can progressively discover the operation it needs:
|
|
218
|
+
|
|
219
|
+
1. `discover({})` returns the four domains and operation counts.
|
|
220
|
+
2. `discover({"domain": "wellness"})` returns a short operation page.
|
|
221
|
+
3. `discover({"domain": "wellness", "operation": "sleep_range"})` returns the
|
|
222
|
+
exact parameter schema, a synthetic example, and its documentation URI.
|
|
223
|
+
4. `wellness` executes the operation:
|
|
224
|
+
|
|
225
|
+
```json
|
|
226
|
+
{
|
|
227
|
+
"operation": "sleep_range",
|
|
228
|
+
"parameters": {
|
|
229
|
+
"startDate": "2026-11-01",
|
|
230
|
+
"endDate": "2026-11-07"
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
`discover` also accepts `query` (up to 200 characters), `limit` (1–10, default 8),
|
|
236
|
+
and `offset` for subsequent pages. It returns `total` and `next_offset`; it never
|
|
237
|
+
loads all parameter schemas at once. For example, `{"query": "women"}` finds the
|
|
238
|
+
two cycle operations. Discovery is a local keyword search, not another model call.
|
|
239
|
+
Known operation contracts can be executed directly without repeating discovery.
|
|
240
|
+
|
|
241
|
+
All tools return a structured envelope with `request_id` and `data`. Failures set
|
|
242
|
+
`isError` and include a safe `error.code` and `error.message`. Query data contains
|
|
243
|
+
`operation` and `result`; discovery data contains catalog metadata. A JSON text
|
|
244
|
+
fallback carries the same envelope for clients without structured-result support.
|
|
245
|
+
|
|
246
|
+
Arguments inside `parameters` preserve Swagger names, including `activityId`,
|
|
247
|
+
`calendarDate`, `startDate`, and `endDate`. Dates use `YYYY-MM-DD`. Optional
|
|
248
|
+
arguments are omitted upstream unless supplied; Swagger defaults are informational.
|
|
249
|
+
Activity search accepts `limit` 1–1000 and a nonnegative `start`. There is no
|
|
250
|
+
automatic data pagination: advance `start` explicitly. Data is not silently truncated;
|
|
251
|
+
responses exceeding the configured cap fail with a safe error. Request small ranges.
|
|
252
|
+
|
|
253
|
+
Activity downloads return `result` containing `media_type`, `encoding: "base64"`,
|
|
254
|
+
and `data`. They are never written to disk. Base64 increases output size; large
|
|
255
|
+
files may exceed server or client limits. No arbitrary HTTP or filesystem tools
|
|
256
|
+
are exposed.
|
|
257
|
+
|
|
258
|
+
### MCP resources and completion
|
|
259
|
+
|
|
260
|
+
The server advertises a guide and four domain resources through `resources/list`:
|
|
261
|
+
|
|
262
|
+
- `fitro://guide`
|
|
263
|
+
- `fitro://domains/{domain}`
|
|
264
|
+
- `fitro://operations/{domain}/{operation}`
|
|
265
|
+
|
|
266
|
+
The last two are also resource templates. Domain resources list all operations
|
|
267
|
+
in that domain, while an operation resource supplies its exact schema and example.
|
|
268
|
+
`completion/complete` suggests domain names and domain-scoped operation names for
|
|
269
|
+
these resource templates. All resource reads and completion requests work offline.
|
|
270
|
+
|
|
271
|
+
Resources and tools use the same catalog. The `discover` tool provides the same
|
|
272
|
+
information for clients that do not expose resources to their model. Server
|
|
273
|
+
instructions explain this workflow during initialization. Prompt workflows and
|
|
274
|
+
dynamic tool activation are not part of this interface.
|
|
275
|
+
|
|
276
|
+
**Migration:** the original 28 endpoint tool names are no longer registered. For
|
|
277
|
+
example, replace `get_hrv({"calendarDate": "2026-11-20"})` with
|
|
278
|
+
`health({"operation": "hrv", "parameters": {"calendarDate": "2026-11-20"}})`.
|
|
279
|
+
|
|
280
|
+
## Configuration
|
|
281
|
+
|
|
282
|
+
| Variable | Default | Purpose |
|
|
283
|
+
| --- | --- | --- |
|
|
284
|
+
| `GARMIN_PERSONAL_API_KEY` | required | Personal API credential |
|
|
285
|
+
| `FITRO_REGION` | `global` | `global` (`.com`) or `china` (`.cn`) |
|
|
286
|
+
| `FITRO_TIMEOUT_SECONDS` | `30` | HTTP timeout per network phase, 1–120 seconds |
|
|
287
|
+
| `FITRO_MAX_RESPONSE_BYTES` | `8388608` | Decoded response cap, 1 KiB–32 MiB |
|
|
288
|
+
|
|
289
|
+
No `.env` files are auto-loaded. TLS verification is enabled; redirects and
|
|
290
|
+
HTTPX environment proxy configuration are disabled. Only official regional hosts
|
|
291
|
+
are reachable through the public configuration. Health data returned by a tool is
|
|
292
|
+
visible to your MCP client and potentially its model provider: choose a trusted
|
|
293
|
+
client and configure its data handling accordingly.
|
|
294
|
+
|
|
295
|
+
A 401 triggers one token renewal, then a safe authentication error. A 403 indicates
|
|
296
|
+
permissions, 404 missing data, and 429 a rate limit; wait before retrying. Other
|
|
297
|
+
HTTP and network failures produce sanitized errors. No automatic retries are made
|
|
298
|
+
for rate limits or server errors. Narrow date ranges if responses exceed the cap.
|
|
299
|
+
|
|
300
|
+
## Private diagnostics
|
|
301
|
+
|
|
302
|
+
The region defaults to **global**. For debugging, append `--debug` after the server
|
|
303
|
+
command in your MCP client configuration:
|
|
304
|
+
|
|
305
|
+
```json
|
|
306
|
+
{
|
|
307
|
+
"mcpServers": {
|
|
308
|
+
"fitro": {
|
|
309
|
+
"command": "uv",
|
|
310
|
+
"args": ["--directory", "/absolute/path/to/gc-gather-mcp", "run", "--locked", "fitro-mcp", "--debug"],
|
|
311
|
+
"env": {
|
|
312
|
+
"GARMIN_PERSONAL_API_KEY": "YOUR_PERSONAL_API_KEY"
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
The PyPI equivalent is `"command": "uvx"` with
|
|
320
|
+
`"args": ["fitro-mcp", "--debug"]`. There is no log-level environment setting.
|
|
321
|
+
|
|
322
|
+
Logs go to **`~/.starbridge/fitro.log`**, using the requested `.starbridge`
|
|
323
|
+
directory spelling. The active file rotates before reaching **1,000,000 bytes**;
|
|
324
|
+
three backups (`fitro.log.1` through `.3`) are retained. Each file is at most
|
|
325
|
+
1 MB, for approximately 4 MB total. An additional private lock file coordinates
|
|
326
|
+
rotation across simultaneous clients. Default verbosity is warnings/errors; `--debug`
|
|
327
|
+
adds fixed diagnostic events. On POSIX systems the directory is `0700` and files
|
|
328
|
+
are `0600`; pre-existing symlinks and hard-linked files are refused.
|
|
329
|
+
|
|
330
|
+
Logs contain only timestamps, severity, fixed generic event names, random diagnostic
|
|
331
|
+
request IDs, HTTP status codes and durations. No health payloads, parameter values,
|
|
332
|
+
queried dates, activity IDs, domain/operation names, URLs, headers, keys, tokens or exception
|
|
333
|
+
text are logged. Third-party SDK/HTTP log output is excluded. Diagnostics remain
|
|
334
|
+
local and are not forwarded as MCP logging notifications. stdout remains MCP-only;
|
|
335
|
+
a logging initialization/write failure reports a fixed message on stderr.
|
|
336
|
+
|
|
337
|
+
Match a failed tool result's `request_id` to the local log when troubleshooting.
|
|
338
|
+
Debug output deliberately cannot show upstream response bodies or detailed payloads.
|
|
339
|
+
|
|
340
|
+
## Develop and verify
|
|
341
|
+
|
|
342
|
+
```bash
|
|
343
|
+
uv sync --locked
|
|
344
|
+
uv run ruff check .
|
|
345
|
+
uv run ruff format --check .
|
|
346
|
+
uv run mypy
|
|
347
|
+
uv run pytest
|
|
348
|
+
uv run pip-audit
|
|
349
|
+
uv build
|
|
350
|
+
uv run twine check dist/*
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
Tests never need an API key or live account. See [AGENTS.md](AGENTS.md) for the repo
|
|
354
|
+
map and definition of done, [architecture](docs/architecture.md) for extension
|
|
355
|
+
points, and [publishing](docs/publishing.md) for release steps. See
|
|
356
|
+
[verification results](docs/verification.md) for the checks run.
|
|
357
|
+
|
|
358
|
+
Source: [official Swagger page](https://developer.garmin.com/gc-developer-program/personal/swagger-docs/).
|
|
359
|
+
The bundled catalog contains reviewed operation metadata, not a runtime dependency
|
|
360
|
+
on the documentation website. API responses are returned as provided, with no
|
|
361
|
+
medical interpretation. Code is [MIT licensed](LICENSE).
|