Problem

When codedb mcp is launched by an MCP client (opencode, Claude Code, etc.) from an unexpected cwd, or when the client does not provide usable roots, the server enters scan=loading_snapshot with files=0 and never recovers.

This produces a connected but functionally empty MCP server.

Observed behavior

cd /Users/dennis/Projects/personal
codedb snapshot        # snapshot has 17 files
codedb mcp             # files=0 scan=loading_snapshot (stuck)
codedb mcp --help      # starts MCP server instead of showing help
codedb mcp --snapshot  # silently ignored, starts server

The only workaround is wrapping the command in sh -lc "cd /path && exec codedb mcp".

Root causes

1. Argument parsing: codedb mcp --help starts the server instead of printing help. Unknown flags like --snapshot are silently ignored.
2. Root resolution: When root == "." and no CODEDB_ROOT is set, the server enters deferred mode and waits for MCP roots. If the client never sends roots (or sends empty roots), the 3s fallback fires — but if cwd is not indexable (e.g. /), the scan never triggers and loading_snapshot persists forever.
3. No git root detection: Running codedb mcp from a subdirectory of a git repo does not discover the repo root.
4. Roots handshake errors: If roots/list returns an error, missing result, or malformed roots, the deferred scan is never triggered.

Expected behavior

1. codedb mcp --help should print help and exit
2. codedb mcp [path] should honor the documented path argument
3. Unknown flags should be rejected with a clear error
4. Git root should be auto-detected from cwd
5. Scan state should never remain stuck in loading_snapshot indefinitely
6. MCP stdout must contain only JSON-RPC messages

Related (already closed)

• mcp: deferred scan stuck in loading_snapshot when client returns no roots #384: deferred scan stuck in loading_snapshot when client returns no roots
• mcp: tool calls during scan-in-progress return empty without indication #371: MCP tool calls during scan return empty results
• Occasional "Transport closed" MCP crash #278: MCP transport-close risk from stdout logging

These were partially addressed but the combined scenario (MCP client + unexpected cwd + no roots) still fails.