docs: recommend Postgres + Valkey MCP servers for agent DX - #113
Merged
Conversation
Adds a Reference page and an opt-in .mcp.json.example wiring read-only Postgres (crystaldba/postgres-mcp, --access-mode=restricted) and the official Redis MCP (redis-mcp-server) at the local dev stack, so a coding agent can read the live schema, rows, cache keys, and queue state instead of guessing. The dev overlay already publishes 5432/6379 on the host (prod never does), so the config works after `dev.sh up` + `cp .mcp.json.example .mcp.json`. Both servers run via uvx (the postgres one pinned to --python 3.13 to dodge a missing pglast wheel on newer Pythons). .mcp.json is gitignored; the example is the source. Fills the ROADMAP Workstream-D 'AI MCP recommendation' item. Validated: both servers install + run via the exact commands; the example's connection strings authenticate against the running dev Postgres and Valkey; docs build:ci clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Building on BoringStack with a coding agent, the agent reads code fine but is blind to runtime state — live schema, rows, cache keys/TTLs, queue backlog — so it guesses. This wires MCP servers at the local dev stack to close that gap. Fills the
ROADMAP.mdWorkstream-D "AI MCP recommendation" item.What's added
.mcp.json.example(repo root, opt-in) —cp .mcp.json.example .mcp.jsonand the agent gets:postgres-mcp--access-mode=restricted— schema, indexes, row samples,EXPLAIN. Pinned--python 3.13(newer Pythons lack apglastwheel and fall back to a failing source build).redis-mcp-server— keys, TTLs,bull:*queue state.uvx; connection defaults match the dev stack (app/app_dev_password/app, Valkey DB 0).reference/mcp-servers.mdx— why, 4-step setup, a trigger→use table, dev-only + read-only cautions (incl. an optional read-only Postgres role), tie-back to lint-as-contract / spec loop. Sidebar entry under Reference + an inbound link frombefore-you-build..gitignore— ignores the user's real.mcp.json(may carry creds); the example is the tracked source.Why it works with zero extra infra
The
development-labelsoverlay already publishes Postgres5432and Valkey6379on the host "so developers canpsql/valkey-cli" — production never does. So afterdev.sh up, a host-run MCP server connects straight to the dev DBs.Validation
uvxcommands in the example.SELECTok) and Valkey (PONG).bun run build:ci(docs) clean; pre-push gate (security + docs) passed.cp .mcp.json.example .mcp.json, open Claude Code, ask "list the tables" / "show the cache keys"; confirm a write through the Postgres server is refused (restricted mode).Dev-DX only — no API/UI/prod runtime changes.