feat: add list_repo_contents and get_repo_tree MCP tools #117

Merged

BrilliantKahn merged 0 commits from refs/pull/117/head into main

2026-05-06 09:49:54 +00:00

BrilliantKahn commented

2026-05-05 18:50:03 +00:00

(Migrated from codeberg.org)

This PR adds two new MCP tools for exploring a Forgejo repository's file structure: list_repo_contents lists the files and directories at a given path (use path="" to list the repository root, returning one level of entries), and get_repo_tree retrieves the Git tree at a ref, with recursive=true returning the complete file tree in a single response (subject to the server's tree-endpoint size cap). Tool descriptions are precise enough that an LLM can select the right tool without trial and error.

Closes #115.

The pagination design for list_repo_contents follows the approach recommended in the maintainer's review on #115: page and limit are omitted entirely from list_repo_contents because the Forgejo SDK's ListContents does not accept pagination options. Exposing phantom parameters would mislead callers — a caller passing page=2 would silently receive page 1 back with no error. get_repo_tree retains page and limit since GetTreesOptions.ListOptions plumbs them through to a real call. Pagination parameters will be added to list_repo_contents when SDK support lands.

This change has been running on an internal MCP deploy since 2026-05-05 (combined with a separate plain-text fix on a different branch) and all tests pass (go test ./... clean).

This PR adds two new MCP tools for exploring a Forgejo repository's file structure: `list_repo_contents` lists the files and directories at a given path (use `path=""` to list the repository root, returning one level of entries), and `get_repo_tree` retrieves the Git tree at a ref, with `recursive=true` returning the complete file tree in a single response (subject to the server's tree-endpoint size cap). Tool descriptions are precise enough that an LLM can select the right tool without trial and error. Closes #115. The pagination design for `list_repo_contents` follows the approach recommended in the [maintainer's review on #115](https://codeberg.org/goern/forgejo-mcp/issues/115#issuecomment-14349947): `page` and `limit` are omitted entirely from `list_repo_contents` because the Forgejo SDK's `ListContents` does not accept pagination options. Exposing phantom parameters would mislead callers — a caller passing `page=2` would silently receive page 1 back with no error. `get_repo_tree` retains `page` and `limit` since `GetTreesOptions.ListOptions` plumbs them through to a real call. Pagination parameters will be added to `list_repo_contents` when SDK support lands. This change has been running on an internal MCP deploy since 2026-05-05 (combined with a separate plain-text fix on a different branch) and all tests pass (`go test ./...` clean).

BrilliantKahn commented

2026-05-06 09:02:50 +00:00

(Migrated from codeberg.org)

Thanks for the review on both PRs!

On the two nits: agreed on both — limit=1000 makes sense for tree-sized entries

On showboat: it sounds interesting and I'd like to look into it for possible future PRs to land changes more maturely. But I'm unfamiliar with the tool and don't want to hold v2.20.0 while we get up to speed, so skipping for these two — I hope you proceed with the merge bundle as planned.

Looking forward to the release! :)

Thanks for the review on both PRs! On the two nits: agreed on both — limit=1000 makes sense for tree-sized entries On showboat: it sounds interesting and I'd like to look into it for possible future PRs to land changes more maturely. But I'm unfamiliar with the tool and don't want to hold v2.20.0 while we get up to speed, so skipping for these two — I hope you proceed with the merge bundle as planned. Looking forward to the release! :)