docs: agent/MCP access guide — connect + query finance data from any MCP client

2026-07-25 22:27:19 +10:00
parent 831d30669b
commit 856e1a51ab
3 changed files with 263 additions and 0 deletions
@@ -135,6 +135,19 @@ cd /mnt/m2cache/appdata/finance-app && npx prisma generate
 ```
 Docker builds run `npx prisma generate` automatically. Do not commit `src/generated/prisma/` — it is gitignored.

+## Agent / MCP Access
+
+Agents read this DB through the read-only `postgres-personal` MCP server (lives in the
+`personal-agent-gateway` repo, not here): `agent_ro` role, SELECT-only, SQLGlot guardrail,
+100-row cap, every call audited to `mcp_query_log`. See `docs/agent-access.md` for the tool
+list, the five analysis views, and per-client setup (Claude Code, Codex, Hermes).
+
+Two things to remember when changing the schema: the agent views are created by
+`smarthome/personal-agent/migrations/006_agent_read_role_views.sql` (not Prisma) and read
+`transactions`/`statements`/`expense_metadata` columns directly — rename a column and they
+break or go stale. And the views are **not** owner-scoped and do **not** merge
+`transaction_overrides`, so agent numbers can differ from the UI.
+
 ## Known Gaps / TODOs

 See `README.md` → **Known Gaps / TODOs** for full details.