feat(docker): add /healthz endpoint and -healthcheck flag (#254)

Adds a Docker healthcheck and the small HTTP/CLI plumbing it needs.

- Expose `GET /healthz` on the HTTP-mode server.
- Add `-healthcheck` to dial `http://127.0.0.1:<port>/healthz` and exit with status.
- Add a Dockerfile `HEALTHCHECK` instruction using `-healthcheck`.
- Document HTTP-mode usage and stdio override guidance.

Closes https://gitea.com/gitea/gitea-mcp/issues/146

Assisted by Codet.

Reviewed-on: https://gitea.com/gitea/gitea-mcp/pulls/254
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>

.gitea/workflows/release-nightly.yml

@@ -22,7 +22,7 @@ jobs:
         uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
 
       - name: Login to DockerHub
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4

.gitea/workflows/release-tag.yml

@@ -66,7 +66,7 @@ jobs:
         uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
 
       - name: Set up Docker BuildX
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
 
       - name: Login to DockerHub
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4

.golangci.yml

@@ -74,7 +74,7 @@ linters:
           arguments:
             - [] # AllowList - do not remove as args for the rule are positional and won't work without lists first
             - [] # DenyList
-            - - skip-package-name-checks: true
+            - - skip-initialism-name-checks: true
     staticcheck:
       checks:
         - all
@@ -110,7 +110,8 @@ formatters:
         - blank
         - default
     gofumpt:
-      extra-rules: true
+      extra:
+        group-params: true
   exclusions:
     generated: lax
 run:

BUILDING.md

@@ -4,7 +4,7 @@ This project includes PowerShell and batch scripts to build the gitea-mcp applic
 
 ## Prerequisites
 
-- Go 1.26 or later
+- Go 1.27 or later
 - Git (for version information)
 - PowerShell 5.1 or later (included with Windows 10/11)
 

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1.26
 
 # Build stage
-FROM --platform=$BUILDPLATFORM golang:1.26-alpine AS builder
+FROM --platform=$BUILDPLATFORM golang:1.27-alpine AS builder
 
 ARG VERSION=dev
 ARG TARGETOS
@@ -32,4 +32,7 @@ USER nonroot:nonroot
 LABEL org.opencontainers.image.version="${VERSION}"
 LABEL org.opencontainers.image.source="https://gitea.com/gitea/gitea-mcp"
 
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD ["/app/gitea-mcp", "-healthcheck"] || exit 1
+
 CMD ["/app/gitea-mcp"]

Makefile

@@ -3,8 +3,8 @@ EXECUTABLE := gitea-mcp
 VERSION ?= $(shell git describe --tags --always | sed 's/-/+/' | sed 's/^v//')
 LDFLAGS := -X "main.Version=$(VERSION)"
 
-GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 # renovate: datasource=go
-GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.6.0 # renovate: datasource=go
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.1 # renovate: datasource=go
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.7.0 # renovate: datasource=go
 
 GOTEST_FLAGS ?= -race -timeout 20m
 

README.md

@@ -8,7 +8,7 @@
 
 ## Installation
 
-Download a binary from the [releases page](https://gitea.com/gitea/gitea-mcp/releases) and put it in your `PATH`, use the `docker.gitea.com/gitea-mcp-server` image, or build from source into `$GOPATH/bin` with `make` and Go 1.26 or later:
+Download a binary from the [releases page](https://gitea.com/gitea/gitea-mcp/releases) and put it in your `PATH`, use the `docker.gitea.com/gitea-mcp-server` image, or build from source into `$GOPATH/bin` with `make` and Go 1.27 or later:
 
 ```bash
 git clone https://gitea.com/gitea/gitea-mcp.git
@@ -26,6 +26,8 @@ The server supports MCP up to `2026-07-28` and negotiates down to the client's v
 
 HTTP is always stateless: `/mcp` accepts POST only, without `Mcp-Session-Id`, standalone SSE or `Last-Event-ID` resumability. Origins are validated, and reverse proxies must forward `Mcp-Protocol-Version`, `Mcp-Method` and `Mcp-Name` unchanged. `Authorization: Bearer <token>` and `Authorization: token <token>` pass a Gitea credential per request, which is credential passthrough rather than MCP OAuth.
 
+HTTP mode also serves `/healthz`, which returns `200 OK` when the server is up. The Docker image's built-in `HEALTHCHECK` runs `gitea-mcp -healthcheck`, which dials `http://127.0.0.1:<port>/healthz` using the same `-p`/`-port` value (or `8080` by default) and exits `0` on success or `1` on failure. Stdio deployments do not serve `/healthz`, so override or disable the image's `HEALTHCHECK` when running in stdio mode.
+
 ### Claude Code
 
 Runs the server through `go run` and requires [Go](https://go.dev):
@@ -180,6 +182,7 @@ Once configured, try `list all my repositories` in the chat box.
 | create_branch                | branch       | Write  | Create a new branch |
 | delete_branch                | branch       | Write  | Delete a branch |
 | list_branches                | branch       | Read   | List repository branches |
+| rename_branch                | branch       | Write  | Rename a branch |
 | create_tag                   | tag          | Write  | Create a tag |
 | delete_tag                   | tag          | Write  | Delete a tag |
 | get_tag                      | tag          | Read   | Get tag details |

README.zh-cn.md

@@ -8,7 +8,7 @@
 
 ## 安装
 
-可从 [发布页面](https://gitea.com/gitea/gitea-mcp/releases) 下载二进制文件并放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 镜像，也可用 `make` 和 Go 1.26 及以上从源码构建到 `$GOPATH/bin`：
+可从 [发布页面](https://gitea.com/gitea/gitea-mcp/releases) 下载二进制文件并放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 镜像，也可用 `make` 和 Go 1.27 及以上从源码构建到 `$GOPATH/bin`：
 
 ```bash
 git clone https://gitea.com/gitea/gitea-mcp.git
@@ -26,6 +26,8 @@ Gitea 主机和访问令牌可通过命令行参数或环境变量提供，命
 
 HTTP 传输固定为无状态：`/mcp` 仅接受 POST，没有 `Mcp-Session-Id`、独立 SSE 和 `Last-Event-ID` 断点续传。服务器会验证来源，反向代理必须原样转发 `Mcp-Protocol-Version`、`Mcp-Method` 和 `Mcp-Name`。`Authorization: Bearer <令牌>` 和 `Authorization: token <令牌>` 会在每个请求中传递 Gitea 凭据，这是凭据透传，而不是 MCP OAuth。
 
+HTTP 模式还提供 `/healthz` 端点，服务器正常运行时返回 `200 OK`。Docker 镜像内置的 `HEALTHCHECK` 会运行 `gitea-mcp -healthcheck`，它使用与 `-p`/`-port` 相同的端口（默认 `8080`）请求 `http://127.0.0.1:<端口>/healthz`，成功时退出码为 `0`，失败时为 `1`。stdio 部署不提供 `/healthz`，因此在 stdio 模式下运行时应覆盖或禁用镜像自带的 `HEALTHCHECK`。
+
 ### Claude Code
 
 通过 `go run` 运行服务器，需要安装 [Go](https://go.dev)：
@@ -180,6 +182,7 @@ Cursor 等客户端可使用 stdio 命令：
 | create_branch                | branch       | 写入 | 创建新分支 |
 | delete_branch                | branch       | 写入 | 删除分支 |
 | list_branches                | branch       | 读取 | 列出仓库分支 |
+| rename_branch                | branch       | 写入 | 重命名分支 |
 | create_tag                   | tag          | 写入 | 创建标签 |
 | delete_tag                   | tag          | 写入 | 删除标签 |
 | get_tag                      | tag          | 读取 | 获取标签详情 |

README.zh-tw.md

@@ -8,7 +8,7 @@
 
 ## 安裝
 
-可從 [發布頁面](https://gitea.com/gitea/gitea-mcp/releases) 下載二進位檔並放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 映像檔，也可用 `make` 與 Go 1.26 以上從原始碼建置到 `$GOPATH/bin`：
+可從 [發布頁面](https://gitea.com/gitea/gitea-mcp/releases) 下載二進位檔並放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 映像檔，也可用 `make` 與 Go 1.27 以上從原始碼建置到 `$GOPATH/bin`：
 
 ```bash
 git clone https://gitea.com/gitea/gitea-mcp.git
@@ -26,6 +26,8 @@ Gitea 主機與存取令牌可透過命令列參數或環境變數提供，命
 
 HTTP 傳輸固定為無狀態：`/mcp` 只接受 POST，沒有 `Mcp-Session-Id`、獨立 SSE 與 `Last-Event-ID` 斷點續傳。伺服器會驗證來源，反向代理必須原樣轉發 `Mcp-Protocol-Version`、`Mcp-Method` 與 `Mcp-Name`。`Authorization: Bearer <令牌>` 與 `Authorization: token <令牌>` 會在每次請求中傳遞 Gitea 憑證，這是憑證透傳，而不是 MCP OAuth。
 
+HTTP 模式也會提供 `/healthz` 端點，伺服器正常運作時回傳 `200 OK`。Docker 映像內建的 `HEALTHCHECK` 會執行 `gitea-mcp -healthcheck`，它使用與 `-p`/`-port` 相同的連接埠（預設 `8080`）連線 `http://127.0.0.1:<連接埠>/healthz`，成功時結束碼為 `0`，失敗時為 `1`。stdio 部署不會提供 `/healthz`，因此在 stdio 模式下運作時應覆寫或停用映像內建的 `HEALTHCHECK`。
+
 ### Claude Code
 
 透過 `go run` 執行伺服器，需要安裝 [Go](https://go.dev)：
@@ -180,6 +182,7 @@ Cursor 等客戶端可使用 stdio 命令：
 | create_branch                | branch       | 寫入 | 創建新分支 |
 | delete_branch                | branch       | 寫入 | 刪除分支 |
 | list_branches                | branch       | 讀取 | 列出倉庫分支 |
+| rename_branch                | branch       | 寫入 | 重新命名分支 |
 | create_tag                   | tag          | 寫入 | 創建標籤 |
 | delete_tag                   | tag          | 寫入 | 刪除標籤 |
 | get_tag                      | tag          | 讀取 | 取得標籤詳情 |

cmd/cmd.go

@@ -5,6 +5,7 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"net/http"
 	"os"
 	"strconv"
 	"strings"
@@ -23,9 +24,11 @@ var (
 	tools                           string
 	scopes                          string
 	version                         bool
+	healthcheck                     bool
 	maxInlineAttachmentBytes        int
 	maxInlineAttachmentBytesFlagSet bool
 	osExit                          = os.Exit
+	healthcheckClient               = http.DefaultClient
 )
 
 func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, readFile func(string) ([]byte, error), stderr io.Writer) {
@@ -53,6 +56,7 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 	fs.BoolVar(&flagPkg.Insecure, "insecure", false, "")
 	fs.BoolVar(&version, "v", false, "")
 	fs.BoolVar(&version, "version", false, "")
+	fs.BoolVar(&healthcheck, "healthcheck", false, "")
 	maxInlineAttachmentBytes = 5 * 1024 * 1024
 	fs.Func("max-inline-attachment-bytes", "", func(val string) error {
 		parsed, err := strconv.Atoi(val)
@@ -81,6 +85,7 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 		fmt.Fprintf(w, "  -k, -insecure\tIgnore TLS certificate errors\n")
 		fmt.Fprintf(w, "  -max-inline-attachment-bytes <bytes>\tInline image attachments up to this size (default: 5242880)\n")
 		fmt.Fprintf(w, "  -v, -version\tPrint version and exit\n")
+		fmt.Fprintf(w, "  -healthcheck\tCheck a running HTTP server's /healthz endpoint and exit\n")
 		fmt.Fprintln(w)
 		fmt.Fprintln(w, "Environment variables:")
 		fmt.Fprintf(w, "  GITEA_ACCESS_TOKEN\tProvide access token\n")
@@ -183,6 +188,14 @@ func Execute() {
 		fmt.Fprintln(os.Stdout, flagPkg.Version)
 		return
 	}
+	if healthcheck {
+		if runHealthcheck(healthcheckClient, flagPkg.Port, os.Stdout, os.Stderr) {
+			osExit(0)
+		} else {
+			osExit(1)
+		}
+		return
+	}
 	if err := operation.Run(); err != nil {
 		if err == context.Canceled {
 			log.Info("Server shutdown due to context cancellation")

cmd/cmd_test.go

@@ -95,3 +95,12 @@ func TestInitFlagSetScopes(t *testing.T) {
 		})
 	}
 }
+
+func TestInitFlagSetHealthcheck(t *testing.T) {
+	t.Cleanup(func() { healthcheck = false })
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	initFlagSet(fs, []string{"-healthcheck"}, func(string) string { return "" }, func(string) ([]byte, error) { return nil, nil }, &bytes.Buffer{})
+	if !healthcheck {
+		t.Error("healthcheck = false, want true")
+	}
+}

cmd/healthcheck.go

@@ -0,0 +1,29 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+)
+
+// runHealthcheck dials the /healthz endpoint on 127.0.0.1:port and reports
+// success or failure. It returns true when the server responds with a 2xx
+// status.
+func runHealthcheck(client *http.Client, port int, stdout, stderr io.Writer) bool {
+	url := fmt.Sprintf("http://127.0.0.1:%d/healthz", port)
+
+	resp, err := client.Get(url)
+	if err != nil {
+		fmt.Fprintf(stderr, "healthcheck failed: %v\n", err)
+		return false
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
+		fmt.Fprintf(stderr, "healthcheck failed: unexpected status %s\n", resp.Status)
+		return false
+	}
+
+	fmt.Fprintln(stdout, "healthy")
+	return true
+}

cmd/healthcheck_test.go

@@ -0,0 +1,81 @@
+package cmd
+
+import (
+	"bytes"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+func TestRunHealthcheck(t *testing.T) {
+	tests := []struct {
+		name       string
+		handler    http.HandlerFunc
+		port       func(server *httptest.Server) int
+		wantOK     bool
+		wantStdout string
+	}{
+		{
+			name: "server responds 200 OK",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusOK)
+			},
+			port:       serverPort,
+			wantOK:     true,
+			wantStdout: "healthy",
+		},
+		{
+			name: "server responds with an error status",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(http.StatusInternalServerError)
+			},
+			port:   serverPort,
+			wantOK: false,
+		},
+		{
+			name:   "nothing listening on the port",
+			port:   func(*httptest.Server) int { return 1 },
+			wantOK: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var server *httptest.Server
+			if tt.handler != nil {
+				server = httptest.NewServer(tt.handler)
+				defer server.Close()
+			}
+
+			var stdout, stderr bytes.Buffer
+			ok := runHealthcheck(http.DefaultClient, tt.port(server), &stdout, &stderr)
+
+			if ok != tt.wantOK {
+				t.Errorf("runHealthcheck() = %v, want %v", ok, tt.wantOK)
+			}
+			if tt.wantStdout != "" && !strings.Contains(stdout.String(), tt.wantStdout) {
+				t.Errorf("stdout = %q, want it to contain %q", stdout.String(), tt.wantStdout)
+			}
+			if tt.wantOK && stderr.Len() != 0 {
+				t.Errorf("stderr = %q, want empty on success", stderr.String())
+			}
+			if !tt.wantOK && stderr.Len() == 0 {
+				t.Error("stderr is empty, want a failure message")
+			}
+		})
+	}
+}
+
+func serverPort(server *httptest.Server) int {
+	_, portStr, err := net.SplitHostPort(server.Listener.Addr().String())
+	if err != nil {
+		panic(err)
+	}
+	port, err := strconv.Atoi(portStr)
+	if err != nil {
+		panic(err)
+	}
+	return port
+}

go.mod

@@ -1,8 +1,8 @@
 module gitea.com/gitea/gitea-mcp
 
-go 1.26.0
+go 1.27
 
-toolchain go1.26.6
+toolchain go1.27.0
 
 require (
 	gitea.dev/sdk v1.2.0
@@ -17,14 +17,14 @@ require (
 	github.com/davidmz/go-pageant v1.0.2 // indirect
 	github.com/google/jsonschema-go v0.4.3 // indirect
 	github.com/hashicorp/go-version v1.9.0 // indirect
-	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/asm v1.2.1 // indirect
 	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	golang.org/x/crypto v0.54.0 // indirect
-	golang.org/x/oauth2 v0.35.0 // indirect
+	golang.org/x/crypto v0.55.0 // indirect
+	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sync v0.22.0 // indirect
 	golang.org/x/sys v0.47.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	golang.org/x/tools v0.47.0 // indirect
+	golang.org/x/tools v0.49.0 // indirect
 )

go.sum

@@ -18,8 +18,8 @@ github.com/modelcontextprotocol/go-sdk v1.7.0 h1:yqjY2dsbKAC0LSuWZVBMrHgiG8ukXv6
 github.com/modelcontextprotocol/go-sdk v1.7.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts=
 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/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
-github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
+github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
 github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
@@ -37,11 +37,11 @@ go.uber.org/zap/exp v0.3.0/go.mod h1:5I384qq7XGxYyByIhHm6jg5CHkGY0nsTfbDLgDDlgJQ
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/crypto v0.0.0-20210513164829-c07d793c2f9a/go.mod h1:P+XmwS30IXTQdn5tA2iutPOUgjI07+tq3H3K9MVA1s8=
-golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
-golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
+golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M=
+golang.org/x/crypto v0.55.0/go.mod h1:uq0V9dE/fzQuJtbnL+2EhWOE63vo164FY8xqEnV9xis=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
-golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
-golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
+golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
+golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
 golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -54,8 +54,8 @@ golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
-golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
-golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
+golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
+golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYskCTPBJVb9jqSc=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

operation/actions/config.go

@@ -148,7 +148,7 @@ func listRepoActionSecretsFn(ctx context.Context, args map[string]any) (*mcp.Cal
 	}
 
 	secrets, _, err := client.Actions.ListRepoSecrets(ctx, owner, repo, gitea_sdk.ListRepoActionsSecretOption{
-		ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+		Page: page, PageSize: pageSize,
 	})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list repo action secrets err: %v", err))
@@ -228,7 +228,7 @@ func listOrgActionSecretsFn(ctx context.Context, args map[string]any) (*mcp.Call
 	}
 
 	secrets, _, err := client.Actions.ListOrgSecrets(ctx, org, gitea_sdk.ListOrgActionsSecretOption{
-		ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+		Page: page, PageSize: pageSize,
 	})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list org action secrets err: %v", err))
@@ -428,7 +428,7 @@ func listOrgActionVariablesFn(ctx context.Context, args map[string]any) (*mcp.Ca
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
 	variables, _, err := client.Actions.ListOrgVariables(ctx, org, gitea_sdk.ListOrgActionsVariableOption{
-		ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+		Page: page, PageSize: pageSize,
 	})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list org action variables err: %v", err))

operation/issue/issue.go

@@ -55,9 +55,9 @@ var (
 
 	IssueReadTool = tool.NewDefinition(
 		IssueReadToolName,
-		"Read issue: details, comments, labels, or the full discussion as Markdown.",
+		"Read issue: details, comments, or labels.",
 		annotation.ReadOnly("Read issue details"),
-		tool.String("method", tool.Required(), tool.Enum("get", "get_comments", "get_labels", "get_discussion_markdown")),
+		tool.String("method", tool.Required(), tool.Enum("get", "get_comments", "get_labels")),
 		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
 		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
 		tool.Number("issue_number", tool.Required()),
@@ -112,8 +112,6 @@ func issueReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult,
 		return getIssueCommentsByIndexFn(ctx, args)
 	case "get_labels":
 		return getIssueLabelsFn(ctx, args)
-	case "get_discussion_markdown":
-		return getIssueDiscussionMarkdownFn(ctx, args)
 	default:
 		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
 	}
@@ -189,10 +187,8 @@ func listRepoIssuesFn(ctx context.Context, args map[string]any) (*mcp.CallToolRe
 		State:      gitea_sdk.StateType(state),
 		Labels:     labels,
 		Milestones: milestones,
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:       page,
+		PageSize:   pageSize,
 	}
 	switch args["type"] {
 	case "issues":
@@ -400,54 +396,6 @@ func getIssueCommentsByIndexFn(ctx context.Context, args map[string]any) (*mcp.C
 	return to.TextResult(out)
 }
 
-func getIssueDiscussionMarkdownFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
-	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)
-	}
-	index, err := params.GetIndex(args, "issue_number")
-	if err != nil {
-		return to.ErrorResult(err)
-	}
-
-	var issue issueWithAssets
-	issuePath := fmt.Sprintf("repos/%s/%s/issues/%d", url.PathEscape(owner), url.PathEscape(repo), index)
-	if _, err := gitea.DoJSON(ctx, "GET", issuePath, nil, nil, &issue); err != nil {
-		return to.ErrorResult(fmt.Errorf("get %v/%v/issue/%v err: %v", owner, repo, index, err))
-	}
-
-	var comments []commentWithAssets
-	commentsPath := fmt.Sprintf("repos/%s/%s/issues/%d/comments", url.PathEscape(owner), url.PathEscape(repo), index)
-	if _, err := gitea.DoJSON(ctx, "GET", commentsPath, nil, nil, &comments); err != nil {
-		return to.ErrorResult(fmt.Errorf("get %v/%v/issues/%v/comments err: %v", owner, repo, index, err))
-	}
-
-	discComments := make([]discussionComment, 0, len(comments))
-	for i := range comments {
-		discComments = append(discComments, discussionComment{
-			Author:    slim.UserLogin(comments[i].Poster),
-			CreatedAt: comments[i].Created,
-			Body:      slim.BodyWithAttachments(comments[i].Body, comments[i].Assets),
-		})
-	}
-
-	md := formatDiscussionMarkdown(discussionIssue{
-		Number:    issue.Index,
-		Title:     issue.Title,
-		Author:    slim.UserLogin(issue.Poster),
-		State:     string(issue.State),
-		Labels:    slim.LabelNames(issue.Labels),
-		Body:      slim.BodyWithAttachments(issue.Body, issue.Assets),
-		CreatedAt: issue.Created,
-	}, discComments)
-
-	return to.RawTextResult(md)
-}
-
 func getIssueLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
 	owner, err := params.GetString(args, "owner")
 	if err != nil {

operation/issue/issue_test.go

@@ -266,119 +266,6 @@ func Test_getIssueByIndexFn_includesAttachments(t *testing.T) {
 	}
 }
 
-func Test_getIssueDiscussionMarkdownFn(t *testing.T) {
-	const (
-		owner = "octo"
-		repo  = "demo"
-	)
-
-	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/issues/42", owner, repo):
-			w.Header().Set("Content-Type", "application/json")
-			_, _ = w.Write([]byte(`{
-				"number": 42,
-				"title": "bug with screenshot",
-				"body": "see attached",
-				"state": "open",
-				"user": {"login": "octocat"},
-				"labels": [{"name": "bug"}],
-				"created_at": "2026-01-02T15:04:05Z",
-				"assets": [
-					{"id": 1, "name": "shot.png", "size": 1024, "browser_download_url": "https://example/shot.png"}
-				]
-			}`))
-		case fmt.Sprintf("/api/v1/repos/%s/%s/issues/42/comments", owner, repo):
-			w.Header().Set("Content-Type", "application/json")
-			_, _ = w.Write([]byte(`[
-				{"id": 1, "body": "see this", "user": {"login": "reviewer"}, "created_at": "2026-01-03T09:00:00Z", "assets": [
-					{"id": 9, "name": "log.txt", "size": 200, "browser_download_url": "https://example/log.txt"}
-				]}
-			]`))
-		default:
-			http.NotFound(w, r)
-		}
-	})
-	server := httptest.NewServer(handler)
-	defer server.Close()
-
-	origHost, origToken, origVersion := flag.Host, flag.Token, flag.Version
-	flag.Host, flag.Token, flag.Version = server.URL, "", "test"
-	defer func() { flag.Host, flag.Token, flag.Version = origHost, origToken, origVersion }()
-
-	args := map[string]any{
-		"owner": owner, "repo": repo, "issue_number": float64(42),
-	}
-	res, err := getIssueDiscussionMarkdownFn(context.Background(), args)
-	if err != nil {
-		t.Fatalf("getIssueDiscussionMarkdownFn() error = %v", err)
-	}
-	if res.IsError {
-		t.Fatalf("unexpected error result: %v", res.Content)
-	}
-	body := res.Content[0].(*mcp.TextContent).Text
-	for _, want := range []string{
-		"# bug with screenshot (#42)",
-		"**Author:** octocat",
-		"**State:** open",
-		"**Labels:** bug",
-		"[shot.png](https://example/shot.png)",
-		"### reviewer on 2026-01-03T09:00:00Z",
-		"[log.txt](https://example/log.txt)",
-	} {
-		if !strings.Contains(body, want) {
-			t.Fatalf("expected markdown to contain %q, got:\n%s", want, body)
-		}
-	}
-}
-
-func Test_getIssueDiscussionMarkdownFn_noComments(t *testing.T) {
-	const (
-		owner = "octo"
-		repo  = "demo"
-	)
-
-	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/issues/7", owner, repo):
-			w.Header().Set("Content-Type", "application/json")
-			_, _ = w.Write([]byte(`{"number": 7, "title": "quiet issue", "state": "open", "user": {"login": "octocat"}}`))
-		case fmt.Sprintf("/api/v1/repos/%s/%s/issues/7/comments", owner, repo):
-			w.Header().Set("Content-Type", "application/json")
-			_, _ = w.Write([]byte(`[]`))
-		default:
-			http.NotFound(w, r)
-		}
-	})
-	server := httptest.NewServer(handler)
-	defer server.Close()
-
-	origHost, origToken, origVersion := flag.Host, flag.Token, flag.Version
-	flag.Host, flag.Token, flag.Version = server.URL, "", "test"
-	defer func() { flag.Host, flag.Token, flag.Version = origHost, origToken, origVersion }()
-
-	args := map[string]any{
-		"owner": owner, "repo": repo, "issue_number": float64(7),
-	}
-	res, err := getIssueDiscussionMarkdownFn(context.Background(), args)
-	if err != nil {
-		t.Fatalf("getIssueDiscussionMarkdownFn() error = %v", err)
-	}
-	if res.IsError {
-		t.Fatalf("unexpected error result: %v", res.Content)
-	}
-	body := res.Content[0].(*mcp.TextContent).Text
-	if !strings.Contains(body, "_No comments yet._") {
-		t.Fatalf("expected placeholder for no comments, got:\n%s", body)
-	}
-}
-
 func Test_getIssueCommentsByIndexFn_includesAttachments(t *testing.T) {
 	const (
 		owner = "octo"

operation/issue/markdown.go

@@ -1,63 +0,0 @@
-package issue
-
-import (
-	"fmt"
-	"strings"
-	"time"
-)
-
-type discussionIssue struct {
-	Number    int64
-	Title     string
-	Author    string
-	State     string
-	Labels    []string
-	Body      string
-	CreatedAt time.Time
-}
-
-type discussionComment struct {
-	Author    string
-	CreatedAt time.Time
-	Body      string
-}
-
-// formatDiscussionMarkdown renders an issue and its comments as a single
-// Markdown document suitable for display without further parsing.
-func formatDiscussionMarkdown(issue discussionIssue, comments []discussionComment) string {
-	var b strings.Builder
-
-	fmt.Fprintf(&b, "# %s (#%d)\n\n", issue.Title, issue.Number)
-	fmt.Fprintf(&b, "**Author:** %s\n", issue.Author)
-	fmt.Fprintf(&b, "**State:** %s\n", issue.State)
-	if len(issue.Labels) > 0 {
-		fmt.Fprintf(&b, "**Labels:** %s\n", strings.Join(issue.Labels, ", "))
-	}
-	if !issue.CreatedAt.IsZero() {
-		fmt.Fprintf(&b, "**Created:** %s\n", issue.CreatedAt.UTC().Format(time.RFC3339))
-	}
-	b.WriteString("\n")
-	b.WriteString(strings.TrimSpace(issue.Body))
-	b.WriteString("\n\n---\n\n## Comments\n\n")
-
-	if len(comments) == 0 {
-		b.WriteString("_No comments yet._\n")
-		return b.String()
-	}
-
-	for i, c := range comments {
-		fmt.Fprintf(&b, "### %s", c.Author)
-		if !c.CreatedAt.IsZero() {
-			fmt.Fprintf(&b, " on %s", c.CreatedAt.UTC().Format(time.RFC3339))
-		}
-		b.WriteString("\n\n")
-		b.WriteString(strings.TrimSpace(c.Body))
-		if i < len(comments)-1 {
-			b.WriteString("\n\n---\n\n")
-		} else {
-			b.WriteString("\n")
-		}
-	}
-
-	return b.String()
-}

operation/issue/markdown_test.go

@@ -1,85 +0,0 @@
-package issue
-
-import (
-	"strings"
-	"testing"
-	"time"
-)
-
-func Test_formatDiscussionMarkdown_includesIssueAndComments(t *testing.T) {
-	created := time.Date(2026, 1, 2, 15, 4, 5, 0, time.UTC)
-	commentTime := time.Date(2026, 1, 3, 9, 0, 0, 0, time.UTC)
-	md := formatDiscussionMarkdown(
-		discussionIssue{
-			Number:    42,
-			Title:     "bug with screenshot",
-			Author:    "octocat",
-			State:     "open",
-			Labels:    []string{"bug", "help wanted"},
-			Body:      "see attached",
-			CreatedAt: created,
-		},
-		[]discussionComment{
-			{Author: "reviewer", CreatedAt: commentTime, Body: "thanks for reporting"},
-		},
-	)
-
-	wantSubstrings := []string{
-		"# bug with screenshot (#42)",
-		"**Author:** octocat",
-		"**State:** open",
-		"**Labels:** bug, help wanted",
-		"**Created:** 2026-01-02T15:04:05Z",
-		"see attached",
-		"## Comments",
-		"### reviewer",
-		"2026-01-03T09:00:00Z",
-		"thanks for reporting",
-	}
-	for _, want := range wantSubstrings {
-		if !strings.Contains(md, want) {
-			t.Fatalf("expected markdown to contain %q, got:\n%s", want, md)
-		}
-	}
-}
-
-func Test_formatDiscussionMarkdown_noComments(t *testing.T) {
-	md := formatDiscussionMarkdown(
-		discussionIssue{
-			Number: 1,
-			Title:  "no comments yet",
-			Author: "octocat",
-			State:  "open",
-		},
-		nil,
-	)
-
-	if !strings.Contains(md, "## Comments") {
-		t.Fatalf("expected a Comments section, got:\n%s", md)
-	}
-	if !strings.Contains(md, "_No comments yet._") {
-		t.Fatalf("expected placeholder for no comments, got:\n%s", md)
-	}
-}
-
-func Test_formatDiscussionMarkdown_attachmentBodyIsInlined(t *testing.T) {
-	md := formatDiscussionMarkdown(
-		discussionIssue{
-			Number: 7,
-			Title:  "with attachment",
-			Author: "octocat",
-			State:  "open",
-			Body:   "see attached\n\n[shot.png](https://example/shot.png)",
-		},
-		[]discussionComment{
-			{Author: "reviewer", Body: "log attached\n\n[log.txt](https://example/log.txt)"},
-		},
-	)
-
-	if !strings.Contains(md, "[shot.png](https://example/shot.png)") {
-		t.Fatalf("expected issue attachment link in markdown, got:\n%s", md)
-	}
-	if !strings.Contains(md, "[log.txt](https://example/log.txt)") {
-		t.Fatalf("expected comment attachment link in markdown, got:\n%s", md)
-	}
-}

operation/label/label.go

@@ -116,10 +116,8 @@ func listRepoLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolRe
 	page, pageSize := params.GetPagination(args, 30)
 
 	opt := gitea_sdk.ListLabelsOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
@@ -261,10 +259,8 @@ func listOrgLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolRes
 	page, pageSize := params.GetPagination(args, 30)
 
 	opt := gitea_sdk.ListOrgLabelsOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/milestone/milestone.go

@@ -134,12 +134,10 @@ func listMilestonesFn(ctx context.Context, args map[string]any) (*mcp.CallToolRe
 	name := params.GetOptionalString(args, "name", "")
 	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListMilestoneOption{
-		State: gitea_sdk.StateType(state),
-		Name:  name,
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		State:    gitea_sdk.StateType(state),
+		Name:     name,
+		Page:     page,
+		PageSize: pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/notification/notification.go

@@ -95,10 +95,8 @@ func notificationWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToo
 func listNotificationsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
 	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListNotificationOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	}
 	if status, ok := args["status"].(string); ok {
 		opt.Status = []gitea_sdk.NotificationStatus{gitea_sdk.NotificationStatus(status)}

operation/operation.go

@@ -133,6 +133,7 @@ func newHTTPServer(addr string, s *mcp.Server) *http.Server {
 			PropagateRequestCancellation: true,
 		},
 	)))
+	mux.HandleFunc("/healthz", handleHealthz)
 	return &http.Server{
 		Addr:              addr,
 		Handler:           mux,
@@ -140,6 +141,12 @@ func newHTTPServer(addr string, s *mcp.Server) *http.Server {
 	}
 }
 
+func handleHealthz(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte("ok\n"))
+}
+
 func Run() error {
 	mcpServer = newMCPServer(flag.Version)
 	RegisterTool(mcpServer)

operation/operation_test.go

@@ -1,6 +1,10 @@
 package operation
 
-import "testing"
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
 
 func TestNewHTTPServerConfig(t *testing.T) {
 	server := newHTTPServer(":12345", newMCPServer("test"))
@@ -18,6 +22,21 @@ func TestNewHTTPServerConfig(t *testing.T) {
 	}
 }
 
+func TestHealthzEndpoint(t *testing.T) {
+	server := newHTTPServer(":0", newMCPServer("test"))
+
+	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	rec := httptest.NewRecorder()
+	server.Handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+	if body := rec.Body.String(); body == "" {
+		t.Error("body is empty, want a non-empty health message")
+	}
+}
+
 func TestParseAuthToken(t *testing.T) {
 	tests := []struct {
 		name      string

operation/pull/pull.go

@@ -349,10 +349,8 @@ func listRepoPullRequestsFn(ctx context.Context, args map[string]any) (*mcp.Call
 		State:     gitea_sdk.StateType(state),
 		Sort:      sort,
 		Milestone: milestone,
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:      page,
+		PageSize:  pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
@@ -509,10 +507,8 @@ func listPullRequestReviewsFn(ctx context.Context, args map[string]any) (*mcp.Ca
 	}
 
 	reviews, _, err := client.PullRequests.ListPullReviews(ctx, owner, repo, index, gitea_sdk.ListPullReviewsOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list reviews for %v/%v/pr/%v err: %v", owner, repo, index, err))
@@ -578,7 +574,7 @@ func listPullRequestReviewCommentsFn(ctx context.Context, args map[string]any) (
 	} else {
 		page, pageSize := params.GetPagination(args, 30)
 		reviews, _, err := client.PullRequests.ListPullReviews(ctx, owner, repo, index, gitea_sdk.ListPullReviewsOptions{
-			ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+			Page: page, PageSize: pageSize,
 		})
 		if err != nil {
 			return to.ErrorResult(fmt.Errorf("list reviews for %v/%v/pr/%v err: %v", owner, repo, index, err))
@@ -1049,7 +1045,7 @@ func getPullRequestFilesFn(ctx context.Context, args map[string]any) (*mcp.CallT
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
 	files, _, err := client.PullRequests.ListPullRequestFiles(ctx, owner, repo, index, gitea_sdk.ListPullRequestFilesOptions{
-		ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+		Page: page, PageSize: pageSize,
 	})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get %v/%v/pr/%v files err: %v", owner, repo, index, err))

operation/repo/branch.go

@@ -2,6 +2,7 @@ package repo
 
 import (
 	"context"
+	"errors"
 	"fmt"
 
 	"gitea.com/gitea/gitea-mcp/pkg/annotation"
@@ -21,6 +22,7 @@ const (
 	CreateBranchToolName = "create_branch"
 	DeleteBranchToolName = "delete_branch"
 	ListBranchesToolName = "list_branches"
+	RenameBranchToolName = "rename_branch"
 )
 
 var (
@@ -52,6 +54,16 @@ var (
 		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
 		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
+
+	RenameBranchTool = tool.NewDefinition(
+		RenameBranchToolName,
+		"Rename an existing branch in a repository.",
+		annotation.Write("Rename a branch"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("branch", tool.Required()),
+		tool.String("new_name", tool.Required()),
+	)
 )
 
 func init() {
@@ -67,6 +79,10 @@ func init() {
 		Tool:    ListBranchesTool,
 		Handler: ListBranchesFn,
 	})
+	BranchTool.RegisterWrite(tool.ServerTool{
+		Tool:    RenameBranchTool,
+		Handler: RenameBranchFn,
+	})
 }
 
 func CreateBranchFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
@@ -135,10 +151,8 @@ func ListBranchesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResu
 	}
 	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListRepoBranchesOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
@@ -151,3 +165,36 @@ func ListBranchesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResu
 
 	return to.TextResult(slimBranches(branches))
 }
+
+func RenameBranchFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	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)
+	}
+	branch, err := params.GetString(args, "branch")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	newName, err := params.GetString(args, "new_name")
+	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))
+	}
+	successful, _, err := client.Repositories.RenameRepoBranch(ctx, owner, repo, branch, gitea_sdk.RenameRepoBranchOption{Name: newName})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("rename branch error: %v", err))
+	}
+	if !successful {
+		return to.ErrorResult(errors.New("rename branch error: unsuccessful"))
+	}
+
+	return to.TextResult("Branch renamed")
+}

operation/repo/branch_test.go

@@ -0,0 +1,136 @@
+package repo
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestRenameBranchFnMissingArgs(t *testing.T) {
+	fullArgs := map[string]any{
+		"owner":    "octo",
+		"repo":     "demo",
+		"branch":   "old-name",
+		"new_name": "new-name",
+	}
+
+	for _, missing := range []string{"owner", "repo", "branch", "new_name"} {
+		t.Run(missing, func(t *testing.T) {
+			args := map[string]any{}
+			for k, v := range fullArgs {
+				if k != missing {
+					args[k] = v
+				}
+			}
+
+			result, err := RenameBranchFn(context.Background(), args)
+			if err != nil {
+				t.Fatalf("RenameBranchFn() error = %v", err)
+			}
+			if !result.IsError {
+				t.Fatalf("RenameBranchFn() with missing %q, want error result", missing)
+			}
+		})
+	}
+}
+
+func TestRenameBranchFn(t *testing.T) {
+	const (
+		owner   = "octo"
+		repo    = "demo"
+		branch  = "old-name"
+		newName = "new-name"
+	)
+
+	for _, tc := range []struct {
+		name         string
+		serverStatus int
+		wantErr      bool
+		wantContains string
+	}{
+		{"success", http.StatusNoContent, false, "Branch renamed"},
+		{"server error", http.StatusInternalServerError, true, "rename branch error"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var (
+				mu      sync.Mutex
+				gotBody map[string]any
+			)
+
+			renamePath := fmt.Sprintf("/api/v1/repos/%s/%s/branches/%s", owner, repo, branch)
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				switch r.URL.Path {
+				case "/api/v1/version":
+					_, _ = w.Write([]byte(`{"version":"1.24.0"}`))
+				case renamePath:
+					mu.Lock()
+					_ = json.NewDecoder(r.Body).Decode(&gotBody)
+					mu.Unlock()
+					w.WriteHeader(tc.serverStatus)
+				default:
+					http.NotFound(w, r)
+				}
+			}))
+			defer server.Close()
+
+			origHost, origToken := flag.Host, flag.Token
+			flag.Host, flag.Token = server.URL, ""
+			defer func() { flag.Host, flag.Token = origHost, origToken }()
+
+			result, err := RenameBranchFn(context.Background(), map[string]any{
+				"owner":    owner,
+				"repo":     repo,
+				"branch":   branch,
+				"new_name": newName,
+			})
+			if err != nil {
+				t.Fatalf("RenameBranchFn() error = %v", err)
+			}
+
+			if result.IsError != tc.wantErr {
+				t.Fatalf("RenameBranchFn() IsError = %v, want %v (result: %v)", result.IsError, tc.wantErr, result)
+			}
+
+			text := result.Content[0].(*mcp.TextContent).Text
+			if !strings.Contains(text, tc.wantContains) {
+				t.Fatalf("result = %s, want it to contain %q", text, tc.wantContains)
+			}
+
+			if !tc.wantErr {
+				mu.Lock()
+				defer mu.Unlock()
+				if gotBody["name"] != newName {
+					t.Fatalf("request body name = %v, want %s", gotBody["name"], newName)
+				}
+			}
+		})
+	}
+}
+
+func TestRenameBranchToolRegistration(t *testing.T) {
+	found := false
+	for _, registered := range BranchTool.WriteTools() {
+		if registered.Tool.Name == RenameBranchToolName {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("%q is not registered as a write tool", RenameBranchToolName)
+	}
+
+	for _, registered := range BranchTool.ReadTools() {
+		if registered.Tool.Name == RenameBranchToolName {
+			t.Fatalf("%q is registered as a read tool, want write only", RenameBranchToolName)
+		}
+	}
+}

operation/repo/commit.go

@@ -69,12 +69,10 @@ func ListRepoCommitsFn(ctx context.Context, args map[string]any) (*mcp.CallToolR
 	sha, _ := args["sha"].(string)
 	path, _ := args["path"].(string)
 	opt := gitea_sdk.ListCommitOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
-		SHA:  sha,
-		Path: path,
+		Page:     page,
+		PageSize: pageSize,
+		SHA:      sha,
+		Path:     path,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/repo/file.go

@@ -266,11 +266,9 @@ func DeleteFileFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult
 		return to.ErrorResult(err)
 	}
 	opt := gitea_sdk.DeleteFileOptions{
-		FileOptions: gitea_sdk.FileOptions{
-			Message:    message,
-			BranchName: branchName,
-		},
-		SHA: sha,
+		Message:    message,
+		BranchName: branchName,
+		SHA:        sha,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/repo/release.go

@@ -236,10 +236,8 @@ func ListReleasesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResu
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
 	releases, _, err := client.Releases.ListReleases(ctx, owner, repo, gitea_sdk.ListReleasesOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:         page,
+		PageSize:     pageSize,
 		IsDraft:      params.GetOptionalBoolPtr(args, "is_draft"),
 		IsPreRelease: params.GetOptionalBoolPtr(args, "is_pre_release"),
 	})

operation/repo/repo.go

@@ -170,10 +170,8 @@ func ForkRepoFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult,
 func ListMyReposFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
 	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListReposOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
@@ -194,10 +192,8 @@ func ListOrgReposFn(ctx context.Context, args map[string]any) (*mcp.CallToolResu
 	}
 	page, pageSize := params.GetPagination(args, 100)
 	opt := gitea_sdk.ListOrgReposOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/repo/tag.go

@@ -185,10 +185,8 @@ func ListTagsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult,
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
 	tags, _, err := client.Repositories.ListRepoTags(ctx, owner, repo, gitea_sdk.ListRepoTagsOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
-		},
+		Page:     int(page),
+		PageSize: int(pageSize),
 	})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list tags error: %v", err))

operation/repo/tree.go

@@ -54,10 +54,8 @@ func GetRepoTreeFn(ctx context.Context, args map[string]any) (*mcp.CallToolResul
 	page, pageSize := params.GetPagination(args, 30)
 
 	opt := gitea_sdk.ListTreeOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:      page,
+		PageSize:  pageSize,
 		Ref:       treeSHA,
 		Recursive: recursive,
 	}

operation/search/search.go

@@ -102,11 +102,9 @@ func UsersFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, err
 	}
 	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.SearchUsersOption{
-		KeyWord: keyword,
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		KeyWord:  keyword,
+		Page:     page,
+		PageSize: pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
@@ -133,10 +131,8 @@ func OrgTeamsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult,
 	opt := gitea_sdk.SearchTeamsOptions{
 		Query:              query,
 		IncludeDescription: includeDescription,
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:               page,
+		PageSize:           pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
@@ -168,10 +164,8 @@ func ReposFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, err
 		IsArchived:           params.GetOptionalBoolPtr(args, "isArchived"),
 		Sort:                 sort,
 		Order:                order,
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:                 page,
+		PageSize:             pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
@@ -192,11 +186,9 @@ func IssuesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, er
 	page, pageSize := params.GetPagination(args, 30)
 
 	opt := gitea_sdk.ListIssueOption{
-		KeyWord: query,
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		KeyWord:  query,
+		Page:     page,
+		PageSize: pageSize,
 	}
 	if state, ok := args["state"].(string); ok {
 		opt.State = gitea_sdk.StateType(state)

operation/timetracking/timetracking.go

@@ -200,10 +200,8 @@ func listTrackedTimesFn(ctx context.Context, args map[string]any) (*mcp.CallTool
 	}
 
 	times, _, err := client.Issues.ListIssueTrackedTimes(ctx, owner, repo, index, gitea_sdk.ListTrackedTimesOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list tracked times for %s/%s#%d err: %v", owner, repo, index, err))
@@ -290,10 +288,8 @@ func listRepoTimesFn(ctx context.Context, args map[string]any) (*mcp.CallToolRes
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
 	times, _, err := client.Issues.ListRepoTrackedTimes(ctx, owner, repo, gitea_sdk.ListTrackedTimesOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list repo tracked times for %s/%s err: %v", owner, repo, err))

operation/user/user.go

@@ -59,10 +59,8 @@ func GetUserOrgsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResul
 	page, pageSize := params.GetPagination(args, 30)
 
 	opt := gitea_sdk.ListOrgsOptions{
-		ListOptions: gitea_sdk.ListOptions{
-			Page:     page,
-			PageSize: pageSize,
-		},
+		Page:     page,
+		PageSize: pageSize,
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

pkg/gitea/attachment_test.go

@@ -191,8 +191,7 @@ func TestDownloadAttachmentErrorsOnNon2xx(t *testing.T) {
 	if status != http.StatusForbidden {
 		t.Fatalf("status = %d, want %d", status, http.StatusForbidden)
 	}
-	var httpErr *HTTPError
-	if !errors.As(err, &httpErr) {
+	if _, ok := errors.AsType[*HTTPError](err); !ok {
 		t.Fatalf("expected HTTPError, got %T", err)
 	}
 }

pkg/gitea/rest.go

@@ -236,8 +236,7 @@ func OpenAttachment(ctx context.Context, attachmentPath, accept string) (*Attach
 func DownloadAttachment(ctx context.Context, attachmentPath, accept string) ([]byte, string, int, error) {
 	resp, err := OpenAttachment(ctx, attachmentPath, accept)
 	if err != nil {
-		var httpErr *HTTPError
-		if errors.As(err, &httpErr) {
+		if httpErr, ok := errors.AsType[*HTTPError](err); ok {
 			return nil, "", httpErr.StatusCode, err
 		}
 		return nil, "", 0, err

pkg/to/to.go

@@ -23,17 +23,6 @@ func TextResult(v any) (*mcp.CallToolResult, error) {
 	}, nil
 }
 
-// RawTextResult returns text as-is, without JSON-encoding it. Use it for
-// content that is already meant to be read directly, such as Markdown.
-func RawTextResult(text string) (*mcp.CallToolResult, error) {
-	if flag.Debug {
-		log.Debugf("Text Result: %s", text)
-	}
-	return &mcp.CallToolResult{
-		Content: []mcp.Content{&mcp.TextContent{Text: text}},
-	}, nil
-}
-
 func ErrorResult(err error) (*mcp.CallToolResult, error) {
 	log.Errorf("%s", err.Error())
 	var result mcp.CallToolResult

pkg/tool/tool.go

@@ -102,8 +102,7 @@ func (s ServerTool) MCPHandler() mcp.ToolHandler {
 
 		result, err = s.Handler(ctx, arguments)
 		if err != nil {
-			var protocolErr *jsonrpc.Error
-			if errors.As(err, &protocolErr) {
+			if _, ok := errors.AsType[*jsonrpc.Error](err); ok {
 				return nil, err
 			}
 			return to.ErrorResult(err)