From 044086b067bfa55c0ac685a2b931b3a1deda5126 Mon Sep 17 00:00:00 2001 From: Mathias Bergqvist Date: Mon, 4 May 2026 22:11:50 +0200 Subject: [PATCH] feat(tools): file_read with default-branch resolution Adds GetFileContents to the gitea client and a file_read MCP tool. When ref is omitted, the tool resolves the repo default_branch via GetRepo before fetching contents. Decoded content capped at 1 MiB. Co-Authored-By: Claude Sonnet 4.6 --- cmd/gitea-mcp/main.go | 1 + internal/gitea/files.go | 34 ++++++++++++ internal/gitea/files_test.go | 30 +++++++++++ internal/tools/file_read.go | 88 ++++++++++++++++++++++++++++++++ internal/tools/file_read_test.go | 64 +++++++++++++++++++++++ 5 files changed, 217 insertions(+) create mode 100644 internal/gitea/files.go create mode 100644 internal/gitea/files_test.go create mode 100644 internal/tools/file_read.go create mode 100644 internal/tools/file_read_test.go diff --git a/cmd/gitea-mcp/main.go b/cmd/gitea-mcp/main.go index eaf27bd..de92eb7 100644 --- a/cmd/gitea-mcp/main.go +++ b/cmd/gitea-mcp/main.go @@ -29,6 +29,7 @@ func main() { reg := registry.New() reg.Register(tools.NewRepoList(giteaClient, ownerAllow)) reg.Register(tools.NewRepoGet(giteaClient, ownerAllow)) + reg.Register(tools.NewFileRead(giteaClient, ownerAllow)) mcpSrv := mcp.NewServer(mcp.ServerOptions{ Registry: reg, diff --git a/internal/gitea/files.go b/internal/gitea/files.go new file mode 100644 index 0000000..db70de6 --- /dev/null +++ b/internal/gitea/files.go @@ -0,0 +1,34 @@ +package gitea + +import ( + "context" + "encoding/json" + "fmt" +) + +type FileContents struct { + Path string `json:"path"` + Sha string `json:"sha"` + Size int64 `json:"size"` + Content string `json:"content"` + Encoding string `json:"encoding"` +} + +func (c *Client) GetFileContents(ctx context.Context, owner, repo, path, ref string) (*FileContents, error) { + p := fmt.Sprintf("/api/v1/repos/%s/%s/contents/%s", owner, repo, path) + if ref != "" { + p += "?ref=" + ref + } + body, status, err := c.GetJSON(ctx, p) + if err != nil { + return nil, err + } + if err := MapStatus(status, body); err != nil { + return nil, err + } + var fc FileContents + if err := json.Unmarshal(body, &fc); err != nil { + return nil, err + } + return &fc, nil +} diff --git a/internal/gitea/files_test.go b/internal/gitea/files_test.go new file mode 100644 index 0000000..7e9246d --- /dev/null +++ b/internal/gitea/files_test.go @@ -0,0 +1,30 @@ +package gitea_test + +import ( + "context" + "net/http" + "net/http/httptest" + "testing" + + "gitea.d-ma.be/mathias/gitea-mcp/internal/gitea" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestGetFileContents(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/api/v1/repos/mathias/infra/contents/README.md", r.URL.Path) + assert.Equal(t, "main", r.URL.Query().Get("ref")) + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"path":"README.md","sha":"deadbeef","size":13,"content":"SGVsbG8sIHdvcmxkIQ==","encoding":"base64"}`)) + })) + defer srv.Close() + + c := gitea.NewClient(srv.URL, "tok") + fc, err := c.GetFileContents(context.Background(), "mathias", "infra", "README.md", "main") + require.NoError(t, err) + assert.Equal(t, "README.md", fc.Path) + assert.Equal(t, "deadbeef", fc.Sha) + assert.Equal(t, int64(13), fc.Size) + assert.Equal(t, "SGVsbG8sIHdvcmxkIQ==", fc.Content) +} diff --git a/internal/tools/file_read.go b/internal/tools/file_read.go new file mode 100644 index 0000000..08c7aeb --- /dev/null +++ b/internal/tools/file_read.go @@ -0,0 +1,88 @@ +package tools + +import ( + "context" + "encoding/base64" + "encoding/json" + "fmt" + + "gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist" + "gitea.d-ma.be/mathias/gitea-mcp/internal/gitea" + "gitea.d-ma.be/mathias/gitea-mcp/internal/registry" +) + +const fileReadMaxBytes = 1 << 20 // 1 MiB + +type FileRead struct { + c *gitea.Client + a *allowlist.Allowlist +} + +func NewFileRead(c *gitea.Client, a *allowlist.Allowlist) *FileRead { + return &FileRead{c: c, a: a} +} + +func (t *FileRead) Descriptor() registry.ToolDescriptor { + return registry.ToolDescriptor{ + Name: "file_read", + Description: "Read a file from a repo at a given ref. Defaults to the repo's default branch.", + InputSchema: json.RawMessage(`{ + "type":"object", + "properties":{ + "owner":{"type":"string"}, + "name":{"type":"string"}, + "path":{"type":"string"}, + "ref":{"type":"string"} + }, + "required":["owner","name","path"] + }`), + } +} + +type fileReadArgs struct { + Owner string `json:"owner"` + Name string `json:"name"` + Path string `json:"path"` + Ref string `json:"ref"` +} + +func (t *FileRead) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) { + var args fileReadArgs + if err := parseArgs(raw, &args); err != nil { + return nil, err + } + if err := t.a.Check(args.Owner); err != nil { + return nil, err + } + + ref := args.Ref + if ref == "" { + repo, err := t.c.GetRepo(ctx, args.Owner, args.Name) + if err != nil { + return nil, err + } + ref = repo.DefaultBranch + } + + fc, err := t.c.GetFileContents(ctx, args.Owner, args.Name, args.Path, ref) + if err != nil { + return nil, err + } + + if fc.Size > fileReadMaxBytes { + return nil, fmt.Errorf("file %q size %d exceeds 1MiB cap: %w", args.Path, fc.Size, gitea.ErrValidation) + } + + decoded, err := base64.StdEncoding.DecodeString(fc.Content) + if err != nil { + return nil, fmt.Errorf("decode base64 content: %w", err) + } + + return textOK(map[string]any{ + "path": fc.Path, + "ref": ref, + "sha": fc.Sha, + "size": fc.Size, + "content": string(decoded), + }) +} diff --git a/internal/tools/file_read_test.go b/internal/tools/file_read_test.go new file mode 100644 index 0000000..f49ba24 --- /dev/null +++ b/internal/tools/file_read_test.go @@ -0,0 +1,64 @@ +package tools_test + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist" + "gitea.d-ma.be/mathias/gitea-mcp/internal/gitea" + "gitea.d-ma.be/mathias/gitea-mcp/internal/tools" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestFileReadToolWithExplicitRef(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/api/v1/repos/mathias/infra/contents/README.md", r.URL.Path) + assert.Equal(t, "main", r.URL.Query().Get("ref")) + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"path":"README.md","sha":"deadbeef","size":13,"content":"SGVsbG8sIHdvcmxkIQ==","encoding":"base64"}`)) + })) + defer srv.Close() + + tool := tools.NewFileRead(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"})) + out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","path":"README.md","ref":"main"}`)) + require.NoError(t, err) + + var result map[string]any + require.NoError(t, json.Unmarshal(out, &result)) + assert.Equal(t, "README.md", result["path"]) + assert.Equal(t, "main", result["ref"]) + assert.Equal(t, "Hello, world!", result["content"]) +} + +func TestFileReadToolDefaultBranchResolution(t *testing.T) { + mux := http.NewServeMux() + mux.HandleFunc("/api/v1/repos/mathias/infra", func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"name":"infra","full_name":"mathias/infra","default_branch":"main"}`)) + }) + mux.HandleFunc("/api/v1/repos/mathias/infra/contents/README.md", func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "main", r.URL.Query().Get("ref")) + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"path":"README.md","sha":"deadbeef","size":13,"content":"SGVsbG8sIHdvcmxkIQ==","encoding":"base64"}`)) + }) + srv := httptest.NewServer(mux) + defer srv.Close() + + tool := tools.NewFileRead(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"})) + out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","path":"README.md"}`)) + require.NoError(t, err) + + var result map[string]any + require.NoError(t, json.Unmarshal(out, &result)) + assert.Equal(t, "main", result["ref"]) +} + +func TestFileReadAllowlistRejects(t *testing.T) { + tool := tools.NewFileRead(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"})) + _, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"infra","path":"README.md"}`)) + require.Error(t, err) +}