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 <noreply@anthropic.com>

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,

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
+}

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)
+}

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),
+	})
+}

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)
+}