monarch-mcp-custom/.deployment.md

# 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 <value>`
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