health-mcp: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

server.py is the command-line entry point. It adjusts sys.path before loading the application from mcp/main.py, where the FastMCP server and transport are configured. Garmin API access, authentication, response mapping, and caching live in gateway.py. Tool handlers are registered in mcp/tools.py, while their dataclass response types are defined in mcp/models.py.

Tests live in tests/ and mirror the main boundaries: test_gateway.py covers Garmin mapping and caching, and test_server.py checks tool registration. icon.png is the README asset. Keep mcp/ without an __init__.py; making it a package would shadow FastMCP's third-party mcp dependency.

Build, Test, and Development Commands

Create an isolated environment and install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run all tests with python -m unittest discover -s tests. Start the default stdio server with python server.py; stdin is reserved for MCP JSON-RPC. For local HTTP development, run python server.py --transport http, which exposes http://127.0.0.1:8000/mcp. There is no separate build step or configured lint/format command.

Coding Style & Naming Conventions

Follow existing Python style: four-space indentation, type annotations, from __future__ import annotations, and small single-purpose helpers. Use snake_case for functions and variables, PascalCase for classes and dataclasses, and leading underscores for private helpers. MCP tool names use the get_<metric> pattern. Keep imports grouped as standard library, third-party, then local modules.

Testing Guidelines

Tests use the standard-library unittest framework and should be named test_*.py, with methods beginning test_. Avoid live Garmin calls: inject a fake client or gateway, as current tests do. Add focused tests for response mapping, cache behavior, validation, and registered tool names when changing those areas.