monarch-mcp: Instructions file for Claude Code

Repository guidance

Financial data and secrets

Never put real financial data in code, tests, docs, or commits. This includes account and merchant names from a user's history, transaction/category/account IDs, amounts, and spending patterns. Use synthetic examples such as Corner Deli, cat_001, and txn_123. A generic brand example is fine; data copied from an account is not.

Do not read or commit credentials, .env, saved sessions, or financial logs. The tracked .mcp.json loads credentials from .env when it exists; keep secrets out of it. Logs can contain tool arguments and API error details. Review and redact them before sharing.

Development

Use Python 3.10+ and uv. Dependency constraints live in pyproject.toml; commit uv.lock for reproducible source installs.

uv sync --locked
uv run python server.py
uv run python scripts/ci.py

The CI script runs ruff lint/format checks, mypy, and pytest. Individual checks:

uv run ruff check .
uv run ruff format --check .
uv run mypy server.py
uv run pytest tests/ -v --tb=short

Use uv run ruff format . to format and uv add / uv remove to change dependencies. CI selects Python 3.10 through 3.15 explicitly and uses locked installs.

.mcp.json is the headless dev entry (claude -p --mcp-config .mcp.json --strict-mcp-config). It runs this checkout from any directory and starts without .env. tests/test_stdio.py::test_mcp_json_launches_checkout launches it in both protocol eras.

Live integration tests are opt-in and never load .env or saved sessions themselves:

MONARCH_RUN_INTEGRATION=true uv run --env-file .env pytest tests/test_integration.py -v

That command contacts Monarch. Ordinary tests use synthetic data and skip live calls. scripts/health_check.py is a separate live diagnostic. Run it with uv run --env-file .env; it uses the client's session defaults.

Workflow

• Follow the user's task before the backlog. Make small changes and reuse existing patterns.
• Validate behavior, types, and formatting before committing.
• Commit only with explicit permission. Keep commits atomic, titles short and plain, and use the configured Git identity with --no-gpg-sign.
• Update this file for architecture changes, milestones, or new findings, not every commit. Put release history in CHANGELOG.md and user setup in README.md.