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>

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