Skip to content

perf: serve-first startup — decouple MCP from index completion #207

@justrach

Description

@justrach

Design from justrach/turbodb — adapted from turbodb's lazy-serve architecture.

Problem

MCP server blocks until the full scan completes. On openclaw (4,950 files), startup takes 42 seconds before the first query can be served. Agents wait with no feedback.

Evidence

Head-to-head benchmark:

  • codedb: 42s before first query
  • Competitor: 16ms to first query (indexes lazily in background)

Proposed Solution

Start serving MCP immediately, index in background:

  1. Load snapshot (if exists) → serve MCP immediately (<100ms)
  2. If no snapshot: walk file list only (~500ms) → serve partial tree/find results
  3. Background thread: build outlines → build trigrams → write snapshot
  4. codedb_status reports scan progress (walking/indexing/ready)

Failing test

test "issue-207: MCP responds during background scan" {
    // Start MCP server
    // Send codedb_status before scan completes
    // Verify response (even if partial results)
}

Expected impact

Metric Before After
Time to first query 42s <100ms (snapshot) or ~500ms (walk)
Full index available 42s 42s (same, but in background)

Files to modify

  • src/main.zig — MCP startup path, decouple scanBg from serving

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions