Add repository file/content read tools #12

New issue

Closed

opened 2026-04-19 07:27:06 +00:00 by jbr870 · 0 comments

jbr870 commented

2026-04-19 07:27:06 +00:00

Owner

Problem

The MCP server currently exposes write/manage operations for issues and wiki pages, plus list_my_repos, but has no tools for reading repository file contents. This forces clients to fall back to web_fetch or manual paste when they need to inspect repo files (skills, configs, source, READMEs, etc.).

Hit this concretely while working on the AI SDLC workflow design — needed to read skill files from devwork-skills to ground a discussion and had no way to do it through the MCP.

Proposed tools

Minimum useful set, mapping to existing Forgejo API endpoints:

get_file_contents — fetch a file at owner/repo/path, optional ref (branch/tag/commit). Returns content + metadata (size, sha, encoding).
- Maps to: GET /repos/{owner}/{repo}/contents/{filepath}
list_directory — list entries at a path. Returns name, type (file/dir/symlink), size, sha for each.
- Maps to: same endpoint, returns array when path is a directory
get_repo_tree — recursive tree listing for a ref. Useful for "what's in this repo" without N round-trips.
- Maps to: GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=true

Nice-to-have (separate tickets if preferred)

search_repo_contents — code search within a repo
get_pull_request + get_pull_request_diff — PR review workflows
list_repo_branches — branch enumeration

Considerations

File size limits: large files should either truncate with a clear marker or refuse with a size hint
Binary files: return base64 with a binary: true flag, or refuse with a hint to use a different tool
Default ref: probably the repo's default branch; make explicit in the response

Why now

Read tools unblock a lot of agent workflows where the MCP is the only forge interface (e.g. Claude.ai sessions without local repo access). Currently those sessions can manage issues/wiki but can't see the code those issues/wiki pages are about.

## Problem The MCP server currently exposes write/manage operations for issues and wiki pages, plus `list_my_repos`, but has no tools for reading repository file contents. This forces clients to fall back to `web_fetch` or manual paste when they need to inspect repo files (skills, configs, source, READMEs, etc.). Hit this concretely while working on the AI SDLC workflow design — needed to read skill files from `devwork-skills` to ground a discussion and had no way to do it through the MCP. ## Proposed tools Minimum useful set, mapping to existing Forgejo API endpoints: - **`get_file_contents`** — fetch a file at `owner/repo/path`, optional `ref` (branch/tag/commit). Returns content + metadata (size, sha, encoding). - Maps to: `GET /repos/{owner}/{repo}/contents/{filepath}` - **`list_directory`** — list entries at a path. Returns name, type (file/dir/symlink), size, sha for each. - Maps to: same endpoint, returns array when path is a directory - **`get_repo_tree`** — recursive tree listing for a ref. Useful for "what's in this repo" without N round-trips. - Maps to: `GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=true` ## Nice-to-have (separate tickets if preferred) - `search_repo_contents` — code search within a repo - `get_pull_request` + `get_pull_request_diff` — PR review workflows - `list_repo_branches` — branch enumeration ## Considerations - File size limits: large files should either truncate with a clear marker or refuse with a size hint - Binary files: return base64 with a `binary: true` flag, or refuse with a hint to use a different tool - Default ref: probably the repo's default branch; make explicit in the response ## Why now Read tools unblock a lot of agent workflows where the MCP is the only forge interface (e.g. Claude.ai sessions without local repo access). Currently those sessions can manage issues/wiki but can't see the code those issues/wiki pages are about.

jbr870 closed this issue

2026-04-27 16:41:00 +00:00

jbr870 referenced this issue

2026-05-10 19:31:08 +00:00

Add repository file write tools (create, update, delete) #23

No labels

status/paused

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

jbr870/forgejo-mcp-server#12

No description provided.

Rows
Columns