Skip to content

list_projects should paginate and avoid eager per-project details #1066

Description

@tmonestudio

What problem does this solve?

After #1046 restores projects that carry a ::missed shadow row, list_projects still performs expensive work for every database before returning:

  1. opens every project database;
  2. counts all nodes and edges;
  3. resolves Git context for every root;
  4. emits the entire result without pagination metadata.

On a cache with 500 valid project databases, one call took about 61.5 seconds. The response also grows linearly, which makes it easy for MCP clients or harnesses to truncate or reject it without a reliable total / has_more signal.

This is most noticeable in long-lived installations where the project cache grows over time.

Proposed solution

Add deterministic pagination to list_projects:

  • offset (default 0);
  • limit (bounded, for example default 50 / max 100);
  • response metadata: total, returned, offset, limit, has_more;
  • stable sorting before applying the page.

Return a compact entry by default (name + root path). Put node/edge counts, database size, and Git branch behind an explicit include_details option.

A local prototype on the same 500-database cache reduced a compact 50-project page to about 0.4 seconds while reporting total=500 and has_more=true.

Alternatives considered

  • Only fix the ::missed filtering in fix(mcp): ignore ::missed shadow rows when resolving a db's project name #1046: restores correctness, but still performs O(all projects) detail work and emits an unbounded response.
  • Raise client response limits: does not address latency or token growth.
  • Add a central registry: potentially faster, but adds synchronization/migration complexity. Directory scan + sorted pagination is a smaller first step.

Confirmations

  • I searched existing issues and this is not a duplicate.

Metadata

Metadata

Assignees

No one assigned

    Labels

    editor/integrationEditor compatibility and CLI integrationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions