Add pagination limit hint to perPage tool descriptions

Help MCP clients understand that the requested page size may be capped
by the Gitea server's MAX_RESPONSE_ITEMS setting.

Co-Authored-By: Claude (claude-opus-4-6) <noreply@anthropic.com>

Makefile

@@ -8,7 +8,7 @@ GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1
 GOFUMPT_PACKAGE ?= mvdan.cc/gofumpt@v0.9.2
 
 .PHONY: help
-help: ## Print this help message.
+help: ## print this help message
 	@echo "Usage: make [target]"
 	@echo ""
 	@echo "Targets:"
@@ -16,7 +16,7 @@ help: ## Print this help message.
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
 .PHONY: install
-install: build ## Install the application.
+install: build ## install the application
 	@echo "Installing $(EXECUTABLE)..."
 	@mkdir -p $(GOPATH)/bin
 	@cp $(EXECUTABLE) $(GOPATH)/bin/$(EXECUTABLE)
@@ -24,23 +24,23 @@ install: build ## Install the application.
 	@echo "Please add $(GOPATH)/bin to your PATH if it is not already there."
 
 .PHONY: uninstall
-uninstall: ## Uninstall the application.
+uninstall: ## uninstall the application
 	@echo "Uninstalling $(EXECUTABLE)..."
 	@rm -f $(GOPATH)/bin/$(EXECUTABLE)
 	@echo "Uninstalled $(EXECUTABLE) from $(GOPATH)/bin/$(EXECUTABLE)"
 
 .PHONY: clean
-clean: ## Clean the build artifacts.
+clean: ## delete build artifacts
 	@echo "Cleaning up build artifacts..."
 	@rm -f $(EXECUTABLE)
 	@echo "Cleaned up $(EXECUTABLE)"
 
 .PHONY: build
-build: ## Build the application.
+build: ## build the application
 	$(GO) build -v -ldflags '-s -w $(LDFLAGS)' -o $(EXECUTABLE)
 
 .PHONY: air
-air: ## Install air for hot reload.
+air: ## install air for hot reload
 	@hash air > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
 		$(GO) install github.com/air-verse/air@latest; \
 	fi
@@ -49,6 +49,10 @@ air: ## Install air for hot reload.
 dev: air ## run the application with hot reload
 	air --build.cmd "make build" --build.bin ./gitea-mcp
 
+.PHONY: fmt
+fmt: ## format the Go code
+	$(GO) run $(GOFUMPT_PACKAGE) -w .
+
 .PHONY: lint
 lint: lint-go ## lint everything
 

README.md

@@ -166,6 +166,9 @@ To configure the MCP server for Gitea, add the following to your MCP configurati
 > You can provide your Gitea host and access token either as command-line arguments or environment variables.
 > Command-line arguments have the highest priority
 
+> [!NOTE]
+> Many tools support `page` and `perPage` parameters for pagination. The maximum effective page size is determined by the Gitea server's `[api].MAX_RESPONSE_ITEMS` setting (default: **50**). Requesting a `perPage` value higher than this limit will be silently capped by the server.
+
 Once everything is set up, try typing the following in your MCP-compatible chatbox:
 
 ```text

README.zh-cn.md

@@ -166,6 +166,9 @@ cp gitea-mcp /usr/local/bin/
 > 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。
 > 命令行参数优先。
 
+> [!注意]
+> 许多工具支持 `page` 和 `perPage` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认值：**50**）。请求超过此限制的 `perPage` 值将被服务器静默截断。
+
 一切设置完成后，可在 MCP 聊天框输入：
 
 ```text

README.zh-tw.md

@@ -166,6 +166,9 @@ cp gitea-mcp /usr/local/bin/
 > 可用命令列參數或環境變數提供 Gitea 主機與存取令牌。
 > 命令列參數優先。
 
+> [!注意]
+> 許多工具支援 `page` 和 `perPage` 分頁參數。最大有效頁面大小由 Gitea 伺服器的 `[api].MAX_RESPONSE_ITEMS` 設定決定（預設值：**50**）。請求超過此限制的 `perPage` 值將被伺服器靜默截斷。
+
 一切設定完成後，可在 MCP 聊天框輸入：
 
 ```text

go.mod

@@ -4,7 +4,7 @@ go 1.26.0
 
 require (
 	code.gitea.io/sdk/gitea v0.23.2
-	github.com/mark3labs/mcp-go v0.44.0
+	github.com/mark3labs/mcp-go v0.45.0
 	go.uber.org/zap v1.27.1
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1
 )

go.sum

@@ -28,8 +28,8 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/mailru/easyjson v0.9.1 h1:LbtsOm5WAswyWbvTEOqhypdPeZzHavpZx96/n553mR8=
 github.com/mailru/easyjson v0.9.1/go.mod h1:1+xMtQp2MRNVL/V1bOzuP3aP8VNwRW55fQUto+XFtTU=
-github.com/mark3labs/mcp-go v0.44.0 h1:OlYfcVviAnwNN40QZUrrzU0QZjq3En7rCU5X09a/B7I=
-github.com/mark3labs/mcp-go v0.44.0/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
+github.com/mark3labs/mcp-go v0.45.0 h1:s0S8qR/9fWaQ3pHxz7pm1uQ0DrswoSnRIxKIjbiQtkc=
+github.com/mark3labs/mcp-go v0.45.0/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=

operation/actions/config.go

@@ -54,7 +54,7 @@ var (
 		mcp.WithString("org", mcp.Description("organization name (required for org methods)")),
 		mcp.WithString("name", mcp.Description("variable name (required for get methods)")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ActionsConfigWriteTool = mcp.NewTool(

operation/actions/runs.go

@@ -39,7 +39,7 @@ var (
 		mcp.WithNumber("max_bytes", mcp.Description("max bytes to return (for 'get_job_log_preview')"), mcp.DefaultNumber(65536), mcp.Min(1024)),
 		mcp.WithString("output_path", mcp.Description("output file path (for 'download_job_log')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ActionsRunWriteTool = mcp.NewTool(

operation/issue/issue.go

@@ -30,8 +30,11 @@ var (
 		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
 		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
 		mcp.WithString("state", mcp.Description("issue state"), mcp.DefaultString("all")),
+		mcp.WithArray("labels", mcp.Description("filter by label names"), mcp.Items(map[string]any{"type": "string"})),
+		mcp.WithString("since", mcp.Description("filter issues updated after this ISO 8601 timestamp")),
+		mcp.WithString("before", mcp.Description("filter issues updated before this ISO 8601 timestamp")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	IssueReadTool = mcp.NewTool(
@@ -56,8 +59,10 @@ var (
 		mcp.WithNumber("milestone", mcp.Description("milestone number (for 'create', 'update')")),
 		mcp.WithString("state", mcp.Description("issue state, one of open, closed, all (for 'update')")),
 		mcp.WithNumber("commentID", mcp.Description("id of issue comment (required for 'edit_comment')")),
-		mcp.WithArray("labels", mcp.Description("array of label IDs (for 'add_labels', 'replace_labels')"), mcp.Items(map[string]any{"type": "number"})),
+		mcp.WithArray("labels", mcp.Description("array of label IDs (for 'create', 'add_labels', 'replace_labels')"), mcp.Items(map[string]any{"type": "number"})),
 		mcp.WithNumber("label_id", mcp.Description("label ID to remove (required for 'remove_label')")),
+		mcp.WithString("deadline", mcp.Description("due date in ISO 8601 format (for 'create', 'update')")),
+		mcp.WithBoolean("remove_deadline", mcp.Description("unset due date (for 'update')")),
 	)
 )
 
@@ -162,14 +167,22 @@ func listRepoIssuesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	if !ok {
 		state = "all"
 	}
+	labels := params.GetStringSlice(req.GetArguments(), "labels")
 	page, pageSize := params.GetPagination(req.GetArguments(), 30)
 	opt := gitea_sdk.ListIssueOption{
-		State: gitea_sdk.StateType(state),
+		State:  gitea_sdk.StateType(state),
+		Labels: labels,
 		ListOptions: gitea_sdk.ListOptions{
 			Page:     page,
 			PageSize: pageSize,
 		},
 	}
+	if t := params.GetOptionalTime(req.GetArguments(), "since"); t != nil {
+		opt.Since = *t
+	}
+	if t := params.GetOptionalTime(req.GetArguments(), "before"); t != nil {
+		opt.Before = *t
+	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
@@ -213,6 +226,10 @@ func createIssueFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolR
 			opt.Milestone = milestone
 		}
 	}
+	if labelIDs, err := params.GetInt64Slice(req.GetArguments(), "labels"); err == nil {
+		opt.Labels = labelIDs
+	}
+	opt.Deadline = params.GetOptionalTime(req.GetArguments(), "deadline")
 	issue, _, err := client.CreateIssue(owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("create %v/%v/issue err: %v", owner, repo, err))
@@ -289,6 +306,10 @@ func editIssueFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRes
 	if ok {
 		opt.State = new(gitea_sdk.StateType(state))
 	}
+	opt.Deadline = params.GetOptionalTime(req.GetArguments(), "deadline")
+	if removeDeadline, ok := req.GetArguments()["remove_deadline"].(bool); ok {
+		opt.RemoveDeadline = &removeDeadline
+	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/issue/issue_test.go

@@ -0,0 +1,167 @@
+package issue
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+func Test_listRepoIssuesFn_filters(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+	)
+
+	var (
+		mu       sync.Mutex
+		gotQuery string
+	)
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.URL.Path == "/api/v1/version":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"version":"1.12.0"}`))
+		case r.URL.Path == fmt.Sprintf("/api/v1/repos/%s/%s", owner, repo):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"private":false}`))
+		case r.URL.Path == fmt.Sprintf("/api/v1/repos/%s/%s/issues", owner, repo):
+			mu.Lock()
+			gotQuery = r.URL.RawQuery
+			mu.Unlock()
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`[]`))
+		default:
+			http.NotFound(w, r)
+		}
+	})
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	origHost := flag.Host
+	origToken := flag.Token
+	origVersion := flag.Version
+	flag.Host = server.URL
+	flag.Token = ""
+	flag.Version = "test"
+	defer func() {
+		flag.Host = origHost
+		flag.Token = origToken
+		flag.Version = origVersion
+	}()
+
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]any{
+				"owner":  owner,
+				"repo":   repo,
+				"labels": []any{"bug", "enhancement"},
+				"since":  "2026-01-01T00:00:00Z",
+			},
+		},
+	}
+
+	_, err := listRepoIssuesFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("listRepoIssuesFn() error = %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	if !strings.Contains(gotQuery, "labels=bug%2Cenhancement") {
+		t.Fatalf("expected labels query param, got %s", gotQuery)
+	}
+	if !strings.Contains(gotQuery, "since=2026-01-01") {
+		t.Fatalf("expected since query param, got %s", gotQuery)
+	}
+}
+
+func Test_createIssueFn_labels(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+	)
+
+	var (
+		mu      sync.Mutex
+		gotBody map[string]any
+	)
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/version":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"version":"1.12.0"}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s", owner, repo):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"private":false}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s/issues", owner, repo):
+			mu.Lock()
+			var body map[string]any
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			gotBody = body
+			mu.Unlock()
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"number":1,"title":"test","state":"open"}`))
+		default:
+			http.NotFound(w, r)
+		}
+	})
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	origHost := flag.Host
+	origToken := flag.Token
+	origVersion := flag.Version
+	flag.Host = server.URL
+	flag.Token = ""
+	flag.Version = "test"
+	defer func() {
+		flag.Host = origHost
+		flag.Token = origToken
+		flag.Version = origVersion
+	}()
+
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]any{
+				"owner":    owner,
+				"repo":     repo,
+				"title":    "test issue",
+				"body":     "body",
+				"labels":   []any{float64(10), float64(20)},
+				"deadline": "2026-06-01T00:00:00Z",
+			},
+		},
+	}
+
+	_, err := createIssueFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("createIssueFn() error = %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	labels, ok := gotBody["labels"].([]any)
+	if !ok || len(labels) != 2 {
+		t.Fatalf("expected 2 labels, got %v", gotBody["labels"])
+	}
+	if labels[0] != float64(10) || labels[1] != float64(20) {
+		t.Fatalf("expected labels [10,20], got %v", labels)
+	}
+	if gotBody["due_date"] == nil {
+		t.Fatalf("expected due_date to be set")
+	}
+}

operation/label/label.go

@@ -32,7 +32,7 @@ var (
 		mcp.WithString("org", mcp.Description("organization name (required for 'list_org')")),
 		mcp.WithNumber("id", mcp.Description("label ID (required for 'get_repo')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	LabelWriteTool = mcp.NewTool(
@@ -47,6 +47,7 @@ var (
 		mcp.WithString("color", mcp.Description("label color hex code e.g. #RRGGBB (required for create, optional for edit)")),
 		mcp.WithString("description", mcp.Description("label description")),
 		mcp.WithBoolean("exclusive", mcp.Description("whether the label is exclusive (org labels only)")),
+		mcp.WithBoolean("is_archived", mcp.Description("whether the label is archived (for create/edit repo label methods)")),
 	)
 )
 
@@ -178,10 +179,13 @@ func createRepoLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	}
 	description, _ := req.GetArguments()["description"].(string) // Optional
 
+	isArchived, _ := req.GetArguments()["is_archived"].(bool)
+
 	opt := gitea_sdk.CreateLabelOption{
 		Name:        name,
 		Color:       color,
 		Description: description,
+		IsArchived:  isArchived,
 	}
 
 	client, err := gitea.ClientFromContext(ctx)
@@ -220,6 +224,9 @@ func editRepoLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToo
 	if description, ok := req.GetArguments()["description"].(string); ok {
 		opt.Description = new(description)
 	}
+	if isArchived, ok := req.GetArguments()["is_archived"].(bool); ok {
+		opt.IsArchived = &isArchived
+	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/milestone/milestone.go

@@ -33,7 +33,7 @@ var (
 		mcp.WithString("state", mcp.Description("milestone state (for 'list')"), mcp.DefaultString("all")),
 		mcp.WithString("name", mcp.Description("milestone name filter (for 'list')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	MilestoneWriteTool = mcp.NewTool(

operation/pull/pull.go

@@ -35,7 +35,7 @@ var (
 		mcp.WithString("sort", mcp.Description("sort"), mcp.Enum("oldest", "recentupdate", "leastupdate", "mostcomment", "leastcomment", "priority"), mcp.DefaultString("recentupdate")),
 		mcp.WithNumber("milestone", mcp.Description("milestone")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	PullRequestReadTool = mcp.NewTool(
@@ -48,7 +48,7 @@ var (
 		mcp.WithNumber("review_id", mcp.Description("review ID (required for 'get_review', 'get_review_comments')")),
 		mcp.WithBoolean("binary", mcp.Description("whether to include binary file changes (for 'get_diff')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	PullRequestWriteTool = mcp.NewTool(
@@ -67,9 +67,15 @@ var (
 		mcp.WithNumber("milestone", mcp.Description("milestone number (for 'update')")),
 		mcp.WithString("state", mcp.Description("PR state (for 'update')"), mcp.Enum("open", "closed")),
 		mcp.WithBoolean("allow_maintainer_edit", mcp.Description("allow maintainer to edit (for 'update')")),
+		mcp.WithArray("labels", mcp.Description("array of label IDs (for 'create', 'update')"), mcp.Items(map[string]any{"type": "number"})),
+		mcp.WithString("deadline", mcp.Description("due date in ISO 8601 format (for 'create', 'update')")),
+		mcp.WithBoolean("remove_deadline", mcp.Description("unset due date (for 'update')")),
 		mcp.WithString("merge_style", mcp.Description("merge style (for 'merge')"), mcp.Enum("merge", "rebase", "rebase-merge", "squash", "fast-forward-only"), mcp.DefaultString("merge")),
 		mcp.WithString("message", mcp.Description("merge commit message (for 'merge') or dismissal reason")),
 		mcp.WithBoolean("delete_branch", mcp.Description("delete branch after merge (for 'merge')")),
+		mcp.WithBoolean("force_merge", mcp.Description("force merge even if checks are not passing (for 'merge')")),
+		mcp.WithBoolean("merge_when_checks_succeed", mcp.Description("auto-merge when checks succeed (for 'merge')")),
+		mcp.WithString("head_commit_id", mcp.Description("expected head commit SHA for merge conflict detection (for 'merge')")),
 		mcp.WithArray("reviewers", mcp.Description("reviewer usernames (for 'add_reviewers', 'remove_reviewers')"), mcp.Items(map[string]any{"type": "string"})),
 		mcp.WithArray("team_reviewers", mcp.Description("team reviewer names (for 'add_reviewers', 'remove_reviewers')"), mcp.Items(map[string]any{"type": "string"})),
 		mcp.WithBoolean("draft", mcp.Description("mark PR as draft (for 'create', 'update'). Gitea uses a 'WIP: ' title prefix for drafts.")),
@@ -331,12 +337,17 @@ func createPullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Cal
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	pr, _, err := client.CreatePullRequest(owner, repo, gitea_sdk.CreatePullRequestOption{
+	opt := gitea_sdk.CreatePullRequestOption{
 		Title: title,
 		Body:  body,
 		Head:  head,
 		Base:  base,
-	})
+	}
+	if labelIDs, err := params.GetInt64Slice(args, "labels"); err == nil {
+		opt.Labels = labelIDs
+	}
+	opt.Deadline = params.GetOptionalTime(args, "deadline")
+	pr, _, err := client.CreatePullRequest(owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("create %v/%v/pull_request err: %v", owner, repo, err))
 	}
@@ -751,11 +762,18 @@ func mergePullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
 
+	forceMerge, _ := args["force_merge"].(bool)
+	mergeWhenChecksSucceed, _ := args["merge_when_checks_succeed"].(bool)
+	headCommitID, _ := args["head_commit_id"].(string)
+
 	opt := gitea_sdk.MergePullRequestOption{
 		Style:                  gitea_sdk.MergeStyle(mergeStyle),
 		Title:                  title,
 		Message:                message,
 		DeleteBranchAfterMerge: deleteBranch,
+		ForceMerge:             forceMerge,
+		MergeWhenChecksSucceed: mergeWhenChecksSucceed,
+		HeadCommitId:           headCommitID,
 	}
 
 	merged, resp, err := client.MergePullRequest(owner, repo, index, opt)
@@ -842,6 +860,13 @@ func editPullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	if allowMaintainerEdit, ok := args["allow_maintainer_edit"].(bool); ok {
 		opt.AllowMaintainerEdit = new(allowMaintainerEdit)
 	}
+	if labelIDs, err := params.GetInt64Slice(args, "labels"); err == nil {
+		opt.Labels = labelIDs
+	}
+	opt.Deadline = params.GetOptionalTime(args, "deadline")
+	if removeDeadline, ok := args["remove_deadline"].(bool); ok {
+		opt.RemoveDeadline = &removeDeadline
+	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/pull/pull_test.go

@@ -254,6 +254,168 @@ func Test_mergePullRequestFn(t *testing.T) {
 	}
 }
 
+func Test_mergePullRequestFn_newParams(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+		index = 8
+	)
+
+	var (
+		mu      sync.Mutex
+		gotBody map[string]any
+	)
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/version":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"version":"1.12.0"}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s", owner, repo):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"private":false}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s/pulls/%d/merge", owner, repo, index):
+			mu.Lock()
+			var body map[string]any
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			gotBody = body
+			mu.Unlock()
+			w.WriteHeader(http.StatusOK)
+		default:
+			http.NotFound(w, r)
+		}
+	})
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	origHost := flag.Host
+	origToken := flag.Token
+	origVersion := flag.Version
+	flag.Host = server.URL
+	flag.Token = ""
+	flag.Version = "test"
+	defer func() {
+		flag.Host = origHost
+		flag.Token = origToken
+		flag.Version = origVersion
+	}()
+
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]any{
+				"owner":                     owner,
+				"repo":                      repo,
+				"index":                     float64(index),
+				"merge_style":               "merge",
+				"force_merge":               true,
+				"merge_when_checks_succeed": true,
+				"head_commit_id":            "abc123",
+			},
+		},
+	}
+
+	_, err := mergePullRequestFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("mergePullRequestFn() error = %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	if gotBody["force_merge"] != true {
+		t.Fatalf("expected force_merge true, got %v", gotBody["force_merge"])
+	}
+	if gotBody["merge_when_checks_succeed"] != true {
+		t.Fatalf("expected merge_when_checks_succeed true, got %v", gotBody["merge_when_checks_succeed"])
+	}
+	if gotBody["head_commit_id"] != "abc123" {
+		t.Fatalf("expected head_commit_id 'abc123', got %v", gotBody["head_commit_id"])
+	}
+}
+
+func Test_createPullRequestFn_labels(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+	)
+
+	var (
+		mu      sync.Mutex
+		gotBody map[string]any
+	)
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/version":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"version":"1.12.0"}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s", owner, repo):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"private":false}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s/pulls", owner, repo):
+			mu.Lock()
+			var body map[string]any
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			gotBody = body
+			mu.Unlock()
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"number":1,"title":"test","state":"open"}`))
+		default:
+			http.NotFound(w, r)
+		}
+	})
+
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	origHost := flag.Host
+	origToken := flag.Token
+	origVersion := flag.Version
+	flag.Host = server.URL
+	flag.Token = ""
+	flag.Version = "test"
+	defer func() {
+		flag.Host = origHost
+		flag.Token = origToken
+		flag.Version = origVersion
+	}()
+
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]any{
+				"owner":    owner,
+				"repo":     repo,
+				"title":    "test",
+				"body":     "body",
+				"head":     "feature",
+				"base":     "main",
+				"labels":   []any{float64(1), float64(2)},
+				"deadline": "2026-06-01T00:00:00Z",
+			},
+		},
+	}
+
+	_, err := createPullRequestFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("createPullRequestFn() error = %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	labels, ok := gotBody["labels"].([]any)
+	if !ok || len(labels) != 2 {
+		t.Fatalf("expected 2 labels, got %v", gotBody["labels"])
+	}
+	if labels[0] != float64(1) || labels[1] != float64(2) {
+		t.Fatalf("expected labels [1,2], got %v", labels)
+	}
+	if gotBody["due_date"] == nil {
+		t.Fatalf("expected due_date to be set")
+	}
+}
+
 func Test_applyDraftPrefix(t *testing.T) {
 	tests := []struct {
 		name    string

operation/repo/branch.go

@@ -43,6 +43,8 @@ var (
 		mcp.WithDescription("List branches"),
 		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
 		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 )
 
@@ -131,10 +133,11 @@ func ListBranchesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTool
 	if err != nil {
 		return to.ErrorResult(err)
 	}
+	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListRepoBranchesOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     1,
-			PageSize: 30,
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)

operation/repo/commit.go

@@ -16,17 +16,28 @@ import (
 
 const (
 	ListRepoCommitsToolName = "list_commits"
+	GetCommitToolName       = "get_commit"
 )
 
-var ListRepoCommitsTool = mcp.NewTool(
-	ListRepoCommitsToolName,
-	mcp.WithDescription("List repository commits"),
-	mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-	mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-	mcp.WithString("sha", mcp.Description("SHA or branch to start listing commits from")),
-	mcp.WithString("path", mcp.Description("path indicates that only commits that include the path's file/dir should be returned.")),
-	mcp.WithNumber("page", mcp.Required(), mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-	mcp.WithNumber("perPage", mcp.Required(), mcp.Description("results per page"), mcp.DefaultNumber(30), mcp.Min(1)),
+var (
+	ListRepoCommitsTool = mcp.NewTool(
+		ListRepoCommitsToolName,
+		mcp.WithDescription("List repository commits"),
+		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
+		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+		mcp.WithString("sha", mcp.Description("SHA or branch to start listing commits from")),
+		mcp.WithString("path", mcp.Description("path indicates that only commits that include the path's file/dir should be returned.")),
+		mcp.WithNumber("page", mcp.Required(), mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Required(), mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30), mcp.Min(1)),
+	)
+
+	GetCommitTool = mcp.NewTool(
+		GetCommitToolName,
+		mcp.WithDescription("Get details of a specific commit"),
+		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
+		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+		mcp.WithString("sha", mcp.Required(), mcp.Description("commit SHA")),
+	)
 )
 
 func init() {
@@ -34,6 +45,10 @@ func init() {
 		Tool:    ListRepoCommitsTool,
 		Handler: ListRepoCommitsFn,
 	})
+	Tool.RegisterRead(server.ServerTool{
+		Tool:    GetCommitTool,
+		Handler: GetCommitFn,
+	})
 }
 
 func ListRepoCommitsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
@@ -75,3 +90,29 @@ func ListRepoCommitsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	}
 	return to.TextResult(slimCommits(commits))
 }
+
+func GetCommitFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called GetCommitFn")
+	args := req.GetArguments()
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	sha, err := params.GetString(args, "sha")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	commit, _, err := client.GetSingleCommit(owner, repo, sha)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get commit %v err: %v", sha, err))
+	}
+	return to.TextResult(slimCommit(commit))
+}

operation/repo/release.go

@@ -67,7 +67,7 @@ var (
 		mcp.WithBoolean("is_draft", mcp.Description("Whether the release is draft"), mcp.DefaultBool(false)),
 		mcp.WithBoolean("is_pre_release", mcp.Description("Whether the release is pre-release"), mcp.DefaultBool(false)),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(20), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(20), mcp.Min(1)),
 	)
 )
 

operation/repo/repo.go

@@ -39,6 +39,8 @@ var (
 		mcp.WithString("license", mcp.Description("License to use")),
 		mcp.WithString("readme", mcp.Description("Readme of the repository to create")),
 		mcp.WithString("default_branch", mcp.Description("DefaultBranch of the repository (used when initializes and in template)")),
+		mcp.WithString("trust_model", mcp.Description("Trust model for verifying GPG signatures"), mcp.Enum("default", "collaborator", "committer", "collaboratorcommitter")),
+		mcp.WithString("object_format_name", mcp.Description("Object format: sha1 or sha256"), mcp.Enum("sha1", "sha256")),
 		mcp.WithString("organization", mcp.Description("Organization name to create repository in (optional - defaults to personal account)")),
 	)
 
@@ -55,7 +57,7 @@ var (
 		ListMyReposToolName,
 		mcp.WithDescription("List my repositories"),
 		mcp.WithNumber("page", mcp.Required(), mcp.Description("Page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Required(), mcp.Description("results per page"), mcp.DefaultNumber(30), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Required(), mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ListOrgReposTool = mcp.NewTool(
@@ -102,19 +104,23 @@ func CreateRepoFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRe
 	license, _ := args["license"].(string)
 	readme, _ := args["readme"].(string)
 	defaultBranch, _ := args["default_branch"].(string)
+	trustModel, _ := args["trust_model"].(string)
+	objectFormatName, _ := args["object_format_name"].(string)
 	organization, _ := args["organization"].(string)
 
 	opt := gitea_sdk.CreateRepoOption{
-		Name:          name,
-		Description:   description,
-		Private:       private,
-		IssueLabels:   issueLabels,
-		AutoInit:      autoInit,
-		Template:      template,
-		Gitignores:    gitignores,
-		License:       license,
-		Readme:        readme,
-		DefaultBranch: defaultBranch,
+		Name:             name,
+		Description:      description,
+		Private:          private,
+		IssueLabels:      issueLabels,
+		AutoInit:         autoInit,
+		Template:         template,
+		Gitignores:       gitignores,
+		License:          license,
+		Readme:           readme,
+		DefaultBranch:    defaultBranch,
+		TrustModel:       gitea_sdk.TrustModel(trustModel),
+		ObjectFormatName: objectFormatName,
 	}
 
 	var repo *gitea_sdk.Repository

operation/repo/slim.go

@@ -184,6 +184,28 @@ func slimContents(c *gitea_sdk.ContentsResponse) map[string]any {
 	return m
 }
 
+func slimTree(t *gitea_sdk.GitTreeResponse) map[string]any {
+	if t == nil {
+		return nil
+	}
+	entries := make([]map[string]any, 0, len(t.Entries))
+	for _, e := range t.Entries {
+		entries = append(entries, map[string]any{
+			"path": e.Path,
+			"mode": e.Mode,
+			"type": e.Type,
+			"size": e.Size,
+			"sha":  e.SHA,
+		})
+	}
+	return map[string]any{
+		"sha":         t.SHA,
+		"truncated":   t.Truncated,
+		"total_count": t.TotalCount,
+		"tree":        entries,
+	}
+}
+
 func slimDirEntries(entries []*gitea_sdk.ContentsResponse) []map[string]any {
 	out := make([]map[string]any, 0, len(entries))
 	for _, c := range entries {

operation/repo/tag.go

@@ -54,7 +54,7 @@ var (
 		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
 		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(20), mcp.Min(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(20), mcp.Min(1)),
 	)
 )
 

operation/repo/tree.go

@@ -0,0 +1,74 @@
+package repo
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.com/gitea/gitea-mcp/pkg/gitea"
+	"gitea.com/gitea/gitea-mcp/pkg/log"
+	"gitea.com/gitea/gitea-mcp/pkg/params"
+	"gitea.com/gitea/gitea-mcp/pkg/to"
+
+	gitea_sdk "code.gitea.io/sdk/gitea"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+const (
+	GetRepoTreeToolName = "get_repository_tree"
+)
+
+var GetRepoTreeTool = mcp.NewTool(
+	GetRepoTreeToolName,
+	mcp.WithDescription("Get the file tree of a repository"),
+	mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
+	mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+	mcp.WithString("tree_sha", mcp.Required(), mcp.Description("SHA, branch name, or tag name")),
+	mcp.WithBoolean("recursive", mcp.Description("whether to get the tree recursively")),
+	mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
+	mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
+)
+
+func init() {
+	Tool.RegisterRead(server.ServerTool{
+		Tool:    GetRepoTreeTool,
+		Handler: GetRepoTreeFn,
+	})
+}
+
+func GetRepoTreeFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called GetRepoTreeFn")
+	args := req.GetArguments()
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	treeSHA, err := params.GetString(args, "tree_sha")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	recursive, _ := args["recursive"].(bool)
+	page, pageSize := params.GetPagination(args, 30)
+
+	opt := gitea_sdk.ListTreeOptions{
+		ListOptions: gitea_sdk.ListOptions{
+			Page:     page,
+			PageSize: pageSize,
+		},
+		Ref:       treeSHA,
+		Recursive: recursive,
+	}
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	tree, _, err := client.GetTrees(owner, repo, opt)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get repository tree err: %v", err))
+	}
+	return to.TextResult(slimTree(tree))
+}

operation/repo/tree_test.go

@@ -0,0 +1,52 @@
+package repo
+
+import (
+	"slices"
+	"testing"
+
+	gitea_sdk "code.gitea.io/sdk/gitea"
+)
+
+func TestSlimTree(t *testing.T) {
+	tree := &gitea_sdk.GitTreeResponse{
+		SHA:        "abc123",
+		TotalCount: 2,
+		Truncated:  false,
+		Entries: []gitea_sdk.GitEntry{
+			{Path: "src", Mode: "040000", Type: "tree", Size: 0, SHA: "def456"},
+			{Path: "main.go", Mode: "100644", Type: "blob", Size: 42, SHA: "789abc"},
+		},
+	}
+
+	m := slimTree(tree)
+	if m["sha"] != "abc123" {
+		t.Errorf("expected sha abc123, got %v", m["sha"])
+	}
+	if m["total_count"] != 2 {
+		t.Errorf("expected total_count 2, got %v", m["total_count"])
+	}
+	entries := m["tree"].([]map[string]any)
+	if len(entries) != 2 {
+		t.Fatalf("expected 2 entries, got %d", len(entries))
+	}
+	if entries[0]["path"] != "src" {
+		t.Errorf("expected first entry path src, got %v", entries[0]["path"])
+	}
+	if entries[1]["type"] != "blob" {
+		t.Errorf("expected second entry type blob, got %v", entries[1]["type"])
+	}
+}
+
+func TestSlimTreeNil(t *testing.T) {
+	if m := slimTree(nil); m != nil {
+		t.Errorf("expected nil, got %v", m)
+	}
+}
+
+func TestGetRepoTreeToolRequired(t *testing.T) {
+	for _, field := range []string{"owner", "repo", "tree_sha"} {
+		if !slices.Contains(GetRepoTreeTool.InputSchema.Required, field) {
+			t.Errorf("expected %q to be required", field)
+		}
+	}
+}

operation/search/search.go

@@ -3,6 +3,7 @@ package search
 import (
 	"context"
 	"fmt"
+	"strings"
 
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
@@ -21,6 +22,7 @@ const (
 	SearchUsersToolName    = "search_users"
 	SearchOrgTeamsToolName = "search_org_teams"
 	SearchReposToolName    = "search_repos"
+	SearchIssuesToolName   = "search_issues"
 )
 
 var (
@@ -29,7 +31,7 @@ var (
 		mcp.WithDescription("search users"),
 		mcp.WithString("keyword", mcp.Required(), mcp.Description("Keyword")),
 		mcp.WithNumber("page", mcp.Description("Page"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	SearOrgTeamsTool = mcp.NewTool(
@@ -39,7 +41,7 @@ var (
 		mcp.WithString("query", mcp.Required(), mcp.Description("search organization teams")),
 		mcp.WithBoolean("includeDescription", mcp.Description("include description?")),
 		mcp.WithNumber("page", mcp.Description("Page"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	SearchReposTool = mcp.NewTool(
@@ -54,7 +56,19 @@ var (
 		mcp.WithString("sort", mcp.Description("Sort")),
 		mcp.WithString("order", mcp.Description("Order")),
 		mcp.WithNumber("page", mcp.Description("Page"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
+	)
+
+	SearchIssuesTool = mcp.NewTool(
+		SearchIssuesToolName,
+		mcp.WithDescription("Search for issues and pull requests across all accessible repositories"),
+		mcp.WithString("query", mcp.Required(), mcp.Description("search keyword")),
+		mcp.WithString("state", mcp.Description("filter by state: open, closed, all"), mcp.Enum("open", "closed", "all")),
+		mcp.WithString("type", mcp.Description("filter by type: issues, pulls"), mcp.Enum("issues", "pulls")),
+		mcp.WithString("labels", mcp.Description("comma-separated list of label names")),
+		mcp.WithString("owner", mcp.Description("filter by repository owner")),
+		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 )
 
@@ -71,6 +85,10 @@ func init() {
 		Tool:    SearchReposTool,
 		Handler: ReposFn,
 	})
+	Tool.RegisterRead(server.ServerTool{
+		Tool:    SearchIssuesTool,
+		Handler: IssuesFn,
+	})
 }
 
 func UsersFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
@@ -175,3 +193,42 @@ func ReposFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult,
 	}
 	return to.TextResult(slimRepos(repos))
 }
+
+func IssuesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called IssuesFn")
+	args := req.GetArguments()
+	query, err := params.GetString(args, "query")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	page, pageSize := params.GetPagination(args, 30)
+
+	opt := gitea_sdk.ListIssueOption{
+		KeyWord: query,
+		ListOptions: gitea_sdk.ListOptions{
+			Page:     page,
+			PageSize: pageSize,
+		},
+	}
+	if state, ok := args["state"].(string); ok {
+		opt.State = gitea_sdk.StateType(state)
+	}
+	if issueType, ok := args["type"].(string); ok {
+		opt.Type = gitea_sdk.IssueType(issueType)
+	}
+	if labels, ok := args["labels"].(string); ok && labels != "" {
+		opt.Labels = strings.Split(labels, ",")
+	}
+	if owner, ok := args["owner"].(string); ok {
+		opt.Owner = owner
+	}
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	issues, _, err := client.ListIssues(opt)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("search issues err: %v", err))
+	}
+	return to.TextResult(slimIssues(issues))
+}

operation/search/slim.go

@@ -86,3 +86,53 @@ func slimRepos(repos []*gitea_sdk.Repository) []map[string]any {
 	}
 	return out
 }
+
+func userLogin(u *gitea_sdk.User) string {
+	if u == nil {
+		return ""
+	}
+	return u.UserName
+}
+
+func labelNames(labels []*gitea_sdk.Label) []string {
+	if len(labels) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(labels))
+	for _, l := range labels {
+		if l != nil {
+			out = append(out, l.Name)
+		}
+	}
+	return out
+}
+
+func slimIssues(issues []*gitea_sdk.Issue) []map[string]any {
+	out := make([]map[string]any, 0, len(issues))
+	for _, i := range issues {
+		if i == nil {
+			continue
+		}
+		m := map[string]any{
+			"number":     i.Index,
+			"title":      i.Title,
+			"state":      i.State,
+			"html_url":   i.HTMLURL,
+			"user":       userLogin(i.Poster),
+			"comments":   i.Comments,
+			"created_at": i.Created,
+			"updated_at": i.Updated,
+		}
+		if len(i.Labels) > 0 {
+			m["labels"] = labelNames(i.Labels)
+		}
+		if i.Repository != nil {
+			m["repository"] = i.Repository.FullName
+		}
+		if i.PullRequest != nil {
+			m["is_pull"] = true
+		}
+		out = append(out, m)
+	}
+	return out
+}

operation/search/slim_test.go

@@ -0,0 +1,54 @@
+package search
+
+import (
+	"slices"
+	"testing"
+
+	gitea_sdk "code.gitea.io/sdk/gitea"
+)
+
+func TestSlimIssues(t *testing.T) {
+	issues := []*gitea_sdk.Issue{
+		{
+			Index:       1,
+			Title:       "Bug report",
+			State:       gitea_sdk.StateOpen,
+			HTMLURL:     "https://gitea.com/org/repo/issues/1",
+			Poster:      &gitea_sdk.User{UserName: "alice"},
+			Labels:      []*gitea_sdk.Label{{Name: "bug"}},
+			Repository:  &gitea_sdk.RepositoryMeta{FullName: "org/repo"},
+			PullRequest: nil,
+		},
+		{
+			Index:       2,
+			Title:       "Add feature",
+			State:       gitea_sdk.StateOpen,
+			Poster:      &gitea_sdk.User{UserName: "bob"},
+			Repository:  &gitea_sdk.RepositoryMeta{FullName: "org/repo"},
+			PullRequest: &gitea_sdk.PullRequestMeta{},
+		},
+	}
+
+	result := slimIssues(issues)
+	if len(result) != 2 {
+		t.Fatalf("expected 2 issues, got %d", len(result))
+	}
+	if result[0]["repository"] != "org/repo" {
+		t.Errorf("expected repository org/repo, got %v", result[0]["repository"])
+	}
+	if result[0]["labels"].([]string)[0] != "bug" {
+		t.Errorf("expected label bug, got %v", result[0]["labels"])
+	}
+	if _, ok := result[0]["is_pull"]; ok {
+		t.Error("issue should not have is_pull")
+	}
+	if result[1]["is_pull"] != true {
+		t.Error("PR should have is_pull=true")
+	}
+}
+
+func TestSearchIssuesToolRequired(t *testing.T) {
+	if !slices.Contains(SearchIssuesTool.InputSchema.Required, "query") {
+		t.Error("search_issues should require query")
+	}
+}

operation/timetracking/timetracking.go

@@ -32,7 +32,7 @@ var (
 		mcp.WithString("repo", mcp.Description("repository name (required for 'list_issue_times', 'list_repo_times')")),
 		mcp.WithNumber("index", mcp.Description("issue index (required for 'list_issue_times')")),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(30)),
 	)
 
 	TimetrackingWriteTool = mcp.NewTool(

operation/user/user.go

@@ -44,7 +44,7 @@ var (
 		GetUserOrgsToolName,
 		mcp.WithDescription("Get organizations associated with the authenticated user"),
 		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(defaultPage)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(defaultPageSize)),
+		mcp.WithNumber("perPage", mcp.Description("results per page (may be capped by the server's MAX_RESPONSE_ITEMS setting, default 50)"), mcp.DefaultNumber(defaultPageSize)),
 	)
 )
 

pkg/params/params.go

@@ -3,6 +3,7 @@ package params
 import (
 	"fmt"
 	"strconv"
+	"time"
 )
 
 // GetString extracts a required string parameter from MCP tool arguments.
@@ -101,6 +102,18 @@ func GetInt64Slice(args map[string]any, key string) ([]int64, error) {
 	return out, nil
 }
 
+// GetOptionalTime extracts an optional RFC3339 timestamp parameter, returning nil if missing or unparseable.
+func GetOptionalTime(args map[string]any, key string) *time.Time {
+	val, ok := args[key].(string)
+	if !ok {
+		return nil
+	}
+	if t, err := time.Parse(time.RFC3339, val); err == nil {
+		return &t
+	}
+	return nil
+}
+
 // GetOptionalInt extracts an optional integer parameter from MCP tool arguments.
 // Returns defaultVal if the key is missing or the value cannot be parsed.
 // Accepts both float64 (JSON number) and string representations.