mcp-timely CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Dependencies are managed with uv. Python >= 3.12.

uv sync                                   # install deps (incl. dev group)
uv run pytest                             # full suite (in-memory MCP client, no network)
uv run pytest tests/test_session.py -k rotated   # single test by name
uv run ruff check .                       # lint
uv run ruff format .                      # format

uv run mcp-timely auth                    # one-time OAuth bootstrap (prints URL, takes OOB code)
uv run mcp-timely                         # run stdio server (default)
TRANSPORT=http MCP_API_KEY=dev uv run mcp-timely   # HTTP server on :8000 (/mcp, /health)

docker compose up                         # HTTP server on :8011 (maps to container :8000)

Git & release conventions

Release is fully automated: any push to main that changes non-doc files triggers .github/workflows/release.yml, which runs tests + pip-audit, bumps the patch in pyproject.toml, appends to CHANGELOG.md, tags vX.Y.Z, builds/pushes a multi-arch image to ghcr.io/caseyro/mcp-timely, then triggers the Komodo stack redeploy via signed webhook.

• Never hand-edit version in pyproject.toml — the CI owns it.
• Include [skip ci] in a commit message to skip the release.
• Pure-markdown and tests/** changes don't trigger a release (paths-ignore).
• Rebase feature branches before merging to main, or the auto-bump commit races yours.
• A green run is not a release: confirm the v* tag appeared.
• The Komodo trigger step is skipped when the KOMODO_WEBHOOK_SECRET repo secret is unset; when set, it must match the stack's webhook secret exactly (Komodo 401s silently on mismatch).
• Dependabot runs weekly (uv, docker, actions ecosystems) with auto-merge; each merged PR ships a release.

Architecture

FastMCP 3.x server (src layout, src/mcp_timely/) exposing three question-shaped, read-only tools over Timely's API. No write path, no user/team parameters: everything is scoped to the authorized user (account + user id resolved lazily at first call and cached).