feat(tools): dir_list

internal/gitea/files.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/url"
 )
 
 type FileContents struct {
@@ -150,6 +151,36 @@ func (c *Client) GetBranchProtection(ctx context.Context, owner, repo, branch st
 	return &bp, nil
 }
 
+type DirEntry struct {
+	Name string `json:"name"`
+	Path string `json:"path"`
+	Type string `json:"type"`
+	Sha  string `json:"sha"`
+	Size int64  `json:"size"`
+}
+
+func (c *Client) ListContents(ctx context.Context, owner, repo, path, ref string) ([]DirEntry, error) {
+	p := fmt.Sprintf("/api/v1/repos/%s/%s/contents/%s", owner, repo, path)
+	if ref != "" {
+		p += "?ref=" + url.QueryEscape(ref)
+	}
+	body, status, err := c.GetJSON(ctx, p)
+	if err != nil {
+		return nil, err
+	}
+	if err := MapStatus(status, body); err != nil {
+		return nil, err
+	}
+	if len(body) > 0 && body[0] == '{' {
+		return nil, fmt.Errorf("path is a file, not a directory — use file_read: %w", ErrValidation)
+	}
+	var entries []DirEntry
+	if err := json.Unmarshal(body, &entries); err != nil {
+		return nil, err
+	}
+	return entries, nil
+}
+
 // UpsertFile creates a file when args.Sha is empty (POST) or updates an existing
 // file when args.Sha is set (PUT). Gitea routes both operations by HTTP method on
 // the same /contents/{path} URL, and rejects PUT without a sha.

internal/gitea/files_test.go

@@ -198,3 +198,38 @@ func TestGetBranchProtectionNotFoundReturnsUnprotected(t *testing.T) {
 	require.NoError(t, err)
 	assert.False(t, bp.Protected)
 }
+
+func TestListContentsDirectory(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/o/r/contents/src", r.URL.Path)
+		assert.Equal(t, "main", r.URL.Query().Get("ref"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[
+			{"name":"main.go","path":"src/main.go","type":"file","sha":"abc","size":100},
+			{"name":"lib","path":"src/lib","type":"dir","sha":"def","size":0}
+		]`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	entries, err := c.ListContents(context.Background(), "o", "r", "src", "main")
+	require.NoError(t, err)
+	require.Len(t, entries, 2)
+	assert.Equal(t, "main.go", entries[0].Name)
+	assert.Equal(t, "file", entries[0].Type)
+	assert.Equal(t, "lib", entries[1].Name)
+	assert.Equal(t, "dir", entries[1].Type)
+}
+
+func TestListContentsOnFileReturnsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"path":"main.go","sha":"abc","size":100,"content":"","encoding":"base64"}`))
+	}))
+	defer srv.Close()
+
+	c := gitea.NewClient(srv.URL, "tok")
+	_, err := c.ListContents(context.Background(), "o", "r", "main.go", "")
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrValidation)
+}

internal/tools/dir_list.go

@@ -0,0 +1,70 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+
+	"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"
+)
+
+type DirList struct {
+	c *gitea.Client
+	a *allowlist.Allowlist
+}
+
+func NewDirList(c *gitea.Client, a *allowlist.Allowlist) *DirList {
+	return &DirList{c: c, a: a}
+}
+
+func (t *DirList) Descriptor() registry.ToolDescriptor {
+	return registry.ToolDescriptor{
+		Name:        "dir_list",
+		Description: "List directory contents in a repository. Use empty path for repo root. Returns name, path, type (file/dir/symlink), sha, size per entry.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"owner":{"type":"string"},
+				"name":{"type":"string"},
+				"path":{"type":"string"},
+				"ref":{"type":"string"}
+			},
+			"required":["owner","name"]
+		}`),
+	}
+}
+
+type dirListArgs struct {
+	Owner string `json:"owner"`
+	Name  string `json:"name"`
+	Path  string `json:"path"`
+	Ref   string `json:"ref"`
+}
+
+func (t *DirList) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
+	var args dirListArgs
+	if err := parseArgs(raw, &args); err != nil {
+		return nil, err
+	}
+	if err := t.a.Check(args.Owner); err != nil {
+		return nil, err
+	}
+
+	entries, err := t.c.ListContents(ctx, args.Owner, args.Name, args.Path, args.Ref)
+	if err != nil {
+		return nil, err
+	}
+
+	result := make([]map[string]any, len(entries))
+	for i, e := range entries {
+		result[i] = map[string]any{
+			"name": e.Name,
+			"path": e.Path,
+			"type": e.Type,
+			"sha":  e.Sha,
+			"size": e.Size,
+		}
+	}
+	return textOK(result)
+}

internal/tools/dir_list_test.go

@@ -0,0 +1,75 @@
+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 TestDirListReturnsEntries(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/owner/repo/contents/src", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[
+			{"name":"main.go","path":"src/main.go","type":"file","sha":"abc","size":512},
+			{"name":"util","path":"src/util","type":"dir","sha":"def","size":0}
+		]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewDirList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","path":"src"}`))
+	require.NoError(t, err)
+
+	var result []map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	require.Len(t, result, 2)
+	assert.Equal(t, "main.go", result[0]["name"])
+	assert.Equal(t, "file", result[0]["type"])
+	assert.Equal(t, "util", result[1]["name"])
+	assert.Equal(t, "dir", result[1]["type"])
+}
+
+func TestDirListRootPath(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/repos/owner/repo/contents/", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[]`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewDirList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","path":""}`))
+	require.NoError(t, err)
+
+	var result []map[string]any
+	require.NoError(t, json.Unmarshal(out, &result))
+	assert.Empty(t, result)
+}
+
+func TestDirListOnFileReturnsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"path":"README.md","sha":"abc","size":10,"content":"","encoding":"base64"}`))
+	}))
+	defer srv.Close()
+
+	tool := tools.NewDirList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"owner"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"owner","name":"repo","path":"README.md"}`))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, gitea.ErrValidation)
+}
+
+func TestDirListAllowlistRejects(t *testing.T) {
+	tool := tools.NewDirList(gitea.NewClient("http://unused", ""), allowlist.New([]string{"allowed"}))
+	_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"repo","path":""}`))
+	require.Error(t, err)
+}