Skip to main content

​
schemabrain doctor

Two modes:
  1. Config health report (default) — checks the host’s MCP config block, the local store, and optionally probes the source database.
  2. Mock-agent smoke (--verify) — runs one end-to-end MCP turn against the substrate, without needing an LLM key or a running MCP host.
schemabrain doctor --host claude-desktop --store-path ./schemabrain.db

​
Flags

FlagDefaultPurpose
--source URL(none — source checks skipped)Source URL to probe (SELECT 1 + read-only session check). Deprecated when the URL contains a password.
--url-env VARNAME(none)Env var holding the source URL. Preferred over --source.
--store-path PATH./schemabrain.dbPath to the local SQLite store.
--host {claude-desktop,claude-code,cursor,windsurf,manual}claude-desktopWhich host config to check. manual skips host-config checks.
--json(off)Emit machine-readable JSON to stdout instead of the human-readable report to stderr. Useful for CI / monitoring.
--verify(off)Run the mock-agent smoke instead of the config-health report.

​
What the config report checks

For --host claude-desktop (and the other supported hosts), doctor walks the host’s config file looking for the schemabrain MCP server entry. It validates:
  • The config file exists at the expected platform path.
  • A schemabrain server block is present.
  • The command resolves to an executable on disk.
  • The args include serve and at least one of --source / --url-env.
  • The --store-path argument points to a readable file (when --store-path is also passed to doctor).
  • The store contains at least one indexed source.
  • When --source / --url-env is also passed, a SELECT 1 probe succeeds and the session is read-only on Postgres.
Each check renders as a Rich-formatted line with a pass / fail / skip status. Failures include a guided next step.

​
--verify (mock-agent smoke)

The --verify mode simulates one MCP tool turn end-to-end without an LLM and without a host:
  1. list_entities — confirms the store carries at least one confirmed entity.
  2. describe_entity on the first entity — confirms drill-down works.
  3. find_relevant_entities with a synthetic query — confirms the retriever returns results.
  4. get_metric on the first metric (if any are declared) — confirms the SQL compiler and (when configured) the PII policy machinery wires up.
Exits 0 if all required stages pass, 2 if any fail. This is the right command to run in CI as a substrate smoke before promoting a build. 
schemabrain doctor --verify --store-path ./schemabrain.db

​
Exit codes

CodeMeaning
0All checks passed.
2At least one check failed.

​
Examples

​
Default — check Claude Desktop wiring

schemabrain doctor --host claude-desktop --store-path ./schemabrain.db

​
Check including source probe

schemabrain doctor --host claude-desktop \
    --store-path ./schemabrain.db \
    --url-env DATABASE_URL

​
CI JSON mode

schemabrain doctor --host manual --store-path ./schemabrain.db --json > doctor.json

​
Substrate smoke (no host, no LLM key)

schemabrain doctor --verify --store-path ./schemabrain.db

schemabrain init

The wizard that wires the config doctor then validates.

schemabrain check

Drift check between persisted definitions and the live source.

schemabrain serve

The server doctor --verify smoke-tests the substrate of.

Setup troubleshooting

Common config failures and their fixes.