Trim tool schemas, add param aliases, new PR methods (#191)

- Tool list size reduced by 26.6% (43,032 → 31,599 bytes on the `tools/list` JSON-RPC response).
- Trim redundant tool/param descriptions; shared description constants for `owner`/`repo`/`page`/`per_page`.
- Schemas now use github-mcp-server param names directly: `issue_number` (was `index` on issue tools), `pull_number` (was `index` on PR tools), `path` (was `filePath`), `query` (was `keyword` on user/repo search), `per_page` (was `perPage`).
- New PR read methods `get_files` and `get_status`; new PR write method `update_branch` (update PR branch from base).
- `list_org_repos` now uses `per_page` (was `pageSize`).
- `milestone_write` accepts `update` and `edit`.
- `create_branch` `old_branch` is optional; Gitea defaults to the repo default branch.
- Fix `list_commits` handler to honour optional `page`/`per_page` schema (was erroring out when callers omitted them).

---
This PR was written with the help of Claude Opus 4.7

Reviewed-on: https://gitea.com/gitea/gitea-mcp/pulls/191
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Co-committed-by: silverwind <me@silverwind.io>

.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
   "name": "Gitea MCP DevContainer",
-  "image": "mcr.microsoft.com/devcontainers/go:1.24-bookworm",
+  "image": "mcr.microsoft.com/devcontainers/go:1.26-bookworm",
   "features": {},
   "customizations": {
     "vscode": {

.golangci.yml

@@ -71,7 +71,10 @@ linters:
         - name: unexported-return
         - name: var-declaration
         - name: var-naming
-          disabled: true
+          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
     staticcheck:
       checks:
         - all
@@ -91,20 +94,21 @@ linters:
       - common-false-positives
       - legacy
       - std-error-handling
-    rules:
-      - linters:
-          - errcheck
-          - staticcheck
-          - unparam
-        path: _test\.go
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0
 formatters:
   enable:
-    - gofmt
+    - gci
     - gofumpt
   settings:
+    gci:
+      custom-order: true
+      sections:
+        - standard
+        - prefix(gitea.com/gitea/gitea-mcp)
+        - blank
+        - default
     gofumpt:
       extra-rules: true
   exclusions:

AGENTS.md

@@ -1,71 +1,8 @@
-# AGENTS.md
-
-This file provides guidance to AI coding agents when working with code in this repository.
-
-## Development Commands
-
-**Build**: `make build` - Build the gitea-mcp binary
-**Install**: `make install` - Build and install to GOPATH/bin
-**Clean**: `make clean` - Remove build artifacts
-**Test**: `go test ./...` - Run all tests
-**Hot reload**: `make dev` - Start development server with hot reload (requires air)
-**Dependencies**: `make vendor` - Tidy and verify module dependencies
-
-## Architecture Overview
-
-This is a **Gitea MCP (Model Context Protocol) Server** written in Go that provides MCP tools for interacting with Gitea repositories, issues, pull requests, users, and more.
-
-**Core Components**:
-
-- `main.go` + `cmd/cmd.go`: CLI entry point and flag parsing
-- `operation/operation.go`: Main server setup and tool registration
-- `pkg/tool/tool.go`: Tool registry with read/write categorization
-- `operation/*/`: Individual tool modules (user, repo, issue, pull, search, wiki, etc.)
-
-**Transport Modes**:
-
-- **stdio** (default): Standard input/output for MCP clients
-- **http**: HTTP server mode on configurable port (default 8080)
-
-**Authentication**:
-
-- Global token via `--token` flag or `GITEA_ACCESS_TOKEN` env var
-- HTTP mode supports per-request Bearer token override in Authorization header
-- Token precedence: HTTP Authorization header > CLI flag > environment variable
-
-**Tool Organization**:
-
-- Tools are categorized as read-only or write operations
-- `--read-only` flag exposes only read tools
-- Tool modules register via `Tool.RegisterRead()` and `Tool.RegisterWrite()`
-
-**Key Configuration**:
-
-- Default Gitea host: `https://gitea.com` (override with `--host` or `GITEA_HOST`)
-- Environment variables can override CLI flags: `MCP_MODE`, `GITEA_READONLY`, `GITEA_DEBUG`, `GITEA_INSECURE`
-- Logs are written to `~/.gitea-mcp/gitea-mcp.log` with rotation
-
-## Available Tools
-
-The server provides 40+ MCP tools covering:
-
-- **User**: get_my_user_info, get_user_orgs, search_users
-- **Repository**: create_repo, fork_repo, list_my_repos, search_repos
-- **Branches/Tags**: create_branch, delete_branch, list_branches, create_tag, list_tags
-- **Files**: get_file_content, create_file, update_file, delete_file, get_dir_content
-- **Issues**: create_issue, list_repo_issues, create_issue_comment, edit_issue
-- **Pull Requests**: create_pull_request, list_repo_pull_requests, get_pull_request_by_index
-- **Releases**: create_release, list_releases, get_latest_release
-- **Wiki**: create_wiki_page, update_wiki_page, list_wiki_pages
-- **Search**: search_repos, search_users, search_org_teams
-- **Version**: get_gitea_mcp_server_version
-
-## Common Development Patterns
-
-**Testing**: Use `go test ./operation -run TestFunctionName` for specific tests
-
-**Token Context**: HTTP requests use `pkg/context.TokenContextKey` for request-scoped token access
-
-**Flag Access**: All packages access configuration via global variables in `pkg/flag/flag.go`
-
-**Graceful Shutdown**: HTTP mode implements graceful shutdown with 10-second timeout on SIGTERM/SIGINT
+- Use `make help` to find available development targets
+- Run `make fmt` to format `.go` files, and run `make lint-go` to lint them
+- Run `make tidy` after any `go.mod` changes
+- Ensure no trailing whitespace in edited files
+- Use Conventional Commits format for commit messages and PR titles (e.g. `type(scope): subject`)
+- Never force-push, amend, or squash unless asked. Use new commits and normal push for pull request updates
+- Include authorship attribution in issue and pull request comments
+- Add `Co-Authored-By` lines to all commits, indicating name and model used

Makefile

@@ -3,12 +3,11 @@ 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.10.1
-GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1
-GOFUMPT_PACKAGE ?= mvdan.cc/gofumpt@v0.9.2
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.3.0
 
 .PHONY: help
-help: ## Print this help message.
+help: ## print this help message
 	@echo "Usage: make [target]"
 	@echo ""
 	@echo "Targets:"
@@ -16,7 +15,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 +23,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 +48,19 @@ 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 $(GOLANGCI_LINT_PACKAGE) fmt
+
+.PHONY: fmt-check
+fmt-check: fmt ## check that Go code is formatted
+	@diff=$$(git diff --color=always); \
+	if [ -n "$$diff" ]; then \
+		echo "Please run 'make fmt' and commit the result:"; \
+		printf "%s" "$${diff}"; \
+		exit 1; \
+	fi
+
 .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

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

README.zh-tw.md

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

cmd/cmd.go

@@ -5,6 +5,7 @@ import (
 	"flag"
 	"fmt"
 	"os"
+	"strings"
 	"text/tabwriter"
 
 	"gitea.com/gitea/gitea-mcp/operation"
@@ -16,6 +17,7 @@ var (
 	host    string
 	port    int
 	token   string
+	tools   string
 	version bool
 )
 
@@ -30,6 +32,9 @@ func init() {
 	flag.StringVar(&token, "token", "", "")
 	flag.BoolVar(&flagPkg.ReadOnly, "r", false, "")
 	flag.BoolVar(&flagPkg.ReadOnly, "read-only", false, "")
+	defaultTools := os.Getenv("GITEA_TOOLS")
+	flag.StringVar(&tools, "O", defaultTools, "")
+	flag.StringVar(&tools, "tools", defaultTools, "")
 	flag.BoolVar(&flagPkg.Debug, "d", false, "")
 	flag.BoolVar(&flagPkg.Debug, "debug", false, "")
 	flag.BoolVar(&flagPkg.Insecure, "k", false, "")
@@ -47,16 +52,19 @@ func init() {
 		fmt.Fprintf(w, "  -p, -port <number>\tHTTP server port (default: 8080)\n")
 		fmt.Fprintf(w, "  -T, -token <token>\tPersonal access token\n")
 		fmt.Fprintf(w, "  -r, -read-only\tExpose only read-only tools\n")
+		fmt.Fprintf(w, "  -O, -tools <names>\tComma-separated list of tool names to expose\n")
 		fmt.Fprintf(w, "  -d, -debug\tEnable debug mode\n")
 		fmt.Fprintf(w, "  -k, -insecure\tIgnore TLS certificate errors\n")
 		fmt.Fprintf(w, "  -v, -version\tPrint version and exit\n")
 		fmt.Fprintln(w)
 		fmt.Fprintln(w, "Environment variables:")
 		fmt.Fprintf(w, "  GITEA_ACCESS_TOKEN\tProvide access token\n")
+		fmt.Fprintf(w, "  GITEA_ACCESS_TOKEN_FILE\tPath to a file containing the access token (e.g. a Docker secret)\n")
 		fmt.Fprintf(w, "  GITEA_DEBUG\tSet to 'true' for debug mode\n")
 		fmt.Fprintf(w, "  GITEA_HOST\tOverride Gitea host URL\n")
 		fmt.Fprintf(w, "  GITEA_INSECURE\tSet to 'true' to ignore TLS errors\n")
 		fmt.Fprintf(w, "  GITEA_READONLY\tSet to 'true' for read-only mode\n")
+		fmt.Fprintf(w, "  GITEA_TOOLS\tComma-separated list of tool names to expose\n")
 		fmt.Fprintf(w, "  MCP_MODE\tOverride transport mode\n")
 		w.Flush()
 	}
@@ -74,6 +82,16 @@ func init() {
 	if flagPkg.Token == "" {
 		flagPkg.Token = os.Getenv("GITEA_ACCESS_TOKEN")
 	}
+	if flagPkg.Token == "" {
+		if tokenFile := os.Getenv("GITEA_ACCESS_TOKEN_FILE"); tokenFile != "" {
+			data, err := os.ReadFile(tokenFile)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "error reading GITEA_ACCESS_TOKEN_FILE: %v\n", err)
+				os.Exit(1)
+			}
+			flagPkg.Token = strings.TrimRight(string(data), "\r\n")
+		}
+	}
 
 	if os.Getenv("MCP_MODE") != "" {
 		flagPkg.Mode = os.Getenv("MCP_MODE")
@@ -83,6 +101,16 @@ func init() {
 		flagPkg.ReadOnly = true
 	}
 
+	allowed := map[string]struct{}{}
+	for t := range strings.SplitSeq(tools, ",") {
+		if t = strings.TrimSpace(t); t != "" {
+			allowed[t] = struct{}{}
+		}
+	}
+	if len(allowed) > 0 {
+		flagPkg.AllowedTools = allowed
+	}
+
 	if os.Getenv("GITEA_DEBUG") == "true" {
 		flagPkg.Debug = true
 	}

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=

main.go

@@ -1,6 +1,8 @@
 package main
 
 import (
+	"runtime/debug"
+
 	"gitea.com/gitea/gitea-mcp/cmd"
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
 )
@@ -8,6 +10,11 @@ import (
 var Version = "dev"
 
 func init() {
+	if Version == "dev" {
+		if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" && info.Main.Version != "(devel)" {
+			Version = info.Main.Version
+		}
+	}
 	flag.Version = Version
 }
 

operation/actions/config.go

@@ -8,6 +8,7 @@ import (
 	"strconv"
 	"time"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -47,27 +48,29 @@ func toSecretMetas(secrets []*gitea_sdk.Secret) []secretMeta {
 var (
 	ActionsConfigReadTool = mcp.NewTool(
 		ActionsConfigReadToolName,
-		mcp.WithDescription("Read Actions secrets and variables configuration."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("list_repo_secrets", "list_org_secrets", "list_repo_variables", "get_repo_variable", "list_org_variables", "get_org_variable")),
-		mcp.WithString("owner", mcp.Description("repository owner (required for repo methods)")),
-		mcp.WithString("repo", mcp.Description("repository name (required for repo methods)")),
-		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.WithDescription("Read Actions secrets and variables."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read Actions secrets and variables")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("list_repo_secrets", "list_org_secrets", "list_repo_variables", "get_repo_variable", "list_org_variables", "get_org_variable")),
+		mcp.WithString("owner", mcp.Description("for repo methods")),
+		mcp.WithString("repo", mcp.Description("for repo methods")),
+		mcp.WithString("org", mcp.Description("for org methods")),
+		mcp.WithString("name", mcp.Description("for get methods")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ActionsConfigWriteTool = mcp.NewTool(
 		ActionsConfigWriteToolName,
-		mcp.WithDescription("Manage Actions secrets and variables: create, update, or delete."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("upsert_repo_secret", "delete_repo_secret", "upsert_org_secret", "delete_org_secret", "create_repo_variable", "update_repo_variable", "delete_repo_variable", "create_org_variable", "update_org_variable", "delete_org_variable")),
-		mcp.WithString("owner", mcp.Description("repository owner (required for repo methods)")),
-		mcp.WithString("repo", mcp.Description("repository name (required for repo methods)")),
-		mcp.WithString("org", mcp.Description("organization name (required for org methods)")),
-		mcp.WithString("name", mcp.Description("secret or variable name (required for most methods)")),
-		mcp.WithString("data", mcp.Description("secret value (required for upsert secret methods)")),
-		mcp.WithString("value", mcp.Description("variable value (required for create/update variable methods)")),
-		mcp.WithString("description", mcp.Description("description for secret or variable")),
+		mcp.WithDescription("Write Actions secrets and variables: upsert, create, update, delete."),
+		mcp.WithToolAnnotation(annotation.Destructive("Manage Actions secrets and variables")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("upsert_repo_secret", "delete_repo_secret", "upsert_org_secret", "delete_org_secret", "create_repo_variable", "update_repo_variable", "delete_repo_variable", "create_org_variable", "update_org_variable", "delete_org_variable")),
+		mcp.WithString("owner", mcp.Description("for repo methods")),
+		mcp.WithString("repo", mcp.Description("for repo methods")),
+		mcp.WithString("org", mcp.Description("for org methods")),
+		mcp.WithString("name", mcp.Description("secret or variable name")),
+		mcp.WithString("data", mcp.Description("secret value (upsert)")),
+		mcp.WithString("value", mcp.Description("variable value")),
+		mcp.WithString("description"),
 	)
 )
 

operation/actions/runs.go

@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 	"strconv"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -27,31 +28,33 @@ const (
 var (
 	ActionsRunReadTool = mcp.NewTool(
 		ActionsRunReadToolName,
-		mcp.WithDescription("Read Actions workflow, run, and job data. Use method 'list_workflows'/'get_workflow' for workflows, 'list_runs'/'get_run' for runs, 'list_jobs'/'list_run_jobs' for jobs, 'get_job_log_preview'/'download_job_log' for logs."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("list_workflows", "get_workflow", "list_runs", "get_run", "list_jobs", "list_run_jobs", "get_job_log_preview", "download_job_log")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("workflow_id", mcp.Description("workflow ID or filename (required for 'get_workflow')")),
-		mcp.WithNumber("run_id", mcp.Description("run ID (required for 'get_run', 'list_run_jobs')")),
-		mcp.WithNumber("job_id", mcp.Description("job ID (required for 'get_job_log_preview', 'download_job_log')")),
-		mcp.WithString("status", mcp.Description("optional status filter (for 'list_runs', 'list_jobs')")),
-		mcp.WithNumber("tail_lines", mcp.Description("number of lines from end of log (for 'get_job_log_preview')"), mcp.DefaultNumber(200), mcp.Min(1)),
-		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.WithDescription("Read Actions workflows, runs, jobs, and logs."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read Actions workflow, run, and job data")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("list_workflows", "get_workflow", "list_runs", "get_run", "list_jobs", "list_run_jobs", "get_job_log_preview", "download_job_log")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("workflow_id", mcp.Description("ID or filename (for 'get_workflow')")),
+		mcp.WithNumber("run_id", mcp.Description("for 'get_run'/'list_run_jobs'")),
+		mcp.WithNumber("job_id", mcp.Description("for log methods")),
+		mcp.WithString("status", mcp.Description("filter for 'list_runs'/'list_jobs'")),
+		mcp.WithNumber("tail_lines", mcp.Description("log tail lines"), mcp.DefaultNumber(200), mcp.Min(1)),
+		mcp.WithNumber("max_bytes", mcp.Description("max log bytes"), mcp.DefaultNumber(65536), mcp.Min(1024)),
+		mcp.WithString("output_path", mcp.Description("for 'download_job_log'")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ActionsRunWriteTool = mcp.NewTool(
 		ActionsRunWriteToolName,
-		mcp.WithDescription("Trigger, cancel, or rerun Actions workflows."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("dispatch_workflow", "cancel_run", "rerun_run")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("workflow_id", mcp.Description("workflow ID or filename (required for 'dispatch_workflow')")),
-		mcp.WithString("ref", mcp.Description("git ref branch or tag (required for 'dispatch_workflow')")),
-		mcp.WithObject("inputs", mcp.Description("workflow inputs object (for 'dispatch_workflow')")),
-		mcp.WithNumber("run_id", mcp.Description("run ID (required for 'cancel_run', 'rerun_run')")),
+		mcp.WithDescription("Write Actions runs: dispatch, cancel, rerun."),
+		mcp.WithToolAnnotation(annotation.Write("Trigger, cancel, or rerun Actions workflows")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("dispatch_workflow", "cancel_run", "rerun_run")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("workflow_id", mcp.Description("ID or filename (for 'dispatch_workflow')")),
+		mcp.WithString("ref", mcp.Description("branch or tag (for 'dispatch_workflow')")),
+		mcp.WithObject("inputs", mcp.Description("for 'dispatch_workflow'")),
+		mcp.WithNumber("run_id", mcp.Description("for 'cancel_run'/'rerun_run'")),
 	)
 )
 

operation/issue/issue.go

@@ -3,7 +3,9 @@ package issue
 import (
 	"context"
 	"fmt"
+	"net/url"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -15,6 +17,18 @@ import (
 	"github.com/mark3labs/mcp-go/server"
 )
 
+// issueWithAssets / commentWithAssets wrap the SDK types to capture the
+// `assets` field that the SDK currently drops on these endpoints.
+type issueWithAssets struct {
+	gitea_sdk.Issue
+	Assets []*gitea_sdk.Attachment `json:"assets"`
+}
+
+type commentWithAssets struct {
+	gitea_sdk.Comment
+	Assets []*gitea_sdk.Attachment `json:"assets"`
+}
+
 var Tool = tool.New()
 
 const (
@@ -26,38 +40,46 @@ const (
 var (
 	ListRepoIssuesTool = mcp.NewTool(
 		ListRepoIssuesToolName,
-		mcp.WithDescription("List repository issues"),
-		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.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("perPage", mcp.Description("results per page"), mcp.DefaultNumber(30)),
+		mcp.WithToolAnnotation(annotation.ReadOnly("List repository issues")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("state", mcp.DefaultString("all")),
+		mcp.WithArray("labels", mcp.Description("label name filter"), mcp.Items(map[string]any{"type": "string"})),
+		mcp.WithString("since", mcp.Description("updated after ISO 8601")),
+		mcp.WithString("before", mcp.Description("updated before ISO 8601")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 
 	IssueReadTool = mcp.NewTool(
 		IssueReadToolName,
-		mcp.WithDescription("Get information about a specific issue. Use method 'get' for issue details, 'get_comments' for issue comments, 'get_labels' for issue labels."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("get", "get_comments", "get_labels")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("index", mcp.Required(), mcp.Description("repository issue index")),
+		mcp.WithDescription("Read issue: details, comments, or labels."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read issue details")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("get", "get_comments", "get_labels")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("issue_number", mcp.Required()),
 	)
 
 	IssueWriteTool = mcp.NewTool(
 		IssueWriteToolName,
-		mcp.WithDescription("Create or update issues and comments, manage labels. Use method 'create' to create an issue, 'update' to edit, 'add_comment'/'edit_comment' for comments, 'add_labels'/'remove_label'/'replace_labels'/'clear_labels' for label management."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("create", "update", "add_comment", "edit_comment", "add_labels", "remove_label", "replace_labels", "clear_labels")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("index", mcp.Description("issue index (required for all methods except 'create')")),
-		mcp.WithString("title", mcp.Description("issue title (required for 'create')")),
-		mcp.WithString("body", mcp.Description("issue/comment body (required for 'create', 'add_comment', 'edit_comment')")),
-		mcp.WithArray("assignees", mcp.Description("usernames to assign (for 'create', 'update')"), mcp.Items(map[string]any{"type": "string"})),
-		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.WithNumber("label_id", mcp.Description("label ID to remove (required for 'remove_label')")),
+		mcp.WithDescription("Write issues: create, update, manage comments and labels."),
+		mcp.WithToolAnnotation(annotation.Write("Create or update issues, comments, and labels")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("create", "update", "add_comment", "edit_comment", "add_labels", "remove_label", "replace_labels", "clear_labels")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("issue_number", mcp.Description("required except for 'create'")),
+		mcp.WithString("title", mcp.Description("required for 'create'")),
+		mcp.WithString("body", mcp.Description("required for 'create'/'add_comment'/'edit_comment'")),
+		mcp.WithArray("assignees", mcp.Items(map[string]any{"type": "string"})),
+		mcp.WithNumber("milestone"),
+		mcp.WithString("state", mcp.Enum("open", "closed", "all")),
+		mcp.WithNumber("commentID", mcp.Description("for 'edit_comment'")),
+		mcp.WithArray("labels", mcp.Description("label IDs"), mcp.Items(map[string]any{"type": "number"})),
+		mcp.WithNumber("label_id", mcp.Description("for 'remove_label'")),
+		mcp.WithString("ref", mcp.Description("branch to associate")),
+		mcp.WithString("deadline", mcp.Description("ISO 8601")),
+		mcp.WithBoolean("remove_deadline"),
 	)
 )
 
@@ -132,20 +154,18 @@ func getIssueByIndexFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	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))
-	}
-	issue, _, err := client.GetIssue(owner, repo, index)
-	if err != nil {
+	var issue issueWithAssets
+	path := fmt.Sprintf("repos/%s/%s/issues/%d", url.PathEscape(owner), url.PathEscape(repo), index)
+	if _, err := gitea.DoJSON(ctx, "GET", path, nil, nil, &issue); err != nil {
 		return to.ErrorResult(fmt.Errorf("get %v/%v/issue/%v err: %v", owner, repo, index, err))
 	}
-
-	return to.TextResult(slimIssue(issue))
+	m := slimIssue(&issue.Issue)
+	m["body"] = bodyWithAttachments(issue.Body, issue.Assets)
+	return to.TextResult(m)
 }
 
 func listRepoIssuesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
@@ -162,14 +182,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 +241,13 @@ 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
+	}
+	if ref, ok := req.GetArguments()["ref"].(string); ok {
+		opt.Ref = ref
+	}
+	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))
@@ -231,7 +266,7 @@ func createIssueCommentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Ca
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -264,7 +299,7 @@ func editIssueFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRes
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -289,6 +324,13 @@ func editIssueFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRes
 	if ok {
 		opt.State = new(gitea_sdk.StateType(state))
 	}
+	if ref, ok := req.GetArguments()["ref"].(string); ok {
+		opt.Ref = &ref
+	}
+	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 {
@@ -345,21 +387,22 @@ func getIssueCommentsByIndexFn(ctx context.Context, req mcp.CallToolRequest) (*m
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	opt := gitea_sdk.ListIssueCommentOptions{}
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	issue, _, err := client.ListIssueComments(owner, repo, index, opt)
-	if err != nil {
+	var comments []commentWithAssets
+	path := fmt.Sprintf("repos/%s/%s/issues/%d/comments", url.PathEscape(owner), url.PathEscape(repo), index)
+	if _, err := gitea.DoJSON(ctx, "GET", path, nil, nil, &comments); err != nil {
 		return to.ErrorResult(fmt.Errorf("get %v/%v/issues/%v/comments err: %v", owner, repo, index, err))
 	}
-
-	return to.TextResult(slimComments(issue))
+	out := make([]map[string]any, 0, len(comments))
+	for i := range comments {
+		m := slimComment(&comments[i].Comment)
+		m["body"] = bodyWithAttachments(comments[i].Body, comments[i].Assets)
+		out = append(out, m)
+	}
+	return to.TextResult(out)
 }
 
 func getIssueLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
@@ -372,7 +415,7 @@ func getIssueLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -400,7 +443,7 @@ func addIssueLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -430,7 +473,7 @@ func replaceIssueLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Ca
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -460,7 +503,7 @@ func clearIssueLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -486,7 +529,7 @@ func removeIssueLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}

operation/issue/issue_test.go

@@ -0,0 +1,269 @@
+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")
+	}
+}
+
+func Test_getIssueByIndexFn_includesAttachments(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",
+				"assets": [
+					{"id": 1, "name": "shot.png", "size": 1024, "browser_download_url": "https://example/shot.png"}
+				]
+			}`))
+		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 }()
+
+	req := mcp.CallToolRequest{Params: mcp.CallToolParams{Arguments: map[string]any{
+		"owner": owner, "repo": repo, "issue_number": float64(42),
+	}}}
+	res, err := getIssueByIndexFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("getIssueByIndexFn() 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, `[shot.png](https://example/shot.png)`) {
+		t.Fatalf("expected attachment markdown inlined in body, got: %s", body)
+	}
+	if strings.Contains(body, `"attachments"`) {
+		t.Fatalf("attachments should be inlined into body, not a separate field: %s", body)
+	}
+}
+
+func Test_getIssueCommentsByIndexFn_includesAttachments(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/comments", owner, repo):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`[
+				{"id": 1, "body": "see this", "assets": [
+					{"id": 9, "name": "log.txt", "size": 200, "browser_download_url": "https://example/log.txt"}
+				]},
+				{"id": 2, "body": "no attachment", "assets": []}
+			]`))
+		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 }()
+
+	req := mcp.CallToolRequest{Params: mcp.CallToolParams{Arguments: map[string]any{
+		"owner": owner, "repo": repo, "issue_number": float64(7),
+	}}}
+	res, err := getIssueCommentsByIndexFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("getIssueCommentsByIndexFn() 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, `[log.txt](https://example/log.txt)`) {
+		t.Fatalf("expected attachment markdown inlined in body, got: %s", body)
+	}
+	if strings.Contains(body, `"attachments"`) {
+		t.Fatalf("attachments should be inlined into body, not a separate field: %s", body)
+	}
+}

operation/issue/slim.go

@@ -1,6 +1,9 @@
 package issue
 
 import (
+	"fmt"
+	"strings"
+
 	gitea_sdk "code.gitea.io/sdk/gitea"
 )
 
@@ -37,6 +40,24 @@ func labelNames(labels []*gitea_sdk.Label) []string {
 	return out
 }
 
+func bodyWithAttachments(body string, atts []*gitea_sdk.Attachment) string {
+	links := make([]string, 0, len(atts))
+	for _, a := range atts {
+		if a == nil || a.DownloadURL == "" {
+			continue
+		}
+		links = append(links, fmt.Sprintf("[%s](%s)", a.Name, a.DownloadURL))
+	}
+	if len(links) == 0 {
+		return body
+	}
+	joined := strings.Join(links, "\n")
+	if body == "" {
+		return joined
+	}
+	return body + "\n\n" + joined
+}
+
 func slimIssue(i *gitea_sdk.Issue) map[string]any {
 	if i == nil {
 		return nil
@@ -63,6 +84,12 @@ func slimIssue(i *gitea_sdk.Issue) map[string]any {
 			"title": i.Milestone.Title,
 		}
 	}
+	if i.Ref != "" {
+		m["ref"] = i.Ref
+	}
+	if i.Deadline != nil {
+		m["deadline"] = i.Deadline
+	}
 	if i.PullRequest != nil {
 		m["is_pull"] = true
 	}
@@ -88,6 +115,12 @@ func slimIssues(issues []*gitea_sdk.Issue) []map[string]any {
 		if len(i.Labels) > 0 {
 			m["labels"] = labelNames(i.Labels)
 		}
+		if i.Ref != "" {
+			m["ref"] = i.Ref
+		}
+		if i.Deadline != nil {
+			m["deadline"] = i.Deadline
+		}
 		out = append(out, m)
 	}
 	return out
@@ -107,14 +140,6 @@ func slimComment(c *gitea_sdk.Comment) map[string]any {
 	}
 }
 
-func slimComments(comments []*gitea_sdk.Comment) []map[string]any {
-	out := make([]map[string]any, 0, len(comments))
-	for _, c := range comments {
-		out = append(out, slimComment(c))
-	}
-	return out
-}
-
 func slimLabels(labels []*gitea_sdk.Label) []map[string]any {
 	out := make([]map[string]any, 0, len(labels))
 	for _, l := range labels {

operation/issue/slim_test.go

@@ -40,6 +40,29 @@ func TestSlimIssue(t *testing.T) {
 	}
 }
 
+func TestBodyWithAttachments(t *testing.T) {
+	atts := []*gitea_sdk.Attachment{
+		{Name: "shot.png", DownloadURL: "https://example/shot.png"},
+		{Name: "log.txt", DownloadURL: "https://example/log.txt"},
+	}
+	got := bodyWithAttachments("see attached", atts)
+	want := "see attached\n\n[shot.png](https://example/shot.png)\n[log.txt](https://example/log.txt)"
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+
+	if got := bodyWithAttachments("only body", nil); got != "only body" {
+		t.Errorf("nil attachments should return body unchanged, got %q", got)
+	}
+	if got := bodyWithAttachments("", atts); got != "[shot.png](https://example/shot.png)\n[log.txt](https://example/log.txt)" {
+		t.Errorf("empty body should drop separator, got %q", got)
+	}
+	skipped := []*gitea_sdk.Attachment{nil, {Name: "noop", DownloadURL: ""}}
+	if got := bodyWithAttachments("body", skipped); got != "body" {
+		t.Errorf("nil/empty-URL attachments should be skipped, got %q", got)
+	}
+}
+
 func TestSlimIssues_ListIsSlimmer(t *testing.T) {
 	i := &gitea_sdk.Issue{
 		Index:  1,

operation/label/label.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -25,28 +26,31 @@ const (
 var (
 	LabelReadTool = mcp.NewTool(
 		LabelReadToolName,
-		mcp.WithDescription("Read label information. Use method 'list_repo_labels' to list repository labels, 'get_repo_label' to get a specific repo label, 'list_org_labels' to list organization labels."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("list_repo_labels", "get_repo_label", "list_org_labels")),
-		mcp.WithString("owner", mcp.Description("repository owner (required for repo methods)")),
-		mcp.WithString("repo", mcp.Description("repository name (required for repo methods)")),
-		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.WithDescription("Read repo or org labels."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read labels")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("list_repo_labels", "get_repo_label", "list_org_labels")),
+		mcp.WithString("owner", mcp.Description("for repo methods")),
+		mcp.WithString("repo", mcp.Description("for repo methods")),
+		mcp.WithString("org", mcp.Description("for org methods")),
+		mcp.WithNumber("id", mcp.Description("label ID (for 'get_repo_label')")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 
 	LabelWriteTool = mcp.NewTool(
 		LabelWriteToolName,
-		mcp.WithDescription("Create, edit, or delete labels for repositories or organizations."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("create_repo_label", "edit_repo_label", "delete_repo_label", "create_org_label", "edit_org_label", "delete_org_label")),
-		mcp.WithString("owner", mcp.Description("repository owner (required for repo methods)")),
-		mcp.WithString("repo", mcp.Description("repository name (required for repo methods)")),
-		mcp.WithString("org", mcp.Description("organization name (required for org methods)")),
-		mcp.WithNumber("id", mcp.Description("label ID (required for edit/delete methods)")),
-		mcp.WithString("name", mcp.Description("label name (required for create, optional for edit)")),
-		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.WithDescription("Write labels (repo or org): create, edit, delete."),
+		mcp.WithToolAnnotation(annotation.Destructive("Create, update, or delete labels")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("create_repo_label", "edit_repo_label", "delete_repo_label", "create_org_label", "edit_org_label", "delete_org_label")),
+		mcp.WithString("owner", mcp.Description("for repo methods")),
+		mcp.WithString("repo", mcp.Description("for repo methods")),
+		mcp.WithString("org", mcp.Description("for org methods")),
+		mcp.WithNumber("id", mcp.Description("for edit/delete")),
+		mcp.WithString("name", mcp.Description("required for create")),
+		mcp.WithString("color", mcp.Description("hex (#RRGGBB); required for create")),
+		mcp.WithString("description"),
+		mcp.WithBoolean("exclusive", mcp.Description("exclusive (org only)")),
+		mcp.WithBoolean("is_archived", mcp.Description("archived (repo only)")),
 	)
 )
 
@@ -178,10 +182,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 +227,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

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -25,28 +26,30 @@ const (
 var (
 	MilestoneReadTool = mcp.NewTool(
 		MilestoneReadToolName,
-		mcp.WithDescription("Read milestone information. Use method 'get' to get a specific milestone, 'list' to list milestones."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("get", "list")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("id", mcp.Description("milestone id (required for 'get')")),
-		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.WithDescription("Read milestones: get one or list."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read milestones")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("get", "list")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("id", mcp.Description("for 'get'")),
+		mcp.WithString("state", mcp.DefaultString("all")),
+		mcp.WithString("name", mcp.Description("name filter (for 'list')")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 
 	MilestoneWriteTool = mcp.NewTool(
 		MilestoneWriteToolName,
-		mcp.WithDescription("Create, edit, or delete milestones."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("create", "edit", "delete")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("id", mcp.Description("milestone id (required for 'edit', 'delete')")),
-		mcp.WithString("title", mcp.Description("milestone title (required for 'create')")),
-		mcp.WithString("description", mcp.Description("milestone description")),
+		mcp.WithDescription("Write milestones: create, update, delete."),
+		mcp.WithToolAnnotation(annotation.Destructive("Create, update, or delete milestones")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("create", "update", "edit", "delete")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("id", mcp.Description("for 'update'/'delete'")),
+		mcp.WithString("title", mcp.Description("for 'create'")),
+		mcp.WithString("description"),
 		mcp.WithString("due_on", mcp.Description("due date")),
-		mcp.WithString("state", mcp.Description("milestone state, one of open, closed (for 'edit')")),
+		mcp.WithString("state", mcp.Enum("open", "closed")),
 	)
 )
 
@@ -84,6 +87,8 @@ func milestoneWriteFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	switch method {
 	case "create":
 		return createMilestoneFn(ctx, req)
+	case "update":
+		return editMilestoneFn(ctx, req)
 	case "edit":
 		return editMilestoneFn(ctx, req)
 	case "delete":
@@ -174,6 +179,7 @@ func createMilestoneFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	if ok {
 		opt.Description = description
 	}
+	opt.Deadline = params.GetOptionalTime(req.GetArguments(), "due_on")
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
@@ -216,6 +222,7 @@ func editMilestoneFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToo
 	if ok {
 		opt.State = new(gitea_sdk.StateType(state))
 	}
+	opt.Deadline = params.GetOptionalTime(req.GetArguments(), "due_on")
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/milestone/milestone_test.go

@@ -0,0 +1,84 @@
+package milestone
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+func Test_milestoneWriteFn_dueOn(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+		id    = 42
+		due   = "2026-05-18T23:59:59Z"
+	)
+
+	var (
+		mu     sync.Mutex
+		bodies = map[string]map[string]any{}
+	)
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/version":
+			_, _ = w.Write([]byte(`{"version":"1.12.0"}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s/milestones", owner, repo),
+			fmt.Sprintf("/api/v1/repos/%s/%s/milestones/%d", owner, repo, id):
+			mu.Lock()
+			var body map[string]any
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			bodies[r.Method] = body
+			mu.Unlock()
+			_, _ = w.Write(fmt.Appendf(nil, `{"id":%d,"title":"v1","due_on":%q}`, id, due))
+		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, "due_on": due}
+
+	cases := []struct {
+		name   string
+		fn     func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error)
+		method string
+		extra  map[string]any
+	}{
+		{"create", createMilestoneFn, http.MethodPost, map[string]any{"title": "v1"}},
+		{"edit", editMilestoneFn, http.MethodPatch, map[string]any{"id": float64(id)}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			a := map[string]any{}
+			maps.Copy(a, args)
+			maps.Copy(a, tc.extra)
+			res, err := tc.fn(context.Background(), mcp.CallToolRequest{Params: mcp.CallToolParams{Arguments: a}})
+			if err != nil || res.IsError {
+				t.Fatalf("%s err=%v result=%v", tc.name, err, res)
+			}
+			mu.Lock()
+			body := bodies[tc.method]
+			mu.Unlock()
+			if got, _ := body["due_on"].(string); got != due {
+				t.Fatalf("%s: expected due_on=%q, got %v (body: %v)", tc.name, due, got, body)
+			}
+		})
+	}
+}

operation/notification/notification.go

@@ -0,0 +1,218 @@
+package notification
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
+	"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.com/gitea/gitea-mcp/pkg/tool"
+
+	gitea_sdk "code.gitea.io/sdk/gitea"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+var Tool = tool.New()
+
+const (
+	NotificationReadToolName  = "notification_read"
+	NotificationWriteToolName = "notification_write"
+)
+
+var (
+	NotificationReadTool = mcp.NewTool(
+		NotificationReadToolName,
+		mcp.WithDescription("Read notifications: list (optionally scoped to a repo) or get a thread by ID."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read notifications")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("list", "get")),
+		mcp.WithString("owner", mcp.Description("scope 'list' to a repo")),
+		mcp.WithString("repo", mcp.Description("scope 'list' to a repo")),
+		mcp.WithNumber("id", mcp.Description("thread ID (for 'get')")),
+		mcp.WithString("status", mcp.Enum("unread", "read", "pinned")),
+		mcp.WithString("subject_type", mcp.Enum("Issue", "Pull", "Commit", "Repository")),
+		mcp.WithString("since", mcp.Description("updated after ISO 8601")),
+		mcp.WithString("before", mcp.Description("updated before ISO 8601")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
+	)
+
+	NotificationWriteTool = mcp.NewTool(
+		NotificationWriteToolName,
+		mcp.WithDescription("Mark a notification or all notifications as read."),
+		mcp.WithToolAnnotation(annotation.Write("Manage notifications")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("mark_read", "mark_all_read")),
+		mcp.WithNumber("id", mcp.Description("thread ID (for 'mark_read')")),
+		mcp.WithString("owner", mcp.Description("scope 'mark_all_read' to a repo")),
+		mcp.WithString("repo", mcp.Description("scope 'mark_all_read' to a repo")),
+		mcp.WithString("last_read_at", mcp.Description("ISO 8601; defaults to now")),
+	)
+)
+
+func init() {
+	Tool.RegisterRead(server.ServerTool{
+		Tool:    NotificationReadTool,
+		Handler: notificationReadFn,
+	})
+	Tool.RegisterWrite(server.ServerTool{
+		Tool:    NotificationWriteTool,
+		Handler: notificationWriteFn,
+	})
+}
+
+func notificationReadFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := req.GetArguments()
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "list":
+		return listNotificationsFn(ctx, req)
+	case "get":
+		return getNotificationFn(ctx, req)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func notificationWriteFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := req.GetArguments()
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "mark_read":
+		return markNotificationReadFn(ctx, req)
+	case "mark_all_read":
+		return markAllNotificationsReadFn(ctx, req)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func listNotificationsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called listNotificationsFn")
+	args := req.GetArguments()
+	page, pageSize := params.GetPagination(args, 30)
+	opt := gitea_sdk.ListNotificationOptions{
+		ListOptions: gitea_sdk.ListOptions{
+			Page:     page,
+			PageSize: pageSize,
+		},
+	}
+	if status, ok := args["status"].(string); ok {
+		opt.Status = []gitea_sdk.NotifyStatus{gitea_sdk.NotifyStatus(status)}
+	}
+	if subjectType, ok := args["subject_type"].(string); ok {
+		opt.SubjectTypes = []gitea_sdk.NotifySubjectType{gitea_sdk.NotifySubjectType(subjectType)}
+	}
+	if t := params.GetOptionalTime(args, "since"); t != nil {
+		opt.Since = *t
+	}
+	if t := params.GetOptionalTime(args, "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))
+	}
+
+	owner := params.GetOptionalString(args, "owner", "")
+	repo := params.GetOptionalString(args, "repo", "")
+	if owner != "" && repo != "" {
+		threads, _, err := client.ListRepoNotifications(owner, repo, opt)
+		if err != nil {
+			return to.ErrorResult(fmt.Errorf("list %v/%v/notifications err: %v", owner, repo, err))
+		}
+		return to.TextResult(slimThreads(threads))
+	}
+
+	threads, _, err := client.ListNotifications(opt)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list notifications err: %v", err))
+	}
+	return to.TextResult(slimThreads(threads))
+}
+
+func getNotificationFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called getNotificationFn")
+	id, err := params.GetIndex(req.GetArguments(), "id")
+	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))
+	}
+	thread, _, err := client.GetNotification(id)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get notification/%v err: %v", id, err))
+	}
+	return to.TextResult(slimThread(thread))
+}
+
+func markNotificationReadFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called markNotificationReadFn")
+	id, err := params.GetIndex(req.GetArguments(), "id")
+	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))
+	}
+	thread, _, err := client.ReadNotification(id)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("mark notification/%v read err: %v", id, err))
+	}
+	if thread != nil {
+		return to.TextResult(slimThread(thread))
+	}
+	return to.TextResult("Notification marked as read")
+}
+
+func markAllNotificationsReadFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called markAllNotificationsReadFn")
+	args := req.GetArguments()
+	lastReadAt := time.Now()
+	if t := params.GetOptionalTime(args, "last_read_at"); t != nil {
+		lastReadAt = *t
+	}
+	opt := gitea_sdk.MarkNotificationOptions{
+		LastReadAt: lastReadAt,
+	}
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+
+	owner := params.GetOptionalString(args, "owner", "")
+	repo := params.GetOptionalString(args, "repo", "")
+	if owner != "" && repo != "" {
+		threads, _, err := client.ReadRepoNotifications(owner, repo, opt)
+		if err != nil {
+			return to.ErrorResult(fmt.Errorf("mark %v/%v/notifications read err: %v", owner, repo, err))
+		}
+		if threads != nil {
+			return to.TextResult(slimThreads(threads))
+		}
+		return to.TextResult("All repository notifications marked as read")
+	}
+
+	threads, _, err := client.ReadNotifications(opt)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("mark all notifications read err: %v", err))
+	}
+	if threads != nil {
+		return to.TextResult(slimThreads(threads))
+	}
+	return to.TextResult("All notifications marked as read")
+}

operation/notification/slim.go

@@ -0,0 +1,66 @@
+package notification
+
+import (
+	gitea_sdk "code.gitea.io/sdk/gitea"
+)
+
+func slimThread(t *gitea_sdk.NotificationThread) map[string]any {
+	if t == nil {
+		return nil
+	}
+	m := map[string]any{
+		"id":         t.ID,
+		"unread":     t.Unread,
+		"updated_at": t.UpdatedAt,
+	}
+	if t.Pinned {
+		m["pinned"] = true
+	}
+	if t.Repository != nil {
+		m["repository"] = t.Repository.FullName
+	}
+	if t.Subject != nil {
+		subject := map[string]any{
+			"title": t.Subject.Title,
+			"type":  t.Subject.Type,
+			"state": t.Subject.State,
+		}
+		if t.Subject.HTMLURL != "" {
+			subject["html_url"] = t.Subject.HTMLURL
+		}
+		if t.Subject.LatestCommentHTMLURL != "" {
+			subject["latest_comment_html_url"] = t.Subject.LatestCommentHTMLURL
+		}
+		m["subject"] = subject
+	}
+	return m
+}
+
+func slimThreads(threads []*gitea_sdk.NotificationThread) []map[string]any {
+	out := make([]map[string]any, 0, len(threads))
+	for _, t := range threads {
+		if t == nil {
+			continue
+		}
+		m := map[string]any{
+			"id":         t.ID,
+			"unread":     t.Unread,
+			"updated_at": t.UpdatedAt,
+		}
+		if t.Pinned {
+			m["pinned"] = true
+		}
+		if t.Repository != nil {
+			m["repository"] = t.Repository.FullName
+		}
+		if t.Subject != nil {
+			m["subject"] = map[string]any{
+				"title": t.Subject.Title,
+				"type":  t.Subject.Type,
+				"state": t.Subject.State,
+			}
+		}
+		out = append(out, m)
+	}
+	return out
+}

operation/operation.go

@@ -15,6 +15,8 @@ import (
 	"gitea.com/gitea/gitea-mcp/operation/issue"
 	"gitea.com/gitea/gitea-mcp/operation/label"
 	"gitea.com/gitea/gitea-mcp/operation/milestone"
+	"gitea.com/gitea/gitea-mcp/operation/notification"
+	"gitea.com/gitea/gitea-mcp/operation/packages"
 	"gitea.com/gitea/gitea-mcp/operation/pull"
 	"gitea.com/gitea/gitea-mcp/operation/repo"
 	"gitea.com/gitea/gitea-mcp/operation/search"
@@ -25,47 +27,27 @@ import (
 	mcpContext "gitea.com/gitea/gitea-mcp/pkg/context"
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
+	"gitea.com/gitea/gitea-mcp/pkg/tool"
 
 	"github.com/mark3labs/mcp-go/server"
 )
 
-var mcpServer *server.MCPServer
+var (
+	mcpServer *server.MCPServer
+
+	domainTools = []*tool.Tool{
+		user.Tool, actions.Tool, repo.Tool, notification.Tool, issue.Tool,
+		label.Tool, milestone.Tool, packages.Tool, pull.Tool, search.Tool,
+		version.Tool, wiki.Tool, timetracking.Tool,
+	}
+)
 
 func RegisterTool(s *server.MCPServer) {
-	// User Tool
-	s.AddTools(user.Tool.Tools()...)
-
-	// Actions Tool
-	s.AddTools(actions.Tool.Tools()...)
-
-	// Repo Tool
-	s.AddTools(repo.Tool.Tools()...)
-
-	// Issue Tool
-	s.AddTools(issue.Tool.Tools()...)
-
-	// Label Tool
-	s.AddTools(label.Tool.Tools()...)
-
-	// Milestone Tool
-	s.AddTools(milestone.Tool.Tools()...)
-
-	// Pull Tool
-	s.AddTools(pull.Tool.Tools()...)
-
-	// Search Tool
-	s.AddTools(search.Tool.Tools()...)
-
-	// Version Tool
-	s.AddTools(version.Tool.Tools()...)
-
-	// Wiki Tool
-	s.AddTools(wiki.Tool.Tools()...)
-
-	// Time Tracking Tool
-	s.AddTools(timetracking.Tool.Tools()...)
-
+	for _, t := range domainTools {
+		s.AddTools(t.Tools()...)
+	}
 	s.DeleteTools("")
+	tool.WarnUnmatchedAllowedTools(domainTools...)
 }
 
 // parseAuthToken extracts the token from an Authorization header.

operation/packages/packages.go

@@ -0,0 +1,225 @@
+package packages
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
+	"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.com/gitea/gitea-mcp/pkg/tool"
+
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+var Tool = tool.New()
+
+const (
+	PackageReadToolName  = "package_read"
+	PackageWriteToolName = "package_write"
+)
+
+var (
+	PackageReadTool = mcp.NewTool(
+		PackageReadToolName,
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read package registry")),
+		mcp.WithDescription("Read package registry: list packages (one entry per version, filter via 'q'/'type'), list versions, or get a version."),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("list", "list_versions", "get")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description("user or org")),
+		mcp.WithString("type", mcp.Description("container/npm/maven/pypi/cargo/generic; required except 'list'")),
+		mcp.WithString("name", mcp.Description("slashes auto-encoded; required except 'list'")),
+		mcp.WithString("version", mcp.Description("for 'get'")),
+		mcp.WithString("q", mcp.Description("search query")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30), mcp.Min(1)),
+	)
+
+	PackageWriteTool = mcp.NewTool(
+		PackageWriteToolName,
+		mcp.WithToolAnnotation(annotation.Destructive("Delete a package version")),
+		mcp.WithDescription("Delete a package version (irreversible)."),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("delete")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description("user or org")),
+		mcp.WithString("type", mcp.Required(), mcp.Description("container/npm/maven/pypi/cargo/generic")),
+		mcp.WithString("name", mcp.Required(), mcp.Description("slashes auto-encoded")),
+		mcp.WithString("version", mcp.Required()),
+	)
+)
+
+func init() {
+	Tool.RegisterRead(server.ServerTool{
+		Tool:    PackageReadTool,
+		Handler: packageReadFn,
+	})
+	Tool.RegisterWrite(server.ServerTool{
+		Tool:    PackageWriteTool,
+		Handler: packageWriteFn,
+	})
+}
+
+func packageReadFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := req.GetArguments()
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "list":
+		return listPackagesFn(ctx, req)
+	case "list_versions":
+		return listPackageVersionsFn(ctx, req)
+	case "get":
+		return getPackageFn(ctx, req)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func packageWriteFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := req.GetArguments()
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "delete":
+		return deletePackageVersionFn(ctx, req)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+// escapePackageName normalises a package name for use in URL paths. It
+// accepts both raw names (my-repo/my-image) and pre-encoded names
+// (my-repo%2Fmy-image), decoding first to avoid double-encoding. A literal
+// '%' followed by two hex digits in a raw name will be folded into its
+// decoded form, but package names typically do not contain '%'.
+func escapePackageName(name string) string {
+	if strings.Contains(name, "%") {
+		if decoded, err := url.PathUnescape(name); err == nil {
+			name = decoded
+		}
+	}
+	return url.PathEscape(name)
+}
+
+func listPackagesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called listPackagesFn")
+	args := req.GetArguments()
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	query := url.Values{}
+	if typ, ok := args["type"].(string); ok && typ != "" {
+		query.Set("type", typ)
+	}
+	if q, ok := args["q"].(string); ok && q != "" {
+		query.Set("q", q)
+	}
+	page, pageSize := params.GetPagination(args, 30)
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
+
+	var result any
+	_, err = gitea.DoJSON(ctx, "GET", "packages/"+url.PathEscape(owner), query, nil, &result)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list packages err: %v", err))
+	}
+
+	return to.TextResult(slimPackages(result))
+}
+
+func listPackageVersionsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called listPackageVersionsFn")
+	args := req.GetArguments()
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	typ, err := params.GetString(args, "type")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	query := url.Values{}
+	page, pageSize := params.GetPagination(args, 30)
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
+
+	var result any
+	_, err = gitea.DoJSON(ctx, "GET", fmt.Sprintf("packages/%s/%s/%s", url.PathEscape(owner), url.PathEscape(typ), escapePackageName(name)), query, nil, &result)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list package versions err: %v", err))
+	}
+
+	return to.TextResult(slimPackages(result))
+}
+
+func getPackageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called getPackageFn")
+	args := req.GetArguments()
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	typ, err := params.GetString(args, "type")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	version, err := params.GetString(args, "version")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	var result any
+	_, err = gitea.DoJSON(ctx, "GET", fmt.Sprintf("packages/%s/%s/%s/%s", url.PathEscape(owner), url.PathEscape(typ), escapePackageName(name), url.PathEscape(version)), nil, nil, &result)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get package err: %v", err))
+	}
+
+	return to.TextResult(slimPackage(result))
+}
+
+func deletePackageVersionFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called deletePackageVersionFn")
+	args := req.GetArguments()
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	typ, err := params.GetString(args, "type")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	version, err := params.GetString(args, "version")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	_, err = gitea.DoJSON(ctx, "DELETE", fmt.Sprintf("packages/%s/%s/%s/%s", url.PathEscape(owner), url.PathEscape(typ), escapePackageName(name), url.PathEscape(version)), nil, nil, nil)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("delete package version err: %v", err))
+	}
+
+	return to.TextResult("Package version deleted successfully")
+}

operation/packages/packages_test.go

@@ -0,0 +1,381 @@
+package packages
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+
+	mcpContext "gitea.com/gitea/gitea-mcp/pkg/context"
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+func TestPackageReadList(t *testing.T) {
+	var mu sync.Mutex
+	var gotQuery map[string]string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		gotQuery = map[string]string{}
+		for k, v := range r.URL.Query() {
+			gotQuery[k] = v[0]
+		}
+		mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":1,"type":"container","name":"myrepo/myimage","version":"v1.0.0","html_url":"http://example.com","created_at":"2025-01-01T00:00:00Z","owner":{"login":"test-org"},"creator":{"login":"admin"}}]`))
+	}))
+	defer srv.Close()
+
+	origHost := flag.Host
+	flag.Host = srv.URL
+	defer func() { flag.Host = origHost }()
+
+	ctx := context.WithValue(context.Background(), mcpContext.TokenContextKey, "test-token")
+
+	t.Run("basic list", func(t *testing.T) {
+		req := mcp.CallToolRequest{}
+		req.Params.Arguments = map[string]any{
+			"method": "list",
+			"owner":  "test-org",
+		}
+
+		result, err := packageReadFn(ctx, req)
+		if err != nil {
+			t.Fatalf("packageReadFn() error: %v", err)
+		}
+		if result.IsError {
+			t.Fatal("packageReadFn() returned error result")
+		}
+
+		text := result.Content[0].(mcp.TextContent).Text
+		var packages []map[string]any
+		if err := json.Unmarshal([]byte(text), &packages); err != nil {
+			t.Fatalf("failed to unmarshal result: %v", err)
+		}
+		if len(packages) != 1 {
+			t.Fatalf("expected 1 package, got %d", len(packages))
+		}
+		if packages[0]["name"] != "myrepo/myimage" {
+			t.Errorf("expected name 'myrepo/myimage', got %v", packages[0]["name"])
+		}
+		if packages[0]["owner"] != "test-org" {
+			t.Errorf("expected owner 'test-org', got %v", packages[0]["owner"])
+		}
+	})
+
+	t.Run("with type and query filters", func(t *testing.T) {
+		req := mcp.CallToolRequest{}
+		req.Params.Arguments = map[string]any{
+			"method": "list",
+			"owner":  "test-org",
+			"type":   "container",
+			"q":      "myimage",
+		}
+
+		_, err := packageReadFn(ctx, req)
+		if err != nil {
+			t.Fatalf("packageReadFn() error: %v", err)
+		}
+
+		mu.Lock()
+		defer mu.Unlock()
+		if gotQuery["type"] != "container" {
+			t.Errorf("expected type=container, got %q", gotQuery["type"])
+		}
+		if gotQuery["q"] != "myimage" {
+			t.Errorf("expected q=myimage, got %q", gotQuery["q"])
+		}
+	})
+
+	t.Run("with pagination", func(t *testing.T) {
+		req := mcp.CallToolRequest{}
+		req.Params.Arguments = map[string]any{
+			"method":   "list",
+			"owner":    "test-org",
+			"page":     float64(2),
+			"per_page": float64(10),
+		}
+
+		_, err := packageReadFn(ctx, req)
+		if err != nil {
+			t.Fatalf("packageReadFn() error: %v", err)
+		}
+
+		mu.Lock()
+		defer mu.Unlock()
+		if gotQuery["page"] != "2" {
+			t.Errorf("expected page=2, got %q", gotQuery["page"])
+		}
+		if gotQuery["limit"] != "10" {
+			t.Errorf("expected limit=10, got %q", gotQuery["limit"])
+		}
+	})
+}
+
+func TestPackageReadListVersions(t *testing.T) {
+	var mu sync.Mutex
+	var gotPath string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		gotPath = r.URL.RawPath
+		if gotPath == "" {
+			gotPath = r.URL.Path
+		}
+		mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":1,"type":"container","name":"myrepo/myimage","version":"v1.0.0"},{"id":2,"type":"container","name":"myrepo/myimage","version":"v2.0.0"}]`))
+	}))
+	defer srv.Close()
+
+	origHost := flag.Host
+	flag.Host = srv.URL
+	defer func() { flag.Host = origHost }()
+
+	ctx := context.WithValue(context.Background(), mcpContext.TokenContextKey, "test-token")
+
+	tests := []struct {
+		testName string
+		name     string
+	}{
+		{"raw slash", "myrepo/myimage"},
+		{"pre-encoded slash", "myrepo%2Fmyimage"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.testName, func(t *testing.T) {
+			req := mcp.CallToolRequest{}
+			req.Params.Arguments = map[string]any{
+				"method": "list_versions",
+				"owner":  "test-org",
+				"type":   "container",
+				"name":   tt.name,
+			}
+
+			result, err := packageReadFn(ctx, req)
+			if err != nil {
+				t.Fatalf("packageReadFn() error: %v", err)
+			}
+			if result.IsError {
+				t.Fatal("packageReadFn() returned error result")
+			}
+
+			mu.Lock()
+			wantPath := "/api/v1/packages/test-org/container/myrepo%2Fmyimage"
+			if gotPath != wantPath {
+				t.Errorf("request path = %q, want %q", gotPath, wantPath)
+			}
+			mu.Unlock()
+
+			text := result.Content[0].(mcp.TextContent).Text
+			var versions []map[string]any
+			if err := json.Unmarshal([]byte(text), &versions); err != nil {
+				t.Fatalf("failed to unmarshal result: %v", err)
+			}
+			if len(versions) != 2 {
+				t.Fatalf("expected 2 versions, got %d", len(versions))
+			}
+		})
+	}
+}
+
+func TestPackageReadGet(t *testing.T) {
+	var mu sync.Mutex
+	var gotPath string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		gotPath = r.URL.RawPath
+		if gotPath == "" {
+			gotPath = r.URL.Path
+		}
+		mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"id":1,"type":"container","name":"myrepo/myimage","version":"v1.0.0","html_url":"http://example.com","created_at":"2025-01-01T00:00:00Z","owner":{"login":"test-org"}}`))
+	}))
+	defer srv.Close()
+
+	origHost := flag.Host
+	flag.Host = srv.URL
+	defer func() { flag.Host = origHost }()
+
+	ctx := context.WithValue(context.Background(), mcpContext.TokenContextKey, "test-token")
+
+	tests := []struct {
+		testName string
+		name     string
+	}{
+		{"raw slash", "myrepo/myimage"},
+		{"pre-encoded slash", "myrepo%2Fmyimage"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.testName, func(t *testing.T) {
+			req := mcp.CallToolRequest{}
+			req.Params.Arguments = map[string]any{
+				"method":  "get",
+				"owner":   "test-org",
+				"type":    "container",
+				"name":    tt.name,
+				"version": "v1.0.0",
+			}
+
+			result, err := packageReadFn(ctx, req)
+			if err != nil {
+				t.Fatalf("packageReadFn() error: %v", err)
+			}
+			if result.IsError {
+				t.Fatal("packageReadFn() returned error result")
+			}
+
+			mu.Lock()
+			wantPath := "/api/v1/packages/test-org/container/myrepo%2Fmyimage/v1.0.0"
+			if gotPath != wantPath {
+				t.Errorf("request path = %q, want %q", gotPath, wantPath)
+			}
+			mu.Unlock()
+
+			text := result.Content[0].(mcp.TextContent).Text
+			var pkg map[string]any
+			if err := json.Unmarshal([]byte(text), &pkg); err != nil {
+				t.Fatalf("failed to unmarshal result: %v", err)
+			}
+			if pkg["name"] != "myrepo/myimage" {
+				t.Errorf("expected name 'myrepo/myimage', got %v", pkg["name"])
+			}
+			if pkg["version"] != "v1.0.0" {
+				t.Errorf("expected version 'v1.0.0', got %v", pkg["version"])
+			}
+		})
+	}
+}
+
+func TestPackageWriteDelete(t *testing.T) {
+	var mu sync.Mutex
+	var gotMethod string
+	var gotPath string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		gotMethod = r.Method
+		gotPath = r.URL.RawPath
+		if gotPath == "" {
+			gotPath = r.URL.Path
+		}
+		mu.Unlock()
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	origHost := flag.Host
+	flag.Host = srv.URL
+	defer func() { flag.Host = origHost }()
+
+	ctx := context.WithValue(context.Background(), mcpContext.TokenContextKey, "test-token")
+
+	req := mcp.CallToolRequest{}
+	req.Params.Arguments = map[string]any{
+		"method":  "delete",
+		"owner":   "test-org",
+		"type":    "container",
+		"name":    "myrepo/myimage",
+		"version": "v1.0.0",
+	}
+
+	result, err := packageWriteFn(ctx, req)
+	if err != nil {
+		t.Fatalf("packageWriteFn() error: %v", err)
+	}
+	if result.IsError {
+		t.Fatal("packageWriteFn() returned error result")
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	if gotMethod != "DELETE" {
+		t.Errorf("expected DELETE method, got %q", gotMethod)
+	}
+	wantPath := "/api/v1/packages/test-org/container/myrepo%2Fmyimage/v1.0.0"
+	if gotPath != wantPath {
+		t.Errorf("request path = %q, want %q", gotPath, wantPath)
+	}
+}
+
+func TestPackageReadUnknownMethod(t *testing.T) {
+	ctx := context.Background()
+	req := mcp.CallToolRequest{}
+	req.Params.Arguments = map[string]any{
+		"method": "bogus",
+		"owner":  "test-org",
+	}
+	if _, err := packageReadFn(ctx, req); err == nil {
+		t.Fatal("expected error for unknown method")
+	}
+}
+
+func TestPackageWriteUnknownMethod(t *testing.T) {
+	ctx := context.Background()
+	req := mcp.CallToolRequest{}
+	req.Params.Arguments = map[string]any{
+		"method": "bogus",
+		"owner":  "test-org",
+	}
+	if _, err := packageWriteFn(ctx, req); err == nil {
+		t.Fatal("expected error for unknown method")
+	}
+}
+
+func TestEscapePackageName(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{"simple name", "mypackage", "mypackage"},
+		{"raw slash", "myrepo/myimage", "myrepo%2Fmyimage"},
+		{"pre-encoded slash", "myrepo%2Fmyimage", "myrepo%2Fmyimage"},
+		{"pre-encoded uppercase", "myrepo%2Fmyimage", "myrepo%2Fmyimage"},
+		{"multiple slashes", "a/b/c", "a%2Fb%2Fc"},
+		{"pre-encoded multiple slashes", "a%2Fb%2Fc", "a%2Fb%2Fc"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := escapePackageName(tt.input)
+			if got != tt.expected {
+				t.Errorf("escapePackageName(%q) = %q, want %q", tt.input, got, tt.expected)
+			}
+		})
+	}
+}
+
+func TestSlimPackage(t *testing.T) {
+	raw := map[string]any{
+		"id":         float64(1),
+		"type":       "container",
+		"name":       "test-repo/test-image",
+		"version":    "v1.0.0",
+		"html_url":   "http://example.com/pkg",
+		"created_at": "2025-01-01T00:00:00Z",
+		"owner":      map[string]any{"login": "test-org", "id": float64(2), "email": ""},
+		"creator":    map[string]any{"login": "admin", "id": float64(1)},
+		"repository": map[string]any{"full_name": "test-org/test-repo", "id": float64(3)},
+	}
+
+	slim := slimPackage(raw)
+	if slim["owner"] != "test-org" {
+		t.Errorf("expected owner 'test-org', got %v", slim["owner"])
+	}
+	if slim["creator"] != "admin" {
+		t.Errorf("expected creator 'admin', got %v", slim["creator"])
+	}
+	if slim["repository"] != "test-org/test-repo" {
+		t.Errorf("expected repository 'test-org/test-repo', got %v", slim["repository"])
+	}
+	if _, ok := slim["owner"].(map[string]any); ok {
+		t.Error("expected owner to be a string, not a map")
+	}
+}

operation/packages/slim.go

@@ -0,0 +1,43 @@
+package packages
+
+func slimPackage(v any) map[string]any {
+	m, ok := v.(map[string]any)
+	if !ok {
+		return nil
+	}
+	out := map[string]any{
+		"id":         m["id"],
+		"type":       m["type"],
+		"name":       m["name"],
+		"version":    m["version"],
+		"html_url":   m["html_url"],
+		"created_at": m["created_at"],
+	}
+	if owner, ok := m["owner"].(map[string]any); ok {
+		out["owner"] = owner["login"]
+	}
+	if creator, ok := m["creator"].(map[string]any); ok {
+		out["creator"] = creator["login"]
+	}
+	if repo, ok := m["repository"].(map[string]any); ok {
+		out["repository"] = repo["full_name"]
+	}
+	return out
+}
+
+func slimPackages(v any) any {
+	switch val := v.(type) {
+	case []any:
+		out := make([]map[string]any, 0, len(val))
+		for _, item := range val {
+			if slim := slimPackage(item); slim != nil {
+				out = append(out, slim)
+			}
+		}
+		return out
+	case map[string]any:
+		return slimPackage(val)
+	default:
+		return v
+	}
+}

operation/pull/pull.go

@@ -3,7 +3,10 @@ package pull
 import (
 	"context"
 	"fmt"
+	"net/url"
+	"strings"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -27,71 +30,81 @@ const (
 var (
 	ListRepoPullRequestsTool = mcp.NewTool(
 		ListRepoPullRequestsToolName,
-		mcp.WithDescription("List repository pull requests"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("state", mcp.Description("state"), mcp.Enum("open", "closed", "all"), mcp.DefaultString("all")),
-		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.WithToolAnnotation(annotation.ReadOnly("List pull requests")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("state", mcp.Enum("open", "closed", "all"), mcp.DefaultString("all")),
+		mcp.WithString("sort", mcp.Enum("oldest", "recentupdate", "leastupdate", "mostcomment", "leastcomment", "priority"), mcp.DefaultString("recentupdate")),
+		mcp.WithNumber("milestone"),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 
 	PullRequestReadTool = mcp.NewTool(
 		PullRequestReadToolName,
-		mcp.WithDescription("Get pull request information. Use method 'get' for PR details, 'get_diff' for diff, 'get_reviews'/'get_review'/'get_review_comments' for review data."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("get", "get_diff", "get_reviews", "get_review", "get_review_comments")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("index", mcp.Required(), mcp.Description("pull request index")),
-		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.WithDescription("Read pull request: details, diff, changed files, head commit status, reviews."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read pull request details")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("get", "get_diff", "get_files", "get_status", "get_reviews", "get_review", "get_review_comments")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("pull_number", mcp.Required()),
+		mcp.WithNumber("review_id", mcp.Description("for 'get_review'/'get_review_comments'")),
+		mcp.WithBoolean("binary", mcp.Description("include binary diff")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 
 	PullRequestWriteTool = mcp.NewTool(
 		PullRequestWriteToolName,
-		mcp.WithDescription("Create, update, or merge pull requests, manage reviewers."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("create", "update", "merge", "add_reviewers", "remove_reviewers")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("index", mcp.Description("pull request index (required for all methods except 'create')")),
-		mcp.WithString("title", mcp.Description("PR title (required for 'create', optional for 'update', 'merge')")),
-		mcp.WithString("body", mcp.Description("PR body (required for 'create', optional for 'update')")),
-		mcp.WithString("head", mcp.Description("PR head branch (required for 'create')")),
-		mcp.WithString("base", mcp.Description("PR base branch (required for 'create', optional for 'update')")),
-		mcp.WithString("assignee", mcp.Description("username to assign (for 'update')")),
-		mcp.WithArray("assignees", mcp.Description("usernames to assign (for 'update')"), mcp.Items(map[string]any{"type": "string"})),
-		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.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.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.WithDescription("Write pull requests: create, update, close, reopen, merge, update branch from base, manage reviewers."),
+		mcp.WithToolAnnotation(annotation.Write("Create, update, close, reopen, or merge pull requests")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("create", "update", "close", "reopen", "merge", "update_branch", "add_reviewers", "remove_reviewers")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("pull_number", mcp.Description("required except for 'create'")),
+		mcp.WithString("title", mcp.Description("required for 'create'; optional for 'update'/'merge'")),
+		mcp.WithString("body", mcp.Description("required for 'create'; optional for 'update'")),
+		mcp.WithString("head", mcp.Description("head branch (required for 'create')")),
+		mcp.WithString("base", mcp.Description("base branch (required for 'create')")),
+		mcp.WithString("assignee", mcp.Description("for 'update'")),
+		mcp.WithArray("assignees", mcp.Description("for 'update'"), mcp.Items(map[string]any{"type": "string"})),
+		mcp.WithNumber("milestone", mcp.Description("for 'update'")),
+		mcp.WithString("state", mcp.Description("for 'update'"), mcp.Enum("open", "closed")),
+		mcp.WithBoolean("allow_maintainer_edit", mcp.Description("for 'update'")),
+		mcp.WithArray("labels", mcp.Description("label IDs"), mcp.Items(map[string]any{"type": "number"})),
+		mcp.WithString("deadline", mcp.Description("ISO 8601")),
+		mcp.WithBoolean("remove_deadline", mcp.Description("for 'update'")),
+		mcp.WithString("merge_style", mcp.Description("for 'merge'"), mcp.Enum("merge", "rebase", "rebase-merge", "squash", "fast-forward-only"), mcp.DefaultString("merge")),
+		mcp.WithString("message", mcp.Description("merge commit message or dismissal reason")),
+		mcp.WithBoolean("delete_branch", mcp.Description("for 'merge'")),
+		mcp.WithBoolean("force_merge", mcp.Description("merge even if checks fail")),
+		mcp.WithBoolean("merge_when_checks_succeed", mcp.Description("for 'merge'")),
+		mcp.WithString("head_commit_id", mcp.Description("expected head SHA for conflict detection")),
+		mcp.WithArray("reviewers", mcp.Description("for 'add_reviewers'/'remove_reviewers'"), mcp.Items(map[string]any{"type": "string"})),
+		mcp.WithArray("team_reviewers", mcp.Description("for 'add_reviewers'/'remove_reviewers'"), mcp.Items(map[string]any{"type": "string"})),
+		mcp.WithBoolean("draft", mcp.Description("uses 'WIP: ' title prefix")),
 	)
 
 	PullRequestReviewWriteTool = mcp.NewTool(
 		PullRequestReviewWriteToolName,
-		mcp.WithDescription("Manage pull request reviews: create, submit, delete, or dismiss."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("create", "submit", "delete", "dismiss")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("index", mcp.Required(), mcp.Description("pull request index")),
-		mcp.WithNumber("review_id", mcp.Description("review ID (required for 'submit', 'delete', 'dismiss')")),
-		mcp.WithString("state", mcp.Description("review state"), mcp.Enum("APPROVED", "REQUEST_CHANGES", "COMMENT", "PENDING")),
-		mcp.WithString("body", mcp.Description("review body/comment")),
-		mcp.WithString("commit_id", mcp.Description("commit SHA to review (for 'create')")),
-		mcp.WithString("message", mcp.Description("dismissal reason (for 'dismiss')")),
-		mcp.WithArray("comments", mcp.Description("inline review comments (for 'create')"), mcp.Items(map[string]any{
+		mcp.WithDescription("Write PR reviews: create, submit, delete, dismiss."),
+		mcp.WithToolAnnotation(annotation.Write("Submit a pull request review")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("create", "submit", "delete", "dismiss")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("pull_number", mcp.Required()),
+		mcp.WithNumber("review_id", mcp.Description("required except for 'create'")),
+		mcp.WithString("state", mcp.Enum("APPROVED", "REQUEST_CHANGES", "COMMENT", "PENDING")),
+		mcp.WithString("body"),
+		mcp.WithString("commit_id", mcp.Description("for 'create'")),
+		mcp.WithString("message", mcp.Description("dismissal reason")),
+		mcp.WithArray("comments", mcp.Description("inline comments (for 'create')"), mcp.Items(map[string]any{
 			"type": "object",
 			"properties": map[string]any{
-				"path":         map[string]any{"type": "string", "description": "file path to comment on"},
-				"body":         map[string]any{"type": "string", "description": "comment body"},
-				"old_line_num": map[string]any{"type": "number", "description": "line number in the old file (for deletions/changes)"},
-				"new_line_num": map[string]any{"type": "number", "description": "line number in the new file (for additions/changes)"},
+				"path":         map[string]any{"type": "string"},
+				"body":         map[string]any{"type": "string"},
+				"old_line_num": map[string]any{"type": "number", "description": "old-file line (deletions)"},
+				"new_line_num": map[string]any{"type": "number", "description": "new-file line (additions)"},
 			},
 		})),
 	)
@@ -126,6 +139,10 @@ func pullRequestReadFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 		return getPullRequestByIndexFn(ctx, req)
 	case "get_diff":
 		return getPullRequestDiffFn(ctx, req)
+	case "get_files":
+		return getPullRequestFilesFn(ctx, req)
+	case "get_status":
+		return getPullRequestStatusFn(ctx, req)
 	case "get_reviews":
 		return listPullRequestReviewsFn(ctx, req)
 	case "get_review":
@@ -147,8 +164,14 @@ func pullRequestWriteFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 		return createPullRequestFn(ctx, req)
 	case "update":
 		return editPullRequestFn(ctx, req)
+	case "close":
+		return closePullRequestFn(ctx, req)
+	case "reopen":
+		return reopenPullRequestFn(ctx, req)
 	case "merge":
 		return mergePullRequestFn(ctx, req)
+	case "update_branch":
+		return updatePullRequestBranchFn(ctx, req)
 	case "add_reviewers":
 		return createPullRequestReviewerFn(ctx, req)
 	case "remove_reviewers":
@@ -158,6 +181,66 @@ func pullRequestWriteFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 	}
 }
 
+func closePullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(req.GetArguments(), "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(req.GetArguments(), "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(req.GetArguments(), "pull_number")
+	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))
+	}
+
+	state := gitea_sdk.StateClosed
+	pr, _, err := client.EditPullRequest(owner, repo, index, gitea_sdk.EditPullRequestOption{
+		State: &state,
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("close %v/%v/pr/%v err: %v", owner, repo, index, err))
+	}
+
+	return to.TextResult(slimPullRequest(pr))
+}
+
+func reopenPullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(req.GetArguments(), "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(req.GetArguments(), "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(req.GetArguments(), "pull_number")
+	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))
+	}
+
+	state := gitea_sdk.StateOpen
+	pr, _, err := client.EditPullRequest(owner, repo, index, gitea_sdk.EditPullRequestOption{
+		State: &state,
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("reopen %v/%v/pr/%v err: %v", owner, repo, index, err))
+	}
+
+	return to.TextResult(slimPullRequest(pr))
+}
+
 func pullRequestReviewWriteFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	method, err := params.GetString(req.GetArguments(), "method")
 	if err != nil {
@@ -188,7 +271,7 @@ func getPullRequestByIndexFn(ctx context.Context, req mcp.CallToolRequest) (*mcp
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -201,7 +284,17 @@ func getPullRequestByIndexFn(ctx context.Context, req mcp.CallToolRequest) (*mcp
 		return to.ErrorResult(fmt.Errorf("get %v/%v/pr/%v err: %v", owner, repo, index, err))
 	}
 
-	return to.TextResult(slimPullRequest(pr))
+	// /pulls/{n} omits `assets`; PRs are issues internally, so the issue
+	// assets endpoint surfaces description attachments.
+	var assets []*gitea_sdk.Attachment
+	assetsPath := fmt.Sprintf("repos/%s/%s/issues/%d/assets", url.PathEscape(owner), url.PathEscape(repo), index)
+	if _, err := gitea.DoJSON(ctx, "GET", assetsPath, nil, nil, &assets); err != nil {
+		log.Debugf("fetch %v/%v/issues/%v/assets err: %v", owner, repo, index, err)
+	}
+
+	m := slimPullRequest(pr)
+	m["body"] = bodyWithAttachments(pr.Body, assets)
+	return to.TextResult(m)
 }
 
 func getPullRequestDiffFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
@@ -215,7 +308,7 @@ func getPullRequestDiffFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Ca
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -271,6 +364,28 @@ func listRepoPullRequestsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.
 	return to.TextResult(slimPullRequests(pullRequests))
 }
 
+// defaultWIPPrefixes are the default Gitea title prefixes that mark a PR as
+// work-in-progress / draft. Gitea matches these case-insensitively.
+var defaultWIPPrefixes = []string{"WIP:", "[WIP]"}
+
+// applyDraftPrefix adds or removes a WIP title prefix that Gitea uses to mark
+// pull requests as drafts. When the title already carries a recognized prefix
+// and isDraft is true, the title is returned unchanged to avoid normalization.
+func applyDraftPrefix(title string, isDraft bool) string {
+	for _, prefix := range defaultWIPPrefixes {
+		if len(title) >= len(prefix) && strings.EqualFold(title[:len(prefix)], prefix) {
+			if isDraft {
+				return title
+			}
+			return strings.TrimLeft(title[len(prefix):], " ")
+		}
+	}
+	if isDraft {
+		return "WIP: " + title
+	}
+	return title
+}
+
 func createPullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	log.Debugf("Called createPullRequestFn")
 	args := req.GetArguments()
@@ -298,16 +413,26 @@ func createPullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Cal
 	if err != nil {
 		return to.ErrorResult(err)
 	}
+
+	if draft, ok := args["draft"].(bool); ok {
+		title = applyDraftPrefix(title, draft)
+	}
+
 	client, err := gitea.ClientFromContext(ctx)
 	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))
 	}
@@ -326,7 +451,7 @@ func createPullRequestReviewerFn(ctx context.Context, req mcp.CallToolRequest) (
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -369,7 +494,7 @@ func deletePullRequestReviewerFn(ctx context.Context, req mcp.CallToolRequest) (
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -412,7 +537,7 @@ func listPullRequestReviewsFn(ctx context.Context, req mcp.CallToolRequest) (*mc
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -447,7 +572,7 @@ func getPullRequestReviewFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -480,7 +605,7 @@ func listPullRequestReviewCommentsFn(ctx context.Context, req mcp.CallToolReques
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -513,7 +638,7 @@ func createPullRequestReviewFn(ctx context.Context, req mcp.CallToolRequest) (*m
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -578,7 +703,7 @@ func submitPullRequestReviewFn(ctx context.Context, req mcp.CallToolRequest) (*m
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -622,7 +747,7 @@ func deletePullRequestReviewFn(ctx context.Context, req mcp.CallToolRequest) (*m
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -662,7 +787,7 @@ func dismissPullRequestReviewFn(ctx context.Context, req mcp.CallToolRequest) (*
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -707,7 +832,7 @@ func mergePullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -722,11 +847,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)
@@ -764,7 +896,7 @@ func editPullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(args, "index")
+	index, err := params.GetIndex(args, "pull_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -774,6 +906,22 @@ func editPullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	if title, ok := args["title"].(string); ok {
 		opt.Title = title
 	}
+	if draft, ok := args["draft"].(bool); ok {
+		if opt.Title == "" {
+			// Fetch current title so the caller doesn't have to provide it
+			// just to toggle draft status.
+			client, err := gitea.ClientFromContext(ctx)
+			if err != nil {
+				return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+			}
+			pr, _, err := client.GetPullRequest(owner, repo, index)
+			if err != nil {
+				return to.ErrorResult(fmt.Errorf("get %v/%v/pr/%v err: %v", owner, repo, index, err))
+			}
+			opt.Title = pr.Title
+		}
+		opt.Title = applyDraftPrefix(opt.Title, draft)
+	}
 	if body, ok := args["body"].(string); ok {
 		opt.Body = new(body)
 	}
@@ -797,6 +945,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 {
@@ -810,3 +965,89 @@ func editPullRequestFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 
 	return to.TextResult(slimPullRequest(pr))
 }
+
+func updatePullRequestBranchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called updatePullRequestBranchFn")
+	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)
+	}
+	index, err := params.GetIndex(args, "pull_number")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	path := fmt.Sprintf("repos/%s/%s/pulls/%d/update", url.PathEscape(owner), url.PathEscape(repo), index)
+	if _, err := gitea.DoJSON(ctx, "POST", path, nil, nil, nil); err != nil {
+		return to.ErrorResult(fmt.Errorf("update %v/%v/pr/%v branch err: %v", owner, repo, index, err))
+	}
+	return to.TextResult(map[string]any{"message": "branch updated from base"})
+}
+
+func getPullRequestFilesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called getPullRequestFilesFn")
+	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)
+	}
+	index, err := params.GetIndex(args, "pull_number")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	page, pageSize := params.GetPagination(args, 30)
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	files, _, err := client.ListPullRequestFiles(owner, repo, index, gitea_sdk.ListPullRequestFilesOptions{
+		ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get %v/%v/pr/%v files err: %v", owner, repo, index, err))
+	}
+	return to.TextResult(files)
+}
+
+func getPullRequestStatusFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	log.Debugf("Called getPullRequestStatusFn")
+	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)
+	}
+	index, err := params.GetIndex(args, "pull_number")
+	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))
+	}
+	pr, _, err := client.GetPullRequest(owner, repo, index)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get %v/%v/pr/%v err: %v", owner, repo, index, err))
+	}
+	if pr.Head == nil || pr.Head.Sha == "" {
+		return to.ErrorResult(fmt.Errorf("pr %v/%v/%v has no head SHA", owner, repo, index))
+	}
+
+	status, _, err := client.GetCombinedStatus(owner, repo, pr.Head.Sha)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get %v/%v/pr/%v status err: %v", owner, repo, index, err))
+	}
+	return to.TextResult(status)
+}

operation/pull/pull_test.go

@@ -6,10 +6,12 @@ import (
 	"fmt"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"sync"
 	"testing"
 
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
 	"github.com/mark3labs/mcp-go/mcp"
 )
 
@@ -78,11 +80,11 @@ func Test_editPullRequestFn(t *testing.T) {
 			req := mcp.CallToolRequest{
 				Params: mcp.CallToolParams{
 					Arguments: map[string]any{
-						"owner": owner,
-						"repo":  repo,
-						"index": ii.val,
-						"title": "WIP: my feature",
-						"state": "open",
+						"owner":       owner,
+						"repo":        repo,
+						"pull_number": ii.val,
+						"title":       "WIP: my feature",
+						"state":       "open",
 					},
 				},
 			}
@@ -193,7 +195,7 @@ func Test_mergePullRequestFn(t *testing.T) {
 					Arguments: map[string]any{
 						"owner":         owner,
 						"repo":          repo,
-						"index":         ii.val,
+						"pull_number":   ii.val,
 						"merge_style":   "squash",
 						"title":         "feat: my squashed commit",
 						"message":       "Squash merge of PR #5",
@@ -254,6 +256,398 @@ 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,
+				"pull_number":               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
+		title   string
+		isDraft bool
+		want    string
+	}{
+		{"add prefix", "my feature", true, "WIP: my feature"},
+		{"already prefixed WIP:", "WIP: my feature", true, "WIP: my feature"},
+		{"already prefixed WIP: no space", "WIP:my feature", true, "WIP:my feature"},
+		{"already prefixed [WIP]", "[WIP] my feature", true, "[WIP] my feature"},
+		{"already prefixed case insensitive", "wip: my feature", true, "wip: my feature"},
+		{"already prefixed [wip]", "[wip] my feature", true, "[wip] my feature"},
+		{"remove WIP: prefix", "WIP: my feature", false, "my feature"},
+		{"remove WIP: no space", "WIP:my feature", false, "my feature"},
+		{"remove [WIP] prefix", "[WIP] my feature", false, "my feature"},
+		{"remove [wip] prefix", "[wip] my feature", false, "my feature"},
+		{"remove wip: lowercase", "wip: my feature", false, "my feature"},
+		{"no prefix not draft", "my feature", false, "my feature"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := applyDraftPrefix(tt.title, tt.isDraft)
+			if got != tt.want {
+				t.Fatalf("applyDraftPrefix(%q, %v) = %q, want %q", tt.title, tt.isDraft, got, tt.want)
+			}
+		})
+	}
+}
+
+func Test_createPullRequestFn_draft(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+	)
+
+	tests := []struct {
+		name      string
+		title     string
+		draft     any // bool or nil (omitted)
+		wantTitle string
+	}{
+		{"draft true", "my feature", true, "WIP: my feature"},
+		{"draft false strips WIP:", "WIP: my feature", false, "my feature"},
+		{"draft false strips [WIP]", "[WIP] my feature", false, "my feature"},
+		{"draft omitted preserves title", "WIP: my feature", nil, "WIP: my feature"},
+		{"draft true already prefixed", "WIP: my feature", true, "WIP: my feature"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			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(fmt.Appendf(nil, `{"number":1,"title":%q,"state":"open"}`, body["title"]))
+				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
+			}()
+
+			args := map[string]any{
+				"owner": owner,
+				"repo":  repo,
+				"title": tc.title,
+				"body":  "test body",
+				"head":  "feature",
+				"base":  "main",
+			}
+			if tc.draft != nil {
+				args["draft"] = tc.draft
+			}
+
+			req := mcp.CallToolRequest{
+				Params: mcp.CallToolParams{
+					Arguments: args,
+				},
+			}
+
+			_, err := createPullRequestFn(context.Background(), req)
+			if err != nil {
+				t.Fatalf("createPullRequestFn() error = %v", err)
+			}
+
+			mu.Lock()
+			defer mu.Unlock()
+
+			if gotBody["title"] != tc.wantTitle {
+				t.Fatalf("expected title %q, got %v", tc.wantTitle, gotBody["title"])
+			}
+		})
+	}
+}
+
+func Test_editPullRequestFn_draft(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+		index = 7
+	)
+
+	tests := []struct {
+		name      string
+		title     string // title arg passed to the tool; empty means omitted
+		draft     any
+		wantTitle string
+	}{
+		{"set draft with title", "my feature", true, "WIP: my feature"},
+		{"unset draft with title", "WIP: my feature", false, "my feature"},
+		{"set draft without title fetches current", "", true, "WIP: existing title"},
+		{"unset draft without title fetches current", "", false, "existing title"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			var (
+				mu      sync.Mutex
+				gotBody map[string]any
+			)
+
+			prPath := fmt.Sprintf("/api/v1/repos/%s/%s/pulls/%d", owner, repo, index)
+			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 prPath:
+					w.Header().Set("Content-Type", "application/json")
+					if r.Method == http.MethodGet {
+						// Auto-fetch: return the existing PR with its current title
+						_, _ = w.Write(fmt.Appendf(nil, `{"number":%d,"title":"existing title","state":"open"}`, index))
+						return
+					}
+					mu.Lock()
+					var body map[string]any
+					_ = json.NewDecoder(r.Body).Decode(&body)
+					gotBody = body
+					mu.Unlock()
+					title := "existing title"
+					if s, ok := body["title"].(string); ok {
+						title = s
+					}
+					_, _ = w.Write(fmt.Appendf(nil, `{"number":%d,"title":%q,"state":"open"}`, index, title))
+				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
+			}()
+
+			args := map[string]any{
+				"owner":       owner,
+				"repo":        repo,
+				"pull_number": float64(index),
+			}
+			if tc.title != "" {
+				args["title"] = tc.title
+			}
+			if tc.draft != nil {
+				args["draft"] = tc.draft
+			}
+
+			req := mcp.CallToolRequest{
+				Params: mcp.CallToolParams{
+					Arguments: args,
+				},
+			}
+
+			_, err := editPullRequestFn(context.Background(), req)
+			if err != nil {
+				t.Fatalf("editPullRequestFn() error = %v", err)
+			}
+
+			mu.Lock()
+			defer mu.Unlock()
+
+			if gotBody["title"] != tc.wantTitle {
+				t.Fatalf("expected title %q, got %v", tc.wantTitle, gotBody["title"])
+			}
+		})
+	}
+}
+
 func Test_getPullRequestDiffFn(t *testing.T) {
 	const (
 		owner   = "octo"
@@ -326,10 +720,10 @@ func Test_getPullRequestDiffFn(t *testing.T) {
 			req := mcp.CallToolRequest{
 				Params: mcp.CallToolParams{
 					Arguments: map[string]any{
-						"owner":  owner,
-						"repo":   repo,
-						"index":  ii.val,
-						"binary": true,
+						"owner":       owner,
+						"repo":        repo,
+						"pull_number": ii.val,
+						"binary":      true,
 					},
 				},
 			}
@@ -377,3 +771,271 @@ func Test_getPullRequestDiffFn(t *testing.T) {
 		})
 	}
 }
+
+func Test_getPullRequestByIndexFn_includesAttachments(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+		index = 9
+	)
+
+	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", owner, repo, index):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"number":9,"title":"feat","body":"see screenshot","state":"open"}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s/issues/%d/assets", owner, repo, index):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`[{"id":1,"name":"shot.png","browser_download_url":"https://example/shot.png"}]`))
+		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 }()
+
+	req := mcp.CallToolRequest{Params: mcp.CallToolParams{Arguments: map[string]any{
+		"owner": owner, "repo": repo, "pull_number": float64(index),
+	}}}
+	res, err := getPullRequestByIndexFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("getPullRequestByIndexFn() 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, `[shot.png](https://example/shot.png)`) {
+		t.Fatalf("expected attachment markdown inlined in body, got: %s", body)
+	}
+}
+
+func Test_getPullRequestByIndexFn_emptyAssetsLeavesBody(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+		index = 9
+	)
+
+	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", owner, repo, index):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"number":9,"title":"feat","body":"plain body","state":"open"}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s/issues/%d/assets", owner, repo, index):
+			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 }()
+
+	req := mcp.CallToolRequest{Params: mcp.CallToolParams{Arguments: map[string]any{
+		"owner": owner, "repo": repo, "pull_number": float64(index),
+	}}}
+	res, err := getPullRequestByIndexFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("getPullRequestByIndexFn() error = %v", err)
+	}
+	body := res.Content[0].(mcp.TextContent).Text
+	if !strings.Contains(body, `"body":"plain body"`) {
+		t.Fatalf("expected body unchanged when assets are empty, got: %s", body)
+	}
+}
+
+func Test_getPullRequestByIndexFn_assetsFailureNonFatal(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+		index = 9
+	)
+
+	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", owner, repo, index):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"number":9,"title":"feat","body":"plain body","state":"open"}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s/issues/%d/assets", owner, repo, index):
+			http.Error(w, "boom", http.StatusInternalServerError)
+		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 }()
+
+	req := mcp.CallToolRequest{Params: mcp.CallToolParams{Arguments: map[string]any{
+		"owner": owner, "repo": repo, "pull_number": float64(index),
+	}}}
+	res, err := getPullRequestByIndexFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("getPullRequestByIndexFn() error = %v", err)
+	}
+	if res.IsError {
+		t.Fatalf("assets fetch failure should not fail the PR fetch: %v", res.Content)
+	}
+	body := res.Content[0].(mcp.TextContent).Text
+	if !strings.Contains(body, `"plain body"`) {
+		t.Fatalf("expected PR body preserved when assets fail, got: %s", body)
+	}
+}
+
+func Test_closePullRequestFn(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+		index = 7
+	)
+
+	var 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", owner, repo, index):
+			if r.Method != http.MethodPatch {
+				t.Errorf("expected PATCH method, got %s", r.Method)
+			}
+			_ = json.NewDecoder(r.Body).Decode(&gotBody)
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write(fmt.Appendf(nil, `{"index":%d,"title":"Fix bug","state":"closed","head":{"ref":"fix-branch"},"base":{"ref":"main"}}`, index))
+		default:
+			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	server := httptest.NewServer(handler)
+	t.Cleanup(server.Close)
+
+	origHost := flag.Host
+	origToken := flag.Token
+	flag.Host = server.URL
+	flag.Token = "test-token"
+	t.Cleanup(func() { flag.Host = origHost; flag.Token = origToken })
+
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]any{
+				"method":      "close",
+				"owner":       owner,
+				"repo":        repo,
+				"pull_number": float64(index),
+			},
+		},
+	}
+
+	result, err := closePullRequestFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("closePullRequestFn() error = %v", err)
+	}
+
+	if gotBody["state"] != "closed" {
+		t.Errorf("expected state=closed, got %v", gotBody["state"])
+	}
+
+	if len(result.Content) == 0 {
+		t.Fatalf("expected content in result")
+	}
+}
+
+func Test_reopenPullRequestFn(t *testing.T) {
+	const (
+		owner = "octo"
+		repo  = "demo"
+		index = 7
+	)
+
+	var 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", owner, repo, index):
+			if r.Method != http.MethodPatch {
+				t.Errorf("expected PATCH method, got %s", r.Method)
+			}
+			_ = json.NewDecoder(r.Body).Decode(&gotBody)
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write(fmt.Appendf(nil, `{"index":%d,"title":"Fix bug","state":"open","head":{"ref":"fix-branch"},"base":{"ref":"main"}}`, index))
+		default:
+			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+
+	server := httptest.NewServer(handler)
+	t.Cleanup(server.Close)
+
+	origHost := flag.Host
+	origToken := flag.Token
+	flag.Host = server.URL
+	flag.Token = "test-token"
+	t.Cleanup(func() { flag.Host = origHost; flag.Token = origToken })
+
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]any{
+				"method":      "reopen",
+				"owner":       owner,
+				"repo":        repo,
+				"pull_number": float64(index),
+			},
+		},
+	}
+
+	result, err := reopenPullRequestFn(context.Background(), req)
+	if err != nil {
+		t.Fatalf("reopenPullRequestFn() error = %v", err)
+	}
+
+	if gotBody["state"] != "open" {
+		t.Errorf("expected state=open, got %v", gotBody["state"])
+	}
+
+	if len(result.Content) == 0 {
+		t.Fatalf("expected content in result")
+	}
+}

operation/pull/slim.go

@@ -1,9 +1,30 @@
 package pull
 
 import (
+	"fmt"
+	"strings"
+
 	gitea_sdk "code.gitea.io/sdk/gitea"
 )
 
+func bodyWithAttachments(body string, atts []*gitea_sdk.Attachment) string {
+	links := make([]string, 0, len(atts))
+	for _, a := range atts {
+		if a == nil || a.DownloadURL == "" {
+			continue
+		}
+		links = append(links, fmt.Sprintf("[%s](%s)", a.Name, a.DownloadURL))
+	}
+	if len(links) == 0 {
+		return body
+	}
+	joined := strings.Join(links, "\n")
+	if body == "" {
+		return joined
+	}
+	return body + "\n\n" + joined
+}
+
 func userLogin(u *gitea_sdk.User) string {
 	if u == nil {
 		return ""

operation/repo/branch.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -23,26 +24,28 @@ const (
 var (
 	CreateBranchTool = mcp.NewTool(
 		CreateBranchToolName,
-		mcp.WithDescription("Create branch"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("branch", mcp.Required(), mcp.Description("Name of the branch to create")),
-		mcp.WithString("old_branch", mcp.Required(), mcp.Description("Name of the old branch to create from")),
+		mcp.WithToolAnnotation(annotation.Write("Create a new branch")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("branch", mcp.Required()),
+		mcp.WithString("old_branch", mcp.Description("source branch (default: repo default)")),
 	)
 
 	DeleteBranchTool = mcp.NewTool(
 		DeleteBranchToolName,
-		mcp.WithDescription("Delete branch"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("branch", mcp.Required(), mcp.Description("Name of the branch to delete")),
+		mcp.WithToolAnnotation(annotation.Destructive("Delete a branch")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("branch", mcp.Required()),
 	)
 
 	ListBranchesTool = mcp.NewTool(
 		ListBranchesToolName,
-		mcp.WithDescription("List branches"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+		mcp.WithToolAnnotation(annotation.ReadOnly("List repository branches")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 )
 
@@ -131,10 +134,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

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -16,17 +17,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.WithToolAnnotation(annotation.ReadOnly("List repository commits")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("sha", mcp.Description("starting SHA or branch")),
+		mcp.WithString("path", mcp.Description("only commits touching this path")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30), mcp.Min(1)),
+	)
+
+	GetCommitTool = mcp.NewTool(
+		GetCommitToolName,
+		mcp.WithToolAnnotation(annotation.ReadOnly("Get commit details")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("sha", mcp.Required()),
+	)
 )
 
 func init() {
@@ -34,6 +46,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) {
@@ -47,20 +63,13 @@ func ListRepoCommitsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	page, err := params.GetIndex(args, "page")
-	if err != nil {
-		return to.ErrorResult(err)
-	}
-	pageSize, err := params.GetIndex(args, "perPage")
-	if err != nil {
-		return to.ErrorResult(err)
-	}
+	page, pageSize := params.GetPagination(args, 30)
 	sha, _ := args["sha"].(string)
 	path, _ := args["path"].(string)
 	opt := gitea_sdk.ListCommitOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 		SHA:  sha,
 		Path: path,
@@ -75,3 +84,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/file.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -28,45 +29,47 @@ const (
 var (
 	GetFileContentTool = mcp.NewTool(
 		GetFileToolName,
-		mcp.WithDescription("Get file Content and Metadata"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("ref", mcp.Required(), mcp.Description("ref can be branch/tag/commit")),
-		mcp.WithString("filePath", mcp.Required(), mcp.Description("file path")),
-		mcp.WithBoolean("withLines", mcp.Description("whether to return file content with lines")),
+		mcp.WithDescription("Get file content and metadata"),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Get file content")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("ref", mcp.Required(), mcp.Description("branch, tag, or commit SHA")),
+		mcp.WithString("path", mcp.Required()),
+		mcp.WithBoolean("withLines", mcp.Description("return numbered lines")),
 	)
 
 	GetDirContentTool = mcp.NewTool(
 		GetDirToolName,
-		mcp.WithDescription("Get a list of entries in a directory"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("ref", mcp.Required(), mcp.Description("ref can be branch/tag/commit")),
-		mcp.WithString("filePath", mcp.Required(), mcp.Description("directory path")),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Get directory contents")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("ref", mcp.Required(), mcp.Description("branch, tag, or commit SHA")),
+		mcp.WithString("path", mcp.Required()),
 	)
 
 	CreateOrUpdateFileTool = mcp.NewTool(
 		CreateOrUpdateFileToolName,
-		mcp.WithDescription("Create or update a file. If sha is provided, updates the existing file; otherwise creates a new file."),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("filePath", mcp.Required(), mcp.Description("file path")),
-		mcp.WithString("content", mcp.Required(), mcp.Description("file content")),
+		mcp.WithDescription("Create or update a file (provide sha to update an existing file)."),
+		mcp.WithToolAnnotation(annotation.Write("Create or update a file")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("path", mcp.Required()),
+		mcp.WithString("content", mcp.Required()),
 		mcp.WithString("message", mcp.Required(), mcp.Description("commit message")),
-		mcp.WithString("branch_name", mcp.Required(), mcp.Description("branch name")),
-		mcp.WithString("sha", mcp.Description("SHA of the existing file (required for update, omit for create)")),
-		mcp.WithString("new_branch_name", mcp.Description("new branch name (for create only)")),
+		mcp.WithString("branch_name", mcp.Required()),
+		mcp.WithString("sha", mcp.Description("existing file SHA (omit to create)")),
+		mcp.WithString("new_branch_name", mcp.Description("new branch (create only)")),
 	)
 
 	DeleteFileTool = mcp.NewTool(
 		DeleteFileToolName,
-		mcp.WithDescription("Delete file"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("filePath", mcp.Required(), mcp.Description("file path")),
+		mcp.WithToolAnnotation(annotation.Destructive("Delete a file")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("path", mcp.Required()),
 		mcp.WithString("message", mcp.Required(), mcp.Description("commit message")),
-		mcp.WithString("branch_name", mcp.Required(), mcp.Description("branch name")),
-		mcp.WithString("sha", mcp.Required(), mcp.Description("sha")),
+		mcp.WithString("branch_name", mcp.Required()),
+		mcp.WithString("sha", mcp.Required()),
 	)
 )
 
@@ -106,7 +109,7 @@ func GetFileContentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 		return to.ErrorResult(err)
 	}
 	ref, _ := args["ref"].(string)
-	filePath, err := params.GetString(args, "filePath")
+	filePath, err := params.GetString(args, "path")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -170,7 +173,7 @@ func GetDirContentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToo
 		return to.ErrorResult(err)
 	}
 	ref, _ := args["ref"].(string)
-	filePath, err := params.GetString(args, "filePath")
+	filePath, err := params.GetString(args, "path")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -196,7 +199,7 @@ func CreateOrUpdateFileFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Ca
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	filePath, err := params.GetString(args, "filePath")
+	filePath, err := params.GetString(args, "path")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -256,7 +259,7 @@ func DeleteFileFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRe
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	filePath, err := params.GetString(args, "filePath")
+	filePath, err := params.GetString(args, "path")
 	if err != nil {
 		return to.ErrorResult(err)
 	}

operation/repo/release.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -25,49 +26,50 @@ const (
 var (
 	CreateReleaseTool = mcp.NewTool(
 		CreateReleaseToolName,
-		mcp.WithDescription("Create release"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("tag_name", mcp.Required(), mcp.Description("tag name")),
-		mcp.WithString("target", mcp.Required(), mcp.Description("target commitish")),
-		mcp.WithString("title", mcp.Required(), mcp.Description("release title")),
-		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.WithString("body", mcp.Description("release body")),
+		mcp.WithToolAnnotation(annotation.Write("Create a release")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("tag_name", mcp.Required()),
+		mcp.WithString("target", mcp.Required(), mcp.Description("commitish")),
+		mcp.WithString("title", mcp.Required()),
+		mcp.WithBoolean("is_draft"),
+		mcp.WithBoolean("is_pre_release"),
+		mcp.WithString("body"),
 	)
 
 	DeleteReleaseTool = mcp.NewTool(
 		DeleteReleaseToolName,
-		mcp.WithDescription("Delete release"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("id", mcp.Required(), mcp.Description("release id")),
+		mcp.WithToolAnnotation(annotation.Destructive("Delete a release")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("id", mcp.Required()),
 	)
 
 	GetReleaseTool = mcp.NewTool(
 		GetReleaseToolName,
-		mcp.WithDescription("Get release"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("id", mcp.Required(), mcp.Description("release id")),
+		mcp.WithDescription("Get a release by ID"),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Get release details")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("id", mcp.Required()),
 	)
 
 	GetLatestReleaseTool = mcp.NewTool(
 		GetLatestReleaseToolName,
-		mcp.WithDescription("Get latest release"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Get latest release")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
 	)
 
 	ListReleasesTool = mcp.NewTool(
 		ListReleasesToolName,
-		mcp.WithDescription("List releases"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		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.WithToolAnnotation(annotation.ReadOnly("List releases")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithBoolean("is_draft"),
+		mcp.WithBoolean("is_pre_release"),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(20), mcp.Min(1)),
 	)
 )
 
@@ -242,7 +244,7 @@ func ListReleasesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTool
 		pIsPreRelease = new(isPreRelease)
 	}
 	page := params.GetOptionalInt(args, "page", 1)
-	pageSize := params.GetOptionalInt(args, "perPage", 20)
+	pageSize := params.GetOptionalInt(args, "per_page", 20)
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/repo/repo.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -28,42 +29,44 @@ const (
 var (
 	CreateRepoTool = mcp.NewTool(
 		CreateRepoToolName,
-		mcp.WithDescription("Create repository in personal account or organization"),
-		mcp.WithString("name", mcp.Required(), mcp.Description("Name of the repository to create")),
-		mcp.WithString("description", mcp.Description("Description of the repository to create")),
-		mcp.WithBoolean("private", mcp.Description("Whether the repository is private")),
-		mcp.WithString("issue_labels", mcp.Description("Issue Label set to use")),
-		mcp.WithBoolean("auto_init", mcp.Description("Whether the repository should be auto-intialized?")),
-		mcp.WithBoolean("template", mcp.Description("Whether the repository is template")),
-		mcp.WithString("gitignores", mcp.Description("Gitignores to use")),
-		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("organization", mcp.Description("Organization name to create repository in (optional - defaults to personal account)")),
+		mcp.WithToolAnnotation(annotation.Write("Create a new repository")),
+		mcp.WithString("name", mcp.Required()),
+		mcp.WithString("description"),
+		mcp.WithBoolean("private"),
+		mcp.WithString("issue_labels"),
+		mcp.WithBoolean("auto_init"),
+		mcp.WithBoolean("template"),
+		mcp.WithString("gitignores"),
+		mcp.WithString("license"),
+		mcp.WithString("readme"),
+		mcp.WithString("default_branch"),
+		mcp.WithString("trust_model", mcp.Enum("default", "collaborator", "committer", "collaboratorcommitter")),
+		mcp.WithString("object_format_name", mcp.Enum("sha1", "sha256")),
+		mcp.WithString("organization", mcp.Description("defaults to personal account")),
 	)
 
 	ForkRepoTool = mcp.NewTool(
 		ForkRepoToolName,
-		mcp.WithDescription("Fork repository"),
-		mcp.WithString("user", mcp.Required(), mcp.Description("User name of the repository to fork")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("Repository name to fork")),
-		mcp.WithString("organization", mcp.Description("Organization name to fork")),
-		mcp.WithString("name", mcp.Description("Name of the forked repository")),
+		mcp.WithToolAnnotation(annotation.Write("Fork a repository")),
+		mcp.WithString("user", mcp.Required(), mcp.Description("owner of source repo")),
+		mcp.WithString("repo", mcp.Required()),
+		mcp.WithString("organization", mcp.Description("target org")),
+		mcp.WithString("name", mcp.Description("fork name")),
 	)
 
 	ListMyReposTool = mcp.NewTool(
 		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.WithToolAnnotation(annotation.ReadOnly("List my repositories")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30), mcp.Min(1)),
 	)
 
 	ListOrgReposTool = mcp.NewTool(
 		ListOrgReposToolName,
-		mcp.WithDescription("List repositories of an organization"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("Organization name")),
-		mcp.WithNumber("page", mcp.Required(), mcp.Description("Page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("pageSize", mcp.Required(), mcp.Description("Page size number"), mcp.DefaultNumber(100), mcp.Min(1)),
+		mcp.WithToolAnnotation(annotation.ReadOnly("List organization repositories")),
+		mcp.WithString("org", mcp.Required()),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(100), mcp.Min(1)),
 	)
 )
 
@@ -102,19 +105,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
@@ -199,18 +206,11 @@ func ListOrgReposFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTool
 	if !ok {
 		return to.ErrorResult(errors.New("organization name is required"))
 	}
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
-	}
+	page, pageSize := params.GetPagination(req.GetArguments(), 100)
 	opt := gitea_sdk.ListOrgReposOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)

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

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -24,37 +25,37 @@ const (
 var (
 	CreateTagTool = mcp.NewTool(
 		CreateTagToolName,
-		mcp.WithDescription("Create tag"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("tag_name", mcp.Required(), mcp.Description("tag name")),
-		mcp.WithString("target", mcp.Description("target commitish"), mcp.DefaultString("")),
-		mcp.WithString("message", mcp.Description("tag message"), mcp.DefaultString("")),
+		mcp.WithToolAnnotation(annotation.Write("Create a tag")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("tag_name", mcp.Required()),
+		mcp.WithString("target", mcp.Description("commitish")),
+		mcp.WithString("message", mcp.Description("tag message")),
 	)
 
 	DeleteTagTool = mcp.NewTool(
 		DeleteTagToolName,
-		mcp.WithDescription("Delete tag"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("tag_name", mcp.Required(), mcp.Description("tag name")),
+		mcp.WithToolAnnotation(annotation.Destructive("Delete a tag")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("tag_name", mcp.Required()),
 	)
 
 	GetTagTool = mcp.NewTool(
 		GetTagToolName,
-		mcp.WithDescription("Get tag"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("tag_name", mcp.Required(), mcp.Description("tag name")),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Get tag details")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("tag_name", mcp.Required()),
 	)
 
 	ListTagsTool = mcp.NewTool(
 		ListTagsToolName,
-		mcp.WithDescription("List tags"),
-		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.WithToolAnnotation(annotation.ReadOnly("List tags")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1), mcp.Min(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(20), mcp.Min(1)),
 	)
 )
 
@@ -179,7 +180,7 @@ func ListTagsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResu
 		return to.ErrorResult(err)
 	}
 	page := params.GetOptionalInt(args, "page", 1)
-	pageSize := params.GetOptionalInt(args, "perPage", 20)
+	pageSize := params.GetOptionalInt(args, "per_page", 20)
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {

operation/repo/tree.go

@@ -0,0 +1,75 @@
+package repo
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
+	"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.WithToolAnnotation(annotation.ReadOnly("Get repository file tree")),
+	mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+	mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+	mcp.WithString("tree_sha", mcp.Required(), mcp.Description("SHA, branch, or tag")),
+	mcp.WithBoolean("recursive"),
+	mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+	mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), 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,7 +3,9 @@ package search
 import (
 	"context"
 	"fmt"
+	"strings"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -21,40 +23,54 @@ const (
 	SearchUsersToolName    = "search_users"
 	SearchOrgTeamsToolName = "search_org_teams"
 	SearchReposToolName    = "search_repos"
+	SearchIssuesToolName   = "search_issues"
 )
 
 var (
 	SearchUsersTool = mcp.NewTool(
 		SearchUsersToolName,
-		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.WithToolAnnotation(annotation.ReadOnly("Search users")),
+		mcp.WithString("query", mcp.Required()),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 
 	SearOrgTeamsTool = mcp.NewTool(
 		SearchOrgTeamsToolName,
-		mcp.WithDescription("search organization teams"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		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.WithToolAnnotation(annotation.ReadOnly("Search organization teams")),
+		mcp.WithString("org", mcp.Required()),
+		mcp.WithString("query", mcp.Required()),
+		mcp.WithBoolean("includeDescription"),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 
 	SearchReposTool = mcp.NewTool(
 		SearchReposToolName,
-		mcp.WithDescription("search repos"),
-		mcp.WithString("keyword", mcp.Required(), mcp.Description("Keyword")),
-		mcp.WithBoolean("keywordIsTopic", mcp.Description("KeywordIsTopic")),
-		mcp.WithBoolean("keywordInDescription", mcp.Description("KeywordInDescription")),
-		mcp.WithNumber("ownerID", mcp.Description("OwnerID")),
-		mcp.WithBoolean("isPrivate", mcp.Description("IsPrivate")),
-		mcp.WithBoolean("isArchived", mcp.Description("IsArchived")),
-		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.WithToolAnnotation(annotation.ReadOnly("Search repositories")),
+		mcp.WithString("query", mcp.Required()),
+		mcp.WithBoolean("keywordIsTopic"),
+		mcp.WithBoolean("keywordInDescription"),
+		mcp.WithNumber("ownerID"),
+		mcp.WithBoolean("isPrivate"),
+		mcp.WithBoolean("isArchived"),
+		mcp.WithString("sort"),
+		mcp.WithString("order"),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
+	)
+
+	SearchIssuesTool = mcp.NewTool(
+		SearchIssuesToolName,
+		mcp.WithDescription("Search issues and PRs across repositories"),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Search issues")),
+		mcp.WithString("query", mcp.Required()),
+		mcp.WithString("state", mcp.Enum("open", "closed", "all")),
+		mcp.WithString("type", mcp.Enum("issues", "pulls")),
+		mcp.WithString("labels", mcp.Description("comma-separated")),
+		mcp.WithString("owner", mcp.Description("filter by owner")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 )
 
@@ -71,11 +87,15 @@ 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) {
 	log.Debugf("Called UsersFn")
-	keyword, err := params.GetString(req.GetArguments(), "keyword")
+	keyword, err := params.GetString(req.GetArguments(), "query")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -131,7 +151,7 @@ func OrgTeamsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResu
 
 func ReposFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	log.Debugf("Called ReposFn")
-	keyword, err := params.GetString(req.GetArguments(), "keyword")
+	keyword, err := params.GetString(req.GetArguments(), "query")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -175,3 +195,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/search_test.go

@@ -16,7 +16,7 @@ func TestSearchToolsRequiredFields(t *testing.T) {
 		{
 			name:     "search_users",
 			tool:     SearchUsersTool,
-			required: []string{"keyword"},
+			required: []string{"query"},
 		},
 		{
 			name:     "search_org_teams",
@@ -26,7 +26,7 @@ func TestSearchToolsRequiredFields(t *testing.T) {
 		{
 			name:     "search_repos",
 			tool:     SearchReposTool,
-			required: []string{"keyword"},
+			required: []string{"query"},
 		},
 	}
 

operation/search/slim.go

@@ -86,3 +86,59 @@ 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.Ref != "" {
+			m["ref"] = i.Ref
+		}
+		if i.Deadline != nil {
+			m["deadline"] = i.Deadline
+		}
+		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

@@ -5,13 +5,14 @@ import (
 	"context"
 	"fmt"
 
-	gitea_sdk "code.gitea.io/sdk/gitea"
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"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.com/gitea/gitea-mcp/pkg/tool"
 
+	gitea_sdk "code.gitea.io/sdk/gitea"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
@@ -26,24 +27,26 @@ const (
 var (
 	TimetrackingReadTool = mcp.NewTool(
 		TimetrackingReadToolName,
-		mcp.WithDescription("Read time tracking data. Use method 'list_issue_times' for issue times, 'list_repo_times' for repository times, 'get_my_stopwatches' for active stopwatches, 'get_my_times' for all your tracked times."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("list_issue_times", "list_repo_times", "get_my_stopwatches", "get_my_times")),
-		mcp.WithString("owner", mcp.Description("repository owner (required for 'list_issue_times', 'list_repo_times')")),
-		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.WithDescription("Read time tracking: issue times, repo times, active stopwatches, your tracked times."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read tracked time")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("list_issue_times", "list_repo_times", "get_my_stopwatches", "get_my_times")),
+		mcp.WithString("owner", mcp.Description("for list_* methods")),
+		mcp.WithString("repo", mcp.Description("for list_* methods")),
+		mcp.WithNumber("issue_number", mcp.Description("for 'list_issue_times'")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(1)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(30)),
 	)
 
 	TimetrackingWriteTool = mcp.NewTool(
 		TimetrackingWriteToolName,
-		mcp.WithDescription("Manage time tracking: stopwatches and tracked time entries."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("start_stopwatch", "stop_stopwatch", "delete_stopwatch", "add_time", "delete_time")),
-		mcp.WithString("owner", mcp.Description("repository owner (required for all methods)")),
-		mcp.WithString("repo", mcp.Description("repository name (required for all methods)")),
-		mcp.WithNumber("index", mcp.Description("issue index (required for all methods)")),
-		mcp.WithNumber("time", mcp.Description("time to add in seconds (required for 'add_time')")),
-		mcp.WithNumber("id", mcp.Description("tracked time entry ID (required for 'delete_time')")),
+		mcp.WithDescription("Write time tracking: stopwatches and entries."),
+		mcp.WithToolAnnotation(annotation.Write("Add or manage tracked time")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("start_stopwatch", "stop_stopwatch", "delete_stopwatch", "add_time", "delete_time")),
+		mcp.WithString("owner", mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Description(params.RepoDesc)),
+		mcp.WithNumber("issue_number"),
+		mcp.WithNumber("time", mcp.Description("seconds (for 'add_time')")),
+		mcp.WithNumber("id", mcp.Description("entry ID (for 'delete_time')")),
 	)
 )
 
@@ -104,7 +107,7 @@ func startStopwatchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -129,7 +132,7 @@ func stopStopwatchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToo
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -154,7 +157,7 @@ func deleteStopwatchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -197,7 +200,7 @@ func listTrackedTimesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -232,7 +235,7 @@ func addTrackedTimeFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -265,7 +268,7 @@ func deleteTrackedTimeFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Cal
 		return to.ErrorResult(err)
 	}
 
-	index, err := params.GetIndex(req.GetArguments(), "index")
+	index, err := params.GetIndex(req.GetArguments(), "issue_number")
 	if err != nil {
 		return to.ErrorResult(err)
 	}

operation/user/user.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -35,16 +36,18 @@ var (
 	// It is registered with a specific name and a description string.
 	GetMyUserInfoTool = mcp.NewTool(
 		GetMyUserInfoToolName,
-		mcp.WithDescription("Get my user info"),
+		mcp.WithDescription("Get current user"),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Get current user information")),
 	)
 
 	// GetUserOrgsTool is the MCP tool for listing organizations for the authenticated user.
-	// It supports pagination via "page" and "perPage" arguments with default values specified above.
+	// It supports pagination via "page" and "per_page" arguments with default values specified above.
 	GetUserOrgsTool = mcp.NewTool(
 		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.WithDescription("List current user's organizations"),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Get user organizations")),
+		mcp.WithNumber("page", mcp.Description(params.PageDesc), mcp.DefaultNumber(defaultPage)),
+		mcp.WithNumber("per_page", mcp.Description(params.PaginationDesc), mcp.DefaultNumber(defaultPageSize)),
 	)
 )
 

operation/version/version.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/to"
@@ -21,7 +22,7 @@ const (
 
 var GetGiteaMCPServerVersionTool = mcp.NewTool(
 	GetGiteaMCPServerVersion,
-	mcp.WithDescription("Get Gitea MCP Server Version"),
+	mcp.WithToolAnnotation(annotation.ReadOnly("Get server version")),
 )
 
 func init() {

operation/wiki/wiki.go

@@ -2,9 +2,11 @@ package wiki
 
 import (
 	"context"
+	"encoding/base64"
 	"fmt"
 	"net/url"
 
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
 	"gitea.com/gitea/gitea-mcp/pkg/gitea"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
 	"gitea.com/gitea/gitea-mcp/pkg/params"
@@ -25,22 +27,24 @@ const (
 var (
 	WikiReadTool = mcp.NewTool(
 		WikiReadToolName,
-		mcp.WithDescription("Read wiki page information. Use method 'list' to list pages, 'get' to get page content, 'get_revisions' for revision history."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("list", "get", "get_revisions")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("pageName", mcp.Description("wiki page name (required for 'get', 'get_revisions')")),
+		mcp.WithDescription("Read wiki: list pages, get content, revision history."),
+		mcp.WithToolAnnotation(annotation.ReadOnly("Read wiki pages")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("list", "get", "get_revisions")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("pageName", mcp.Description("for 'get'/'get_revisions'")),
 	)
 
 	WikiWriteTool = mcp.NewTool(
 		WikiWriteToolName,
-		mcp.WithDescription("Create, update, or delete wiki pages."),
-		mcp.WithString("method", mcp.Required(), mcp.Description("operation to perform"), mcp.Enum("create", "update", "delete")),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("pageName", mcp.Description("wiki page name (required for 'update', 'delete')")),
-		mcp.WithString("title", mcp.Description("wiki page title (required for 'create', optional for 'update')")),
-		mcp.WithString("content_base64", mcp.Description("page content, base64 encoded (required for 'create', 'update')")),
+		mcp.WithDescription("Write wiki pages: create, update, delete."),
+		mcp.WithToolAnnotation(annotation.Destructive("Create, update, or delete wiki pages")),
+		mcp.WithString("method", mcp.Required(), mcp.Enum("create", "update", "delete")),
+		mcp.WithString("owner", mcp.Required(), mcp.Description(params.OwnerDesc)),
+		mcp.WithString("repo", mcp.Required(), mcp.Description(params.RepoDesc)),
+		mcp.WithString("pageName", mcp.Description("for 'update'/'delete'")),
+		mcp.WithString("title", mcp.Description("for 'create'")),
+		mcp.WithString("content", mcp.Description("for 'create'/'update'")),
 		mcp.WithString("message", mcp.Description("commit message")),
 	)
 )
@@ -176,7 +180,7 @@ func createWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	contentBase64, err := params.GetString(args, "content_base64")
+	content, err := params.GetString(args, "content")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
@@ -188,7 +192,7 @@ func createWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 
 	requestBody := map[string]string{
 		"title":          title,
-		"content_base64": contentBase64,
+		"content_base64": base64.StdEncoding.EncodeToString([]byte(content)),
 		"message":        message,
 	}
 
@@ -216,13 +220,13 @@ func updateWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	if err != nil {
 		return to.ErrorResult(err)
 	}
-	contentBase64, err := params.GetString(args, "content_base64")
+	content, err := params.GetString(args, "content")
 	if err != nil {
 		return to.ErrorResult(err)
 	}
 
 	requestBody := map[string]string{
-		"content_base64": contentBase64,
+		"content_base64": base64.StdEncoding.EncodeToString([]byte(content)),
 	}
 
 	// If title is given, use it. Otherwise, keep current page name

operation/wiki/wiki_test.go

@@ -0,0 +1,75 @@
+package wiki
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	mcpContext "gitea.com/gitea/gitea-mcp/pkg/context"
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+func TestWikiWriteBase64Encoding(t *testing.T) {
+	tests := []struct {
+		name    string
+		method  string
+		content string
+	}{
+		{"create ascii", "create", "Hello, World!"},
+		{"create unicode", "create", "日本語テスト 🎉"},
+		{"create multiline", "create", "line1\nline2\nline3"},
+		{"update ascii", "update", "Updated content"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var gotBody map[string]string
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				body, _ := io.ReadAll(r.Body)
+				_ = json.Unmarshal(body, &gotBody)
+				w.Header().Set("Content-Type", "application/json")
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte(`{"title":"test"}`))
+			}))
+			defer srv.Close()
+
+			origHost := flag.Host
+			flag.Host = srv.URL
+			defer func() { flag.Host = origHost }()
+
+			ctx := context.WithValue(context.Background(), mcpContext.TokenContextKey, "test-token")
+
+			args := map[string]any{
+				"method":   tt.method,
+				"owner":    "org",
+				"repo":     "repo",
+				"content":  tt.content,
+				"pageName": "TestPage",
+				"title":    "TestPage",
+			}
+
+			req := mcp.CallToolRequest{}
+			req.Params.Arguments = args
+
+			result, err := wikiWriteFn(ctx, req)
+			if err != nil {
+				t.Fatalf("wikiWriteFn() error: %v", err)
+			}
+			if result.IsError {
+				t.Fatalf("wikiWriteFn() returned error result")
+			}
+
+			got := gotBody["content_base64"]
+			want := base64.StdEncoding.EncodeToString([]byte(tt.content))
+			if got != want {
+				t.Errorf("content_base64 = %q, want %q", got, want)
+			}
+		})
+	}
+}

pkg/annotation/annotation.go

@@ -0,0 +1,22 @@
+// Package annotation provides shared MCP tool annotation helpers.
+package annotation
+
+import "github.com/mark3labs/mcp-go/mcp"
+
+// ReadOnly returns a ToolAnnotation for read-only tools.
+func ReadOnly(title string) mcp.ToolAnnotation {
+	t := true
+	return mcp.ToolAnnotation{Title: title, ReadOnlyHint: &t}
+}
+
+// Write returns a ToolAnnotation for write tools.
+func Write(title string) mcp.ToolAnnotation {
+	f := false
+	return mcp.ToolAnnotation{Title: title, ReadOnlyHint: &f}
+}
+
+// Destructive returns a ToolAnnotation for destructive write tools.
+func Destructive(title string) mcp.ToolAnnotation {
+	f, t := false, true
+	return mcp.ToolAnnotation{Title: title, ReadOnlyHint: &f, DestructiveHint: &t}
+}

pkg/flag/flag.go

@@ -7,7 +7,8 @@ var (
 	Version string
 	Mode    string
 
-	Insecure bool
-	ReadOnly bool
-	Debug    bool
+	Insecure     bool
+	ReadOnly     bool
+	Debug        bool
+	AllowedTools map[string]struct{}
 )

pkg/gitea/gitea.go

@@ -7,9 +7,10 @@ import (
 	"fmt"
 	"net/http"
 
-	"code.gitea.io/sdk/gitea"
 	mcpContext "gitea.com/gitea/gitea-mcp/pkg/context"
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"code.gitea.io/sdk/gitea"
 )
 
 func NewClient(token string) (*gitea.Client, error) {

pkg/gitea/redirect_test.go

@@ -99,7 +99,7 @@ func TestDoJSON_GETRedirectFollowed(t *testing.T) {
 	mux.HandleFunc("GET /api/v1/repos/owner/new-name/pulls/1", func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusOK)
-		json.NewEncoder(w).Encode(map[string]any{"id": 1, "title": "found"})
+		_ = json.NewEncoder(w).Encode(map[string]any{"id": 1, "title": "found"})
 	})
 	srv := httptest.NewServer(mux)
 	defer srv.Close()

pkg/log/log.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
 	"go.uber.org/zap"
 	"go.uber.org/zap/zapcore"
 	"gopkg.in/natefinch/lumberjack.v2"

pkg/params/params.go

@@ -3,6 +3,17 @@ package params
 import (
 	"fmt"
 	"strconv"
+	"time"
+)
+
+// Shared parameter description strings used across tools. Extracted to avoid
+// repeating the same boilerplate in every tool schema (saves tokens in the
+// tool list sent to MCP clients).
+const (
+	OwnerDesc      = "repo owner"
+	RepoDesc       = "repo name"
+	PageDesc       = "page"
+	PaginationDesc = "results per page"
 )
 
 // GetString extracts a required string parameter from MCP tool arguments.
@@ -41,9 +52,9 @@ func GetStringSlice(args map[string]any, key string) []string {
 	return out
 }
 
-// GetPagination extracts page and perPage parameters, returning them as ints.
+// GetPagination extracts page and per_page parameters, returning them as ints.
 func GetPagination(args map[string]any, defaultPageSize int64) (page, pageSize int) {
-	return int(GetOptionalInt(args, "page", 1)), int(GetOptionalInt(args, "perPage", defaultPageSize))
+	return int(GetOptionalInt(args, "page", 1)), int(GetOptionalInt(args, "per_page", defaultPageSize))
 }
 
 // ToInt64 converts a value to int64, accepting both float64 (JSON number) and
@@ -101,6 +112,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.

pkg/params/params_test.go

@@ -5,6 +5,17 @@ import (
 	"testing"
 )
 
+func TestGetPagination(t *testing.T) {
+	page, perPage := GetPagination(map[string]any{"page": float64(2), "per_page": float64(40)}, 30)
+	if page != 2 || perPage != 40 {
+		t.Errorf("GetPagination = (%d, %d), want (2, 40)", page, perPage)
+	}
+	page, perPage = GetPagination(map[string]any{}, 30)
+	if page != 1 || perPage != 30 {
+		t.Errorf("GetPagination defaults = (%d, %d), want (1, 30)", page, perPage)
+	}
+}
+
 func TestToInt64(t *testing.T) {
 	tests := []struct {
 		name string

pkg/to/to.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 
 	"gitea.com/gitea/gitea-mcp/pkg/log"
+
 	"github.com/mark3labs/mcp-go/mcp"
 )
 

pkg/tool/tool.go

@@ -1,7 +1,12 @@
 package tool
 
 import (
+	"slices"
+	"strings"
+
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
+	"gitea.com/gitea/gitea-mcp/pkg/log"
+
 	"github.com/mark3labs/mcp-go/server"
 )
 
@@ -26,12 +31,48 @@ func (t *Tool) RegisterRead(s server.ServerTool) {
 }
 
 func (t *Tool) Tools() []server.ServerTool {
-	tools := make([]server.ServerTool, 0, len(t.write)+len(t.read))
-	if flag.ReadOnly {
-		tools = append(tools, t.read...)
-		return tools
+	all := make([]server.ServerTool, 0, len(t.write)+len(t.read))
+	if !flag.ReadOnly {
+		all = append(all, t.write...)
 	}
-	tools = append(tools, t.write...)
-	tools = append(tools, t.read...)
-	return tools
+	all = append(all, t.read...)
+	if len(flag.AllowedTools) == 0 {
+		return all
+	}
+	filtered := make([]server.ServerTool, 0, len(all))
+	for _, st := range all {
+		if _, ok := flag.AllowedTools[st.Tool.Name]; ok {
+			filtered = append(filtered, st)
+		}
+	}
+	return filtered
+}
+
+// WarnUnmatchedAllowedTools logs any names in flag.AllowedTools that don't
+// match a tool registered on any of the given domains. No-op if the allowlist
+// is empty.
+func WarnUnmatchedAllowedTools(domains ...*Tool) {
+	if len(flag.AllowedTools) == 0 {
+		return
+	}
+	known := map[string]struct{}{}
+	for _, d := range domains {
+		for _, st := range d.read {
+			known[st.Tool.Name] = struct{}{}
+		}
+		for _, st := range d.write {
+			known[st.Tool.Name] = struct{}{}
+		}
+	}
+	var unmatched []string
+	for name := range flag.AllowedTools {
+		if _, ok := known[name]; !ok {
+			unmatched = append(unmatched, name)
+		}
+	}
+	if len(unmatched) == 0 {
+		return
+	}
+	slices.Sort(unmatched)
+	log.Warnf("Unknown tools in --tools allowlist (ignored): %s", strings.Join(unmatched, ", "))
 }

pkg/tool/tool_test.go

@@ -0,0 +1,100 @@
+package tool
+
+import (
+	"slices"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+func makeTool(name string) server.ServerTool {
+	return server.ServerTool{Tool: mcp.NewTool(name)}
+}
+
+func names(sts []server.ServerTool) []string {
+	out := make([]string, len(sts))
+	for i, st := range sts {
+		out[i] = st.Tool.Name
+	}
+	return out
+}
+
+func TestTools(t *testing.T) {
+	tests := []struct {
+		name     string
+		readOnly bool
+		allowed  map[string]struct{}
+		read     []string
+		write    []string
+		want     []string
+	}{
+		{
+			name:  "no filters returns write then read",
+			read:  []string{"r1", "r2"},
+			write: []string{"w1", "w2"},
+			want:  []string{"w1", "w2", "r1", "r2"},
+		},
+		{
+			name:     "read-only excludes write",
+			readOnly: true,
+			read:     []string{"r1", "r2"},
+			write:    []string{"w1"},
+			want:     []string{"r1", "r2"},
+		},
+		{
+			name:    "allowlist keeps only listed",
+			allowed: map[string]struct{}{"r1": {}, "w1": {}},
+			read:    []string{"r1", "r2"},
+			write:   []string{"w1", "w2"},
+			want:    []string{"w1", "r1"},
+		},
+		{
+			name:     "allowlist intersected with read-only drops write entries",
+			readOnly: true,
+			allowed:  map[string]struct{}{"r1": {}, "w1": {}},
+			read:     []string{"r1", "r2"},
+			write:    []string{"w1", "w2"},
+			want:     []string{"r1"},
+		},
+		{
+			name:    "allowlist with only unknown names returns empty",
+			allowed: map[string]struct{}{"unknown": {}},
+			read:    []string{"r1"},
+			write:   []string{"w1"},
+			want:    []string{},
+		},
+		{
+			name:    "empty allowlist map passes through",
+			allowed: map[string]struct{}{},
+			read:    []string{"r1"},
+			write:   []string{"w1"},
+			want:    []string{"w1", "r1"},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			origRO, origAllow := flag.ReadOnly, flag.AllowedTools
+			t.Cleanup(func() {
+				flag.ReadOnly, flag.AllowedTools = origRO, origAllow
+			})
+			flag.ReadOnly = tt.readOnly
+			flag.AllowedTools = tt.allowed
+
+			tr := New()
+			for _, n := range tt.read {
+				tr.RegisterRead(makeTool(n))
+			}
+			for _, n := range tt.write {
+				tr.RegisterWrite(makeTool(n))
+			}
+
+			got := names(tr.Tools())
+			if !slices.Equal(got, tt.want) {
+				t.Errorf("Tools() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}