AI Agents: LocalDB Simulator

AI Agents Key feature

localdb-simulator ships a built-in MCP server so AI coding agents (Claude Code, Cursor, OpenCode…) can start, reset, seed and query your test databases: without Docker and with deterministic state.

Why agents care: no Docker daemon to pull, no cloud account, wire-compatible drivers, and lds test --reset gives a reproducible baseline for every run.

How the pieces fit together

AI Agent

Claude Code · Cursor · OpenCode

▼ MCP stdio

lds mcp

14 tools · 2 resources (JSON-RPC)

▼ REST /api/v1

Emulators

Redis · PostgreSQL · MongoDB on 127.0.0.1

▼ wire protocol

Your app + tests

ioredis · pg · mongodb drivers

The agent drives the emulators through MCP; your application connects with ordinary drivers, exactly as it would against production.

The deterministic test loop

1 · Reset flush + restart

→

2 · Seed baseline fixture

→

3 · Run tests or queries

→

4 · Verify assert on state

→

5 · Cleanup snapshot restore / reset

One command covers steps 1 and 2: lds test --reset --fixture baseline.yaml. Idempotent: every run starts from exactly the same state.

1 · Register the MCP server (once per project)

Pick your client. The server command is always the same: lds mcp (or npx @localdb/cli mcp).

$ claude mcp add localdb -- npx @localdb/cli mcp

Or add the server to your client's MCP config file (the command is always lds mcp):

Client	Config file	Entry
Claude Code	`.mcp.json`	`{ "mcpServers": { "localdb": { "command": "lds", "args": ["mcp"] } } }`
Cursor	`.cursor/mcp.json`	`{ "mcpServers": { "localdb": { "command": "lds", "args": ["mcp"] } } }`
VS Code (Copilot)	`.vscode/mcp.json`	`{ "servers": { "localdb": { "command": "lds", "args": ["mcp"] } } }`
OpenCode	`opencode.json`	`{ "mcp": { "localdb": { "type": "local", "command": ["lds", "mcp"] } } }`

Verify the registration, then ask the agent to run list_services. The response shows every emulator with its connection string.

MCP tools reference

Tool	What it does
`list_services`	All emulators: status, port, connection string, metrics
`service_status`	Detailed status and metrics for one service
`start_service` / `stop_service` / `restart_service`	Lifecycle control
`reset_service`	Flush all data and restart (deterministic empty state)
`run_query`	SQL (postgres) or MQL (mongodb): `db.collection.find({...})`
`list_keys` / `get_key`	Browse keys (redis), tables (postgres), collections (mongodb)
`snapshot_save` / `snapshot_list` / `snapshot_restore`	Checkpoint and restore all services
`compat_report`	Supported / partial / unsupported commands per emulator
`get_metrics`	Live memory, uptime, commands/sec, key count

Resources: localdb://services and localdb://services/{name}/compat are readable directly as JSON.

2 · The deterministic test workflow

The canonical agent workflow: reset to a known baseline, run tests, leave no state behind:

$ lds test --reset --fixture examples/fixtures/baseline.yaml

--reset flushes and restarts every service; --fixture seeds a baseline afterwards. Idempotent: the result state is exactly the baseline, every time. In CI the same command replaces Docker services: blocks:

# .github/workflows/test.yml
- run: pnpm install
- run: npx @localdb/cli test --reset --fixture examples/fixtures/baseline.yaml
- run: pnpm test          # connects to 127.0.0.1:6379 / :5432 / :27017

3 · Example: agent fixes a failing test

Give the agent a task such as: "The checkout test fails because the cart is empty after checkout. Fix it, then verify with a clean Redis state." A well-behaved agent walks this path:

list_services to confirm redis + postgres are running
compat_report (redis) to learn that MULTI/EXEC are unsupported, so it avoids transactions
reset_service (redis) for a clean state, then snapshot_save as a checkpoint
run_query (postgres) to inspect the schema, then edit the code
Run the app tests, which connect through real drivers
run_query to assert the cart was cleared, then snapshot_restore to leave no residue

4 · Know the limits before you write (compat_report)

Every emulator publishes an honest compatibility matrix. Call it before writing queries so the agent never hits a false failure:

$ lds compat
Redis: RESP (engine: scratch)
  ✅ 90+ supported · ⚠️ 3 partial · ❌ 38 unsupported
  unsupported: MULTI EXEC EVAL BLPOP XADD GEOADD ...

The same data is available to the agent as the compat_report MCP tool or the GET /api/v1/services/:name/compat endpoint. Postgres and MongoDB are backed by real engines, so their reports are correspondingly short.