feat(mcp): add list_tree tool

[brianphillips]

This PR adds a list_tree tool to the MCP package. This tool allows an agent to list files and directories from a repository path. This can be used as a simple directory listing tool or for a directory tree tool by specifying a depth > 1

Summary by CodeRabbit

• New Features

  • Added a new list_tree tool to browse repository trees with depth control, includeFiles/includeDirectories toggles, and a maxEntries limit.

• Documentation

  • Added usage details, parameters, and examples for the new list_tree tool in docs, README, and changelog.

• Bug Fixes

  • Improved repository-not-found message to include the repository name for clearer diagnostics.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a new MCP tool list_tree (client method, server tool, schemas, types, utils, and documentation) that lists repository files/directories with depth, includeFiles/includeDirectories, and maxEntries controls; returns sorted, deduplicated entries with truncation metadata.

Changes

Cohort / File(s)	Summary
Documentation docs/docs/features/mcp-server.mdx, packages/mcp/README.md, packages/mcp/CHANGELOG.md	Added docs and changelog entries describing the new list_tree tool and its parameters (repo, path, ref, depth, includeFiles, includeDirectories, maxEntries).
Client API packages/mcp/src/client.ts	Added listTree(request: ListTreeApiRequest) which POSTs to /api/tree, sends JSON body and optional API key header, and validates/parses the response via new schema.
Server & Exports packages/mcp/src/index.ts	Registered list_tree tool implementation on the MCP server (breadth-first traversal, depth/maxEntries bounds, deduplication, filtering, truncation) and exported related constants, types, and utilities. (Implementation appears inserted twice.)
Schemas / Constants packages/mcp/src/schemas.ts	Added API and public schemas: listTreeApiRequestSchema, listTreeApiResponseSchema, listTreeRequestSchema, listTreeEntrySchema, listTreeResponseSchema, plus constants DEFAULT_TREE_DEPTH, MAX_TREE_DEPTH, DEFAULT_MAX_TREE_ENTRIES, MAX_MAX_TREE_ENTRIES.
Types packages/mcp/src/types.ts	Exported new types mapped from schemas: ListTreeApiRequest, ListTreeApiResponse, ListTreeApiNode, ListTreeRequest, ListTreeEntry, ListTreeResponse.
Utilities packages/mcp/src/utils.ts	Added normalizeTreePath, joinTreePath, buildTreeNodeIndex, and sortTreeEntries for path normalization, tree indexing, and stable sorting of entries.
Web API message packages/web/src/features/git/getTreeApi.ts	Adjusted repository-not-found response to include a descriptive message: notFound(\Repository "${repoName}" not found.`)`.

Sequence Diagram

sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server
    participant TreeAPI as Tree API (/api/tree)

    Client->>Server: list_tree(request: repo,path,ref,depth,filters,maxEntries)
    Server->>Server: normalizeTreePath(path)
    Server->>Server: enforceBounds(depth,maxEntries)
    alt includeFiles OR includeDirectories
        Server->>TreeAPI: POST /api/tree (breadth-first per depth)
        TreeAPI-->>Server: tree nodes
        Server->>Server: buildTreeNodeIndex(nodes)
        Server->>Server: extract, dedupe, filter entries
        Server->>Server: sortTreeEntries(entries)
        Server->>Server: truncateWhenMaxReached()
    else both filters false
        Server->>Server: return empty entries
    end
    Server-->>Client: ListTreeResponse(entries,totalReturned,truncated)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(mcp): add list_tree tool' accurately and concisely summarizes the main change—adding a new list_tree tool to the MCP package.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[brendan-kellam]

This approach makes sense for the apis that we expose, and I'm happy to ship this. For context,/api/tree is designed around the file tree viewer in the code browser, and is why we accept a list of paths (representing open directories) and return a tree spanning the union.

An alternative, potentially simpler, approach I was going to suggest is that we could use ls-tree with -r to recurse from a specified path. It does not accept a max depth unfortunately, so we would need to truncate the output to the specified depth. Perf is ok (because of #791), even on large repos like UnrealEngine:

> UnrealEngine git:(release) time git ls-tree -r HEAD . > /dev/null
git ls-tree -r HEAD . > /dev/null  0.10s user 0.02s system 94% cpu 0.125 total

Regardless of the approach, we will want to move this api surface into the server s.t., we can also add a list_tree tool to the Ask agent. I'll leave that for a follow-up PR that I can open later this week.