From d704f5b82b07752924c73526707d7dac2d942f64 Mon Sep 17 00:00:00 2001 From: b3nw Date: Tue, 5 May 2026 03:27:20 +0000 Subject: [PATCH] docs: add internal deployment guide, remove temp debug files - Delete BUG-REPORT.md (bug resolved) - Delete MonarchAPI.md (research complete, library chosen) - Add .deployment.md with Komodo stack ops, auth notes, and troubleshooting --- .deployment.md | 207 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 .deployment.md diff --git a/.deployment.md b/.deployment.md new file mode 100644 index 0000000..2c7bedb --- /dev/null +++ b/.deployment.md @@ -0,0 +1,207 @@ +# Monarch MCP Custom — Deployment Guide + +> **Internal / Private.** Not for public distribution. This doc covers how the local Komodo deployment works and how to operate it. + +--- + +## Architecture + +``` +Git push to main + | + v +Gitea Actions (.gitea/workflows/build.yaml) + | + v +Docker build + push to gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest + | + v +Komodo Stack "monarch-mcp" pulls image and deploys + | + v +Container runs on host port 8070 (mapped to container 8000) +``` + +--- + +## Gitea Build Workflow + +**File:** `.gitea/workflows/build.yaml` + +Triggers on every push to `main` or `master`: + +1. Checks out the repo +2. Logs into `gitea.ext.ben.io` container registry (uses `secrets.CR_PAT`) +3. Builds and pushes `gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest` + +### Manual Build Trigger + +If you need to force a rebuild without a code change, push an empty commit: + +```bash +git commit --allow-empty -m "chore: trigger rebuild" +git push origin main +``` + +Or edit `.gitea/workflows/build.yaml` and push. + +--- + +## Komodo Stack Deployment + +**Stack Name:** `monarch-mcp` +**Server:** `6942f06939bbe4eb5a9f21aa` (main Docker host) +**Image:** `gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest` +**Host Port:** `8070` → Container `8000` + +### Environment Variables (from `.env`) + +| Variable | Purpose | Source | +|---|---|---| +| `MONARCH_TOKEN` | Session token for Monarch Money API | Extract from browser DevTools | +| `MONARCH_EMAIL` | Account email for re-auth fallback | Plaintext | +| `MONARCH_PASSWORD` | Account password for re-auth fallback | Plaintext | +| `MONARCH_MFA_SECRET` | TOTP secret for re-auth fallback | Plaintext (from 2FA setup) | +| `MONARCH_PORT` | Host port mapping (default 8070) | `.env` | +| `LOG_LEVEL` | Python logging level (INFO/DEBUG) | `.env` | + +### How to Redeploy + +**Via Komodo UI:** +1. Navigate to Stacks → monarch-mcp +2. Click **Deploy** (or **Pull** then **Deploy** to force fresh image) + +**Via MCP / API:** +```python +# Using the komodo_mcp tool +DeployStack(stack="monarch-mcp") +``` + +**Force fresh image pull:** +The stack has `auto_pull: true`, so a standard Deploy should pull the latest image. If not, use **Pull Stack** first. + +--- + +## Container Operations + +### Check Logs + +**Via Komodo UI:** +Stack → monarch-mcp → Logs → Select service `monarch-mcp` + +**Via Komodo API:** +```python +GetStackLog(stack="monarch-mcp", services=["monarch-mcp"], tail=50) +``` + +### Health Check + +The container exposes a health endpoint: + +```bash +curl http://localhost:8070/health +# Expected: {"status": "ok"} +``` + +Docker compose healthcheck config (in `compose.yaml`): +- Interval: 30s +- Timeout: 10s +- Retries: 3 +- Start period: 10s + +--- + +## Local Development + +### Install Dependencies + +```bash +uv sync +``` + +### Run Locally + +```bash +uv run python src/monarch_mcp_custom/server.py +# or +python -m monarch_mcp_custom.server +``` + +### Test the Library Directly + +```bash +uv run python -c " +from monarchmoney import MonarchMoney, MonarchMoneyEndpoints +print(MonarchMoneyEndpoints.BASE_URL) +" +``` + +--- + +## Authentication Notes + +### Token Source +The `MONARCH_TOKEN` is a session token extracted from browser DevTools: +1. Log into Monarch Money at `https://app.monarch.com` +2. Open DevTools → Network → filter by `graphql` +3. Click any request → Headers → `Authorization: Token ` +4. Copy the token value (without `Token ` prefix) + +### Token Lifetime +Tokens appear to last several months. If API calls start returning 401: +1. Extract a fresh token from the browser +2. Update the `MONARCH_TOKEN` env var in Komodo +3. Redeploy the stack + +### Re-Authentication Fallback +If token auth fails, the MCP server will attempt to re-authenticate using `MONARCH_EMAIL`, `MONARCH_PASSWORD`, and `MONARCH_MFA_SECRET`. This is subject to rate limiting by Monarch. + +--- + +## Troubleshooting + +### 401 Unauthorized +- Token expired? Extract fresh token from browser. +- Check `MONARCH_TOKEN` is set correctly in Komodo stack env. +- Verify library version in startup logs (should show `monarchmoney 1.3.2+` and `BASE_URL: https://api.monarch.com`). + +### 429 Rate Limited +- Monarch Money rate-limits login attempts. +- Wait ~15-60 seconds before retrying. +- The retry decorator handles 429 with a 15s backoff. + +### Image Not Updating +- Check Gitea Actions for build failures. +- Force a **Pull Stack** in Komodo before deploying. +- Verify the commit hash in Komodo matches the latest. + +### Build Fails +- Check `.gitea/workflows/build.yaml` logs in Gitea. +- Ensure `secrets.CR_PAT` is valid for `gitea.ext.ben.io`. + +--- + +## Useful Commands + +```bash +# Quick health check +curl -s http://localhost:8070/health | jq . + +# Check running container +docker ps | grep monarch-mcp + +# Inspect container logs directly on host +docker logs monarch-mcp-custom --tail 50 -f + +# Restart container +docker restart monarch-mcp-custom +``` + +--- + +## Related Resources + +- **Repo:** `git.local.ben.io:b3nw/monarch-mcp-custom.git` +- **Container Registry:** `gitea.ext.ben.io/b3nw/monarch-mcp-custom` +- **Komodo Stack:** `monarch-mcp` (ID: `694b492b6e2254e6ad636e9b`) +- **Upstream Library:** https://github.com/bradleyseanf/monarchmoneycommunity