Merge branch 'main' into refactor/migrate-official-mcp-go-sdk

Co-Authored-By: OpenAI Codex (GPT-5) <noreply@openai.com>

.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": {

.gitea/workflows/release-nightly.yml

@@ -14,7 +14,7 @@ jobs:
       DOCKER_LATEST: nightly
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0 # all history for all branches and tags
 
@@ -37,7 +37,7 @@ jobs:
           echo REPO_VERSION=$(git describe --tags --always | sed 's/-/+/' | sed 's/^v//') >> $GITHUB_OUTPUT
 
       - name: Build and push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
           file: ./Dockerfile

.gitea/workflows/release-tag.yml

@@ -10,20 +10,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version: stable
+      - name: Install GoReleaser
+        run: go install github.com/goreleaser/goreleaser/v2@latest
       - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v6
-        with:
-          distribution: goreleaser
-          # 'latest', 'nightly', or a semver
-          version: "~> v2"
-          args: release --clean
+        run: goreleaser release --clean
         env:
           GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GORELEASER_FORCE_TOKEN: "gitea"
@@ -35,7 +32,7 @@ jobs:
       DOCKER_LATEST: latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0 # all history for all branches and tags
 
@@ -58,7 +55,7 @@ jobs:
           echo REPO_VERSION=${GITHUB_REF_NAME#v} >> $GITHUB_OUTPUT
 
       - name: Build and push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
           file: ./Dockerfile

.gitea/workflows/test-pr.yml

@@ -7,20 +7,15 @@ jobs:
   check-and-test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
         with:
           go-version-file: 'go.mod'
+      - name: lint
+        run: make lint
+      - name: test
+        run: make test
       - name: build
-        run: |
-          make build
-
-  govulncheck_job:
-    runs-on: ubuntu-latest
-    name: Run govulncheck
-    steps:
-      - id: govulncheck
-        uses: golang/govulncheck-action@v1
-        with:
-          go-version-file: 'go.mod'
-          go-package: ./...
+        run: make build
+      - name: security-check
+        run: make security-check

.golangci.yml

@@ -0,0 +1,117 @@
+version: "2"
+output:
+  sort-order:
+    - file
+linters:
+  default: none
+  enable:
+    - bidichk
+    - bodyclose
+    - depguard
+    - errcheck
+    - forbidigo
+    - gocheckcompilerdirectives
+    - gocritic
+    - govet
+    - ineffassign
+    - mirror
+    - modernize
+    - nakedret
+    - nilnil
+    - nolintlint
+    - perfsprint
+    - revive
+    - staticcheck
+    - testifylint
+    - unconvert
+    - unparam
+    - unused
+    - usestdlibvars
+    - usetesting
+    - wastedassign
+  settings:
+    depguard:
+      rules:
+        main:
+          deny:
+            - pkg: io/ioutil
+              desc: use os or io instead
+            - pkg: golang.org/x/exp
+              desc: it's experimental and unreliable
+            - pkg: github.com/pkg/errors
+              desc: use builtin errors package instead
+    nolintlint:
+      allow-unused: false
+      require-explanation: true
+      require-specific: true
+    gocritic:
+      enabled-checks:
+        - equalFold
+      disabled-checks: []
+    revive:
+      severity: error
+      rules:
+        - name: blank-imports
+        - name: constant-logical-expr
+        - name: context-as-argument
+        - name: context-keys-type
+        - name: dot-imports
+        - name: empty-lines
+        - name: error-return
+        - name: error-strings
+        - name: exported
+        - name: identical-branches
+        - name: if-return
+        - name: increment-decrement
+        - name: modifies-value-receiver
+        - name: package-comments
+        - name: redefines-builtin-id
+        - name: superfluous-else
+        - name: time-naming
+        - name: unexported-return
+        - name: var-declaration
+        - name: var-naming
+          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
+    testifylint: {}
+    usetesting:
+      os-temp-dir: true
+    perfsprint:
+      concat-loop: false
+    govet:
+      enable:
+        - nilness
+        - unusedwrite
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+formatters:
+  enable:
+    - gci
+    - gofumpt
+  settings:
+    gci:
+      custom-order: true
+      sections:
+        - standard
+        - prefix(gitea.com/gitea/gitea-mcp)
+        - blank
+        - default
+    gofumpt:
+      extra-rules: true
+  exclusions:
+    generated: lax
+run:
+  timeout: 10m

AGENTS.md

@@ -1,71 +1,16 @@
-# 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
+- Never assume, verify before claiming
+- Use `make help` to find available development targets
+- PR descriptions: minimal, only what and why, no task lists or file listings
+- Reference issues and PRs by full URL, not by number
+- Use Conventional Commits for commit messages and PR titles, e.g. `type(scope): subject`; `!` before the colon if breaking. Use `test` type for test-only changes.
+- Add an `Assisted-by: AGENT_NAME:MODEL_VERSION` trailer to commit messages, never `Co-Authored-By` or `Signed-off-by`
+- Attribute agent authorship on one trailing line in issue and pull request comments, never as a PR description section
+- Never force-push, amend, or squash unless asked. Use new commits and normal push for pull request updates
+- Keep comments short, prefer same-line, explain why, never narrate code. Preserve existing ones that still apply
+- Ensure no trailing whitespace in edited files
+- Run `make fmt` to format `.go` files, `make lint-go` to lint them, and `make tidy` after any `go.mod` changes
+- Fix the cause rather than disabling a linter or weakening a test. Where unavoidable, use the narrowest scope with a trailing comment giving the reason
+- Register new tools with `Tool.RegisterRead` or `Tool.RegisterWrite`, and add them to the tool tables in `README.md`, `README.zh-cn.md` and `README.zh-tw.md`
+- Run single go tests with `go test -run '^TestName$' ./modulepath/`
+- Write the fewest, fastest tests covering the behavior, extending an existing one where possible. Prefer unit tests where logic is testable in isolation
+- Wait on a deterministic condition rather than `sleep`

BUILDING.md

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

CLAUDE.md

@@ -1,71 +1 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) 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
+@AGENTS.md

Dockerfile

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1.4
 
 # Build stage
-FROM --platform=$BUILDPLATFORM golang:1.24-alpine AS builder
+FROM --platform=$BUILDPLATFORM golang:1.26-alpine AS builder
 
 ARG VERSION=dev
 ARG TARGETOS
@@ -22,11 +22,14 @@ RUN --mount=type=cache,target=/go/pkg/mod \
 # Final stage
 FROM gcr.io/distroless/static-debian12:nonroot
 
+ARG VERSION=dev
+
 WORKDIR /app
 COPY --from=builder --chown=nonroot:nonroot /app/gitea-mcp .
 
 USER nonroot:nonroot
 
 LABEL org.opencontainers.image.version="${VERSION}"
+LABEL org.opencontainers.image.source="https://gitea.com/gitea/gitea-mcp"
 
 CMD ["/app/gitea-mcp"]

Makefile

@@ -3,8 +3,13 @@ EXECUTABLE := gitea-mcp
 VERSION ?= $(shell git describe --tags --always | sed 's/-/+/' | sed 's/^v//')
 LDFLAGS := -X "main.Version=$(VERSION)"
 
+GOLANGCI_LINT_PACKAGE ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 # renovate: datasource=go
+GOVULNCHECK_PACKAGE ?= golang.org/x/vuln/cmd/govulncheck@v1.3.0 # renovate: datasource=go
+
+GOTEST_FLAGS ?= -race -timeout 20m
+
 .PHONY: help
-help: ## Print this help message.
+help: ## print this help message
 	@echo "Usage: make [target]"
 	@echo ""
 	@echo "Targets:"
@@ -12,7 +17,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)
@@ -20,23 +25,27 @@ 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: test
+test: ## run Go tests
+	$(GO) test $(GOTEST_FLAGS) ./...
+
 .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
@@ -45,8 +54,42 @@ 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
+
+.PHONY: lint-fix
+lint-fix: lint-go-fix ## lint everything and fix issues
+
+.PHONY: lint-go
+lint-go: ## lint go files
+	$(GO) run $(GOLANGCI_LINT_PACKAGE) run
+
+.PHONY: lint-go-fix
+lint-go-fix: ## lint go files and fix issues
+	$(GO) run $(GOLANGCI_LINT_PACKAGE) run --fix
+
+.PHONY: security-check
+security-check: ## run security check
+	$(GO) run $(GOVULNCHECK_PACKAGE) -show color ./... || true
+
+.PHONY: tidy
+tidy: ## run go mod tidy
+	$(eval MIN_GO_VERSION := $(shell grep -Eo '^go\s+[0-9]+\.[0-9.]+' go.mod | cut -d' ' -f2))
+	$(GO) mod tidy -compat=$(MIN_GO_VERSION)
+
 .PHONY: vendor
-vendor: ## tidy and verify module dependencies
-	@echo 'Tidying and verifying module dependencies...'
-	go mod tidy
-	go mod verify
+vendor: tidy ## tidy and verify module dependencies
+	$(GO) mod verify

README.md

@@ -2,40 +2,27 @@
 
 [繁體中文](README.zh-tw.md) | [简体中文](README.zh-cn.md)
 
-**Gitea MCP Server** is an integration plugin designed to connect Gitea with Model Context Protocol (MCP) systems. This allows for seamless command execution and repository management through an MCP-compatible chat interface.
+**Gitea MCP Server** connects a [Gitea](https://about.gitea.com) instance to [Model Context Protocol](https://modelcontextprotocol.io) clients, so repositories, issues, pull requests and more can be browsed and managed from an MCP-compatible chat interface.
 
 [![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}&quality=insiders)
 
-## Table of Contents
+## Installation
 
-- [Gitea MCP Server](#gitea-mcp-server)
-  - [Table of Contents](#table-of-contents)
-  - [What is Gitea?](#what-is-gitea)
-  - [What is MCP?](#what-is-mcp)
-  - [🚧 Installation](#-installation)
-    - [Usage with Claude Code](#usage-with-claude-code)
-    - [Usage with VS Code](#usage-with-vs-code)
-    - [📥 Download the official binary release](#-download-the-official-binary-release)
-    - [🔧 Build from Source](#-build-from-source)
-    - [📁 Add to PATH](#-add-to-path)
-  - [🚀 Usage](#-usage)
-  - [✅ Available Tools](#-available-tools)
-  - [🐛 Debugging](#-debugging)
-  - [🛠 Troubleshooting](#-troubleshooting)
+Download a binary from the [releases page](https://gitea.com/gitea/gitea-mcp/releases) and put it in your `PATH`, use the `docker.gitea.com/gitea-mcp-server` image, or build from source into `$GOPATH/bin` with `make` and Go 1.26 or later:
 
-## What is Gitea?
+```bash
+git clone https://gitea.com/gitea/gitea-mcp.git
+cd gitea-mcp
+make install
+```
 
-Gitea is a community-managed lightweight code hosting solution written in Go. It is published under the MIT license. Gitea provides Git hosting including a repository viewer, issue tracking, pull requests, and more.
+## Configuration
 
-## What is MCP?
+Pass the Gitea host and access token as command-line flags or environment variables, flags take precedence. Run `gitea-mcp --help` for the full list of flags and environment variables. Logs are written to `$HOME/.gitea-mcp/gitea-mcp.log`, add `-d` for debug logging.
 
-Model Context Protocol (MCP) is a protocol that allows for the integration of various tools and systems through a chat interface. It enables seamless command execution and management of repositories, users, and other resources.
+### Claude Code
 
-## 🚧 Installation
-
-### Usage with Claude Code
-
-This method uses `go run` and requires [Go](https://go.dev) to be installed.
+Runs the server through `go run` and requires [Go](https://go.dev):
 
 ```bash
 claude mcp add --transport stdio --scope user gitea \
@@ -44,15 +31,9 @@ claude mcp add --transport stdio --scope user gitea \
   -- go run gitea.com/gitea/gitea-mcp@latest -t stdio
 ```
 
-### Usage with VS Code
+### VS Code
 
-For quick installation, use one of the one-click install buttons at the top of this README.
-
-For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
-
-Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
-
-> Note that the `mcp` key is not needed in the `.vscode/mcp.json` file.
+Use the install buttons at the top of this README, or add the block below to your User Settings (JSON), reachable via `Ctrl + Shift + P` and `Preferences: Open User Settings (JSON)`. It also works in a workspace `.vscode/mcp.json`, where the `mcp` key is omitted.
 
 ```json
 {
@@ -68,14 +49,7 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
     "servers": {
       "gitea-mcp": {
         "command": "docker",
-        "args": [
-          "run",
-          "-i",
-          "--rm",
-          "-e",
-          "GITEA_ACCESS_TOKEN",
-          "docker.gitea.com/gitea-mcp-server"
-        ],
+        "args": ["run", "-i", "--rm", "-e", "GITEA_ACCESS_TOKEN", "docker.gitea.com/gitea-mcp-server"],
         "env": {
           "GITEA_ACCESS_TOKEN": "${input:gitea_token}"
         }
@@ -85,59 +59,50 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
 }
 ```
 
-### 📥 Download the official binary release
+### OpenCode
 
-You can download the official release from [official Gitea MCP binary releases](https://gitea.com/gitea/gitea-mcp/releases).
+Add the following to the top-level `mcp` object of your [OpenCode](https://opencode.ai) config:
 
-### 🔧 Build from Source
-
-You can download the source code by cloning the repository using Git:
-
-```bash
-git clone https://gitea.com/gitea/gitea-mcp.git
+```json
+    "gitea-mcp": {
+      "enabled": true,
+      "type": "local",
+      "command": [
+        "gitea-mcp",
+        "-t", "stdio",
+        "-H", "https://gitea.com",
+        "-T", "<your personal access token>"
+      ]
+    }
 ```
 
-Before building, make sure you have the following installed:
+### Mistral Vibe
 
-- make
-- Golang (Go 1.24 or later recommended)
+Add the following to `~/.vibe/config.toml`:
 
-Then run:
+```toml
+[[mcp_servers]]
+name = "gitea"
+transport = "stdio"
+command = "docker"
+args = ["run", "--rm", "-i", "-e", "GITEA_ACCESS_TOKEN", "-e", "GITEA_HOST", "docker.gitea.com/gitea-mcp-server"]
 
-```bash
-make install
+[mcp_servers.env]
+GITEA_ACCESS_TOKEN = "TOKEN"
+GITEA_HOST = "https://gitea.com"
 ```
 
-### 📁 Add to PATH
+### Other clients
 
-After installing, copy the binary gitea-mcp to a directory included in your system's PATH. For example:
-
-```bash
-cp gitea-mcp /usr/local/bin/
-```
-
-## 🚀 Usage
-
-This example is for Cursor, you can also use plugins in VSCode.
-To configure the MCP server for Gitea, add the following to your MCP configuration file:
-
-- **stdio mode**
+Clients such as Cursor take either a stdio command:
 
 ```json
 {
   "mcpServers": {
     "gitea": {
       "command": "gitea-mcp",
-      "args": [
-        "-t",
-        "stdio",
-        "--host",
-        "https://gitea.com"
-        // "--token", "<your personal access token>"
-      ],
+      "args": ["-t", "stdio", "--host", "https://gitea.com"],
       "env": {
-        // "GITEA_HOST": "https://gitea.com",
-        // "GITEA_INSECURE": "true",
         "GITEA_ACCESS_TOKEN": "<your personal access token>"
       }
     }
@@ -145,7 +110,7 @@ To configure the MCP server for Gitea, add the following to your MCP configurati
 }
 ```
 
-- **http mode**
+or an http endpoint, for a server started with `gitea-mcp -t http --port 8080`:
 
 ```json
 {
@@ -160,124 +125,74 @@ To configure the MCP server for Gitea, add the following to your MCP configurati
 }
 ```
 
-**Default log path**: `$HOME/.gitea-mcp/gitea-mcp.log`
+Once configured, try `list all my repositories` in the chat box.
 
-> [!NOTE]
-> You can provide your Gitea host and access token either as command-line arguments or environment variables.
-> Command-line arguments have the highest priority
+## Available Tools
 
-Once everything is set up, try typing the following in your MCP-compatible chatbox:
+| Tool                         | Scope        | Access | Description                                                                                |
+| :--------------------------- | :----------- | :----- | :----------------------------------------------------------------------------------------- |
+| get_gitea_mcp_server_version | version      | Read   | Get the Gitea MCP server version                                                           |
+| get_me                       | user         | Read   | Get the current authenticated user                                                         |
+| get_user_orgs                | user         | Read   | List the current user's organizations                                                      |
+| search_users                 | search       | Read   | Search for users                                                                           |
+| search_org_teams             | search       | Read   | Search teams within an organization                                                        |
+| search_repos                 | search       | Read   | Search for repositories                                                                    |
+| search_issues                | search       | Read   | Search issues and pull requests across repositories                                        |
+| notification_read            | notification | Read   | Read notifications: list (optionally scoped to a repo) or get a thread by ID               |
+| notification_write           | notification | Write  | Mark a notification or all notifications as read                                           |
+| label_read                   | label        | Read   | Read repository or organization labels                                                     |
+| label_write                  | label        | Write  | Write labels (repo or org): create, edit, delete                                           |
+| milestone_read               | milestone    | Read   | Read milestones: get one or list                                                           |
+| milestone_write              | milestone    | Write  | Write milestones: create, update, delete                                                   |
+| wiki_read                    | wiki         | Read   | Read wiki: list pages, get content, revision history                                       |
+| wiki_write                   | wiki         | Write  | Write wiki pages: create, update, delete                                                   |
+| timetracking_read            | timetracking | Read   | Read time tracking: issue/repo times, active stopwatches, your tracked times               |
+| timetracking_write           | timetracking | Write  | Write time tracking: stopwatches and entries                                               |
+| package_read                 | packages     | Read   | Read package registry: list packages, list versions, or get a version                      |
+| package_write                | packages     | Write  | Delete a package version (irreversible)                                                    |
+| list_issues                  | issue        | Read   | List repository issues                                                                     |
+| attachment_read              | issue        | Read   | Read issue/comment attachments: list metadata, get metadata, or download content           |
+| issue_read                   | issue        | Read   | Read issue: details, comments, or labels                                                   |
+| issue_write                  | issue        | Write  | Write issues: create, update, manage comments and labels                                   |
+| list_pull_requests           | pull_request | Read   | List repository pull requests                                                              |
+| pull_request_read            | pull_request | Read   | Read pull request: details, diff, files, status, reviews, review comments                  |
+| pull_request_write           | pull_request | Write  | Write pull requests: create, update, close, reopen, merge, update branch, manage reviewers |
+| pull_request_review_write    | pull_request | Write  | Write PR reviews: create, submit, delete, dismiss, reply to and resolve review comments    |
+| actions_config_read          | actions      | Read   | Read Actions secrets and variables                                                         |
+| actions_config_write         | actions      | Write  | Write Actions secrets and variables: upsert, create, update, delete                        |
+| actions_run_read             | actions      | Read   | Read Actions workflows, runs, jobs, logs, and artifacts                                    |
+| actions_run_write            | actions      | Write  | Write Actions runs: dispatch, cancel, rerun                                                |
+| create_repo                  | repository   | Write  | Create a new repository                                                                    |
+| fork_repo                    | repository   | Write  | Fork a repository                                                                          |
+| list_my_repos                | repository   | Read   | List repositories owned by the current user                                                |
+| list_org_repos               | repository   | Read   | List repositories in an organization                                                       |
+| get_repository_tree          | repository   | Read   | Get the repository file tree                                                               |
+| get_file_contents            | file         | Read   | Get file content and metadata                                                              |
+| get_dir_contents             | file         | Read   | Get the entries in a directory                                                             |
+| create_or_update_file        | file         | Write  | Create or update a file (provide sha to update an existing file)                           |
+| delete_file                  | file         | Write  | Delete a file                                                                              |
+| create_branch                | branch       | Write  | Create a new branch                                                                        |
+| delete_branch                | branch       | Write  | Delete a branch                                                                            |
+| list_branches                | branch       | Read   | List repository branches                                                                   |
+| create_tag                   | tag          | Write  | Create a tag                                                                               |
+| delete_tag                   | tag          | Write  | Delete a tag                                                                               |
+| get_tag                      | tag          | Read   | Get tag details                                                                            |
+| list_tags                    | tag          | Read   | List repository tags                                                                       |
+| list_commits                 | commit       | Read   | List repository commits                                                                    |
+| get_commit                   | commit       | Read   | Get commit details                                                                         |
+| create_release               | release      | Write  | Create a release                                                                           |
+| delete_release               | release      | Write  | Delete a release                                                                           |
+| get_release                  | release      | Read   | Get a release by ID                                                                        |
+| get_latest_release           | release      | Read   | Get the latest release                                                                     |
+| list_releases                | release      | Read   | List repository releases                                                                   |
 
-```text
-list all my repositories
+> **Note:** Several tools are consolidated, action-based tools, a single tool exposes multiple operations through a `method` parameter. Tools with `Write` access are hidden when the server runs in read-only mode (`-r` / `GITEA_READONLY`), and the exposed tool set can be filtered by scope with `-S` / `--scope` (`GITEA_SCOPES`) and/or by individual tool name with `-O` / `--tools` (`GITEA_TOOLS`).
+
+With neither flag set, every tool loads. `--scope` limits loading to tools whose Scope column value is in the given list; `--tools` limits loading to the named tools; setting both loads the union of the selected scopes and the individually named tools. Unknown scope names are ignored with a startup warning.
+
+```bash
+gitea-mcp -S issue,pull_request
+gitea-mcp --scope repository,branch --tools get_me
 ```
 
-## ✅ Available Tools
-
-The Gitea MCP Server supports the following tools:
-
-|               Tool                |    Scope     |                       Description                        |
-| :-------------------------------: | :----------: | :------------------------------------------------------: |
-|         get_my_user_info          |     User     |      Get the information of the authenticated user       |
-|           get_user_orgs           |     User     | Get organizations associated with the authenticated user |
-|            create_repo            |  Repository  |                 Create a new repository                  |
-|             fork_repo             |  Repository  |                    Fork a repository                     |
-|           list_my_repos           |  Repository  |  List all repositories owned by the authenticated user   |
-|           create_branch           |    Branch    |                   Create a new branch                    |
-|           delete_branch           |    Branch    |                     Delete a branch                      |
-|           list_branches           |    Branch    |            List all branches in a repository             |
-|          create_release           |   Release    |           Create a new release in a repository           |
-|          delete_release           |   Release    |            Delete a release from a repository            |
-|            get_release            |   Release    |                      Get a release                       |
-|        get_latest_release         |   Release    |          Get the latest release in a repository          |
-|           list_releases           |   Release    |            List all releases in a repository             |
-|            create_tag             |     Tag      |                     Create a new tag                     |
-|            delete_tag             |     Tag      |                       Delete a tag                       |
-|              get_tag              |     Tag      |                        Get a tag                         |
-|             list_tags             |     Tag      |              List all tags in a repository               |
-|         list_repo_commits         |    Commit    |             List all commits in a repository             |
-|         get_file_content          |     File     |          Get the content and metadata of a file          |
-|          get_dir_content          |     File     |           Get a list of entries in a directory           |
-|            create_file            |     File     |                    Create a new file                     |
-|            update_file            |     File     |                 Update an existing file                  |
-|            delete_file            |     File     |                      Delete a file                       |
-|        get_issue_by_index         |    Issue     |                Get an issue by its index                 |
-|         list_repo_issues          |    Issue     |             List all issues in a repository              |
-|           create_issue            |    Issue     |                    Create a new issue                    |
-|       create_issue_comment        |    Issue     |               Create a comment on an issue               |
-|            edit_issue             |    Issue     |                       Edit a issue                       |
-|        edit_issue_comment         |    Issue     |                Edit a comment on an issue                |
-|    get_issue_comments_by_index    |    Issue     |          Get comments of an issue by its index           |
-|     get_pull_request_by_index     | Pull Request |             Get a pull request by its index              |
-|       get_pull_request_diff       | Pull Request |                 Get a pull request diff                  |
-|      list_repo_pull_requests      | Pull Request |          List all pull requests in a repository          |
-|        create_pull_request        | Pull Request |                Create a new pull request                 |
-|   create_pull_request_reviewer    | Pull Request |             Add reviewers to a pull request              |
-|   delete_pull_request_reviewer    | Pull Request |           Remove reviewers from a pull request           |
-|     list_pull_request_reviews     | Pull Request |           List all reviews for a pull request            |
-|      get_pull_request_review      | Pull Request |               Get a specific review by ID                |
-| list_pull_request_review_comments | Pull Request |            List inline comments for a review             |
-|    create_pull_request_review     | Pull Request |      Create a review with optional inline comments       |
-|    submit_pull_request_review     | Pull Request |                 Submit a pending review                  |
-|    delete_pull_request_review     | Pull Request |                     Delete a review                      |
-|    dismiss_pull_request_review    | Pull Request |          Dismiss a review with optional message          |
-|           search_users            |     User     |                     Search for users                     |
-|         search_org_teams          | Organization |           Search for teams in an organization            |
-|          list_org_labels          | Organization |        List labels defined at organization level         |
-|         create_org_label          | Organization |            Create a label in an organization             |
-|          edit_org_label           | Organization |             Edit a label in an organization              |
-|         delete_org_label          | Organization |            Delete a label in an organization             |
-|           search_repos            |  Repository  |                 Search for repositories                  |
-|     list_repo_action_secrets      |   Actions    |     List repository Actions secrets (metadata only)      |
-|     upsert_repo_action_secret     |   Actions    |    Create/update (upsert) a repository Actions secret    |
-|     delete_repo_action_secret     |   Actions    |            Delete a repository Actions secret            |
-|      list_org_action_secrets      |   Actions    |    List organization Actions secrets (metadata only)     |
-|     upsert_org_action_secret      |   Actions    |  Create/update (upsert) an organization Actions secret   |
-|     delete_org_action_secret      |   Actions    |          Delete an organization Actions secret           |
-|    list_repo_action_variables     |   Actions    |            List repository Actions variables             |
-|     get_repo_action_variable      |   Actions    |            Get a repository Actions variable             |
-|    create_repo_action_variable    |   Actions    |           Create a repository Actions variable           |
-|    update_repo_action_variable    |   Actions    |           Update a repository Actions variable           |
-|    delete_repo_action_variable    |   Actions    |           Delete a repository Actions variable           |
-|     list_org_action_variables     |   Actions    |           List organization Actions variables            |
-|      get_org_action_variable      |   Actions    |           Get an organization Actions variable           |
-|    create_org_action_variable     |   Actions    |         Create an organization Actions variable          |
-|    update_org_action_variable     |   Actions    |         Update an organization Actions variable          |
-|    delete_org_action_variable     |   Actions    |         Delete an organization Actions variable          |
-|    list_repo_action_workflows     |   Actions    |            List repository Actions workflows             |
-|     get_repo_action_workflow      |   Actions    |            Get a repository Actions workflow             |
-|   dispatch_repo_action_workflow   |   Actions    |     Trigger (dispatch) a repository Actions workflow     |
-|       list_repo_action_runs       |   Actions    |               List repository Actions runs               |
-|        get_repo_action_run        |   Actions    |               Get a repository Actions run               |
-|      cancel_repo_action_run       |   Actions    |             Cancel a repository Actions run              |
-|       rerun_repo_action_run       |   Actions    |              Rerun a repository Actions run              |
-|       list_repo_action_jobs       |   Actions    |               List repository Actions jobs               |
-|     list_repo_action_run_jobs     |   Actions    |               List Actions jobs for a run                |
-|  get_repo_action_job_log_preview  |   Actions    |           Get a job log preview (tail/limited)           |
-|   download_repo_action_job_log    |   Actions    |               Download a job log to a file               |
-|   get_gitea_mcp_server_version    |    Server    |         Get the version of the Gitea MCP Server          |
-|          list_wiki_pages          |     Wiki     |           List all wiki pages in a repository            |
-|           get_wiki_page           |     Wiki     |           Get a wiki page content and metadata           |
-|        get_wiki_revisions         |     Wiki     |           Get revisions history of a wiki page           |
-|         create_wiki_page          |     Wiki     |                  Create a new wiki page                  |
-|         update_wiki_page          |     Wiki     |               Update an existing wiki page               |
-|         delete_wiki_page          |     Wiki     |                    Delete a wiki page                    |
-
-## 🐛 Debugging
-
-To enable debug mode, add the `-d` flag when running the Gitea MCP Server with http mode:
-
-```sh
-./gitea-mcp -t http [--port 8080] --token <your personal access token> -d
-```
-
-## 🛠 Troubleshooting
-
-If you encounter any issues, here are some common troubleshooting steps:
-
-1. **Check your PATH**: Ensure that the `gitea-mcp` binary is in a directory included in your system's PATH.
-2. **Verify dependencies**: Make sure you have all the required dependencies installed, such as `make` and `Golang`.
-3. **Review configuration**: Double-check your MCP configuration file for any errors or missing information.
-4. **Consult logs**: Check the logs for any error messages or warnings that can provide more information about the issue.
-
-Enjoy exploring and managing your Gitea repositories via chat!
+Many tools accept `page` and `per_page` for pagination. The maximum effective page size is the Gitea server's `[api].MAX_RESPONSE_ITEMS` setting (default **50**), larger values are silently capped.

README.zh-cn.md

@@ -2,40 +2,27 @@
 
 [English](README.md) | [繁體中文](README.zh-tw.md)
 
-**Gitea MCP 服务器** 是一个集成插件，旨在将 Gitea 与 Model Context Protocol (MCP) 系统连接起来。这允许通过 MCP 兼容的聊天界面无缝执行命令和管理仓库。
+**Gitea MCP 服务器** 将 [Gitea](https://about.gitea.com) 实例接入 [Model Context Protocol](https://modelcontextprotocol.io) 客户端，让仓库、问题、拉取请求等都能在兼容 MCP 的聊天界面中浏览和管理。
 
 [![在 VS Code 中使用 Docker 安装](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}) [![在 VS Code Insiders 中使用 Docker 安装](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}&quality=insiders)
 
-## 目录
+## 安装
 
-- [Gitea MCP 服务器](#gitea-mcp-服务器)
-  - [目录](#目录)
-  - [什么是 Gitea？](#什么是-gitea)
-  - [什么是 MCP？](#什么是-mcp)
-  - [🚧 安装](#-安装)
-    - [在 Claude Code 中使用](#在-claude-code-中使用)
-    - [在 VS Code 中使用](#在-vs-code-中使用)
-    - [📥 下载官方二进制版本](#-下载官方二进制版本)
-    - [🔧 从源码构建](#-从源码构建)
-    - [📁 加入 PATH](#-加入-path)
-  - [🚀 使用](#-使用)
-  - [✅ 可用工具](#-可用工具)
-  - [🐛 调试](#-调试)
-  - [🛠 疑难排解](#-疑难排解)
+可从 [发布页面](https://gitea.com/gitea/gitea-mcp/releases) 下载二进制文件并放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 镜像，也可用 `make` 和 Go 1.26 及以上从源码构建到 `$GOPATH/bin`：
 
-## 什么是 Gitea？
+```bash
+git clone https://gitea.com/gitea/gitea-mcp.git
+cd gitea-mcp
+make install
+```
 
-Gitea 是一个由社区管理的轻量级代码托管解决方案，使用 Go 语言编写，采用 MIT 许可证。Gitea 提供 Git 托管，包括仓库浏览、问题追踪、拉取请求等功能。
+## 配置
 
-## 什么是 MCP？
+Gitea 主机和访问令牌可通过命令行参数或环境变量提供，命令行参数优先。运行 `gitea-mcp --help` 可查看完整的参数与环境变量列表。日志写入 `$HOME/.gitea-mcp/gitea-mcp.log`，加上 `-d` 可启用调试日志。
 
-Model Context Protocol (MCP) 是一种协议，允许通过聊天界面整合各种工具和系统。它能够无缝执行命令并管理仓库、用户及其他资源。
+### Claude Code
 
-## 🚧 安装
-
-### 在 Claude Code 中使用
-
-此方式使用 `go run`，需要安装 [Go](https://go.dev)。
+通过 `go run` 运行服务器，需要安装 [Go](https://go.dev)：
 
 ```bash
 claude mcp add --transport stdio --scope user gitea \
@@ -44,15 +31,9 @@ claude mcp add --transport stdio --scope user gitea \
   -- go run gitea.com/gitea/gitea-mcp@latest -t stdio
 ```
 
-### 在 VS Code 中使用
+### VS Code
 
-要快速安装，请使用本 README 顶部的安装按钮。
-
-如需手动安装，请将以下 JSON 块添加到 VS Code 的用户设置 (JSON) 文件。可通过按 `Ctrl + Shift + P` 并输入 `Preferences: Open User Settings (JSON)`。
-
-也可添加到工作区的 `.vscode/mcp.json` 文件，方便与他人共享配置。
-
-> `.vscode/mcp.json` 文件不需要 `mcp` 键。
+可使用本 README 顶部的安装按钮，或将下面的内容加入用户设置 (JSON)，按 `Ctrl + Shift + P` 并输入 `Preferences: Open User Settings (JSON)` 即可打开。也可放在工作区的 `.vscode/mcp.json` 中，此时无需 `mcp` 键。
 
 ```json
 {
@@ -68,14 +49,7 @@ claude mcp add --transport stdio --scope user gitea \
     "servers": {
       "gitea-mcp": {
         "command": "docker",
-        "args": [
-          "run",
-          "-i",
-          "--rm",
-          "-e",
-          "GITEA_ACCESS_TOKEN",
-          "docker.gitea.com/gitea-mcp-server"
-        ],
+        "args": ["run", "-i", "--rm", "-e", "GITEA_ACCESS_TOKEN", "docker.gitea.com/gitea-mcp-server"],
         "env": {
           "GITEA_ACCESS_TOKEN": "${input:gitea_token}"
         }
@@ -85,59 +59,50 @@ claude mcp add --transport stdio --scope user gitea \
 }
 ```
 
-### 📥 下载官方二进制版本
+### OpenCode
 
-可在 [官方 Gitea MCP 二进制版本](https://gitea.com/gitea/gitea-mcp/releases) 下载。
+将下面的内容加入 [OpenCode](https://opencode.ai) 配置的顶层 `mcp` 对象：
 
-### 🔧 从源码构建
-
-可用 Git 下载源码：
-
-```bash
-git clone https://gitea.com/gitea/gitea-mcp.git
+```json
+    "gitea-mcp": {
+      "enabled": true,
+      "type": "local",
+      "command": [
+        "gitea-mcp",
+        "-t", "stdio",
+        "-H", "https://gitea.com",
+        "-T", "<your personal access token>"
+      ]
+    }
 ```
 
-构建前请先安装：
+### Mistral Vibe
 
-- make
-- Golang（建议 Go 1.24 及以上）
+将下面的内容加入 `~/.vibe/config.toml`：
 
-然后运行：
+```toml
+[[mcp_servers]]
+name = "gitea"
+transport = "stdio"
+command = "docker"
+args = ["run", "--rm", "-i", "-e", "GITEA_ACCESS_TOKEN", "-e", "GITEA_HOST", "docker.gitea.com/gitea-mcp-server"]
 
-```bash
-make install
+[mcp_servers.env]
+GITEA_ACCESS_TOKEN = "TOKEN"
+GITEA_HOST = "https://gitea.com"
 ```
 
-### 📁 加入 PATH
+### 其他客户端
 
-安装后，将 gitea-mcp 可执行文件复制到系统 PATH 目录，例如：
-
-```bash
-cp gitea-mcp /usr/local/bin/
-```
-
-## 🚀 使用
-
-此示例适用于 Cursor，也可在 VSCode 使用插件。  
-要配置 Gitea MCP 服务器，请将以下内容添加到 MCP 配置文件：
-
-- **stdio 模式**
+Cursor 等客户端可使用 stdio 命令：
 
 ```json
 {
   "mcpServers": {
     "gitea": {
       "command": "gitea-mcp",
-      "args": [
-        "-t",
-        "stdio",
-        "--host",
-        "https://gitea.com"
-        // "--token", "<your personal access token>"
-      ],
+      "args": ["-t", "stdio", "--host", "https://gitea.com"],
       "env": {
-        // "GITEA_HOST": "https://gitea.com",
-        // "GITEA_INSECURE": "true",
         "GITEA_ACCESS_TOKEN": "<your personal access token>"
       }
     }
@@ -145,7 +110,7 @@ cp gitea-mcp /usr/local/bin/
 }
 ```
 
-- **http 模式**
+或使用 http 端点，对应以 `gitea-mcp -t http --port 8080` 启动的服务器：
 
 ```json
 {
@@ -160,96 +125,74 @@ cp gitea-mcp /usr/local/bin/
 }
 ```
 
-**默认日志路径**: `$HOME/.gitea-mcp/gitea-mcp.log`
+配置完成后，可在聊天框输入 `列出我所有的仓库` 试试。
 
-> [!注意]
-> 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。  
-> 命令行参数优先。
+## 可用工具
 
-一切设置完成后，可在 MCP 聊天框输入：
+| 工具                           | 范围           | 访问 | 描述                                 |
+| :--------------------------- | :----------- | :- | :--------------------------------- |
+| get_gitea_mcp_server_version | version      | 读取 | 获取 Gitea MCP 服务器版本                 |
+| get_me                       | user         | 读取 | 获取当前已认证用户                          |
+| get_user_orgs                | user         | 读取 | 列出当前用户的组织                          |
+| search_users                 | search       | 读取 | 搜索用户                               |
+| search_org_teams             | search       | 读取 | 搜索组织中的团队                           |
+| search_repos                 | search       | 读取 | 搜索仓库                               |
+| search_issues                | search       | 读取 | 跨仓库搜索问题和拉取请求                       |
+| notification_read            | notification | 读取 | 读取通知：列出（可限定仓库）或按 ID 获取会话           |
+| notification_write           | notification | 写入 | 将某条或全部通知标记为已读                      |
+| label_read                   | label        | 读取 | 读取仓库或组织标签                          |
+| label_write                  | label        | 写入 | 写入标签（仓库或组织）：创建、编辑、删除               |
+| milestone_read               | milestone    | 读取 | 读取里程碑：获取单个或列出                      |
+| milestone_write              | milestone    | 写入 | 写入里程碑：创建、更新、删除                     |
+| wiki_read                    | wiki         | 读取 | 读取 Wiki：列出页面、获取内容、修订历史             |
+| wiki_write                   | wiki         | 写入 | 写入 Wiki 页面：创建、更新、删除                |
+| timetracking_read            | timetracking | 读取 | 读取时间跟踪：问题/仓库耗时、活动计时器、我的跟踪记录        |
+| timetracking_write           | timetracking | 写入 | 写入时间跟踪：计时器和记录条目                    |
+| package_read                 | packages     | 读取 | 读取软件包注册表：列出软件包、列出版本或获取某个版本         |
+| package_write                | packages     | 写入 | 删除软件包版本（不可恢复）                      |
+| list_issues                  | issue        | 读取 | 列出仓库问题                             |
+| attachment_read              | issue        | 读取 | 读取问题/评论附件：列出元数据、获取元数据或下载内容         |
+| issue_read                   | issue        | 读取 | 读取问题：详情、评论或标签                      |
+| issue_write                  | issue        | 写入 | 写入问题：创建、更新、管理评论和标签                 |
+| list_pull_requests           | pull_request | 读取 | 列出仓库拉取请求                           |
+| pull_request_read            | pull_request | 读取 | 读取拉取请求：详情、差异、变更文件、头部提交状态、审查、审查评论   |
+| pull_request_write           | pull_request | 写入 | 写入拉取请求：创建、更新、关闭、重新打开、合并、更新分支、管理审查者 |
+| pull_request_review_write    | pull_request | 写入 | 写入 PR 审查：创建、提交、删除、驳回、回复和解决审查评论 |
+| actions_config_read          | actions      | 读取 | 读取 Actions 密钥和变量                   |
+| actions_config_write         | actions      | 写入 | 写入 Actions 密钥和变量：更新插入、创建、更新、删除     |
+| actions_run_read             | actions      | 读取 | 读取 Actions 工作流、运行、作业、日志和构件         |
+| actions_run_write            | actions      | 写入 | 写入 Actions 运行：触发、取消、重新运行           |
+| create_repo                  | repository   | 写入 | 创建新仓库                              |
+| fork_repo                    | repository   | 写入 | 复刻仓库                               |
+| list_my_repos                | repository   | 读取 | 列出当前用户拥有的仓库                        |
+| list_org_repos               | repository   | 读取 | 列出组织中的仓库                           |
+| get_repository_tree          | repository   | 读取 | 获取仓库文件树                            |
+| get_file_contents            | file         | 读取 | 获取文件内容和元数据                         |
+| get_dir_contents             | file         | 读取 | 获取目录中的条目                           |
+| create_or_update_file        | file         | 写入 | 创建或更新文件（提供 sha 以更新现有文件）            |
+| delete_file                  | file         | 写入 | 删除文件                               |
+| create_branch                | branch       | 写入 | 创建新分支                              |
+| delete_branch                | branch       | 写入 | 删除分支                               |
+| list_branches                | branch       | 读取 | 列出仓库分支                             |
+| create_tag                   | tag          | 写入 | 创建标签                               |
+| delete_tag                   | tag          | 写入 | 删除标签                               |
+| get_tag                      | tag          | 读取 | 获取标签详情                             |
+| list_tags                    | tag          | 读取 | 列出仓库标签                             |
+| list_commits                 | commit       | 读取 | 列出仓库提交                             |
+| get_commit                   | commit       | 读取 | 获取提交详情                             |
+| create_release               | release      | 写入 | 创建版本发布                             |
+| delete_release               | release      | 写入 | 删除版本发布                             |
+| get_release                  | release      | 读取 | 按 ID 获取版本发布                        |
+| get_latest_release           | release      | 读取 | 获取最新版本发布                           |
+| list_releases                | release      | 读取 | 列出仓库版本发布                           |
 
-```text
-列出我所有的仓库
+> **说明：** 部分工具是聚合的、基于操作的工具，单个工具通过 `method` 参数暴露多个操作。当服务器以只读模式运行时（`-r` / `GITEA_READONLY`），访问为「写入」的工具会被隐藏；可通过 `-S` / `--scope`（`GITEA_SCOPES`）按范围过滤，或通过 `-O` / `--tools`（`GITEA_TOOLS`）按工具名称过滤对外暴露的工具集合。
+
+未设置任一参数时，会加载所有工具；仅设置 `--scope` 时，会加载这些范围内的所有工具；仅设置 `--tools` 时，只会加载指定名称的工具；两者都设置时，会加载所选范围的工具与指定工具名称的并集。范围名称即上表「范围」列中的值，未知的范围名称仅会在启动时产生警告并被忽略。
+
+```bash
+gitea-mcp -S issue,pull_request
+gitea-mcp --scope repository,branch --tools get_me
 ```
 
-## ✅ 可用工具
-
-Gitea MCP 服务器支持以下工具：
-
-|               工具                |   范围   |            描述            |
-| :-------------------------------: | :------: | :------------------------: |
-|         get_my_user_info          |   用户   |     获取已认证用户信息     |
-|           get_user_orgs           |   用户   |   获取已认证用户关联组织   |
-|            create_repo            |   仓库   |         创建新仓库         |
-|             fork_repo             |   仓库   |          复刻仓库          |
-|           list_my_repos           |   仓库   |      列出用户所有仓库      |
-|           create_branch           |   分支   |         创建新分支         |
-|           delete_branch           |   分支   |          删除分支          |
-|           list_branches           |   分支   |        列出所有分支        |
-|          create_release           | 版本发布 |       创建新版本发布       |
-|          delete_release           | 版本发布 |        删除版本发布        |
-|            get_release            | 版本发布 |        获取版本发布        |
-|        get_latest_release         | 版本发布 |      获取最新版本发布      |
-|           list_releases           | 版本发布 |      列出所有版本发布      |
-|            create_tag             |   标签   |         创建新标签         |
-|            delete_tag             |   标签   |          删除标签          |
-|              get_tag              |   标签   |          获取标签          |
-|             list_tags             |   标签   |        列出所有标签        |
-|         list_repo_commits         |   提交   |        列出所有提交        |
-|         get_file_content          |   文件   |    获取文件内容和元数据    |
-|          get_dir_content          |   文件   |      获取目录内容列表      |
-|            create_file            |   文件   |         创建新文件         |
-|            update_file            |   文件   |        更新现有文件        |
-|            delete_file            |   文件   |          删除文件          |
-|        get_issue_by_index         |   问题   |       按索引获取问题       |
-|         list_repo_issues          |   问题   |        列出所有问题        |
-|           create_issue            |   问题   |         创建新问题         |
-|       create_issue_comment        |   问题   |      在问题上创建评论      |
-|            edit_issue             |   问题   |          编辑问题          |
-|        edit_issue_comment         |   问题   |        编辑问题评论        |
-|    get_issue_comments_by_index    |   问题   |     按索引获取问题评论     |
-|     get_pull_request_by_index     | 拉取请求 |     按索引获取拉取请求     |
-|      list_repo_pull_requests      | 拉取请求 |      列出所有拉取请求      |
-|        create_pull_request        | 拉取请求 |       创建新拉取请求       |
-|   create_pull_request_reviewer    | 拉取请求 |    为拉取请求添加审查者    |
-|   delete_pull_request_reviewer    | 拉取请求 |    移除拉取请求的审查者    |
-|     list_pull_request_reviews     | 拉取请求 |   列出拉取请求的所有审查   |
-|      get_pull_request_review      | 拉取请求 |     按 ID 获取特定审查     |
-| list_pull_request_review_comments | 拉取请求 |     列出审查的行内评论     |
-|    create_pull_request_review     | 拉取请求 |  创建审查（可含行内评论）  |
-|    submit_pull_request_review     | 拉取请求 |      提交待处理的审查      |
-|    delete_pull_request_review     | 拉取请求 |          删除审查          |
-|    dismiss_pull_request_review    | 拉取请求 |    驳回审查（可附消息）    |
-|           search_users            |   用户   |          搜索用户          |
-|         search_org_teams          |   组织   |        搜索组织团队        |
-|          list_org_labels          |   组织   |        列出组织标签        |
-|         create_org_label          |   组织   |        创建组织标签        |
-|          edit_org_label           |   组织   |        编辑组织标签        |
-|         delete_org_label          |   组织   |        删除组织标签        |
-|           search_repos            |   仓库   |          搜索仓库          |
-|   get_gitea_mcp_server_version    |  服务器  | 获取 Gitea MCP 服务器版本  |
-|          list_wiki_pages          |   Wiki   |     列出所有 Wiki 页面     |
-|           get_wiki_page           |   Wiki   | 获取 Wiki 页面内容和元数据 |
-|        get_wiki_revisions         |   Wiki   |     获取 Wiki 修订历史     |
-|         create_wiki_page          |   Wiki   |      创建新 Wiki 页面      |
-|         update_wiki_page          |   Wiki   |     更新现有 Wiki 页面     |
-|         delete_wiki_page          |   Wiki   |       删除 Wiki 页面       |
-
-## 🐛 调试
-
-启用调试模式时，请在 http 模式运行 Gitea MCP 服务器时加上 `-d` 标志：
-
-```sh
-./gitea-mcp -t http [--port 8080] --token <your personal access token> -d
-```
-
-## 🛠 疑难排解
-
-如遇问题，可参考以下步骤：
-
-1. **检查 PATH**：确保 `gitea-mcp` 可执行文件已在系统 PATH 目录中。
-2. **验证依赖**：确认已安装 `make` 和 `Golang` 等必要依赖。
-3. **检查配置**：仔细检查 MCP 配置文件是否有错误或遗漏。
-4. **查看日志**：检查日志消息或警告以获取更多信息。
-
-享受通过聊天探索和管理您的 Gitea 仓库！
+许多工具支持 `page` 和 `per_page` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认 **50**），超出的值会被静默截断。

README.zh-tw.md

@@ -2,40 +2,27 @@
 
 [English](README.md) | [简体中文](README.zh-cn.md)
 
-**Gitea MCP 伺服器** 是一個整合插件，旨在將 Gitea 與 Model Context Protocol (MCP) 系統連接起來。這允許通過 MCP 兼容的聊天界面無縫執行命令和管理倉庫。
+**Gitea MCP 伺服器** 將 [Gitea](https://about.gitea.com) 實例接入 [Model Context Protocol](https://modelcontextprotocol.io) 客戶端，讓倉庫、問題、拉取請求等都能在相容 MCP 的聊天介面中瀏覽與管理。
 
 [![在 VS Code 中使用 Docker 安裝](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}) [![在 VS Code Insiders 中使用 Docker 安裝](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}&quality=insiders)
 
-## 目錄
+## 安裝
 
-- [Gitea MCP 伺服器](#gitea-mcp-伺服器)
-  - [目錄](#目錄)
-  - [什麼是 Gitea？](#什麼是-gitea)
-  - [什麼是 MCP？](#什麼是-mcp)
-  - [🚧 安裝](#-安裝)
-    - [在 Claude Code 中使用](#在-claude-code-中使用)
-    - [在 VS Code 中使用](#在-vs-code-中使用)
-    - [📥 下載官方二進位版本](#-下載官方二進位版本)
-    - [🔧 從原始碼建置](#-從原始碼建置)
-    - [📁 加入 PATH](#-加入-path)
-  - [🚀 使用](#-使用)
-  - [✅ 可用工具](#-可用工具)
-  - [🐛 調試](#-調試)
-  - [🛠 疑難排解](#-疑難排解)
+可從 [發布頁面](https://gitea.com/gitea/gitea-mcp/releases) 下載二進位檔並放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 映像檔，也可用 `make` 與 Go 1.26 以上從原始碼建置到 `$GOPATH/bin`：
 
-## 什麼是 Gitea？
+```bash
+git clone https://gitea.com/gitea/gitea-mcp.git
+cd gitea-mcp
+make install
+```
 
-Gitea 是一個由社群管理的輕量級程式碼託管解決方案，使用 Go 語言編寫，採用 MIT 授權。Gitea 提供 Git 託管，包括倉庫瀏覽、議題追蹤、拉取請求等功能。
+## 設定
 
-## 什麼是 MCP？
+Gitea 主機與存取令牌可透過命令列參數或環境變數提供，命令列參數優先。執行 `gitea-mcp --help` 可查看完整的參數與環境變數列表。日誌寫入 `$HOME/.gitea-mcp/gitea-mcp.log`，加上 `-d` 可啟用除錯日誌。
 
-Model Context Protocol (MCP) 是一種協議，允許透過聊天介面整合各種工具與系統。它能夠無縫執行命令並管理倉庫、使用者及其他資源。
+### Claude Code
 
-## 🚧 安裝
-
-### 在 Claude Code 中使用
-
-此方式使用 `go run`，需要安裝 [Go](https://go.dev)。
+透過 `go run` 執行伺服器，需要安裝 [Go](https://go.dev)：
 
 ```bash
 claude mcp add --transport stdio --scope user gitea \
@@ -44,15 +31,9 @@ claude mcp add --transport stdio --scope user gitea \
   -- go run gitea.com/gitea/gitea-mcp@latest -t stdio
 ```
 
-### 在 VS Code 中使用
+### VS Code
 
-欲快速安裝，請使用本 README 頂部的安裝按鈕。
-
-如需手動安裝，請將下列 JSON 區塊加入 VS Code 的使用者設定 (JSON) 檔案。可按 `Ctrl + Shift + P` 並輸入 `Preferences: Open User Settings (JSON)`。
-
-也可加入至工作區的 `.vscode/mcp.json` 檔案，方便與他人共享設定。
-
-> `.vscode/mcp.json` 檔案不需 `mcp` 鍵。
+可使用本 README 頂部的安裝按鈕，或將下面的內容加入使用者設定 (JSON)，按 `Ctrl + Shift + P` 並輸入 `Preferences: Open User Settings (JSON)` 即可開啟。也可放在工作區的 `.vscode/mcp.json` 中，此時不需要 `mcp` 鍵。
 
 ```json
 {
@@ -68,14 +49,7 @@ claude mcp add --transport stdio --scope user gitea \
     "servers": {
       "gitea-mcp": {
         "command": "docker",
-        "args": [
-          "run",
-          "-i",
-          "--rm",
-          "-e",
-          "GITEA_ACCESS_TOKEN",
-          "docker.gitea.com/gitea-mcp-server"
-        ],
+        "args": ["run", "-i", "--rm", "-e", "GITEA_ACCESS_TOKEN", "docker.gitea.com/gitea-mcp-server"],
         "env": {
           "GITEA_ACCESS_TOKEN": "${input:gitea_token}"
         }
@@ -85,59 +59,50 @@ claude mcp add --transport stdio --scope user gitea \
 }
 ```
 
-### 📥 下載官方二進位版本
+### OpenCode
 
-可至 [官方 Gitea MCP 二進位版本](https://gitea.com/gitea/gitea-mcp/releases) 下載。
+將下面的內容加入 [OpenCode](https://opencode.ai) 設定的頂層 `mcp` 物件：
 
-### 🔧 從原始碼建置
-
-可用 Git 下載原始碼：
-
-```bash
-git clone https://gitea.com/gitea/gitea-mcp.git
+```json
+    "gitea-mcp": {
+      "enabled": true,
+      "type": "local",
+      "command": [
+        "gitea-mcp",
+        "-t", "stdio",
+        "-H", "https://gitea.com",
+        "-T", "<your personal access token>"
+      ]
+    }
 ```
 
-建置前請先安裝：
+### Mistral Vibe
 
-- make
-- Golang（建議 Go 1.24 以上）
+將下面的內容加入 `~/.vibe/config.toml`：
 
-然後執行：
+```toml
+[[mcp_servers]]
+name = "gitea"
+transport = "stdio"
+command = "docker"
+args = ["run", "--rm", "-i", "-e", "GITEA_ACCESS_TOKEN", "-e", "GITEA_HOST", "docker.gitea.com/gitea-mcp-server"]
 
-```bash
-make install
+[mcp_servers.env]
+GITEA_ACCESS_TOKEN = "TOKEN"
+GITEA_HOST = "https://gitea.com"
 ```
 
-### 📁 加入 PATH
+### 其他客戶端
 
-安裝後，將 gitea-mcp 執行檔複製到系統 PATH 目錄，例如：
-
-```bash
-cp gitea-mcp /usr/local/bin/
-```
-
-## 🚀 使用
-
-此範例適用於 Cursor，也可在 VSCode 使用插件。  
-欲設定 Gitea MCP 伺服器，請將下列內容加入 MCP 設定檔：
-
-- **stdio 模式**
+Cursor 等客戶端可使用 stdio 命令：
 
 ```json
 {
   "mcpServers": {
     "gitea": {
       "command": "gitea-mcp",
-      "args": [
-        "-t",
-        "stdio",
-        "--host",
-        "https://gitea.com"
-        // "--token", "<your personal access token>"
-      ],
+      "args": ["-t", "stdio", "--host", "https://gitea.com"],
       "env": {
-        // "GITEA_HOST": "https://gitea.com",
-        // "GITEA_INSECURE": "true",
         "GITEA_ACCESS_TOKEN": "<your personal access token>"
       }
     }
@@ -145,7 +110,7 @@ cp gitea-mcp /usr/local/bin/
 }
 ```
 
-- **http 模式**
+或使用 http 端點，對應以 `gitea-mcp -t http --port 8080` 啟動的伺服器：
 
 ```json
 {
@@ -160,96 +125,74 @@ cp gitea-mcp /usr/local/bin/
 }
 ```
 
-**預設日誌路徑**: `$HOME/.gitea-mcp/gitea-mcp.log`
+設定完成後，可在聊天框輸入 `列出我所有的倉庫` 試試。
 
-> [!注意]
-> 可用命令列參數或環境變數提供 Gitea 主機與存取令牌。  
-> 命令列參數優先。
+## 可用工具
 
-一切設定完成後，可在 MCP 聊天框輸入：
+| 工具                           | 範圍           | 存取 | 描述                                 |
+| :--------------------------- | :----------- | :- | :--------------------------------- |
+| get_gitea_mcp_server_version | version      | 讀取 | 取得 Gitea MCP 伺服器版本                 |
+| get_me                       | user         | 讀取 | 取得目前已認證用戶                          |
+| get_user_orgs                | user         | 讀取 | 列出目前用戶的組織                          |
+| search_users                 | search       | 讀取 | 搜尋用戶                               |
+| search_org_teams             | search       | 讀取 | 搜尋組織中的團隊                           |
+| search_repos                 | search       | 讀取 | 搜尋倉庫                               |
+| search_issues                | search       | 讀取 | 跨倉庫搜尋問題和拉取請求                       |
+| notification_read            | notification | 讀取 | 讀取通知：列出（可限定倉庫）或依 ID 取得會話           |
+| notification_write           | notification | 寫入 | 將某條或全部通知標記為已讀                      |
+| label_read                   | label        | 讀取 | 讀取倉庫或組織標籤                          |
+| label_write                  | label        | 寫入 | 寫入標籤（倉庫或組織）：創建、編輯、刪除               |
+| milestone_read               | milestone    | 讀取 | 讀取里程碑：取得單個或列出                      |
+| milestone_write              | milestone    | 寫入 | 寫入里程碑：創建、更新、刪除                     |
+| wiki_read                    | wiki         | 讀取 | 讀取 Wiki：列出頁面、取得內容、修訂歷史             |
+| wiki_write                   | wiki         | 寫入 | 寫入 Wiki 頁面：創建、更新、刪除                |
+| timetracking_read            | timetracking | 讀取 | 讀取時間追蹤：問題/倉庫耗時、活動計時器、我的追蹤記錄        |
+| timetracking_write           | timetracking | 寫入 | 寫入時間追蹤：計時器和記錄項目                    |
+| package_read                 | packages     | 讀取 | 讀取軟體套件註冊表：列出套件、列出版本或取得某個版本         |
+| package_write                | packages     | 寫入 | 刪除軟體套件版本（不可復原）                     |
+| list_issues                  | issue        | 讀取 | 列出倉庫問題                             |
+| attachment_read              | issue        | 讀取 | 讀取問題/評論附件：列出中繼資料、取得中繼資料或下載內容       |
+| issue_read                   | issue        | 讀取 | 讀取問題：詳情、評論或標籤                      |
+| issue_write                  | issue        | 寫入 | 寫入問題：創建、更新、管理評論和標籤                 |
+| list_pull_requests           | pull_request | 讀取 | 列出倉庫拉取請求                           |
+| pull_request_read            | pull_request | 讀取 | 讀取拉取請求：詳情、差異、變更檔案、頭部提交狀態、審查、審查評論   |
+| pull_request_write           | pull_request | 寫入 | 寫入拉取請求：創建、更新、關閉、重新開啟、合併、更新分支、管理審查者 |
+| pull_request_review_write    | pull_request | 寫入 | 寫入 PR 審查：創建、提交、刪除、駁回、回覆和解決審查評論 |
+| actions_config_read          | actions      | 讀取 | 讀取 Actions 密鑰和變數                   |
+| actions_config_write         | actions      | 寫入 | 寫入 Actions 密鑰和變數：更新插入、創建、更新、刪除     |
+| actions_run_read             | actions      | 讀取 | 讀取 Actions 工作流程、執行、作業、日誌和產物        |
+| actions_run_write            | actions      | 寫入 | 寫入 Actions 執行：觸發、取消、重新執行           |
+| create_repo                  | repository   | 寫入 | 創建新倉庫                              |
+| fork_repo                    | repository   | 寫入 | 復刻倉庫                               |
+| list_my_repos                | repository   | 讀取 | 列出目前用戶擁有的倉庫                        |
+| list_org_repos               | repository   | 讀取 | 列出組織中的倉庫                           |
+| get_repository_tree          | repository   | 讀取 | 取得倉庫檔案樹                            |
+| get_file_contents            | file         | 讀取 | 取得檔案內容與中繼資料                        |
+| get_dir_contents             | file         | 讀取 | 取得目錄中的項目                           |
+| create_or_update_file        | file         | 寫入 | 創建或更新檔案（提供 sha 以更新現有檔案）            |
+| delete_file                  | file         | 寫入 | 刪除檔案                               |
+| create_branch                | branch       | 寫入 | 創建新分支                              |
+| delete_branch                | branch       | 寫入 | 刪除分支                               |
+| list_branches                | branch       | 讀取 | 列出倉庫分支                             |
+| create_tag                   | tag          | 寫入 | 創建標籤                               |
+| delete_tag                   | tag          | 寫入 | 刪除標籤                               |
+| get_tag                      | tag          | 讀取 | 取得標籤詳情                             |
+| list_tags                    | tag          | 讀取 | 列出倉庫標籤                             |
+| list_commits                 | commit       | 讀取 | 列出倉庫提交                             |
+| get_commit                   | commit       | 讀取 | 取得提交詳情                             |
+| create_release               | release      | 寫入 | 創建版本發布                             |
+| delete_release               | release      | 寫入 | 刪除版本發布                             |
+| get_release                  | release      | 讀取 | 依 ID 取得版本發布                        |
+| get_latest_release           | release      | 讀取 | 取得最新版本發布                           |
+| list_releases                | release      | 讀取 | 列出倉庫版本發布                           |
 
-```text
-列出我所有的倉庫
+> **說明：** 部分工具是聚合的、基於操作的工具，單個工具透過 `method` 參數暴露多個操作。當伺服器以唯讀模式執行時（`-r` / `GITEA_READONLY`），存取為「寫入」的工具會被隱藏；可透過 `-S` / `--scope`（`GITEA_SCOPES`）依範圍過濾，或透過 `-O` / `--tools`（`GITEA_TOOLS`）依工具名稱過濾對外暴露的工具集合。
+
+未設定任一參數時，會載入所有工具；僅設定 `--scope` 時，會載入這些範圍內的所有工具；僅設定 `--tools` 時，只會載入指定名稱的工具；兩者皆設定時，會載入所選範圍的工具與指定工具名稱的聯集。範圍名稱即上表「範圍」欄中的值，未知的範圍名稱僅會在啟動時發出警告並被忽略。
+
+```bash
+gitea-mcp -S issue,pull_request
+gitea-mcp --scope repository,branch --tools get_me
 ```
 
-## ✅ 可用工具
-
-Gitea MCP 伺服器支援以下工具：
-
-|               工具                |   範圍   |             描述             |
-| :-------------------------------: | :------: | :--------------------------: |
-|         get_my_user_info          |   用戶   |      取得已認證用戶資訊      |
-|           get_user_orgs           |   用戶   |    取得已認證用戶所屬組織    |
-|            create_repo            |   倉庫   |          創建新倉庫          |
-|             fork_repo             |   倉庫   |           復刻倉庫           |
-|           list_my_repos           |   倉庫   |       列出用戶所有倉庫       |
-|           create_branch           |   分支   |          創建新分支          |
-|           delete_branch           |   分支   |           刪除分支           |
-|           list_branches           |   分支   |         列出所有分支         |
-|          create_release           | 版本發布 |        創建新版本發布        |
-|          delete_release           | 版本發布 |         刪除版本發布         |
-|            get_release            | 版本發布 |         取得版本發布         |
-|        get_latest_release         | 版本發布 |       取得最新版本發布       |
-|           list_releases           | 版本發布 |       列出所有版本發布       |
-|            create_tag             |   標籤   |          創建新標籤          |
-|            delete_tag             |   標籤   |           刪除標籤           |
-|              get_tag              |   標籤   |           取得標籤           |
-|             list_tags             |   標籤   |         列出所有標籤         |
-|         list_repo_commits         |   提交   |         列出所有提交         |
-|         get_file_content          |   文件   |    取得文件內容與中繼資料    |
-|          get_dir_content          |   文件   |       取得目錄內容列表       |
-|            create_file            |   文件   |          創建新文件          |
-|            update_file            |   文件   |         更新現有文件         |
-|            delete_file            |   文件   |           刪除文件           |
-|        get_issue_by_index         |   問題   |        依索引取得問題        |
-|         list_repo_issues          |   問題   |         列出所有問題         |
-|           create_issue            |   問題   |          創建新問題          |
-|       create_issue_comment        |   問題   |       在問題上創建評論       |
-|            edit_issue             |   問題   |           編輯問題           |
-|        edit_issue_comment         |   問題   |         編輯問題評論         |
-|    get_issue_comments_by_index    |   問題   |      依索引取得問題評論      |
-|     get_pull_request_by_index     | 拉取請求 |      依索引取得拉取請求      |
-|      list_repo_pull_requests      | 拉取請求 |       列出所有拉取請求       |
-|        create_pull_request        | 拉取請求 |        創建新拉取請求        |
-|   create_pull_request_reviewer    | 拉取請求 |     為拉取請求添加審查者     |
-|   delete_pull_request_reviewer    | 拉取請求 |     移除拉取請求的審查者     |
-|     list_pull_request_reviews     | 拉取請求 |    列出拉取請求的所有審查    |
-|      get_pull_request_review      | 拉取請求 |      依 ID 取得特定審查      |
-| list_pull_request_review_comments | 拉取請求 |      列出審查的行內評論      |
-|    create_pull_request_review     | 拉取請求 |   創建審查（可含行內評論）   |
-|    submit_pull_request_review     | 拉取請求 |       提交待處理的審查       |
-|    delete_pull_request_review     | 拉取請求 |           刪除審查           |
-|    dismiss_pull_request_review    | 拉取請求 |     駁回審查（可附訊息）     |
-|           search_users            |   用戶   |           搜尋用戶           |
-|         search_org_teams          |   組織   |         搜尋組織團隊         |
-|          list_org_labels          |   組織   |         列出組織標籤         |
-|         create_org_label          |   組織   |         創建組織標籤         |
-|          edit_org_label           |   組織   |         編輯組織標籤         |
-|         delete_org_label          |   組織   |         刪除組織標籤         |
-|           search_repos            |   倉庫   |           搜尋倉庫           |
-|   get_gitea_mcp_server_version    |  伺服器  |  取得 Gitea MCP 伺服器版本   |
-|          list_wiki_pages          |   Wiki   |      列出所有 Wiki 頁面      |
-|           get_wiki_page           |   Wiki   | 取得 Wiki 頁面內容與中繼資料 |
-|        get_wiki_revisions         |   Wiki   |      取得 Wiki 修訂歷史      |
-|         create_wiki_page          |   Wiki   |       創建新 Wiki 頁面       |
-|         update_wiki_page          |   Wiki   |      更新現有 Wiki 頁面      |
-|         delete_wiki_page          |   Wiki   |        刪除 Wiki 頁面        |
-
-## 🐛 調試
-
-啟用調試模式時，請在 http 模式執行 Gitea MCP 伺服器時加上 `-d` 旗標：
-
-```sh
-./gitea-mcp -t http [--port 8080] --token <your personal access token> -d
-```
-
-## 🛠 疑難排解
-
-如遇問題，可參考以下步驟：
-
-1. **檢查 PATH**：確保 `gitea-mcp` 執行檔已在系統 PATH 目錄中。
-2. **驗證依賴**：確認已安裝 `make` 與 `Golang` 等必要依賴。
-3. **檢查設定**：仔細檢查 MCP 設定檔是否有錯誤或遺漏。
-4. **查看日誌**：檢查日誌訊息或警告以獲取更多資訊。
-
-享受透過聊天探索與管理您的 Gitea 倉庫！
+許多工具支援 `page` 和 `per_page` 分頁參數。最大有效頁面大小由 Gitea 伺服器的 `[api].MAX_RESPONSE_ITEMS` 設定決定（預設 **50**），超出的值會被靜默截斷。

cmd/cmd.go

@@ -3,7 +3,12 @@ package cmd
 import (
 	"context"
 	"flag"
+	"fmt"
+	"io"
 	"os"
+	"strconv"
+	"strings"
+	"text/tabwriter"
 
 	"gitea.com/gitea/gitea-mcp/operation"
 	flagPkg "gitea.com/gitea/gitea-mcp/pkg/flag"
@@ -14,59 +19,80 @@ var (
 	host                            string
 	port                            int
 	token                           string
+	tools                           string
+	scopes                          string
+	version                         bool
+	maxInlineAttachmentBytes        int
+	maxInlineAttachmentBytesFlagSet bool
+	osExit                          = os.Exit
 )
 
-func init() {
-	flag.StringVar(
-		&flagPkg.Mode,
-		"t",
-		"stdio",
-		"Transport type (stdio or http)",
-	)
-	flag.StringVar(
-		&flagPkg.Mode,
-		"transport",
-		"stdio",
-		"Transport type (stdio or http)",
-	)
-	flag.StringVar(
-		&host,
-		"host",
-		os.Getenv("GITEA_HOST"),
-		"Gitea host",
-	)
-	flag.IntVar(
-		&port,
-		"port",
-		8080,
-		"http port",
-	)
-	flag.StringVar(
-		&token,
-		"token",
-		"",
-		"Your personal access token",
-	)
-	flag.BoolVar(
-		&flagPkg.ReadOnly,
-		"read-only",
-		false,
-		"Read-only mode",
-	)
-	flag.BoolVar(
-		&flagPkg.Debug,
-		"d",
-		false,
-		"debug mode (If -d flag is provided, debug mode will be enabled by default)",
-	)
-	flag.BoolVar(
-		&flagPkg.Insecure,
-		"insecure",
-		false,
-		"ignore TLS certificate errors",
-	)
+func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, readFile func(string) ([]byte, error), stderr io.Writer) {
+	fs.StringVar(&flagPkg.Mode, "t", "stdio", "")
+	fs.StringVar(&flagPkg.Mode, "transport", "stdio", "")
+	fs.StringVar(&host, "H", getenv("GITEA_HOST"), "")
+	fs.StringVar(&host, "host", getenv("GITEA_HOST"), "")
+	fs.IntVar(&port, "p", 8080, "")
+	fs.IntVar(&port, "port", 8080, "")
+	fs.StringVar(&token, "T", "", "")
+	fs.StringVar(&token, "token", "", "")
+	fs.BoolVar(&flagPkg.ReadOnly, "r", false, "")
+	fs.BoolVar(&flagPkg.ReadOnly, "read-only", false, "")
+	defaultTools := getenv("GITEA_TOOLS")
+	fs.StringVar(&tools, "O", defaultTools, "")
+	fs.StringVar(&tools, "tools", defaultTools, "")
+	defaultScopes := getenv("GITEA_SCOPES")
+	fs.StringVar(&scopes, "S", defaultScopes, "")
+	fs.StringVar(&scopes, "scope", defaultScopes, "")
+	fs.BoolVar(&flagPkg.Debug, "d", false, "")
+	fs.BoolVar(&flagPkg.Debug, "debug", false, "")
+	fs.BoolVar(&flagPkg.Insecure, "k", false, "")
+	fs.BoolVar(&flagPkg.Insecure, "insecure", false, "")
+	fs.BoolVar(&version, "v", false, "")
+	fs.BoolVar(&version, "version", false, "")
+	maxInlineAttachmentBytes = 5 * 1024 * 1024
+	fs.Func("max-inline-attachment-bytes", "", func(val string) error {
+		parsed, err := strconv.Atoi(val)
+		if err != nil || parsed < 0 {
+			return fmt.Errorf("invalid value %q", val)
+		}
+		maxInlineAttachmentBytes = parsed
+		maxInlineAttachmentBytesFlagSet = true
+		return nil
+	})
 
-	flag.Parse()
+	fs.Usage = func() {
+		w := tabwriter.NewWriter(stderr, 0, 0, 3, ' ', 0)
+		fmt.Fprintln(stderr, "Usage: gitea-mcp [options]")
+		fmt.Fprintln(stderr)
+		fmt.Fprintln(stderr, "Options:")
+		fmt.Fprintf(w, "  -t, -transport <type>\tTransport type: stdio or http (default: stdio)\n")
+		fmt.Fprintf(w, "  -H, -host <url>\tGitea host URL (default: https://gitea.com)\n")
+		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, "  -S, -scope <names>\tComma-separated list of tool scopes 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, "  -max-inline-attachment-bytes <bytes>\tInline image attachments up to this size (default: 5242880)\n")
+		fmt.Fprintf(w, "  -v, -version\tPrint version and exit\n")
+		fmt.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_MAX_INLINE_ATTACHMENT_BYTES\tOverride inline image attachment size limit in bytes\n")
+		fmt.Fprintf(w, "  GITEA_READONLY\tSet to 'true' for read-only mode\n")
+		fmt.Fprintf(w, "  GITEA_SCOPES\tComma-separated list of tool scopes to expose\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()
+	}
+
+	_ = fs.Parse(args)
 
 	flagPkg.Host = host
 	if flagPkg.Host == "" {
@@ -74,37 +100,92 @@ func init() {
 	}
 
 	flagPkg.Port = port
+	flagPkg.MaxInlineAttachmentBytes = maxInlineAttachmentBytes
 
 	flagPkg.Token = token
 	if flagPkg.Token == "" {
-		flagPkg.Token = os.Getenv("GITEA_ACCESS_TOKEN")
+		flagPkg.Token = getenv("GITEA_ACCESS_TOKEN")
+	}
+	if flagPkg.Token == "" {
+		if tokenFile := getenv("GITEA_ACCESS_TOKEN_FILE"); tokenFile != "" {
+			data, err := readFile(tokenFile)
+			if err != nil {
+				fmt.Fprintf(stderr, "error reading GITEA_ACCESS_TOKEN_FILE: %v\n", err)
+				osExit(1)
+			}
+			flagPkg.Token = strings.TrimRight(string(data), "\r\n")
+		}
 	}
 
-	if os.Getenv("MCP_MODE") != "" {
-		flagPkg.Mode = os.Getenv("MCP_MODE")
+	if getenv("MCP_MODE") != "" {
+		flagPkg.Mode = getenv("MCP_MODE")
 	}
-
-	if os.Getenv("GITEA_READONLY") == "true" {
+	if getenv("GITEA_READONLY") == "true" {
 		flagPkg.ReadOnly = true
 	}
 
-	if os.Getenv("GITEA_DEBUG") == "true" {
-		flagPkg.Debug = 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
 	}
 
-	// Set insecure mode based on environment variable
-	if os.Getenv("GITEA_INSECURE") == "true" {
+	allowedScopes := map[string]struct{}{}
+	for s := range strings.SplitSeq(scopes, ",") {
+		if s = normalizeScope(s); s != "" {
+			allowedScopes[s] = struct{}{}
+		}
+	}
+	if len(allowedScopes) > 0 {
+		flagPkg.AllowedScopes = allowedScopes
+	}
+	if getenv("GITEA_DEBUG") == "true" {
+		flagPkg.Debug = true
+	}
+	if getenv("GITEA_INSECURE") == "true" {
 		flagPkg.Insecure = true
 	}
+	if !maxInlineAttachmentBytesFlagSet {
+		if val := getenv("GITEA_MAX_INLINE_ATTACHMENT_BYTES"); val != "" {
+			parsed, err := strconv.Atoi(val)
+			if err != nil || parsed < 0 {
+				fmt.Fprintf(stderr, "invalid GITEA_MAX_INLINE_ATTACHMENT_BYTES: %q\n", val)
+				osExit(1)
+			}
+			flagPkg.MaxInlineAttachmentBytes = parsed
+		}
+	}
+}
+
+// normalizeScope trims whitespace, lowercases, and converts internal spaces
+// and hyphens to underscores, so "Pull Request", "pull-request", and
+// "PULL_REQUEST" all normalize to "pull_request".
+func normalizeScope(s string) string {
+	s = strings.TrimSpace(s)
+	s = strings.ToLower(s)
+	s = strings.ReplaceAll(s, " ", "_")
+	s = strings.ReplaceAll(s, "-", "_")
+	return s
 }
 
 func Execute() {
-	defer log.Default().Sync()
+	initFlagSet(flag.CommandLine, os.Args[1:], os.Getenv, os.ReadFile, os.Stderr)
+	if version {
+		fmt.Fprintln(os.Stdout, flagPkg.Version)
+		return
+	}
 	if err := operation.Run(); err != nil {
 		if err == context.Canceled {
 			log.Info("Server shutdown due to context cancellation")
+			_ = log.Default().Sync() // best-effort flush
 			return
 		}
+		_ = log.Default().Sync() // best-effort flush
 		log.Fatalf("Run Gitea MCP Server Error: %v", err)
 	}
+	_ = log.Default().Sync() // best-effort flush
 }

cmd/cmd_test.go

@@ -0,0 +1,76 @@
+package cmd
+
+import (
+	"bytes"
+	"flag"
+	"maps"
+	"slices"
+	"testing"
+
+	flagPkg "gitea.com/gitea/gitea-mcp/pkg/flag"
+)
+
+func TestInitFlagSetScopes(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		env  map[string]string
+		want []string
+	}{
+		{
+			name: "no scope flag or env leaves AllowedScopes unset",
+			args: []string{},
+			want: nil,
+		},
+		{
+			name: "-S sets a single scope",
+			args: []string{"-S", "repository"},
+			want: []string{"repository"},
+		},
+		{
+			name: "-scope sets a comma-separated list",
+			args: []string{"-scope", "repository,file"},
+			want: []string{"file", "repository"},
+		},
+		{
+			name: "GITEA_SCOPES env sets the default",
+			args: []string{},
+			env:  map[string]string{"GITEA_SCOPES": "issue,pull_request"},
+			want: []string{"issue", "pull_request"},
+		},
+		{
+			name: "-S flag takes precedence over GITEA_SCOPES env",
+			args: []string{"-S", "file"},
+			env:  map[string]string{"GITEA_SCOPES": "issue"},
+			want: []string{"file"},
+		},
+		{
+			name: "normalizes case, whitespace, and hyphens/spaces to underscores",
+			args: []string{"-S", " Pull Request , pull-request , PULL_REQUEST "},
+			want: []string{"pull_request"},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			origScopes := flagPkg.AllowedScopes
+			t.Cleanup(func() {
+				flagPkg.AllowedScopes = origScopes
+			})
+			flagPkg.AllowedScopes = nil
+
+			getenv := func(key string) string { return tt.env[key] }
+			readFile := func(string) ([]byte, error) { return nil, nil }
+			fs := flag.NewFlagSet("test", flag.ContinueOnError)
+			var stderr bytes.Buffer
+
+			initFlagSet(fs, tt.args, getenv, readFile, &stderr)
+
+			got := slices.Sorted(maps.Keys(flagPkg.AllowedScopes))
+			want := slices.Clone(tt.want)
+			slices.Sort(want)
+			if !slices.Equal(got, want) {
+				t.Errorf("AllowedScopes = %v, want %v", got, want)
+			}
+		})
+	}
+}

go.mod

@@ -1,29 +1,28 @@
 module gitea.com/gitea/gitea-mcp
 
-go 1.24.0
+go 1.26.0
 
 require (
-	code.gitea.io/sdk/gitea v0.22.1
-	github.com/mark3labs/mcp-go v0.42.0
-	go.uber.org/zap v1.27.0
+	gitea.dev/sdk v1.2.0
+	github.com/modelcontextprotocol/go-sdk v1.7.0
+	go.uber.org/zap v1.28.0
+	go.uber.org/zap/exp v0.3.0
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1
 )
 
 require (
-	github.com/42wim/httpsig v1.2.3 // indirect
-	github.com/bahlo/generic-list-go v0.2.0 // indirect
-	github.com/buger/jsonparser v1.1.1 // indirect
+	github.com/42wim/httpsig v1.2.4 // indirect
 	github.com/davidmz/go-pageant v1.0.2 // indirect
-	github.com/go-fed/httpsig v1.1.0 // indirect
-	github.com/google/uuid v1.6.0 // indirect
-	github.com/hashicorp/go-version v1.7.0 // indirect
-	github.com/invopop/jsonschema v0.13.0 // indirect
-	github.com/mailru/easyjson v0.9.1 // indirect
-	github.com/spf13/cast v1.10.0 // indirect
-	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
+	github.com/google/jsonschema-go v0.4.3 // indirect
+	github.com/hashicorp/go-version v1.9.0 // indirect
+	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	golang.org/x/crypto v0.43.0 // indirect
-	golang.org/x/sys v0.37.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
+	golang.org/x/crypto v0.54.0 // indirect
+	golang.org/x/oauth2 v0.35.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/time v0.15.0 // indirect
+	golang.org/x/tools v0.47.0 // indirect
 )

go.sum

@@ -1,73 +1,61 @@
-code.gitea.io/sdk/gitea v0.22.1 h1:7K05KjRORyTcTYULQ/AwvlVS6pawLcWyXZcTr7gHFyA=
-code.gitea.io/sdk/gitea v0.22.1/go.mod h1:yyF5+GhljqvA30sRDreoyHILruNiy4ASufugzYg0VHM=
-github.com/42wim/httpsig v1.2.3 h1:xb0YyWhkYj57SPtfSttIobJUPJZB9as1nsfo7KWVcEs=
-github.com/42wim/httpsig v1.2.3/go.mod h1:nZq9OlYKDrUBhptd77IHx4/sZZD+IxTBADvAPI9G/EM=
-github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
-github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
-github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs=
-github.com/buger/jsonparser v1.1.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
+gitea.dev/sdk v1.2.0 h1:avRtJl/nKCGispgSalo9czoZM9Rto1awnE0caNAoXGo=
+gitea.dev/sdk v1.2.0/go.mod h1:rfh5oNdIK24cbCREwIn1tqWKQW+IICXFGWJyebuOAOE=
+github.com/42wim/httpsig v1.2.4 h1:mI5bH0nm4xn7K18fo1K3okNDRq8CCJ0KbBYWyA6r8lU=
+github.com/42wim/httpsig v1.2.4/go.mod h1:yKsYfSyTBEohkPik224QPFylmzEBtda/kjyIAJjh3ps=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davidmz/go-pageant v1.0.2 h1:bPblRCh5jGU+Uptpz6LgMZGD5hJoOt7otgT454WvHn0=
 github.com/davidmz/go-pageant v1.0.2/go.mod h1:P2EDDnMqIwG5Rrp05dTRITj9z2zpGcD9efWSkTNKLIE=
-github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
-github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
-github.com/go-fed/httpsig v1.1.0 h1:9M+hb0jkEICD8/cAiNqEB66R87tTINszBRTjwjQzWcI=
-github.com/go-fed/httpsig v1.1.0/go.mod h1:RCMrTZvN1bJYtofsG4rd5NaO5obxQ5xBkdiS7xsT7bM=
-github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
-github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-github.com/hashicorp/go-version v1.7.0 h1:5tqGy27NaOTB8yJKUZELlFAS/LTKJkrmONwQKeRZfjY=
-github.com/hashicorp/go-version v1.7.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
-github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
-github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
-github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
-github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
-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.42.0 h1:gk/8nYJh8t3yroCAOBhNbYsM9TCKvkM13I5t5Hfu6Ls=
-github.com/mark3labs/mcp-go v0.42.0/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
+github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/hashicorp/go-version v1.9.0 h1:CeOIz6k+LoN3qX9Z0tyQrPtiB1DFYRPfCIBtaXPSCnA=
+github.com/hashicorp/go-version v1.9.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
+github.com/modelcontextprotocol/go-sdk v1.7.0 h1:yqjY2dsbKAC0LSuWZVBMrHgiG8ukXv6NRo0JiALay44=
+github.com/modelcontextprotocol/go-sdk v1.7.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
-github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
-github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
-github.com/spf13/cast v1.10.0/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
-github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
-github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
-github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
 go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
-go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
-go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
-golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+go.uber.org/zap v1.28.0 h1:IZzaP1Fv73/T/pBMLk4VutPl36uNC+OSUh3JLG3FIjo=
+go.uber.org/zap v1.28.0/go.mod h1:rDLpOi171uODNm/mxFcuYWxDsqWSAVkFdX4XojSKg/Q=
+go.uber.org/zap/exp v0.3.0 h1:6JYzdifzYkGmTdRR59oYH+Ng7k49H9qVpWwNSsGJj3U=
+go.uber.org/zap/exp v0.3.0/go.mod h1:5I384qq7XGxYyByIhHm6jg5CHkGY0nsTfbDLgDDlgJQ=
+go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/crypto v0.0.0-20210513164829-c07d793c2f9a/go.mod h1:P+XmwS30IXTQdn5tA2iutPOUgjI07+tq3H3K9MVA1s8=
-golang.org/x/crypto v0.43.0 h1:dduJYIi3A3KOfdGOHX8AVZ/jGiyPa3IbBozJ5kNuE04=
-golang.org/x/crypto v0.43.0/go.mod h1:BFbav4mRNlXJL4wNeejLpWxB7wMbc79PdRGhWKncxR0=
-golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
-golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
+golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.37.0 h1:fdNQudmxPjkdUTPnLn5mdQv7Zwvbvpaxqs831goi9kQ=
-golang.org/x/sys v0.37.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.36.0 h1:zMPR+aF8gfksFprF/Nc/rd1wRS1EI6nDBGyWAvDzx2Q=
-golang.org/x/term v0.36.0/go.mod h1:Qu394IJq6V6dCBRgwqshf3mPF85AqzYEzofzRdZkWss=
-golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
+golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYskCTPBJVb9jqSc=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

main.go

@@ -1,15 +1,20 @@
 package main
 
 import (
+	"runtime/debug"
+
 	"gitea.com/gitea/gitea-mcp/cmd"
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
 )
 
-var (
-	Version = "dev"
-)
+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/actions.go

@@ -5,6 +5,4 @@ import (
 )
 
 // Tool is the registry for all Actions-related MCP tools.
-var Tool = tool.New()
-
-
+var Tool = tool.New("actions")

operation/actions/artifacts.go

@@ -0,0 +1,195 @@
+package actions
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"gitea.com/gitea/gitea-mcp/pkg/gitea"
+	"gitea.com/gitea/gitea-mcp/pkg/params"
+	"gitea.com/gitea/gitea-mcp/pkg/to"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// Artifact endpoints require Gitea 1.25+. Older servers answer 404/405, which is
+// surfaced as a clear "not supported" message rather than a raw HTTP error.
+func artifactNotSupportedErr(err error) error {
+	var httpErr *gitea.HTTPError
+	if errors.As(err, &httpErr) && (httpErr.StatusCode == http.StatusNotFound || httpErr.StatusCode == http.StatusMethodNotAllowed) {
+		return fmt.Errorf("actions artifacts not supported on this Gitea version (endpoint returned %d, requires Gitea 1.25+). Check https://docs.gitea.com/api/1.25/ for available Actions endpoints", httpErr.StatusCode)
+	}
+	return err
+}
+
+func listRepoActionArtifactsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	page, pageSize := params.GetPagination(args, 30)
+
+	query := url.Values{}
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
+	if name := params.GetOptionalString(args, "artifact_name", ""); name != "" {
+		query.Set("name", name)
+	}
+
+	var result any
+	err = doJSONWithFallback(ctx, "GET",
+		[]string{
+			fmt.Sprintf("repos/%s/%s/actions/artifacts", url.PathEscape(owner), url.PathEscape(repo)),
+		},
+		query, nil, &result,
+	)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list action artifacts err: %v", artifactNotSupportedErr(err)))
+	}
+	return to.TextResult(slimActionArtifacts(result))
+}
+
+func listRepoActionRunArtifactsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	runID, err := params.GetIndex(args, "run_id")
+	if err != nil || runID <= 0 {
+		return to.ErrorResult(errors.New("run_id is required"))
+	}
+	page, pageSize := params.GetPagination(args, 30)
+
+	query := url.Values{}
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
+	if name := params.GetOptionalString(args, "artifact_name", ""); name != "" {
+		query.Set("name", name)
+	}
+
+	var result any
+	err = doJSONWithFallback(ctx, "GET",
+		[]string{
+			fmt.Sprintf("repos/%s/%s/actions/runs/%d/artifacts", url.PathEscape(owner), url.PathEscape(repo), runID),
+		},
+		query, nil, &result,
+	)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list action run artifacts err: %v", artifactNotSupportedErr(err)))
+	}
+	return to.TextResult(slimActionArtifacts(result))
+}
+
+func getRepoActionArtifactFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	artifactID, err := params.GetIndex(args, "artifact_id")
+	if err != nil || artifactID <= 0 {
+		return to.ErrorResult(errors.New("artifact_id is required"))
+	}
+
+	var result any
+	err = doJSONWithFallback(ctx, "GET",
+		[]string{
+			fmt.Sprintf("repos/%s/%s/actions/artifacts/%d", url.PathEscape(owner), url.PathEscape(repo), artifactID),
+		},
+		nil, nil, &result,
+	)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get action artifact err: %v", artifactNotSupportedErr(err)))
+	}
+	return to.TextResult(slimActionArtifact(result))
+}
+
+func downloadRepoActionArtifactFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	artifactID, err := params.GetIndex(args, "artifact_id")
+	if err != nil || artifactID <= 0 {
+		return to.ErrorResult(errors.New("artifact_id is required"))
+	}
+	outputPath, _ := args["output_path"].(string)
+
+	// Best-effort metadata lookup: gives a friendly filename and lets us fail
+	// early with a clear message when the artifact has expired.
+	var meta map[string]any
+	_ = doJSONWithFallback(ctx, "GET",
+		[]string{fmt.Sprintf("repos/%s/%s/actions/artifacts/%d", url.PathEscape(owner), url.PathEscape(repo), artifactID)},
+		nil, nil, &meta,
+	)
+	if expired, ok := meta["expired"].(bool); ok && expired {
+		return to.ErrorResult(fmt.Errorf("artifact %d has expired and is no longer downloadable", artifactID))
+	}
+
+	// The zip endpoint answers with a 302 redirect to signed blob storage;
+	// DoBytes follows GET redirects and returns the archive bytes.
+	raw, _, err := gitea.DoBytes(ctx, "GET",
+		fmt.Sprintf("repos/%s/%s/actions/artifacts/%d/zip", url.PathEscape(owner), url.PathEscape(repo), artifactID),
+		nil, nil, "application/zip",
+	)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("download action artifact err: %v", artifactNotSupportedErr(err)))
+	}
+
+	if outputPath == "" {
+		home, _ := os.UserHomeDir()
+		if home == "" {
+			home = os.TempDir()
+		}
+		outputPath = filepath.Join(home, ".gitea-mcp", "artifacts", "actions-artifacts", owner, repo, artifactFilename(meta, artifactID))
+	}
+
+	if err := os.MkdirAll(filepath.Dir(outputPath), 0o700); err != nil {
+		return to.ErrorResult(fmt.Errorf("create output dir err: %v", err))
+	}
+	if err := os.WriteFile(outputPath, raw, 0o600); err != nil {
+		return to.ErrorResult(fmt.Errorf("write artifact file err: %v", err))
+	}
+
+	res := map[string]any{
+		"artifact_id": artifactID,
+		"path":        outputPath,
+		"bytes":       len(raw),
+	}
+	if name, ok := meta["name"].(string); ok && name != "" {
+		res["name"] = name
+	}
+	return to.TextResult(res)
+}
+
+// artifactFilename derives a safe "<name>.zip" filename from artifact metadata,
+// falling back to the artifact ID when the name is missing or path-unsafe.
+func artifactFilename(meta map[string]any, artifactID int64) string {
+	name, _ := meta["name"].(string)
+	name = strings.TrimSpace(name)
+	if name != "" && !strings.ContainsAny(name, `/\`) && name != "." && name != ".." {
+		return name + ".zip"
+	}
+	return fmt.Sprintf("%d.zip", artifactID)
+}

operation/actions/artifacts_test.go

@@ -0,0 +1,29 @@
+package actions
+
+import "testing"
+
+func TestArtifactFilename(t *testing.T) {
+	tests := []struct {
+		name       string
+		meta       map[string]any
+		artifactID int64
+		want       string
+	}{
+		{"uses name", map[string]any{"name": "build-output"}, 7, "build-output.zip"},
+		{"trims whitespace", map[string]any{"name": "  logs  "}, 7, "logs.zip"},
+		{"missing name falls back to id", map[string]any{}, 7, "7.zip"},
+		{"empty name falls back to id", map[string]any{"name": ""}, 7, "7.zip"},
+		{"non-string name falls back to id", map[string]any{"name": 42}, 7, "7.zip"},
+		{"rejects forward slash traversal", map[string]any{"name": "../etc/passwd"}, 7, "7.zip"},
+		{"rejects backslash traversal", map[string]any{"name": `..\win`}, 7, "7.zip"},
+		{"rejects dot", map[string]any{"name": "."}, 7, "7.zip"},
+		{"rejects dotdot", map[string]any{"name": ".."}, 7, "7.zip"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := artifactFilename(tt.meta, tt.artifactID); got != tt.want {
+				t.Errorf("artifactFilename() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}

operation/actions/config.go

@@ -0,0 +1,534 @@
+package actions
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"strconv"
+	"time"
+
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
+	"gitea.com/gitea/gitea-mcp/pkg/gitea"
+	"gitea.com/gitea/gitea-mcp/pkg/params"
+	"gitea.com/gitea/gitea-mcp/pkg/to"
+	"gitea.com/gitea/gitea-mcp/pkg/tool"
+
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+const (
+	ActionsConfigReadToolName  = "actions_config_read"
+	ActionsConfigWriteToolName = "actions_config_write"
+)
+
+type secretMeta struct {
+	Name        string    `json:"name"`
+	Description string    `json:"description,omitempty"`
+	CreatedAt   time.Time `json:"created_at,omitzero"`
+}
+
+func toSecretMetas(secrets []*gitea_sdk.Secret) []secretMeta {
+	metas := make([]secretMeta, 0, len(secrets))
+	for _, s := range secrets {
+		if s == nil {
+			continue
+		}
+		metas = append(metas, secretMeta{
+			Name:        s.Name,
+			Description: s.Description,
+			CreatedAt:   s.Created,
+		})
+	}
+	return metas
+}
+
+var (
+	ActionsConfigReadTool = tool.NewDefinition(
+		ActionsConfigReadToolName,
+		"Read Actions secrets and variables.",
+		annotation.ReadOnly("Read Actions secrets and variables"),
+		tool.String("method", tool.Required(), tool.Enum("list_repo_secrets", "list_org_secrets", "list_repo_variables", "get_repo_variable", "list_org_variables", "get_org_variable")),
+		tool.String("owner", tool.Description("for repo methods")),
+		tool.String("repo", tool.Description("for repo methods")),
+		tool.String("org", tool.Description("for org methods")),
+		tool.String("name", tool.Description("for get methods")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1), tool.Minimum(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30), tool.Minimum(1)),
+	)
+
+	ActionsConfigWriteTool = tool.NewDefinition(
+		ActionsConfigWriteToolName,
+		"Write Actions secrets and variables: upsert, create, update, delete.",
+		annotation.Destructive("Manage Actions secrets and variables"),
+		tool.String("method", tool.Required(), tool.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")),
+		tool.String("owner", tool.Description("for repo methods")),
+		tool.String("repo", tool.Description("for repo methods")),
+		tool.String("org", tool.Description("for org methods")),
+		tool.String("name", tool.Description("secret or variable name")),
+		tool.String("data", tool.Description("secret value (upsert)")),
+		tool.String("value", tool.Description("variable value")),
+		tool.String("description"),
+	)
+)
+
+func init() {
+	Tool.RegisterRead(tool.ServerTool{Tool: ActionsConfigReadTool, Handler: configReadFn})
+	Tool.RegisterWrite(tool.ServerTool{Tool: ActionsConfigWriteTool, Handler: configWriteFn})
+}
+
+func configReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "list_repo_secrets":
+		return listRepoActionSecretsFn(ctx, args)
+	case "list_org_secrets":
+		return listOrgActionSecretsFn(ctx, args)
+	case "list_repo_variables":
+		return listRepoActionVariablesFn(ctx, args)
+	case "get_repo_variable":
+		return getRepoActionVariableFn(ctx, args)
+	case "list_org_variables":
+		return listOrgActionVariablesFn(ctx, args)
+	case "get_org_variable":
+		return getOrgActionVariableFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func configWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "upsert_repo_secret":
+		return upsertRepoActionSecretFn(ctx, args)
+	case "delete_repo_secret":
+		return deleteRepoActionSecretFn(ctx, args)
+	case "upsert_org_secret":
+		return upsertOrgActionSecretFn(ctx, args)
+	case "delete_org_secret":
+		return deleteOrgActionSecretFn(ctx, args)
+	case "create_repo_variable":
+		return createRepoActionVariableFn(ctx, args)
+	case "update_repo_variable":
+		return updateRepoActionVariableFn(ctx, args)
+	case "delete_repo_variable":
+		return deleteRepoActionVariableFn(ctx, args)
+	case "create_org_variable":
+		return createOrgActionVariableFn(ctx, args)
+	case "update_org_variable":
+		return updateOrgActionVariableFn(ctx, args)
+	case "delete_org_variable":
+		return deleteOrgActionVariableFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func listRepoActionSecretsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	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))
+	}
+
+	secrets, _, err := client.Actions.ListRepoSecrets(ctx, owner, repo, gitea_sdk.ListRepoActionsSecretOption{
+		ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list repo action secrets err: %v", err))
+	}
+
+	return to.TextResult(toSecretMetas(secrets))
+}
+
+func upsertRepoActionSecretFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	data, err := params.GetString(args, "data")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	description, _ := args["description"].(string)
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	resp, err := client.Actions.CreateRepoSecret(ctx, owner, repo, name, gitea_sdk.CreateOrUpdateSecretOption{
+		Data:        data,
+		Description: description,
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("upsert repo action secret err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "secret upserted", "status": resp.StatusCode})
+}
+
+func deleteRepoActionSecretFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	resp, err := client.Actions.DeleteRepoSecret(ctx, owner, repo, name)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("delete repo action secret err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "secret deleted", "status": resp.StatusCode})
+}
+
+func listOrgActionSecretsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	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))
+	}
+
+	secrets, _, err := client.Actions.ListOrgSecrets(ctx, org, gitea_sdk.ListOrgActionsSecretOption{
+		ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list org action secrets err: %v", err))
+	}
+
+	return to.TextResult(toSecretMetas(secrets))
+}
+
+func upsertOrgActionSecretFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	data, err := params.GetString(args, "data")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	description, _ := args["description"].(string)
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	resp, err := client.Actions.CreateOrgSecret(ctx, org, name, gitea_sdk.CreateOrUpdateSecretOption{
+		Data:        data,
+		Description: description,
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("upsert org action secret err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "secret upserted", "status": resp.StatusCode})
+}
+
+func deleteOrgActionSecretFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	escapedOrg := url.PathEscape(org)
+	escapedSecret := url.PathEscape(name)
+	_, err = gitea.DoJSON(ctx, "DELETE", fmt.Sprintf("orgs/%s/actions/secrets/%s", escapedOrg, escapedSecret), nil, nil, nil)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("delete org action secret err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "secret deleted"})
+}
+
+func listRepoActionVariablesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	page, pageSize := params.GetPagination(args, 30)
+
+	query := url.Values{}
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
+
+	var result any
+	_, err = gitea.DoJSON(ctx, "GET", fmt.Sprintf("repos/%s/%s/actions/variables", url.PathEscape(owner), url.PathEscape(repo)), query, nil, &result)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list repo action variables err: %v", err))
+	}
+	return to.TextResult(result)
+}
+
+func getRepoActionVariableFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	variable, _, err := client.Actions.GetRepoVariable(ctx, owner, repo, name)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get repo action variable err: %v", err))
+	}
+	return to.TextResult(variable)
+}
+
+func createRepoActionVariableFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	value, err := params.GetString(args, "value")
+	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))
+	}
+	resp, err := client.Actions.CreateRepoVariable(ctx, owner, repo, name, value)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("create repo action variable err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "variable created", "status": resp.StatusCode})
+}
+
+func updateRepoActionVariableFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	value, err := params.GetString(args, "value")
+	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))
+	}
+	resp, err := client.Actions.UpdateRepoVariable(ctx, owner, repo, name, value)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("update repo action variable err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "variable updated", "status": resp.StatusCode})
+}
+
+func deleteRepoActionVariableFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	resp, err := client.Actions.DeleteRepoVariable(ctx, owner, repo, name)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("delete repo action variable err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "variable deleted", "status": resp.StatusCode})
+}
+
+func listOrgActionVariablesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	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))
+	}
+	variables, _, err := client.Actions.ListOrgVariables(ctx, org, gitea_sdk.ListOrgActionsVariableOption{
+		ListOptions: gitea_sdk.ListOptions{Page: page, PageSize: pageSize},
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list org action variables err: %v", err))
+	}
+	return to.TextResult(variables)
+}
+
+func getOrgActionVariableFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	variable, _, err := client.Actions.GetOrgVariable(ctx, org, name)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get org action variable err: %v", err))
+	}
+	return to.TextResult(variable)
+}
+
+func createOrgActionVariableFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	value, err := params.GetString(args, "value")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	description, _ := args["description"].(string)
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	resp, err := client.Actions.CreateOrgVariable(ctx, org, name, gitea_sdk.CreateActionsVariableOption{
+		Value:       value,
+		Description: description,
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("create org action variable err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "variable created", "status": resp.StatusCode})
+}
+
+func updateOrgActionVariableFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	value, err := params.GetString(args, "value")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	description, _ := args["description"].(string)
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	resp, err := client.Actions.UpdateOrgVariable(ctx, org, name, gitea_sdk.UpdateActionsVariableOption{
+		Name:        name,
+		Value:       value,
+		Description: description,
+	})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("update org action variable err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "variable updated", "status": resp.StatusCode})
+}
+
+func deleteOrgActionVariableFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	_, err = gitea.DoJSON(ctx, "DELETE", fmt.Sprintf("orgs/%s/actions/variables/%s", url.PathEscape(org), url.PathEscape(name)), nil, nil, nil)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("delete org action variable err: %v", err))
+	}
+	return to.TextResult(map[string]any{"message": "variable deleted"})
+}

operation/actions/logs.go

@@ -1,198 +0,0 @@
-package actions
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/url"
-	"os"
-	"path/filepath"
-
-	"gitea.com/gitea/gitea-mcp/pkg/gitea"
-	"gitea.com/gitea/gitea-mcp/pkg/log"
-	"gitea.com/gitea/gitea-mcp/pkg/to"
-
-	"github.com/mark3labs/mcp-go/mcp"
-	"github.com/mark3labs/mcp-go/server"
-)
-
-const (
-	GetRepoActionJobLogPreviewToolName = "get_repo_action_job_log_preview"
-	DownloadRepoActionJobLogToolName   = "download_repo_action_job_log"
-)
-
-var (
-	GetRepoActionJobLogPreviewTool = mcp.NewTool(
-		GetRepoActionJobLogPreviewToolName,
-		mcp.WithDescription("Get a repository Actions job log preview (tail/limited for chat-friendly output)"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("job_id", mcp.Required(), mcp.Description("job ID")),
-		mcp.WithNumber("tail_lines", mcp.Description("number of lines from the end of the log"), mcp.DefaultNumber(200), mcp.Min(1)),
-		mcp.WithNumber("max_bytes", mcp.Description("max bytes to return"), mcp.DefaultNumber(65536), mcp.Min(1024)),
-	)
-
-	DownloadRepoActionJobLogTool = mcp.NewTool(
-		DownloadRepoActionJobLogToolName,
-		mcp.WithDescription("Download a repository Actions job log to a file on the MCP server filesystem"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("job_id", mcp.Required(), mcp.Description("job ID")),
-		mcp.WithString("output_path", mcp.Description("optional output file path; if omitted, uses ~/.gitea-mcp/artifacts/actions-logs/...")),
-	)
-)
-
-func init() {
-	Tool.RegisterRead(server.ServerTool{Tool: GetRepoActionJobLogPreviewTool, Handler: GetRepoActionJobLogPreviewFn})
-	Tool.RegisterRead(server.ServerTool{Tool: DownloadRepoActionJobLogTool, Handler: DownloadRepoActionJobLogFn})
-}
-
-func logPaths(owner, repo string, jobID int64) []string {
-	// Primary candidate endpoints, plus a few commonly-seen variants across versions.
-	// We try these in order; 404/405 falls through.
-	return []string{
-		fmt.Sprintf("repos/%s/%s/actions/jobs/%d/logs", url.PathEscape(owner), url.PathEscape(repo), jobID),
-		fmt.Sprintf("repos/%s/%s/actions/jobs/%d/log", url.PathEscape(owner), url.PathEscape(repo), jobID),
-		fmt.Sprintf("repos/%s/%s/actions/tasks/%d/log", url.PathEscape(owner), url.PathEscape(repo), jobID),
-		fmt.Sprintf("repos/%s/%s/actions/task/%d/log", url.PathEscape(owner), url.PathEscape(repo), jobID),
-	}
-}
-
-func fetchJobLogBytes(ctx context.Context, owner, repo string, jobID int64) ([]byte, string, error) {
-	var lastErr error
-	for _, p := range logPaths(owner, repo, jobID) {
-		b, _, err := gitea.DoBytes(ctx, "GET", p, nil, nil, "text/plain")
-		if err == nil {
-			return b, p, nil
-		}
-		lastErr = err
-		var httpErr *gitea.HTTPError
-		if errors.As(err, &httpErr) && (httpErr.StatusCode == 404 || httpErr.StatusCode == 405) {
-			continue
-		}
-		return nil, p, err
-	}
-	return nil, "", lastErr
-}
-
-func tailByLines(data []byte, tailLines int) []byte {
-	if tailLines <= 0 || len(data) == 0 {
-		return data
-	}
-	// Find the start index of the last N lines by scanning backwards.
-	lines := 0
-	i := len(data) - 1
-	for i >= 0 {
-		if data[i] == '\n' {
-			lines++
-			if lines > tailLines {
-				return data[i+1:]
-			}
-		}
-		i--
-	}
-	return data
-}
-
-func limitBytes(data []byte, maxBytes int) ([]byte, bool) {
-	if maxBytes <= 0 {
-		return data, false
-	}
-	if len(data) <= maxBytes {
-		return data, false
-	}
-	// Keep the tail so the most recent log content is preserved.
-	return data[len(data)-maxBytes:], true
-}
-
-func GetRepoActionJobLogPreviewFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetRepoActionJobLogPreviewFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	jobIDFloat, ok := req.GetArguments()["job_id"].(float64)
-	if !ok || jobIDFloat <= 0 {
-		return to.ErrorResult(fmt.Errorf("job_id is required"))
-	}
-	tailLinesFloat, _ := req.GetArguments()["tail_lines"].(float64)
-	maxBytesFloat, _ := req.GetArguments()["max_bytes"].(float64)
-	tailLines := int(tailLinesFloat)
-	if tailLines <= 0 {
-		tailLines = 200
-	}
-	maxBytes := int(maxBytesFloat)
-	if maxBytes <= 0 {
-		maxBytes = 65536
-	}
-
-	jobID := int64(jobIDFloat)
-	raw, usedPath, err := fetchJobLogBytes(ctx, owner, repo, jobID)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get job log err: %v", err))
-	}
-
-	tailed := tailByLines(raw, tailLines)
-	limited, truncated := limitBytes(tailed, maxBytes)
-
-	return to.TextResult(map[string]any{
-		"endpoint":     usedPath,
-		"job_id":       jobID,
-		"bytes":        len(raw),
-		"tail_lines":   tailLines,
-		"max_bytes":    maxBytes,
-		"truncated":    truncated,
-		"log":          string(limited),
-	})
-}
-
-func DownloadRepoActionJobLogFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DownloadRepoActionJobLogFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	jobIDFloat, ok := req.GetArguments()["job_id"].(float64)
-	if !ok || jobIDFloat <= 0 {
-		return to.ErrorResult(fmt.Errorf("job_id is required"))
-	}
-	outputPath, _ := req.GetArguments()["output_path"].(string)
-	jobID := int64(jobIDFloat)
-
-	raw, usedPath, err := fetchJobLogBytes(ctx, owner, repo, jobID)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("download job log err: %v", err))
-	}
-
-	if outputPath == "" {
-		home, _ := os.UserHomeDir()
-		if home == "" {
-			home = os.TempDir()
-		}
-		outputPath = filepath.Join(home, ".gitea-mcp", "artifacts", "actions-logs", owner, repo, fmt.Sprintf("%d.log", jobID))
-	}
-
-	if err := os.MkdirAll(filepath.Dir(outputPath), 0o700); err != nil {
-		return to.ErrorResult(fmt.Errorf("create output dir err: %v", err))
-	}
-	if err := os.WriteFile(outputPath, raw, 0o600); err != nil {
-		return to.ErrorResult(fmt.Errorf("write log file err: %v", err))
-	}
-
-	return to.TextResult(map[string]any{
-		"endpoint": usedPath,
-		"job_id":   jobID,
-		"path":     outputPath,
-		"bytes":    len(raw),
-	})
-}
-
-

operation/actions/logs_test.go

@@ -20,5 +20,3 @@ func TestLimitBytesKeepsTail(t *testing.T) {
 		t.Fatalf("limitBytes tail = %q, want %q", string(out), "6789")
 	}
 }
-
-

operation/actions/runs.go

@@ -4,168 +4,153 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"net/http"
 	"net/url"
+	"os"
+	"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"
 	"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"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
 const (
-	ListRepoActionWorkflowsToolName    = "list_repo_action_workflows"
-	GetRepoActionWorkflowToolName      = "get_repo_action_workflow"
-	DispatchRepoActionWorkflowToolName = "dispatch_repo_action_workflow"
-
-	ListRepoActionRunsToolName  = "list_repo_action_runs"
-	GetRepoActionRunToolName    = "get_repo_action_run"
-	CancelRepoActionRunToolName = "cancel_repo_action_run"
-	RerunRepoActionRunToolName  = "rerun_repo_action_run"
-
-	ListRepoActionJobsToolName    = "list_repo_action_jobs"
-	ListRepoActionRunJobsToolName = "list_repo_action_run_jobs"
+	ActionsRunReadToolName  = "actions_run_read"
+	ActionsRunWriteToolName = "actions_run_write"
 )
 
 var (
-	ListRepoActionWorkflowsTool = mcp.NewTool(
-		ListRepoActionWorkflowsToolName,
-		mcp.WithDescription("List repository Actions workflows"),
-		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("pageSize", mcp.Description("page size"), mcp.DefaultNumber(50), mcp.Min(1)),
+	ActionsRunReadTool = tool.NewDefinition(
+		ActionsRunReadToolName,
+		"Read Actions workflows, runs, jobs, logs, and artifacts.",
+		annotation.ReadOnly("Read Actions workflow, run, job, and artifact data"),
+		tool.String("method", tool.Required(), tool.Enum("list_workflows", "get_workflow", "list_runs", "get_run", "list_jobs", "list_run_jobs", "get_job", "get_job_log_preview", "download_job_log", "list_artifacts", "list_run_artifacts", "get_artifact", "download_artifact")),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("workflow_id", tool.Description("ID or filename (for 'get_workflow')")),
+		tool.Number("run_id", tool.Description("for 'get_run'/'list_run_jobs'/'list_run_artifacts'")),
+		tool.Number("job_id", tool.Description("for 'get_job'/log methods")),
+		tool.Number("artifact_id", tool.Description("for 'get_artifact'/'download_artifact'")),
+		tool.String("artifact_name", tool.Description("name filter for 'list_artifacts'/'list_run_artifacts'")),
+		tool.String("status", tool.Description("filter for 'list_runs'/'list_jobs'")),
+		tool.Number("tail_lines", tool.Description("log tail lines"), tool.Default(200), tool.Minimum(1)),
+		tool.Number("max_bytes", tool.Description("max log bytes"), tool.Default(65536), tool.Minimum(1024)),
+		tool.String("output_path", tool.Description("for 'download_job_log'/'download_artifact'")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1), tool.Minimum(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30), tool.Minimum(1)),
 	)
 
-	GetRepoActionWorkflowTool = mcp.NewTool(
-		GetRepoActionWorkflowToolName,
-		mcp.WithDescription("Get a repository Actions workflow by ID"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("workflow_id", mcp.Required(), mcp.Description("workflow ID or filename (e.g. 'my-workflow.yml')")),
-	)
-
-	DispatchRepoActionWorkflowTool = mcp.NewTool(
-		DispatchRepoActionWorkflowToolName,
-		mcp.WithDescription("Trigger (dispatch) a repository Actions workflow"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("workflow_id", mcp.Required(), mcp.Description("workflow ID or filename (e.g. 'my-workflow.yml')")),
-		mcp.WithString("ref", mcp.Required(), mcp.Description("git ref (branch or tag)")),
-		mcp.WithObject("inputs", mcp.Description("workflow inputs object")),
-	)
-
-	ListRepoActionRunsTool = mcp.NewTool(
-		ListRepoActionRunsToolName,
-		mcp.WithDescription("List repository Actions workflow runs"),
-		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("pageSize", mcp.Description("page size"), mcp.DefaultNumber(50), mcp.Min(1)),
-		mcp.WithString("status", mcp.Description("optional status filter")),
-	)
-
-	GetRepoActionRunTool = mcp.NewTool(
-		GetRepoActionRunToolName,
-		mcp.WithDescription("Get a repository Actions run by ID"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("run_id", mcp.Required(), mcp.Description("run ID")),
-	)
-
-	CancelRepoActionRunTool = mcp.NewTool(
-		CancelRepoActionRunToolName,
-		mcp.WithDescription("Cancel a repository Actions run"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("run_id", mcp.Required(), mcp.Description("run ID")),
-	)
-
-	RerunRepoActionRunTool = mcp.NewTool(
-		RerunRepoActionRunToolName,
-		mcp.WithDescription("Rerun a repository Actions run"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("run_id", mcp.Required(), mcp.Description("run ID")),
-	)
-
-	ListRepoActionJobsTool = mcp.NewTool(
-		ListRepoActionJobsToolName,
-		mcp.WithDescription("List repository Actions jobs"),
-		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("pageSize", mcp.Description("page size"), mcp.DefaultNumber(50), mcp.Min(1)),
-		mcp.WithString("status", mcp.Description("optional status filter")),
-	)
-
-	ListRepoActionRunJobsTool = mcp.NewTool(
-		ListRepoActionRunJobsToolName,
-		mcp.WithDescription("List Actions jobs for a specific run"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("run_id", mcp.Required(), mcp.Description("run ID")),
-		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(50), mcp.Min(1)),
+	ActionsRunWriteTool = tool.NewDefinition(
+		ActionsRunWriteToolName,
+		"Write Actions runs: dispatch, cancel, rerun.",
+		annotation.Write("Trigger, cancel, or rerun Actions workflows"),
+		tool.String("method", tool.Required(), tool.Enum("dispatch_workflow", "cancel_run", "rerun_run")),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("workflow_id", tool.Description("ID or filename (for 'dispatch_workflow')")),
+		tool.String("ref", tool.Description("branch or tag (for 'dispatch_workflow')")),
+		tool.Object("inputs", tool.Description("for 'dispatch_workflow'")),
+		tool.Number("run_id", tool.Description("for 'cancel_run'/'rerun_run'")),
 	)
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{Tool: ListRepoActionWorkflowsTool, Handler: ListRepoActionWorkflowsFn})
-	Tool.RegisterRead(server.ServerTool{Tool: GetRepoActionWorkflowTool, Handler: GetRepoActionWorkflowFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: DispatchRepoActionWorkflowTool, Handler: DispatchRepoActionWorkflowFn})
-
-	Tool.RegisterRead(server.ServerTool{Tool: ListRepoActionRunsTool, Handler: ListRepoActionRunsFn})
-	Tool.RegisterRead(server.ServerTool{Tool: GetRepoActionRunTool, Handler: GetRepoActionRunFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: CancelRepoActionRunTool, Handler: CancelRepoActionRunFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: RerunRepoActionRunTool, Handler: RerunRepoActionRunFn})
-
-	Tool.RegisterRead(server.ServerTool{Tool: ListRepoActionJobsTool, Handler: ListRepoActionJobsFn})
-	Tool.RegisterRead(server.ServerTool{Tool: ListRepoActionRunJobsTool, Handler: ListRepoActionRunJobsFn})
+	Tool.RegisterRead(tool.ServerTool{Tool: ActionsRunReadTool, Handler: runReadFn})
+	Tool.RegisterWrite(tool.ServerTool{Tool: ActionsRunWriteTool, Handler: runWriteFn})
 }
 
-func doJSONWithFallback(ctx context.Context, method string, paths []string, query url.Values, body any, respOut any) (string, int, error) {
+func runReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "list_workflows":
+		return listRepoActionWorkflowsFn(ctx, args)
+	case "get_workflow":
+		return getRepoActionWorkflowFn(ctx, args)
+	case "list_runs":
+		return listRepoActionRunsFn(ctx, args)
+	case "get_run":
+		return getRepoActionRunFn(ctx, args)
+	case "list_jobs":
+		return listRepoActionJobsFn(ctx, args)
+	case "list_run_jobs":
+		return listRepoActionRunJobsFn(ctx, args)
+	case "get_job":
+		return getRepoActionJobFn(ctx, args)
+	case "get_job_log_preview":
+		return getRepoActionJobLogPreviewFn(ctx, args)
+	case "download_job_log":
+		return downloadRepoActionJobLogFn(ctx, args)
+	case "list_artifacts":
+		return listRepoActionArtifactsFn(ctx, args)
+	case "list_run_artifacts":
+		return listRepoActionRunArtifactsFn(ctx, args)
+	case "get_artifact":
+		return getRepoActionArtifactFn(ctx, args)
+	case "download_artifact":
+		return downloadRepoActionArtifactFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func runWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "dispatch_workflow":
+		return dispatchRepoActionWorkflowFn(ctx, args)
+	case "cancel_run":
+		return cancelRepoActionRunFn(ctx, args)
+	case "rerun_run":
+		return rerunRepoActionRunFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func doJSONWithFallback(ctx context.Context, method string, paths []string, query url.Values, body, respOut any) error {
 	var lastErr error
 	for _, p := range paths {
-		status, err := gitea.DoJSON(ctx, method, p, query, body, respOut)
+		_, err := gitea.DoJSON(ctx, method, p, query, body, respOut)
 		if err == nil {
-			return p, status, nil
+			return nil
 		}
 		lastErr = err
 		var httpErr *gitea.HTTPError
-		if errors.As(err, &httpErr) && (httpErr.StatusCode == 404 || httpErr.StatusCode == 405) {
+		if errors.As(err, &httpErr) && (httpErr.StatusCode == http.StatusNotFound || httpErr.StatusCode == http.StatusMethodNotAllowed) {
 			continue
 		}
-		return p, status, err
+		return err
 	}
-	return "", 0, lastErr
+	return lastErr
 }
 
-func ListRepoActionWorkflowsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoActionWorkflowsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func listRepoActionWorkflowsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	page, _ := req.GetArguments()["page"].(float64)
-	if page <= 0 {
-		page = 1
-	}
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
-	if pageSize <= 0 {
-		pageSize = 50
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
+	page, pageSize := params.GetPagination(args, 30)
 	query := url.Values{}
-	query.Set("page", fmt.Sprintf("%d", int(page)))
-	query.Set("limit", fmt.Sprintf("%d", int(pageSize)))
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
 
 	var result any
-	_, _, err := doJSONWithFallback(ctx, "GET",
+	err = doJSONWithFallback(ctx, "GET",
 		[]string{
 			fmt.Sprintf("repos/%s/%s/actions/workflows", url.PathEscape(owner), url.PathEscape(repo)),
 		},
@@ -174,26 +159,25 @@ func ListRepoActionWorkflowsFn(ctx context.Context, req mcp.CallToolRequest) (*m
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list action workflows err: %v", err))
 	}
-	return to.TextResult(result)
+	return to.TextResult(slimActionWorkflows(result))
 }
 
-func GetRepoActionWorkflowFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetRepoActionWorkflowFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func getRepoActionWorkflowFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	workflowID, ok := req.GetArguments()["workflow_id"].(string)
-	if !ok || workflowID == "" {
-		return to.ErrorResult(fmt.Errorf("workflow_id is required"))
+	workflowID, err := params.GetString(args, "workflow_id")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
 	var result any
-	_, _, err := doJSONWithFallback(ctx, "GET",
+	err = doJSONWithFallback(ctx, "GET",
 		[]string{
 			fmt.Sprintf("repos/%s/%s/actions/workflows/%s", url.PathEscape(owner), url.PathEscape(repo), url.PathEscape(workflowID)),
 		},
@@ -202,37 +186,31 @@ func GetRepoActionWorkflowFn(ctx context.Context, req mcp.CallToolRequest) (*mcp
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get action workflow err: %v", err))
 	}
-	return to.TextResult(result)
+	return to.TextResult(slimActionWorkflow(result))
 }
 
-func DispatchRepoActionWorkflowFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DispatchRepoActionWorkflowFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func dispatchRepoActionWorkflowFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	workflowID, ok := req.GetArguments()["workflow_id"].(string)
-	if !ok || workflowID == "" {
-		return to.ErrorResult(fmt.Errorf("workflow_id is required"))
+	workflowID, err := params.GetString(args, "workflow_id")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	ref, ok := req.GetArguments()["ref"].(string)
-	if !ok || ref == "" {
-		return to.ErrorResult(fmt.Errorf("ref is required"))
+	ref, err := params.GetString(args, "ref")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
 	var inputs map[string]any
-	if raw, exists := req.GetArguments()["inputs"]; exists {
+	if raw, exists := args["inputs"]; exists {
 		if m, ok := raw.(map[string]any); ok {
 			inputs = m
-		} else if m, ok := raw.(map[string]interface{}); ok {
-			inputs = make(map[string]any, len(m))
-			for k, v := range m {
-				inputs[k] = v
-			}
 		}
 	}
 
@@ -243,7 +221,7 @@ func DispatchRepoActionWorkflowFn(ctx context.Context, req mcp.CallToolRequest)
 		body["inputs"] = inputs
 	}
 
-	_, _, err := doJSONWithFallback(ctx, "POST",
+	err = doJSONWithFallback(ctx, "POST",
 		[]string{
 			fmt.Sprintf("repos/%s/%s/actions/workflows/%s/dispatches", url.PathEscape(owner), url.PathEscape(repo), url.PathEscape(workflowID)),
 			fmt.Sprintf("repos/%s/%s/actions/workflows/%s/dispatch", url.PathEscape(owner), url.PathEscape(repo), url.PathEscape(workflowID)),
@@ -252,7 +230,7 @@ func DispatchRepoActionWorkflowFn(ctx context.Context, req mcp.CallToolRequest)
 	)
 	if err != nil {
 		var httpErr *gitea.HTTPError
-		if errors.As(err, &httpErr) && (httpErr.StatusCode == 404 || httpErr.StatusCode == 405) {
+		if errors.As(err, &httpErr) && (httpErr.StatusCode == http.StatusNotFound || httpErr.StatusCode == http.StatusMethodNotAllowed) {
 			return to.ErrorResult(fmt.Errorf("workflow dispatch not supported on this Gitea version (endpoint returned %d). Check https://docs.gitea.com/api/1.24/ for available Actions endpoints", httpErr.StatusCode))
 		}
 		return to.ErrorResult(fmt.Errorf("dispatch action workflow err: %v", err))
@@ -260,35 +238,27 @@ func DispatchRepoActionWorkflowFn(ctx context.Context, req mcp.CallToolRequest)
 	return to.TextResult(map[string]any{"message": "workflow dispatched"})
 }
 
-func ListRepoActionRunsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoActionRunsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func listRepoActionRunsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	page, _ := req.GetArguments()["page"].(float64)
-	if page <= 0 {
-		page = 1
-	}
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
-	if pageSize <= 0 {
-		pageSize = 50
-	}
-	statusFilter, _ := req.GetArguments()["status"].(string)
+	page, pageSize := params.GetPagination(args, 30)
+	statusFilter, _ := args["status"].(string)
 
 	query := url.Values{}
-	query.Set("page", fmt.Sprintf("%d", int(page)))
-	query.Set("limit", fmt.Sprintf("%d", int(pageSize)))
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
 	if statusFilter != "" {
 		query.Set("status", statusFilter)
 	}
 
 	var result any
-	_, _, err := doJSONWithFallback(ctx, "GET",
+	err = doJSONWithFallback(ctx, "GET",
 		[]string{
 			fmt.Sprintf("repos/%s/%s/actions/runs", url.PathEscape(owner), url.PathEscape(repo)),
 		},
@@ -297,55 +267,53 @@ func ListRepoActionRunsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Ca
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list action runs err: %v", err))
 	}
-	return to.TextResult(result)
+	return to.TextResult(slimActionRuns(result))
 }
 
-func GetRepoActionRunFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetRepoActionRunFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func getRepoActionRunFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	runID, ok := req.GetArguments()["run_id"].(float64)
-	if !ok || runID <= 0 {
-		return to.ErrorResult(fmt.Errorf("run_id is required"))
+	runID, err := params.GetIndex(args, "run_id")
+	if err != nil || runID <= 0 {
+		return to.ErrorResult(errors.New("run_id is required"))
 	}
 
 	var result any
-	_, _, err := doJSONWithFallback(ctx, "GET",
+	err = doJSONWithFallback(ctx, "GET",
 		[]string{
-			fmt.Sprintf("repos/%s/%s/actions/runs/%d", url.PathEscape(owner), url.PathEscape(repo), int64(runID)),
+			fmt.Sprintf("repos/%s/%s/actions/runs/%d", url.PathEscape(owner), url.PathEscape(repo), runID),
 		},
 		nil, nil, &result,
 	)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get action run err: %v", err))
 	}
-	return to.TextResult(result)
+	return to.TextResult(slimActionRun(result))
 }
 
-func CancelRepoActionRunFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CancelRepoActionRunFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func cancelRepoActionRunFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	runID, ok := req.GetArguments()["run_id"].(float64)
-	if !ok || runID <= 0 {
-		return to.ErrorResult(fmt.Errorf("run_id is required"))
+	runID, err := params.GetIndex(args, "run_id")
+	if err != nil || runID <= 0 {
+		return to.ErrorResult(errors.New("run_id is required"))
 	}
 
-	_, _, err := doJSONWithFallback(ctx, "POST",
+	err = doJSONWithFallback(ctx, "POST",
 		[]string{
-			fmt.Sprintf("repos/%s/%s/actions/runs/%d/cancel", url.PathEscape(owner), url.PathEscape(repo), int64(runID)),
+			fmt.Sprintf("repos/%s/%s/actions/runs/%d/cancel", url.PathEscape(owner), url.PathEscape(repo), runID),
 		},
 		nil, nil, nil,
 	)
@@ -355,31 +323,30 @@ func CancelRepoActionRunFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.C
 	return to.TextResult(map[string]any{"message": "run cancellation requested"})
 }
 
-func RerunRepoActionRunFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called RerunRepoActionRunFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func rerunRepoActionRunFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	runID, ok := req.GetArguments()["run_id"].(float64)
-	if !ok || runID <= 0 {
-		return to.ErrorResult(fmt.Errorf("run_id is required"))
+	runID, err := params.GetIndex(args, "run_id")
+	if err != nil || runID <= 0 {
+		return to.ErrorResult(errors.New("run_id is required"))
 	}
 
-	_, _, err := doJSONWithFallback(ctx, "POST",
+	err = doJSONWithFallback(ctx, "POST",
 		[]string{
-			fmt.Sprintf("repos/%s/%s/actions/runs/%d/rerun", url.PathEscape(owner), url.PathEscape(repo), int64(runID)),
-			fmt.Sprintf("repos/%s/%s/actions/runs/%d/rerun-failed-jobs", url.PathEscape(owner), url.PathEscape(repo), int64(runID)),
+			fmt.Sprintf("repos/%s/%s/actions/runs/%d/rerun", url.PathEscape(owner), url.PathEscape(repo), runID),
+			fmt.Sprintf("repos/%s/%s/actions/runs/%d/rerun-failed-jobs", url.PathEscape(owner), url.PathEscape(repo), runID),
 		},
 		nil, nil, nil,
 	)
 	if err != nil {
 		var httpErr *gitea.HTTPError
-		if errors.As(err, &httpErr) && (httpErr.StatusCode == 404 || httpErr.StatusCode == 405) {
+		if errors.As(err, &httpErr) && (httpErr.StatusCode == http.StatusNotFound || httpErr.StatusCode == http.StatusMethodNotAllowed) {
 			return to.ErrorResult(fmt.Errorf("workflow rerun not supported on this Gitea version (endpoint returned %d). Check https://docs.gitea.com/api/1.24/ for available Actions endpoints", httpErr.StatusCode))
 		}
 		return to.ErrorResult(fmt.Errorf("rerun action run err: %v", err))
@@ -387,35 +354,27 @@ func RerunRepoActionRunFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Ca
 	return to.TextResult(map[string]any{"message": "run rerun requested"})
 }
 
-func ListRepoActionJobsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoActionJobsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func listRepoActionJobsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	page, _ := req.GetArguments()["page"].(float64)
-	if page <= 0 {
-		page = 1
-	}
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
-	if pageSize <= 0 {
-		pageSize = 50
-	}
-	statusFilter, _ := req.GetArguments()["status"].(string)
+	page, pageSize := params.GetPagination(args, 30)
+	statusFilter, _ := args["status"].(string)
 
 	query := url.Values{}
-	query.Set("page", fmt.Sprintf("%d", int(page)))
-	query.Set("limit", fmt.Sprintf("%d", int(pageSize)))
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
 	if statusFilter != "" {
 		query.Set("status", statusFilter)
 	}
 
 	var result any
-	_, _, err := doJSONWithFallback(ctx, "GET",
+	err = doJSONWithFallback(ctx, "GET",
 		[]string{
 			fmt.Sprintf("repos/%s/%s/actions/jobs", url.PathEscape(owner), url.PathEscape(repo)),
 		},
@@ -424,45 +383,199 @@ func ListRepoActionJobsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Ca
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list action jobs err: %v", err))
 	}
-	return to.TextResult(result)
+	return to.TextResult(slimActionJobs(result))
 }
 
-func ListRepoActionRunJobsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoActionRunJobsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func listRepoActionRunJobsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	runID, ok := req.GetArguments()["run_id"].(float64)
-	if !ok || runID <= 0 {
-		return to.ErrorResult(fmt.Errorf("run_id is required"))
-	}
-	page, _ := req.GetArguments()["page"].(float64)
-	if page <= 0 {
-		page = 1
-	}
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
-	if pageSize <= 0 {
-		pageSize = 50
+	runID, err := params.GetIndex(args, "run_id")
+	if err != nil || runID <= 0 {
+		return to.ErrorResult(errors.New("run_id is required"))
 	}
+	page, pageSize := params.GetPagination(args, 30)
 
 	query := url.Values{}
-	query.Set("page", fmt.Sprintf("%d", int(page)))
-	query.Set("limit", fmt.Sprintf("%d", int(pageSize)))
+	query.Set("page", strconv.Itoa(page))
+	query.Set("limit", strconv.Itoa(pageSize))
 
 	var result any
-	_, _, err := doJSONWithFallback(ctx, "GET",
+	err = doJSONWithFallback(ctx, "GET",
 		[]string{
-			fmt.Sprintf("repos/%s/%s/actions/runs/%d/jobs", url.PathEscape(owner), url.PathEscape(repo), int64(runID)),
+			fmt.Sprintf("repos/%s/%s/actions/runs/%d/jobs", url.PathEscape(owner), url.PathEscape(repo), runID),
 		},
 		query, nil, &result,
 	)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list action run jobs err: %v", err))
 	}
-	return to.TextResult(result)
+	return to.TextResult(slimActionJobs(result))
+}
+
+func getRepoActionJobFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	jobID, err := params.GetIndex(args, "job_id")
+	if err != nil || jobID <= 0 {
+		return to.ErrorResult(errors.New("job_id is required"))
+	}
+
+	var result any
+	err = doJSONWithFallback(ctx, "GET",
+		[]string{
+			fmt.Sprintf("repos/%s/%s/actions/jobs/%d", url.PathEscape(owner), url.PathEscape(repo), jobID),
+		},
+		nil, nil, &result,
+	)
+	if err != nil {
+		var httpErr *gitea.HTTPError
+		if errors.As(err, &httpErr) && (httpErr.StatusCode == http.StatusNotFound || httpErr.StatusCode == http.StatusMethodNotAllowed) {
+			return to.ErrorResult(fmt.Errorf("get action job not supported on this Gitea version (endpoint returned %d, requires Gitea 1.26+). Check https://docs.gitea.com/api/1.26/ for available Actions endpoints", httpErr.StatusCode))
+		}
+		return to.ErrorResult(fmt.Errorf("get action job err: %v", err))
+	}
+	return to.TextResult(slimActionJob(result))
+}
+
+func logPaths(owner, repo string, jobID int64) []string {
+	return []string{
+		fmt.Sprintf("repos/%s/%s/actions/jobs/%d/logs", url.PathEscape(owner), url.PathEscape(repo), jobID),
+		fmt.Sprintf("repos/%s/%s/actions/jobs/%d/log", url.PathEscape(owner), url.PathEscape(repo), jobID),
+		fmt.Sprintf("repos/%s/%s/actions/tasks/%d/log", url.PathEscape(owner), url.PathEscape(repo), jobID),
+		fmt.Sprintf("repos/%s/%s/actions/task/%d/log", url.PathEscape(owner), url.PathEscape(repo), jobID),
+	}
+}
+
+func fetchJobLogBytes(ctx context.Context, owner, repo string, jobID int64) ([]byte, string, error) {
+	var lastErr error
+	for _, p := range logPaths(owner, repo, jobID) {
+		b, _, err := gitea.DoBytes(ctx, "GET", p, nil, nil, "text/plain")
+		if err == nil {
+			return b, p, nil
+		}
+		lastErr = err
+		var httpErr *gitea.HTTPError
+		if errors.As(err, &httpErr) && (httpErr.StatusCode == http.StatusNotFound || httpErr.StatusCode == http.StatusMethodNotAllowed) {
+			continue
+		}
+		return nil, p, err
+	}
+	return nil, "", lastErr
+}
+
+func tailByLines(data []byte, tailLines int) []byte {
+	if tailLines <= 0 || len(data) == 0 {
+		return data
+	}
+	lines := 0
+	i := len(data) - 1
+	for i >= 0 {
+		if data[i] == '\n' {
+			lines++
+			if lines > tailLines {
+				return data[i+1:]
+			}
+		}
+		i--
+	}
+	return data
+}
+
+func limitBytes(data []byte, maxBytes int) ([]byte, bool) {
+	if maxBytes <= 0 {
+		return data, false
+	}
+	if len(data) <= maxBytes {
+		return data, false
+	}
+	return data[len(data)-maxBytes:], true
+}
+
+func getRepoActionJobLogPreviewFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	jobID, err := params.GetIndex(args, "job_id")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	tailLines := int(params.GetOptionalInt(args, "tail_lines", 200))
+	maxBytes := int(params.GetOptionalInt(args, "max_bytes", 65536))
+	raw, usedPath, err := fetchJobLogBytes(ctx, owner, repo, jobID)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get job log err: %v", err))
+	}
+
+	tailed := tailByLines(raw, tailLines)
+	limited, truncated := limitBytes(tailed, maxBytes)
+
+	return to.TextResult(map[string]any{
+		"endpoint":   usedPath,
+		"job_id":     jobID,
+		"bytes":      len(raw),
+		"tail_lines": tailLines,
+		"max_bytes":  maxBytes,
+		"truncated":  truncated,
+		"log":        string(limited),
+	})
+}
+
+func downloadRepoActionJobLogFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	jobID, err := params.GetIndex(args, "job_id")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	outputPath, _ := args["output_path"].(string)
+
+	raw, usedPath, err := fetchJobLogBytes(ctx, owner, repo, jobID)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("download job log err: %v", err))
+	}
+
+	if outputPath == "" {
+		home, _ := os.UserHomeDir()
+		if home == "" {
+			home = os.TempDir()
+		}
+		outputPath = filepath.Join(home, ".gitea-mcp", "artifacts", "actions-logs", owner, repo, fmt.Sprintf("%d.log", jobID))
+	}
+
+	if err := os.MkdirAll(filepath.Dir(outputPath), 0o700); err != nil {
+		return to.ErrorResult(fmt.Errorf("create output dir err: %v", err))
+	}
+	if err := os.WriteFile(outputPath, raw, 0o600); err != nil {
+		return to.ErrorResult(fmt.Errorf("write log file err: %v", err))
+	}
+
+	return to.TextResult(map[string]any{
+		"endpoint": usedPath,
+		"job_id":   jobID,
+		"path":     outputPath,
+		"bytes":    len(raw),
+	})
 }

operation/actions/secrets.go

@@ -1,292 +0,0 @@
-package actions
-
-import (
-	"context"
-	"fmt"
-	"net/url"
-	"time"
-
-	"gitea.com/gitea/gitea-mcp/pkg/gitea"
-	"gitea.com/gitea/gitea-mcp/pkg/log"
-	"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 (
-	ListRepoActionSecretsToolName  = "list_repo_action_secrets"
-	UpsertRepoActionSecretToolName = "upsert_repo_action_secret"
-	DeleteRepoActionSecretToolName = "delete_repo_action_secret"
-	ListOrgActionSecretsToolName   = "list_org_action_secrets"
-	UpsertOrgActionSecretToolName  = "upsert_org_action_secret"
-	DeleteOrgActionSecretToolName  = "delete_org_action_secret"
-)
-
-type secretMeta struct {
-	Name        string    `json:"name"`
-	Description string    `json:"description,omitempty"`
-	CreatedAt   time.Time `json:"created_at,omitempty"`
-}
-
-var (
-	ListRepoActionSecretsTool = mcp.NewTool(
-		ListRepoActionSecretsToolName,
-		mcp.WithDescription("List repository Actions secrets (metadata only; secret values are never returned)"),
-		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("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100), mcp.Min(1)),
-	)
-
-	UpsertRepoActionSecretTool = mcp.NewTool(
-		UpsertRepoActionSecretToolName,
-		mcp.WithDescription("Create or update (upsert) a repository Actions secret"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("secret name")),
-		mcp.WithString("data", mcp.Required(), mcp.Description("secret value")),
-		mcp.WithString("description", mcp.Description("secret description")),
-	)
-
-	DeleteRepoActionSecretTool = mcp.NewTool(
-		DeleteRepoActionSecretToolName,
-		mcp.WithDescription("Delete a repository Actions secret"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("secretName", mcp.Required(), mcp.Description("secret name")),
-	)
-
-	ListOrgActionSecretsTool = mcp.NewTool(
-		ListOrgActionSecretsToolName,
-		mcp.WithDescription("List organization Actions secrets (metadata only; secret values are never returned)"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100), mcp.Min(1)),
-	)
-
-	UpsertOrgActionSecretTool = mcp.NewTool(
-		UpsertOrgActionSecretToolName,
-		mcp.WithDescription("Create or update (upsert) an organization Actions secret"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("secret name")),
-		mcp.WithString("data", mcp.Required(), mcp.Description("secret value")),
-		mcp.WithString("description", mcp.Description("secret description")),
-	)
-
-	DeleteOrgActionSecretTool = mcp.NewTool(
-		DeleteOrgActionSecretToolName,
-		mcp.WithDescription("Delete an organization Actions secret"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		mcp.WithString("secretName", mcp.Required(), mcp.Description("secret name")),
-	)
-)
-
-func init() {
-	Tool.RegisterRead(server.ServerTool{Tool: ListRepoActionSecretsTool, Handler: ListRepoActionSecretsFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: UpsertRepoActionSecretTool, Handler: UpsertRepoActionSecretFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: DeleteRepoActionSecretTool, Handler: DeleteRepoActionSecretFn})
-
-	Tool.RegisterRead(server.ServerTool{Tool: ListOrgActionSecretsTool, Handler: ListOrgActionSecretsFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: UpsertOrgActionSecretTool, Handler: UpsertOrgActionSecretFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: DeleteOrgActionSecretTool, Handler: DeleteOrgActionSecretFn})
-}
-
-func ListRepoActionSecretsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoActionSecretsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	page, _ := req.GetArguments()["page"].(float64)
-	if page <= 0 {
-		page = 1
-	}
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
-	if pageSize <= 0 {
-		pageSize = 100
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-
-	secrets, _, err := client.ListRepoActionSecret(owner, repo, gitea_sdk.ListRepoActionSecretOption{
-		ListOptions: gitea_sdk.ListOptions{Page: int(page), PageSize: int(pageSize)},
-	})
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("list repo action secrets err: %v", err))
-	}
-
-	metas := make([]secretMeta, 0, len(secrets))
-	for _, s := range secrets {
-		if s == nil {
-			continue
-		}
-		metas = append(metas, secretMeta{
-			Name:        s.Name,
-			Description: s.Description,
-			CreatedAt:   s.Created,
-		})
-	}
-	return to.TextResult(metas)
-}
-
-func UpsertRepoActionSecretFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called UpsertRepoActionSecretFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-	data, ok := req.GetArguments()["data"].(string)
-	if !ok || data == "" {
-		return to.ErrorResult(fmt.Errorf("data is required"))
-	}
-	description, _ := req.GetArguments()["description"].(string)
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	resp, err := client.CreateRepoActionSecret(owner, repo, gitea_sdk.CreateSecretOption{
-		Name:        name,
-		Data:        data,
-		Description: description,
-	})
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("upsert repo action secret err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "secret upserted", "status": resp.StatusCode})
-}
-
-func DeleteRepoActionSecretFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteRepoActionSecretFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	secretName, ok := req.GetArguments()["secretName"].(string)
-	if !ok || secretName == "" {
-		return to.ErrorResult(fmt.Errorf("secretName is required"))
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	resp, err := client.DeleteRepoActionSecret(owner, repo, secretName)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("delete repo action secret err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "secret deleted", "status": resp.StatusCode})
-}
-
-func ListOrgActionSecretsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListOrgActionSecretsFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok || org == "" {
-		return to.ErrorResult(fmt.Errorf("org is required"))
-	}
-	page, _ := req.GetArguments()["page"].(float64)
-	if page <= 0 {
-		page = 1
-	}
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
-	if pageSize <= 0 {
-		pageSize = 100
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-
-	secrets, _, err := client.ListOrgActionSecret(org, gitea_sdk.ListOrgActionSecretOption{
-		ListOptions: gitea_sdk.ListOptions{Page: int(page), PageSize: int(pageSize)},
-	})
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("list org action secrets err: %v", err))
-	}
-
-	metas := make([]secretMeta, 0, len(secrets))
-	for _, s := range secrets {
-		if s == nil {
-			continue
-		}
-		metas = append(metas, secretMeta{
-			Name:        s.Name,
-			Description: s.Description,
-			CreatedAt:   s.Created,
-		})
-	}
-	return to.TextResult(metas)
-}
-
-func UpsertOrgActionSecretFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called UpsertOrgActionSecretFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok || org == "" {
-		return to.ErrorResult(fmt.Errorf("org is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-	data, ok := req.GetArguments()["data"].(string)
-	if !ok || data == "" {
-		return to.ErrorResult(fmt.Errorf("data is required"))
-	}
-	description, _ := req.GetArguments()["description"].(string)
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	resp, err := client.CreateOrgActionSecret(org, gitea_sdk.CreateSecretOption{
-		Name:        name,
-		Data:        data,
-		Description: description,
-	})
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("upsert org action secret err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "secret upserted", "status": resp.StatusCode})
-}
-
-func DeleteOrgActionSecretFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteOrgActionSecretFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok || org == "" {
-		return to.ErrorResult(fmt.Errorf("org is required"))
-	}
-	secretName, ok := req.GetArguments()["secretName"].(string)
-	if !ok || secretName == "" {
-		return to.ErrorResult(fmt.Errorf("secretName is required"))
-	}
-
-	escapedOrg := url.PathEscape(org)
-	escapedSecret := url.PathEscape(secretName)
-	_, err := gitea.DoJSON(ctx, "DELETE", fmt.Sprintf("orgs/%s/actions/secrets/%s", escapedOrg, escapedSecret), nil, nil, nil)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("delete org action secret err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "secret deleted"})
-}

operation/actions/slim.go

@@ -0,0 +1,115 @@
+package actions
+
+func pick(m map[string]any, keys ...string) map[string]any {
+	out := make(map[string]any, len(keys))
+	for _, k := range keys {
+		if v, ok := m[k]; ok {
+			out[k] = v
+		}
+	}
+	return out
+}
+
+func slimPaginated(raw any, itemFn func(map[string]any) map[string]any) any {
+	m, ok := raw.(map[string]any)
+	if !ok {
+		return raw
+	}
+	result := make(map[string]any)
+	if tc, ok := m["total_count"]; ok {
+		result["total_count"] = tc
+	}
+	for key, val := range m {
+		if key == "total_count" {
+			continue
+		}
+		arr, ok := val.([]any)
+		if !ok {
+			continue
+		}
+		slimmed := make([]any, 0, len(arr))
+		for _, item := range arr {
+			if im, ok := item.(map[string]any); ok {
+				slimmed = append(slimmed, itemFn(im))
+			}
+		}
+		result[key] = slimmed
+		break
+	}
+	return result
+}
+
+func slimRun(m map[string]any) map[string]any {
+	return pick(m, "id", "name", "head_branch", "head_sha", "run_number",
+		"event", "status", "conclusion", "workflow_id",
+		"html_url", "created_at", "updated_at")
+}
+
+func slimJob(m map[string]any) map[string]any {
+	out := pick(m, "id", "run_id", "name", "workflow_name",
+		"status", "conclusion", "html_url",
+		"started_at", "completed_at")
+	if steps, ok := m["steps"].([]any); ok {
+		slim := make([]any, 0, len(steps))
+		for _, s := range steps {
+			if sm, ok := s.(map[string]any); ok {
+				slim = append(slim, pick(sm, "name", "number", "status", "conclusion"))
+			}
+		}
+		out["steps"] = slim
+	}
+	return out
+}
+
+func slimWorkflow(m map[string]any) map[string]any {
+	return pick(m, "id", "name", "path", "state", "html_url", "created_at", "updated_at")
+}
+
+func slimActionRun(raw any) any {
+	if m, ok := raw.(map[string]any); ok {
+		return slimRun(m)
+	}
+	return raw
+}
+
+func slimActionRuns(raw any) any {
+	return slimPaginated(raw, slimRun)
+}
+
+func slimActionJob(raw any) any {
+	if m, ok := raw.(map[string]any); ok {
+		return slimJob(m)
+	}
+	return raw
+}
+
+func slimActionJobs(raw any) any {
+	return slimPaginated(raw, slimJob)
+}
+
+func slimActionWorkflow(raw any) any {
+	if m, ok := raw.(map[string]any); ok {
+		return slimWorkflow(m)
+	}
+	return raw
+}
+
+func slimActionWorkflows(raw any) any {
+	return slimPaginated(raw, slimWorkflow)
+}
+
+func slimArtifact(m map[string]any) map[string]any {
+	return pick(m, "id", "name", "size_in_bytes", "expired",
+		"created_at", "updated_at", "expires_at")
+}
+
+func slimActionArtifact(raw any) any {
+	if m, ok := raw.(map[string]any); ok {
+		return slimArtifact(m)
+	}
+	return raw
+}
+
+func slimActionArtifacts(raw any) any {
+	return slimPaginated(raw, slimArtifact)
+}

operation/actions/slim_test.go

@@ -0,0 +1,57 @@
+package actions
+
+import "testing"
+
+func TestSlimActionJobKeepsExpectedKeys(t *testing.T) {
+	raw := map[string]any{
+		"id":            float64(42),
+		"run_id":        float64(7),
+		"name":          "build",
+		"workflow_name": "CI",
+		"status":        "completed",
+		"conclusion":    "success",
+		"html_url":      "https://gitea.example/x",
+		"started_at":    "2026-01-01T00:00:00Z",
+		"completed_at":  "2026-01-01T00:01:00Z",
+		"steps": []any{
+			map[string]any{"name": "checkout", "number": float64(1), "status": "completed", "conclusion": "success", "extra": "drop me"},
+		},
+		// fields that must be dropped
+		"head_sha":    "deadbeef",
+		"runner_name": "runner-1",
+	}
+
+	out, ok := slimActionJob(raw).(map[string]any)
+	if !ok {
+		t.Fatalf("slimActionJob did not return a map, got %T", slimActionJob(raw))
+	}
+
+	for _, k := range []string{"id", "run_id", "name", "workflow_name", "status", "conclusion", "html_url", "started_at", "completed_at", "steps"} {
+		if _, present := out[k]; !present {
+			t.Errorf("expected key %q to be kept", k)
+		}
+	}
+	for _, k := range []string{"head_sha", "runner_name"} {
+		if _, present := out[k]; present {
+			t.Errorf("expected key %q to be dropped", k)
+		}
+	}
+
+	steps, ok := out["steps"].([]any)
+	if !ok || len(steps) != 1 {
+		t.Fatalf("expected 1 slimmed step, got %v", out["steps"])
+	}
+	step := steps[0].(map[string]any)
+	if _, present := step["extra"]; present {
+		t.Errorf("expected step field 'extra' to be dropped")
+	}
+	if step["name"] != "checkout" {
+		t.Errorf("expected step name 'checkout', got %v", step["name"])
+	}
+}
+
+func TestSlimActionJobPassesThroughNonMap(t *testing.T) {
+	if got := slimActionJob("not-a-map"); got != "not-a-map" {
+		t.Errorf("expected passthrough, got %v", got)
+	}
+}

operation/actions/variables.go

@@ -1,402 +0,0 @@
-package actions
-
-import (
-	"context"
-	"fmt"
-	"net/url"
-
-	"gitea.com/gitea/gitea-mcp/pkg/gitea"
-	"gitea.com/gitea/gitea-mcp/pkg/log"
-	"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 (
-	ListRepoActionVariablesToolName  = "list_repo_action_variables"
-	GetRepoActionVariableToolName    = "get_repo_action_variable"
-	CreateRepoActionVariableToolName = "create_repo_action_variable"
-	UpdateRepoActionVariableToolName = "update_repo_action_variable"
-	DeleteRepoActionVariableToolName = "delete_repo_action_variable"
-
-	ListOrgActionVariablesToolName   = "list_org_action_variables"
-	GetOrgActionVariableToolName     = "get_org_action_variable"
-	CreateOrgActionVariableToolName  = "create_org_action_variable"
-	UpdateOrgActionVariableToolName  = "update_org_action_variable"
-	DeleteOrgActionVariableToolName  = "delete_org_action_variable"
-)
-
-var (
-	ListRepoActionVariablesTool = mcp.NewTool(
-		ListRepoActionVariablesToolName,
-		mcp.WithDescription("List repository Actions variables"),
-		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("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100), mcp.Min(1)),
-	)
-
-	GetRepoActionVariableTool = mcp.NewTool(
-		GetRepoActionVariableToolName,
-		mcp.WithDescription("Get a repository Actions variable by name"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("variable name")),
-	)
-
-	CreateRepoActionVariableTool = mcp.NewTool(
-		CreateRepoActionVariableToolName,
-		mcp.WithDescription("Create a repository Actions variable"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("variable name")),
-		mcp.WithString("value", mcp.Required(), mcp.Description("variable value")),
-	)
-
-	UpdateRepoActionVariableTool = mcp.NewTool(
-		UpdateRepoActionVariableToolName,
-		mcp.WithDescription("Update a repository Actions variable"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("variable name")),
-		mcp.WithString("value", mcp.Required(), mcp.Description("new variable value")),
-	)
-
-	DeleteRepoActionVariableTool = mcp.NewTool(
-		DeleteRepoActionVariableToolName,
-		mcp.WithDescription("Delete a repository Actions variable"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("variable name")),
-	)
-
-	ListOrgActionVariablesTool = mcp.NewTool(
-		ListOrgActionVariablesToolName,
-		mcp.WithDescription("List organization Actions variables"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1), mcp.Min(1)),
-		mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100), mcp.Min(1)),
-	)
-
-	GetOrgActionVariableTool = mcp.NewTool(
-		GetOrgActionVariableToolName,
-		mcp.WithDescription("Get an organization Actions variable by name"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("variable name")),
-	)
-
-	CreateOrgActionVariableTool = mcp.NewTool(
-		CreateOrgActionVariableToolName,
-		mcp.WithDescription("Create an organization Actions variable"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("variable name")),
-		mcp.WithString("value", mcp.Required(), mcp.Description("variable value")),
-		mcp.WithString("description", mcp.Description("variable description")),
-	)
-
-	UpdateOrgActionVariableTool = mcp.NewTool(
-		UpdateOrgActionVariableToolName,
-		mcp.WithDescription("Update an organization Actions variable"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("variable name")),
-		mcp.WithString("value", mcp.Required(), mcp.Description("new variable value")),
-		mcp.WithString("description", mcp.Description("new variable description")),
-	)
-
-	DeleteOrgActionVariableTool = mcp.NewTool(
-		DeleteOrgActionVariableToolName,
-		mcp.WithDescription("Delete an organization Actions variable"),
-		mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("variable name")),
-	)
-)
-
-func init() {
-	Tool.RegisterRead(server.ServerTool{Tool: ListRepoActionVariablesTool, Handler: ListRepoActionVariablesFn})
-	Tool.RegisterRead(server.ServerTool{Tool: GetRepoActionVariableTool, Handler: GetRepoActionVariableFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: CreateRepoActionVariableTool, Handler: CreateRepoActionVariableFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: UpdateRepoActionVariableTool, Handler: UpdateRepoActionVariableFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: DeleteRepoActionVariableTool, Handler: DeleteRepoActionVariableFn})
-
-	Tool.RegisterRead(server.ServerTool{Tool: ListOrgActionVariablesTool, Handler: ListOrgActionVariablesFn})
-	Tool.RegisterRead(server.ServerTool{Tool: GetOrgActionVariableTool, Handler: GetOrgActionVariableFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: CreateOrgActionVariableTool, Handler: CreateOrgActionVariableFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: UpdateOrgActionVariableTool, Handler: UpdateOrgActionVariableFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: DeleteOrgActionVariableTool, Handler: DeleteOrgActionVariableFn})
-}
-
-func ListRepoActionVariablesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoActionVariablesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	page, _ := req.GetArguments()["page"].(float64)
-	if page <= 0 {
-		page = 1
-	}
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
-	if pageSize <= 0 {
-		pageSize = 100
-	}
-
-	query := url.Values{}
-	query.Set("page", fmt.Sprintf("%d", int(page)))
-	query.Set("limit", fmt.Sprintf("%d", int(pageSize)))
-
-	var result any
-	_, err := gitea.DoJSON(ctx, "GET", fmt.Sprintf("repos/%s/%s/actions/variables", url.PathEscape(owner), url.PathEscape(repo)), query, nil, &result)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("list repo action variables err: %v", err))
-	}
-	return to.TextResult(result)
-}
-
-func GetRepoActionVariableFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetRepoActionVariableFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	variable, _, err := client.GetRepoActionVariable(owner, repo, name)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get repo action variable err: %v", err))
-	}
-	return to.TextResult(variable)
-}
-
-func CreateRepoActionVariableFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateRepoActionVariableFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-	value, ok := req.GetArguments()["value"].(string)
-	if !ok || value == "" {
-		return to.ErrorResult(fmt.Errorf("value is required"))
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	resp, err := client.CreateRepoActionVariable(owner, repo, name, value)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("create repo action variable err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "variable created", "status": resp.StatusCode})
-}
-
-func UpdateRepoActionVariableFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called UpdateRepoActionVariableFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-	value, ok := req.GetArguments()["value"].(string)
-	if !ok || value == "" {
-		return to.ErrorResult(fmt.Errorf("value is required"))
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	resp, err := client.UpdateRepoActionVariable(owner, repo, name, value)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("update repo action variable err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "variable updated", "status": resp.StatusCode})
-}
-
-func DeleteRepoActionVariableFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteRepoActionVariableFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok || owner == "" {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok || repo == "" {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	resp, err := client.DeleteRepoActionVariable(owner, repo, name)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("delete repo action variable err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "variable deleted", "status": resp.StatusCode})
-}
-
-func ListOrgActionVariablesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListOrgActionVariablesFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok || org == "" {
-		return to.ErrorResult(fmt.Errorf("org is required"))
-	}
-	page, _ := req.GetArguments()["page"].(float64)
-	if page <= 0 {
-		page = 1
-	}
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
-	if pageSize <= 0 {
-		pageSize = 100
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	variables, _, err := client.ListOrgActionVariable(org, gitea_sdk.ListOrgActionVariableOption{
-		ListOptions: gitea_sdk.ListOptions{Page: int(page), PageSize: int(pageSize)},
-	})
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("list org action variables err: %v", err))
-	}
-	return to.TextResult(variables)
-}
-
-func GetOrgActionVariableFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetOrgActionVariableFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok || org == "" {
-		return to.ErrorResult(fmt.Errorf("org is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	variable, _, err := client.GetOrgActionVariable(org, name)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get org action variable err: %v", err))
-	}
-	return to.TextResult(variable)
-}
-
-func CreateOrgActionVariableFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateOrgActionVariableFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok || org == "" {
-		return to.ErrorResult(fmt.Errorf("org is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-	value, ok := req.GetArguments()["value"].(string)
-	if !ok || value == "" {
-		return to.ErrorResult(fmt.Errorf("value is required"))
-	}
-	description, _ := req.GetArguments()["description"].(string)
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	resp, err := client.CreateOrgActionVariable(org, gitea_sdk.CreateOrgActionVariableOption{
-		Name:        name,
-		Value:       value,
-		Description: description,
-	})
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("create org action variable err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "variable created", "status": resp.StatusCode})
-}
-
-func UpdateOrgActionVariableFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called UpdateOrgActionVariableFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok || org == "" {
-		return to.ErrorResult(fmt.Errorf("org is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-	value, ok := req.GetArguments()["value"].(string)
-	if !ok || value == "" {
-		return to.ErrorResult(fmt.Errorf("value is required"))
-	}
-	description, _ := req.GetArguments()["description"].(string)
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	resp, err := client.UpdateOrgActionVariable(org, name, gitea_sdk.UpdateOrgActionVariableOption{
-		Value:       value,
-		Description: description,
-	})
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("update org action variable err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "variable updated", "status": resp.StatusCode})
-}
-
-func DeleteOrgActionVariableFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteOrgActionVariableFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok || org == "" {
-		return to.ErrorResult(fmt.Errorf("org is required"))
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok || name == "" {
-		return to.ErrorResult(fmt.Errorf("name is required"))
-	}
-
-	_, err := gitea.DoJSON(ctx, "DELETE", fmt.Sprintf("orgs/%s/actions/variables/%s", url.PathEscape(org), url.PathEscape(name)), nil, nil, nil)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("delete org action variable err: %v", err))
-	}
-	return to.TextResult(map[string]any{"message": "variable deleted"})
-}
-
-

operation/issue/attachment.go

@@ -0,0 +1,313 @@
+package issue
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"mime"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.com/gitea/gitea-mcp/pkg/annotation"
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+	"gitea.com/gitea/gitea-mcp/pkg/gitea"
+	"gitea.com/gitea/gitea-mcp/pkg/params"
+	"gitea.com/gitea/gitea-mcp/pkg/to"
+	"gitea.com/gitea/gitea-mcp/pkg/tool"
+
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+const AttachmentReadToolName = "attachment_read"
+
+var AttachmentReadTool = tool.NewDefinition(
+	AttachmentReadToolName,
+	"Read issue/comment attachments: list metadata, get metadata, or download content.",
+	annotation.ReadOnly("Read issue or comment attachments"),
+	tool.String("method", tool.Required(), tool.Enum("list", "get", "download")),
+	tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+	tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+	tool.Number("issue_number", tool.Description("required for issue attachment list/get or issue-scoped metadata lookup")),
+	tool.Number("comment_id", tool.Description("required for comment attachment list/get or comment-scoped metadata lookup")),
+	tool.Number("attachment_id", tool.Description("required for get and for download when attachment_uuid is not provided")),
+	tool.String("attachment_uuid", tool.Description("attachment UUID for direct download path lookup")),
+	tool.String("output_path", tool.Description("write the attachment to this exact path")),
+)
+
+func init() {
+	Tool.RegisterRead(tool.ServerTool{Tool: AttachmentReadTool, Handler: attachmentReadFn})
+}
+
+func attachmentReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "list":
+		return listAttachmentsFn(ctx, args)
+	case "get":
+		return getAttachmentFn(ctx, args)
+	case "download":
+		return downloadAttachmentFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func listAttachmentsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, repo, issueNumber, commentID, err := attachmentScopeArgs(args)
+	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))
+	}
+	var attachments []*gitea_sdk.Attachment
+	if issueNumber > 0 {
+		attachments, _, err = client.Issues.ListIssueAttachments(ctx, owner, repo, issueNumber)
+	} else {
+		attachments, _, err = client.Issues.ListIssueCommentAttachments(ctx, owner, repo, commentID)
+	}
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list attachments err: %v", err))
+	}
+	return to.TextResult(slimAttachments(attachments))
+}
+
+func getAttachmentFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	att, err := lookupAttachment(ctx, args)
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	return to.TextResult(slimAttachment(att))
+}
+
+func downloadAttachmentFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	explicitOutputPath := params.GetOptionalString(args, "output_path", "")
+	attachmentUUID := strings.TrimSpace(params.GetOptionalString(args, "attachment_uuid", ""))
+
+	var att *gitea_sdk.Attachment
+	if attachmentUUID == "" {
+		att, err = lookupAttachment(ctx, args)
+		if err != nil {
+			return to.ErrorResult(err)
+		}
+		attachmentUUID = strings.TrimSpace(att.UUID)
+	}
+	if attachmentUUID == "" {
+		return to.ErrorResult(errors.New("attachment_uuid or attachment metadata with uuid is required"))
+	}
+
+	name := attachmentUUID
+	if att != nil && strings.TrimSpace(att.Name) != "" {
+		name = strings.TrimSpace(att.Name)
+	}
+
+	resp, err := gitea.OpenAttachment(ctx, "/attachments/"+attachmentUUID, "*/*")
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("download attachment err: %v", err))
+	}
+	defer resp.Body.Close()
+
+	mimeType := normalizeAttachmentContentType(resp.ContentType, name)
+	if explicitOutputPath == "" && shouldInlineAttachment(att, mimeType) {
+		limited, readErr := io.ReadAll(io.LimitReader(resp.Body, int64(flag.MaxInlineAttachmentBytes)+1))
+		if readErr != nil {
+			return to.ErrorResult(fmt.Errorf("read attachment err: %v", readErr))
+		}
+		if len(limited) <= flag.MaxInlineAttachmentBytes {
+			text := fmt.Sprintf("attachment %s (%s, %d bytes, %s)", name, attachmentUUID, len(limited), mimeType)
+			return &mcp.CallToolResult{Content: []mcp.Content{
+				&mcp.TextContent{Text: text},
+				&mcp.ImageContent{Data: limited, MIMEType: mimeType},
+			}}, nil
+		}
+		outputPath := defaultAttachmentPath(owner, repo, name, attachmentUUID)
+		if err := os.MkdirAll(filepath.Dir(outputPath), 0o700); err != nil {
+			return to.ErrorResult(fmt.Errorf("create output dir err: %v", err))
+		}
+		reader := io.MultiReader(bytes.NewReader(limited), resp.Body)
+		written, err := gitea.WriteAttachment(reader, outputPath)
+		if err != nil {
+			return to.ErrorResult(fmt.Errorf("write attachment file err: %v", err))
+		}
+		return attachmentFileResult(att, outputPath, written, name, attachmentUUID, mimeType)
+	}
+
+	outputPath := explicitOutputPath
+	if outputPath == "" {
+		outputPath = defaultAttachmentPath(owner, repo, name, attachmentUUID)
+	}
+	if err := os.MkdirAll(filepath.Dir(outputPath), 0o700); err != nil {
+		return to.ErrorResult(fmt.Errorf("create output dir err: %v", err))
+	}
+	written, err := gitea.WriteAttachment(resp.Body, outputPath)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("write attachment file err: %v", err))
+	}
+	return attachmentFileResult(att, outputPath, written, name, attachmentUUID, mimeType)
+}
+
+func shouldInlineAttachment(att *gitea_sdk.Attachment, mimeType string) bool {
+	if !strings.HasPrefix(mimeType, "image/") || flag.MaxInlineAttachmentBytes <= 0 {
+		return false
+	}
+	if att == nil || att.Size <= 0 {
+		return true
+	}
+	return att.Size <= int64(flag.MaxInlineAttachmentBytes)
+}
+
+func attachmentFileResult(att *gitea_sdk.Attachment, outputPath string, written int64, name, attachmentUUID, mimeType string) (*mcp.CallToolResult, error) {
+	res := map[string]any{
+		"path":         outputPath,
+		"bytes":        written,
+		"name":         name,
+		"uuid":         attachmentUUID,
+		"mime_type":    mimeType,
+		"content_type": mimeType,
+	}
+	if att != nil {
+		res["attachment_id"] = att.ID
+	}
+	return to.TextResult(res)
+}
+
+func attachmentScopeArgs(args map[string]any) (owner, repo string, issueNumber, commentID int64, err error) {
+	owner, err = params.GetString(args, "owner")
+	if err != nil {
+		return "", "", 0, 0, err
+	}
+	repo, err = params.GetString(args, "repo")
+	if err != nil {
+		return "", "", 0, 0, err
+	}
+	issueNumber = params.GetOptionalInt(args, "issue_number", 0)
+	commentID = params.GetOptionalInt(args, "comment_id", 0)
+	if (issueNumber > 0) == (commentID > 0) {
+		return "", "", 0, 0, errors.New("exactly one of issue_number or comment_id is required")
+	}
+	return owner, repo, issueNumber, commentID, nil
+}
+
+func lookupAttachment(ctx context.Context, args map[string]any) (*gitea_sdk.Attachment, error) {
+	owner, repo, issueNumber, commentID, err := attachmentScopeArgs(args)
+	if err != nil {
+		return nil, err
+	}
+	attachmentID := params.GetOptionalInt(args, "attachment_id", 0)
+	if attachmentID <= 0 {
+		return nil, errors.New("attachment_id is required")
+	}
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("get gitea client err: %v", err)
+	}
+	if issueNumber > 0 {
+		att, _, err := client.Issues.GetIssueAttachment(ctx, owner, repo, issueNumber, attachmentID)
+		if err != nil {
+			return nil, fmt.Errorf("get issue attachment err: %v", err)
+		}
+		return att, nil
+	}
+	att, _, err := client.Issues.GetIssueCommentAttachment(ctx, owner, repo, commentID, attachmentID)
+	if err != nil {
+		return nil, fmt.Errorf("get issue comment attachment err: %v", err)
+	}
+	return att, nil
+}
+
+func slimAttachments(atts []*gitea_sdk.Attachment) []map[string]any {
+	out := make([]map[string]any, 0, len(atts))
+	for _, att := range atts {
+		out = append(out, slimAttachment(att))
+	}
+	return out
+}
+
+func slimAttachment(att *gitea_sdk.Attachment) map[string]any {
+	if att == nil {
+		return nil
+	}
+	m := map[string]any{
+		"id":             att.ID,
+		"name":           att.Name,
+		"uuid":           att.UUID,
+		"size":           att.Size,
+		"download_count": att.DownloadCount,
+		"created_at":     att.Created,
+		"mime_type":      inferAttachmentMimeType(att.Name),
+	}
+	if att.DownloadURL != "" {
+		m["browser_download_url"] = att.DownloadURL
+	}
+	return m
+}
+
+func inferAttachmentMimeType(name string) string {
+	if ext := strings.ToLower(filepath.Ext(strings.TrimSpace(name))); ext != "" {
+		if mimeType := mime.TypeByExtension(ext); mimeType != "" {
+			return strings.Split(mimeType, ";")[0]
+		}
+	}
+	return "application/octet-stream"
+}
+
+func normalizeAttachmentContentType(contentType, name string) string {
+	mediaType, _, err := mime.ParseMediaType(contentType)
+	if err == nil && mediaType != "" && mediaType != "application/octet-stream" {
+		return mediaType
+	}
+	return inferAttachmentMimeType(name)
+}
+
+func defaultAttachmentPath(owner, repo, name, uuid string) string {
+	home, _ := os.UserHomeDir()
+	if home == "" {
+		home = os.TempDir()
+	}
+	filename := attachmentFilename(name, uuid)
+	ext := filepath.Ext(filename)
+	base := strings.TrimSuffix(filename, ext)
+	if uuid != "" {
+		filename = uuid
+		if base != "" && base != "attachment" {
+			filename = base + "-" + uuid
+		}
+		filename += ext
+	}
+	return filepath.Join(home, ".gitea-mcp", "attachments", safePathPart(owner), safePathPart(repo), filename)
+}
+
+func attachmentFilename(name, uuid string) string {
+	name = strings.TrimSpace(name)
+	if name != "" && !strings.ContainsAny(name, `/\\`) && name != "." && name != ".." {
+		return name
+	}
+	if uuid != "" {
+		return uuid + ".bin"
+	}
+	return "attachment.bin"
+}
+
+func safePathPart(name string) string {
+	name = strings.TrimSpace(name)
+	if name != "" && !strings.ContainsAny(name, `/\\`) && name != "." && name != ".." {
+		return name
+	}
+	return "unknown"
+}

operation/issue/attachment_test.go

@@ -0,0 +1,241 @@
+package issue
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+	"gitea.com/gitea/gitea-mcp/pkg/gitea"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestAttachmentFilename(t *testing.T) {
+	tests := []struct {
+		name string
+		file string
+		uuid string
+		want string
+	}{
+		{"uses attachment name", "screenshot.png", "abc", "screenshot.png"},
+		{"falls back for traversal", "../etc/passwd", "abc", "abc.bin"},
+		{"falls back for empty name", "", "abc", "abc.bin"},
+		{"uses generic fallback", "", "", "attachment.bin"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := attachmentFilename(tt.file, tt.uuid); got != tt.want {
+				t.Fatalf("attachmentFilename() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestInferAttachmentMimeType(t *testing.T) {
+	if got := inferAttachmentMimeType("shot.png"); got != "image/png" {
+		t.Fatalf("inferAttachmentMimeType() = %q, want image/png", got)
+	}
+	if got := inferAttachmentMimeType("archive.unknownext"); got != "application/octet-stream" {
+		t.Fatalf("inferAttachmentMimeType() = %q, want application/octet-stream", got)
+	}
+}
+
+func TestDefaultAttachmentPath(t *testing.T) {
+	got := defaultAttachmentPath("octo", "demo", "shot.png", "uuid-1")
+	want := filepath.Join(".gitea-mcp", "attachments", "octo", "demo", "shot-uuid-1.png")
+	if !strings.HasSuffix(got, want) {
+		t.Fatalf("defaultAttachmentPath() = %q, want suffix %q", got, want)
+	}
+}
+
+func TestAttachmentReadListIssueAttachments(t *testing.T) {
+	const owner = "octo"
+	const 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", owner, repo):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"private":false}`))
+		case fmt.Sprintf("/api/v1/repos/%s/%s/issues/42/assets", owner, repo):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`[{"id":1,"name":"shot.png","uuid":"uuid-1","size":10,"download_count":2}]`))
+		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 }()
+
+	res, err := attachmentReadFn(context.Background(), map[string]any{
+		"method": "list", "owner": owner, "repo": repo, "issue_number": float64(42),
+	})
+	if err != nil {
+		t.Fatalf("attachmentReadFn() error = %v", err)
+	}
+	body := res.Content[0].(*mcp.TextContent).Text
+	if !strings.Contains(body, `"mime_type":"image/png"`) || !strings.Contains(body, `"uuid":"uuid-1"`) {
+		t.Fatalf("unexpected body: %s", body)
+	}
+}
+
+func TestDownloadAttachmentRejectsRedirectLoopAtHopLimit(t *testing.T) {
+	var serverURL string
+	redirects := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/attachments/uuid-1" {
+			t.Fatalf("path = %s", r.URL.Path)
+		}
+		redirects++
+		http.Redirect(w, r, serverURL+"/attachments/uuid-1", http.StatusFound)
+	}))
+	defer server.Close()
+	serverURL = server.URL
+
+	origHost := flag.Host
+	flag.Host = server.URL
+	defer func() { flag.Host = origHost }()
+
+	_, _, _, err := gitea.DownloadAttachment(context.Background(), "/attachments/uuid-1", "*/*")
+	if err == nil {
+		t.Fatal("expected redirect limit error")
+	}
+	if !strings.Contains(err.Error(), "stopped after 10 redirects") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if redirects != 10 {
+		t.Fatalf("redirects = %d, want 10", redirects)
+	}
+}
+
+func TestAttachmentReadDownloadSavesLargeAttachmentToDefaultFile(t *testing.T) {
+	const owner = "octo"
+	const repo = "demo"
+	const uuid = "uuid-1"
+	const name = "large.bin"
+	payload := strings.Repeat("a", 32)
+
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	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/42/assets/1", owner, repo):
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{"id": 1, "name": name, "uuid": uuid, "size": len(payload)})
+		case "/attachments/" + uuid:
+			w.Header().Set("Content-Type", "application/octet-stream")
+			_, _ = w.Write([]byte(payload))
+		default:
+			http.NotFound(w, r)
+		}
+	})
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	origHost, origToken, origVersion, origInline := flag.Host, flag.Token, flag.Version, flag.MaxInlineAttachmentBytes
+	flag.Host, flag.Token, flag.Version = server.URL, "", "test"
+	flag.MaxInlineAttachmentBytes = 8
+	defer func() {
+		flag.Host, flag.Token, flag.Version, flag.MaxInlineAttachmentBytes = origHost, origToken, origVersion, origInline
+	}()
+
+	res, err := attachmentReadFn(context.Background(), map[string]any{
+		"method": "download", "owner": owner, "repo": repo, "issue_number": float64(42), "attachment_id": float64(1),
+	})
+	if err != nil {
+		t.Fatalf("attachmentReadFn() error = %v", err)
+	}
+	body := res.Content[0].(*mcp.TextContent).Text
+	wantPath := filepath.Join(home, ".gitea-mcp", "attachments", owner, repo, "large-uuid-1.bin")
+	if !strings.Contains(body, wantPath) {
+		t.Fatalf("result missing path %q: %s", wantPath, body)
+	}
+	data, err := os.ReadFile(wantPath)
+	if err != nil {
+		t.Fatalf("ReadFile(%q): %v", wantPath, err)
+	}
+	if string(data) != payload {
+		t.Fatalf("saved payload mismatch")
+	}
+	if !strings.Contains(body, `"bytes":32`) {
+		t.Fatalf("result missing bytes: %s", body)
+	}
+}
+
+func TestAttachmentReadDownloadReturnsRawImageContent(t *testing.T) {
+	const uuid = "uuid-1"
+	payload := []byte{0, 1, 2, 250}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/attachments/"+uuid {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "image/png")
+		_, _ = w.Write(payload)
+	}))
+	defer server.Close()
+
+	originalHost := flag.Host
+	originalLimit := flag.MaxInlineAttachmentBytes
+	flag.Host = server.URL
+	flag.MaxInlineAttachmentBytes = len(payload)
+	defer func() {
+		flag.Host = originalHost
+		flag.MaxInlineAttachmentBytes = originalLimit
+	}()
+
+	result, err := attachmentReadFn(context.Background(), map[string]any{
+		"method":          "download",
+		"owner":           "octo",
+		"repo":            "demo",
+		"attachment_uuid": uuid,
+	})
+	if err != nil {
+		t.Fatalf("attachmentReadFn() error = %v", err)
+	}
+	if len(result.Content) != 2 {
+		t.Fatalf("content count = %d, want 2", len(result.Content))
+	}
+	if _, ok := result.Content[0].(*mcp.TextContent); !ok {
+		t.Fatalf("first content type = %T, want *mcp.TextContent", result.Content[0])
+	}
+	image, ok := result.Content[1].(*mcp.ImageContent)
+	if !ok {
+		t.Fatalf("second content type = %T, want *mcp.ImageContent", result.Content[1])
+	}
+	if image.MIMEType != "image/png" {
+		t.Errorf("image MIME type = %q, want image/png", image.MIMEType)
+	}
+	if !bytes.Equal(image.Data, payload) {
+		t.Errorf("image data = %v, want raw payload %v", image.Data, payload)
+	}
+	wire, err := json.Marshal(image)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	wantBase64 := base64.StdEncoding.EncodeToString(payload)
+	if !strings.Contains(string(wire), `"data":"`+wantBase64+`"`) {
+		t.Errorf("wire image = %s, want base64 data %q", wire, wantBase64)
+	}
+}

operation/issue/issue.go

@@ -3,245 +3,280 @@ 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/ptr"
+	"gitea.com/gitea/gitea-mcp/pkg/params"
+	"gitea.com/gitea/gitea-mcp/pkg/slim"
 	"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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var Tool = tool.New()
+// 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("issue")
 
 const (
-	GetIssueByIndexToolName         = "get_issue_by_index"
-	ListRepoIssuesToolName          = "list_repo_issues"
-	CreateIssueToolName             = "create_issue"
-	CreateIssueCommentToolName      = "create_issue_comment"
-	EditIssueToolName               = "edit_issue"
-	EditIssueCommentToolName        = "edit_issue_comment"
-	GetIssueCommentsByIndexToolName = "get_issue_comments_by_index"
+	ListRepoIssuesToolName = "list_issues"
+	IssueReadToolName      = "issue_read"
+	IssueWriteToolName     = "issue_write"
 )
 
 var (
-	GetIssueByIndexTool = mcp.NewTool(
-		GetIssueByIndexToolName,
-		mcp.WithDescription("get issue by index"),
-		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")),
-	)
-
-	ListRepoIssuesTool = mcp.NewTool(
+	ListRepoIssuesTool = tool.NewDefinition(
 		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("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100)),
+		"List issues in a repository (or pull requests, via the 'type' filter), filterable by state, labels, milestones, and update time range.",
+		annotation.ReadOnly("List repository issues"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("state", tool.Default("all")),
+		tool.String("type", tool.Description("issues or pulls"), tool.Enum("issues", "pulls")),
+		tool.Array("labels", tool.Description("label name filter"), tool.Items(map[string]any{"type": "string"})),
+		tool.Array("milestones", tool.Description("milestone name or ID filter"), tool.Items(map[string]any{"type": "string"})),
+		tool.String("since", tool.Description("updated after ISO 8601")),
+		tool.String("before", tool.Description("updated before ISO 8601")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 
-	CreateIssueTool = mcp.NewTool(
-		CreateIssueToolName,
-		mcp.WithDescription("create issue"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("title", mcp.Required(), mcp.Description("issue title")),
-		mcp.WithString("body", mcp.Required(), mcp.Description("issue body")),
+	IssueReadTool = tool.NewDefinition(
+		IssueReadToolName,
+		"Read issue: details, comments, or labels.",
+		annotation.ReadOnly("Read issue details"),
+		tool.String("method", tool.Required(), tool.Enum("get", "get_comments", "get_labels")),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Number("issue_number", tool.Required()),
 	)
 
-	CreateIssueCommentTool = mcp.NewTool(
-		CreateIssueCommentToolName,
-		mcp.WithDescription("create issue comment"),
-		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.WithString("body", mcp.Required(), mcp.Description("issue comment body")),
-	)
-
-	EditIssueTool = mcp.NewTool(
-		EditIssueToolName,
-		mcp.WithDescription("edit issue"),
-		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.WithString("title", mcp.Description("issue title"), mcp.DefaultString("")),
-		mcp.WithString("body", mcp.Description("issue body content")),
-		mcp.WithArray("assignees", mcp.Description("usernames to assign to this issue"), mcp.Items(map[string]interface{}{"type": "string"})),
-		mcp.WithNumber("milestone", mcp.Description("milestone number")),
-		mcp.WithString("state", mcp.Description("issue state, one of open, closed, all")),
-	)
-
-	EditIssueCommentTool = mcp.NewTool(
-		EditIssueCommentToolName,
-		mcp.WithDescription("edit issue comment"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("commentID", mcp.Required(), mcp.Description("id of issue comment")),
-		mcp.WithString("body", mcp.Required(), mcp.Description("issue comment body")),
-	)
-
-	GetIssueCommentsByIndexTool = mcp.NewTool(
-		GetIssueCommentsByIndexToolName,
-		mcp.WithDescription("get issue comment by index"),
-		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")),
+	IssueWriteTool = tool.NewDefinition(
+		IssueWriteToolName,
+		"Write issues: create, update, manage comments and labels.",
+		annotation.Write("Create or update issues, comments, and labels"),
+		tool.String("method", tool.Required(), tool.Enum("create", "update", "add_comment", "edit_comment", "add_labels", "remove_label", "replace_labels", "clear_labels")),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Number("issue_number", tool.Description("required except for 'create'")),
+		tool.String("title", tool.Description("required for 'create'")),
+		tool.String("body", tool.Description("required for 'create'/'add_comment'/'edit_comment'")),
+		tool.Array("assignees", tool.Items(map[string]any{"type": "string"})),
+		tool.Number("milestone"),
+		tool.String("state", tool.Enum("open", "closed", "all")),
+		tool.Number("commentID", tool.Description("for 'edit_comment'")),
+		tool.Array("labels", tool.Description("label IDs"), tool.Items(map[string]any{"type": "number"})),
+		tool.Number("label_id", tool.Description("for 'remove_label'")),
+		tool.String("ref", tool.Description("branch to associate")),
+		tool.String("deadline", tool.Description("ISO 8601")),
+		tool.Boolean("remove_deadline"),
 	)
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    GetIssueByIndexTool,
-		Handler: GetIssueByIndexFn,
-	})
-	Tool.RegisterRead(server.ServerTool{
+	Tool.RegisterRead(tool.ServerTool{
 		Tool:    ListRepoIssuesTool,
-		Handler: ListRepoIssuesFn,
+		Handler: listRepoIssuesFn,
 	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    CreateIssueTool,
-		Handler: CreateIssueFn,
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    IssueReadTool,
+		Handler: issueReadFn,
 	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    CreateIssueCommentTool,
-		Handler: CreateIssueCommentFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    EditIssueTool,
-		Handler: EditIssueFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    EditIssueCommentTool,
-		Handler: EditIssueCommentFn,
-	})
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    GetIssueCommentsByIndexTool,
-		Handler: GetIssueCommentsByIndexFn,
+	Tool.RegisterWrite(tool.ServerTool{
+		Tool:    IssueWriteTool,
+		Handler: issueWriteFn,
 	})
 }
 
-func GetIssueByIndexFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetIssueByIndexFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
-	}
-	client, err := gitea.ClientFromContext(ctx)
+func issueReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+		return to.ErrorResult(err)
 	}
-	issue, _, err := client.GetIssue(owner, repo, int64(index))
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get %v/%v/issue/%v err: %v", owner, repo, int64(index), err))
+	switch method {
+	case "get":
+		return getIssueByIndexFn(ctx, args)
+	case "get_comments":
+		return getIssueCommentsByIndexFn(ctx, args)
+	case "get_labels":
+		return getIssueLabelsFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
 	}
-
-	return to.TextResult(issue)
 }
 
-func ListRepoIssuesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListIssuesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func issueWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	switch method {
+	case "create":
+		return createIssueFn(ctx, args)
+	case "update":
+		return editIssueFn(ctx, args)
+	case "add_comment":
+		return createIssueCommentFn(ctx, args)
+	case "edit_comment":
+		return editIssueCommentFn(ctx, args)
+	case "add_labels":
+		return addIssueLabelsFn(ctx, args)
+	case "remove_label":
+		return removeIssueLabelFn(ctx, args)
+	case "replace_labels":
+		return replaceIssueLabelsFn(ctx, args)
+	case "clear_labels":
+		return clearIssueLabelsFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
 	}
-	state, ok := req.GetArguments()["state"].(string)
+}
+
+func getIssueByIndexFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	var issue issueWithAssets
+	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))
+	}
+	m := slimIssue(&issue.Issue)
+	m["body"] = slim.BodyWithAttachments(issue.Body, issue.Assets)
+	return to.TextResult(m)
+}
+
+func listRepoIssuesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	state, ok := args["state"].(string)
 	if !ok {
 		state = "all"
 	}
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
-	}
+	labels := params.GetStringSlice(args, "labels")
+	milestones := params.GetStringSlice(args, "milestones")
+	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListIssueOption{
 		State:      gitea_sdk.StateType(state),
+		Labels:     labels,
+		Milestones: milestones,
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
+	switch args["type"] {
+	case "issues":
+		opt.Type = gitea_sdk.IssueTypeIssue
+	case "pulls":
+		opt.Type = gitea_sdk.IssueTypePull
+	}
+	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))
 	}
-	issues, _, err := client.ListRepoIssues(owner, repo, opt)
+	issues, _, err := client.Issues.ListRepoIssues(ctx, owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get %v/%v/issues err: %v", owner, repo, err))
 	}
-	return to.TextResult(issues)
+	return to.TextResult(slimIssues(issues))
 }
 
-func CreateIssueFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateIssueFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func createIssueFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	title, ok := req.GetArguments()["title"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("title is required"))
+	title, err := params.GetString(args, "title")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	body, ok := req.GetArguments()["body"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("body is required"))
+	body, err := params.GetString(args, "body")
+	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.CreateIssue(owner, repo, gitea_sdk.CreateIssueOption{
+	opt := gitea_sdk.CreateIssueOption{
 		Title: title,
 		Body:  body,
-	})
+	}
+	opt.Assignees = params.GetStringSlice(args, "assignees")
+	if val, exists := args["milestone"]; exists {
+		if milestone, ok := params.ToInt64(val); ok {
+			opt.Milestone = milestone
+		}
+	}
+	if labelIDs, err := params.GetInt64Slice(args, "labels"); err == nil {
+		opt.Labels = labelIDs
+	}
+	if ref, ok := args["ref"].(string); ok {
+		opt.Ref = ref
+	}
+	opt.Deadline = params.GetOptionalTime(args, "deadline")
+	issue, _, err := client.Issues.CreateIssue(ctx, owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("create %v/%v/issue err: %v", owner, repo, err))
 	}
 
-	return to.TextResult(issue)
+	return to.TextResult(slimIssue(issue))
 }
 
-func CreateIssueCommentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateIssueCommentFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func createIssueCommentFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	body, ok := req.GetArguments()["body"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("body is required"))
+	body, err := params.GetString(args, "body")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 	opt := gitea_sdk.CreateIssueCommentOption{
 		Body: body,
@@ -250,88 +285,76 @@ func CreateIssueCommentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Ca
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	issueComment, _, err := client.CreateIssueComment(owner, repo, int64(index), opt)
+	issueComment, _, err := client.Issues.CreateIssueComment(ctx, owner, repo, index, opt)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("create %v/%v/issue/%v/comment err: %v", owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("create %v/%v/issue/%v/comment err: %v", owner, repo, index, err))
 	}
 
-	return to.TextResult(issueComment)
+	return to.TextResult(slimComment(issueComment))
 }
 
-func EditIssueFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called EditIssueFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func editIssueFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	opt := gitea_sdk.EditIssueOption{}
-
-	title, ok := req.GetArguments()["title"].(string)
-	if ok {
+	opt := gitea_sdk.EditIssueOption{
+		Body:           params.GetPresentStringPtr(args, "body"),
+		Ref:            params.GetPresentStringPtr(args, "ref"),
+		Assignees:      params.GetStringSlice(args, "assignees"),
+		Deadline:       params.GetOptionalTime(args, "deadline"),
+		RemoveDeadline: params.GetOptionalBoolPtr(args, "remove_deadline"),
+	}
+	if title, ok := args["title"].(string); ok {
 		opt.Title = title
 	}
-	body, ok := req.GetArguments()["body"].(string)
-	if ok {
-		opt.Body = ptr.To(body)
-	}
-	var assignees []string
-	if assigneesArg, exists := req.GetArguments()["assignees"]; exists {
-		if assigneesSlice, ok := assigneesArg.([]interface{}); ok {
-			for _, assignee := range assigneesSlice {
-				if assigneeStr, ok := assignee.(string); ok {
-					assignees = append(assignees, assigneeStr)
+	if val, exists := args["milestone"]; exists {
+		if milestone, ok := params.ToInt64(val); ok {
+			opt.Milestone = &milestone
 		}
 	}
-		}
-	}
-	opt.Assignees = assignees
-	milestone, ok := req.GetArguments()["milestone"].(float64)
-	if ok {
-		opt.Milestone = ptr.To(int64(milestone))
-	}
-	state, ok := req.GetArguments()["state"].(string)
-	if ok {
-		opt.State = ptr.To(gitea_sdk.StateType(state))
+	if state, ok := args["state"].(string); ok {
+		s := gitea_sdk.StateType(state)
+		opt.State = &s
 	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	issue, _, err := client.EditIssue(owner, repo, int64(index), opt)
+	issue, _, err := client.Issues.EditIssue(ctx, owner, repo, index, opt)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("edit %v/%v/issue/%v err: %v", owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("edit %v/%v/issue/%v err: %v", owner, repo, index, err))
 	}
 
-	return to.TextResult(issue)
+	return to.TextResult(slimIssue(issue))
 }
 
-func EditIssueCommentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called EditIssueCommentFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func editIssueCommentFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	commentID, ok := req.GetArguments()["commentID"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("comment ID is required"))
+	commentID, err := params.GetIndex(args, "commentID")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	body, ok := req.GetArguments()["body"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("body is required"))
+	body, err := params.GetString(args, "body")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 	opt := gitea_sdk.EditIssueCommentOption{
 		Body: body,
@@ -340,37 +363,174 @@ func EditIssueCommentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	issueComment, _, err := client.EditIssueComment(owner, repo, int64(commentID), opt)
+	issueComment, _, err := client.Issues.EditIssueComment(ctx, owner, repo, commentID, opt)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("edit %v/%v/issues/comments/%v err: %v", owner, repo, int64(commentID), err))
+		return to.ErrorResult(fmt.Errorf("edit %v/%v/issues/comments/%v err: %v", owner, repo, commentID, err))
 	}
 
-	return to.TextResult(issueComment)
+	return to.TextResult(slimComment(issueComment))
 }
 
-func GetIssueCommentsByIndexFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetIssueCommentsByIndexFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func getIssueCommentsByIndexFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	opt := gitea_sdk.ListIssueCommentOptions{}
+	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))
+	}
+	out := make([]map[string]any, 0, len(comments))
+	for i := range comments {
+		m := slimComment(&comments[i].Comment)
+		m["body"] = slim.BodyWithAttachments(comments[i].Body, comments[i].Assets)
+		out = append(out, m)
+	}
+	return to.TextResult(out)
+}
+
+func getIssueLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
 	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, int64(index), opt)
+	labels, _, err := client.Issues.GetIssueLabels(ctx, owner, repo, index, gitea_sdk.ListLabelsOptions{})
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get %v/%v/issues/%v/comments err: %v", owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("get %v/%v/issues/%v/labels err: %v", owner, repo, index, err))
+	}
+	return to.TextResult(slim.Labels(labels))
+}
+
+func addIssueLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	labels, err := params.GetInt64Slice(args, "labels")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	return to.TextResult(issue)
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	issueLabels, _, err := client.Issues.AddIssueLabels(ctx, owner, repo, index, gitea_sdk.IssueLabelsOption{Labels: labels})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("add labels to %v/%v/issue/%v err: %v", owner, repo, index, err))
+	}
+	return to.TextResult(slim.Labels(issueLabels))
+}
+
+func replaceIssueLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	labels, err := params.GetInt64Slice(args, "labels")
+	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))
+	}
+	issueLabels, _, err := client.Issues.ReplaceIssueLabels(ctx, owner, repo, index, gitea_sdk.IssueLabelsOption{Labels: labels})
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("replace labels on %v/%v/issue/%v err: %v", owner, repo, index, err))
+	}
+	return to.TextResult(slim.Labels(issueLabels))
+}
+
+func clearIssueLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	_, err = client.Issues.ClearIssueLabels(ctx, owner, repo, index)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("clear labels on %v/%v/issue/%v err: %v", owner, repo, index, err))
+	}
+	return to.TextResult("Labels cleared successfully")
+}
+
+func removeIssueLabelFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	labelID, err := params.GetIndex(args, "label_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))
+	}
+	_, err = client.Issues.DeleteIssueLabel(ctx, owner, repo, index, labelID)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("remove label %v from %v/%v/issue/%v err: %v", labelID, owner, repo, index, err))
+	}
+	return to.TextResult("Label removed successfully")
 }

operation/issue/issue_test.go

@@ -0,0 +1,316 @@
+package issue
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func 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
+	}()
+
+	args := map[string]any{
+		"owner":      owner,
+		"repo":       repo,
+		"type":       "issues",
+		"labels":     []any{"bug", "enhancement"},
+		"milestones": []any{"v1.0", "2"},
+		"since":      "2026-01-01T00:00:00Z",
+	}
+
+	_, err := listRepoIssuesFn(context.Background(), args)
+	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)
+	}
+	if !strings.Contains(gotQuery, "milestones=v1.0%2C2") {
+		t.Fatalf("expected milestones query param, got %s", gotQuery)
+	}
+	if !strings.Contains(gotQuery, "type=issues") {
+		t.Fatalf("expected type query param, got %s", gotQuery)
+	}
+}
+
+func Test_listRepoIssuesFn_includesMilestone(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", 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):
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`[
+				{"number": 1, "title": "with milestone", "state": "closed", "milestone": {"id": 5, "title": "v1.0"}},
+				{"number": 2, "title": "without milestone", "state": "open"}
+			]`))
+		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,
+	}
+	res, err := listRepoIssuesFn(context.Background(), args)
+	if err != nil {
+		t.Fatalf("listRepoIssuesFn() 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, `"milestone"`) || !strings.Contains(body, `"v1.0"`) {
+		t.Fatalf("expected milestone in list output, got: %s", body)
+	}
+}
+
+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
+	}()
+
+	args := 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(), args)
+	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 }()
+
+	args := map[string]any{
+		"owner": owner, "repo": repo, "issue_number": float64(42),
+	}
+	res, err := getIssueByIndexFn(context.Background(), args)
+	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 }()
+
+	args := map[string]any{
+		"owner": owner, "repo": repo, "issue_number": float64(7),
+	}
+	res, err := getIssueCommentsByIndexFn(context.Background(), args)
+	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

@@ -0,0 +1,95 @@
+package issue
+
+import (
+	"gitea.com/gitea/gitea-mcp/pkg/slim"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func slimIssue(i *gitea_sdk.Issue) map[string]any {
+	if i == nil {
+		return nil
+	}
+	m := map[string]any{
+		"number":     i.Index,
+		"title":      i.Title,
+		"body":       i.Body,
+		"state":      i.State,
+		"html_url":   i.HTMLURL,
+		"user":       slim.UserLogin(i.Poster),
+		"labels":     slim.LabelNames(i.Labels),
+		"comments":   i.Comments,
+		"created_at": i.Created,
+		"updated_at": i.Updated,
+		"closed_at":  i.Closed,
+	}
+	if len(i.Assignees) > 0 {
+		m["assignees"] = slim.UserLogins(i.Assignees)
+	}
+	if i.Milestone != nil {
+		m["milestone"] = map[string]any{
+			"id":    i.Milestone.ID,
+			"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
+	}
+	return m
+}
+
+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":       slim.UserLogin(i.Poster),
+			"comments":   i.Comments,
+			"created_at": i.Created,
+			"updated_at": i.Updated,
+		}
+		if len(i.Labels) > 0 {
+			m["labels"] = slim.LabelNames(i.Labels)
+		}
+		if i.Milestone != nil {
+			m["milestone"] = map[string]any{
+				"id":    i.Milestone.ID,
+				"title": i.Milestone.Title,
+			}
+		}
+		if i.Ref != "" {
+			m["ref"] = i.Ref
+		}
+		if i.Deadline != nil {
+			m["deadline"] = i.Deadline
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+func slimComment(c *gitea_sdk.Comment) map[string]any {
+	if c == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":         c.ID,
+		"body":       c.Body,
+		"user":       slim.UserLogin(c.Poster),
+		"html_url":   c.HTMLURL,
+		"created_at": c.Created,
+		"updated_at": c.Updated,
+	}
+}

operation/issue/slim_test.go

@@ -0,0 +1,69 @@
+package issue
+
+import (
+	"testing"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func TestSlimIssue(t *testing.T) {
+	i := &gitea_sdk.Issue{
+		Index:   42,
+		Title:   "Bug report",
+		Body:    "Something is broken",
+		State:   "open",
+		HTMLURL: "https://gitea.com/org/repo/issues/42",
+		Poster:  &gitea_sdk.User{UserName: "alice"},
+		Labels:  []*gitea_sdk.Label{{Name: "bug"}},
+		Milestone: &gitea_sdk.Milestone{
+			ID:    1,
+			Title: "v1.0",
+		},
+		PullRequest: &gitea_sdk.PullRequestMeta{HasMerged: false},
+	}
+
+	m := slimIssue(i)
+
+	if m["number"] != int64(42) {
+		t.Errorf("expected number 42, got %v", m["number"])
+	}
+	if m["body"] != "Something is broken" {
+		t.Errorf("expected body, got %v", m["body"])
+	}
+	if m["is_pull"] != true {
+		t.Error("expected is_pull true for issue with PullRequest")
+	}
+
+	ms := m["milestone"].(map[string]any)
+	if ms["title"] != "v1.0" {
+		t.Errorf("expected milestone title v1.0, got %v", ms["title"])
+	}
+}
+
+func TestSlimIssues_ListIsSlimmer(t *testing.T) {
+	i := &gitea_sdk.Issue{
+		Index:  1,
+		Title:  "Issue",
+		State:  "open",
+		Body:   "Full body",
+		Poster: &gitea_sdk.User{UserName: "alice"},
+		Labels: []*gitea_sdk.Label{{Name: "enhancement"}},
+	}
+
+	single := slimIssue(i)
+	list := slimIssues([]*gitea_sdk.Issue{i})
+
+	// Single has body, list does not
+	if _, ok := single["body"]; !ok {
+		t.Error("single issue should have body")
+	}
+	if _, ok := list[0]["body"]; ok {
+		t.Error("list issue should not have body")
+	}
+}
+
+func TestSlimIssues_Nil(t *testing.T) {
+	if r := slimIssues(nil); len(r) != 0 {
+		t.Errorf("expected empty slice, got %v", r)
+	}
+}

operation/label/label.go

@@ -4,560 +4,294 @@ 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/ptr"
+	"gitea.com/gitea/gitea-mcp/pkg/params"
+	"gitea.com/gitea/gitea-mcp/pkg/slim"
 	"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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var Tool = tool.New()
+var Tool = tool.New("label")
 
 const (
-	ListRepoLabelsToolName     = "list_repo_labels"
-	GetRepoLabelToolName       = "get_repo_label"
-	CreateRepoLabelToolName    = "create_repo_label"
-	EditRepoLabelToolName      = "edit_repo_label"
-	DeleteRepoLabelToolName    = "delete_repo_label"
-	AddIssueLabelsToolName     = "add_issue_labels"
-	ReplaceIssueLabelsToolName = "replace_issue_labels"
-	ClearIssueLabelsToolName   = "clear_issue_labels"
-	RemoveIssueLabelToolName   = "remove_issue_label"
-    ListOrgLabelsToolName      = "list_org_labels"
-    CreateOrgLabelToolName     = "create_org_label"
-    EditOrgLabelToolName       = "edit_org_label"
-    DeleteOrgLabelToolName     = "delete_org_label"
+	LabelReadToolName  = "label_read"
+	LabelWriteToolName = "label_write"
 )
 
 var (
-	ListRepoLabelsTool = mcp.NewTool(
-		ListRepoLabelsToolName,
-		mcp.WithDescription("Lists all labels for a given repository"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100)),
+	LabelReadTool = tool.NewDefinition(
+		LabelReadToolName,
+		"Read repo or org labels.",
+		annotation.ReadOnly("Read labels"),
+		tool.String("method", tool.Required(), tool.Enum("list_repo_labels", "get_repo_label", "list_org_labels")),
+		tool.String("owner", tool.Description("for repo methods")),
+		tool.String("repo", tool.Description("for repo methods")),
+		tool.String("org", tool.Description("for org methods")),
+		tool.Number("id", tool.Description("label ID (for 'get_repo_label')")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 
-	GetRepoLabelTool = mcp.NewTool(
-		GetRepoLabelToolName,
-		mcp.WithDescription("Gets a single label by its ID for a repository"),
-		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("label ID")),
+	LabelWriteTool = tool.NewDefinition(
+		LabelWriteToolName,
+		"Write labels (repo or org): create, edit, delete.",
+		annotation.Destructive("Create, update, or delete labels"),
+		tool.String("method", tool.Required(), tool.Enum("create_repo_label", "edit_repo_label", "delete_repo_label", "create_org_label", "edit_org_label", "delete_org_label")),
+		tool.String("owner", tool.Description("for repo methods")),
+		tool.String("repo", tool.Description("for repo methods")),
+		tool.String("org", tool.Description("for org methods")),
+		tool.Number("id", tool.Description("for edit/delete")),
+		tool.String("name", tool.Description("required for create")),
+		tool.String("color", tool.Description("hex (#RRGGBB); required for create")),
+		tool.String("description"),
+		tool.Boolean("exclusive", tool.Description("exclusive (org only)")),
+		tool.Boolean("is_archived", tool.Description("archived (repo only)")),
 	)
-
-	CreateRepoLabelTool = mcp.NewTool(
-		CreateRepoLabelToolName,
-		mcp.WithDescription("Creates a new label for a repository"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("name", mcp.Required(), mcp.Description("label name")),
-		mcp.WithString("color", mcp.Required(), mcp.Description("label color (hex code, e.g., #RRGGBB)")),
-		mcp.WithString("description", mcp.Description("label description")),
-	)
-
-	EditRepoLabelTool = mcp.NewTool(
-		EditRepoLabelToolName,
-		mcp.WithDescription("Edits an existing label in a repository"),
-		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("label ID")),
-		mcp.WithString("name", mcp.Description("new label name")),
-		mcp.WithString("color", mcp.Description("new label color (hex code, e.g., #RRGGBB)")),
-		mcp.WithString("description", mcp.Description("new label description")),
-	)
-
-	DeleteRepoLabelTool = mcp.NewTool(
-		DeleteRepoLabelToolName,
-		mcp.WithDescription("Deletes a label from a repository"),
-		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("label ID")),
-	)
-
-	AddIssueLabelsTool = mcp.NewTool(
-		AddIssueLabelsToolName,
-		mcp.WithDescription("Adds one or more labels to an issue"),
-		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("issue index")),
-		mcp.WithArray("labels", mcp.Required(), mcp.Description("array of label IDs to add"), mcp.Items(map[string]interface{}{"type": "number"})),
-	)
-
-	ReplaceIssueLabelsTool = mcp.NewTool(
-		ReplaceIssueLabelsToolName,
-		mcp.WithDescription("Replaces all labels on an issue"),
-		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("issue index")),
-		mcp.WithArray("labels", mcp.Required(), mcp.Description("array of label IDs to replace with"), mcp.Items(map[string]interface{}{"type": "number"})),
-	)
-
-	ClearIssueLabelsTool = mcp.NewTool(
-		ClearIssueLabelsToolName,
-		mcp.WithDescription("Removes all labels from an issue"),
-		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("issue index")),
-	)
-
-	RemoveIssueLabelTool = mcp.NewTool(
-		RemoveIssueLabelToolName,
-		mcp.WithDescription("Removes a single label from an issue"),
-		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("issue index")),
-		mcp.WithNumber("label_id", mcp.Required(), mcp.Description("label ID to remove")),
-	)
-
-    ListOrgLabelsTool = mcp.NewTool(
-        ListOrgLabelsToolName,
-        mcp.WithDescription("Lists labels defined at organization level"),
-        mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-        mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-        mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100)),
-    )
-
-    CreateOrgLabelTool = mcp.NewTool(
-        CreateOrgLabelToolName,
-        mcp.WithDescription("Creates a new label for an organization"),
-        mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-        mcp.WithString("name", mcp.Required(), mcp.Description("label name")),
-        mcp.WithString("color", mcp.Required(), mcp.Description("label color (hex code, e.g., #RRGGBB)")),
-        mcp.WithString("description", mcp.Description("label description")),
-        mcp.WithBoolean("exclusive", mcp.Description("whether the label is exclusive"), mcp.DefaultBool(false)),
-    )
-
-    EditOrgLabelTool = mcp.NewTool(
-        EditOrgLabelToolName,
-        mcp.WithDescription("Edits an existing organization label"),
-        mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-        mcp.WithNumber("id", mcp.Required(), mcp.Description("label ID")),
-        mcp.WithString("name", mcp.Description("new label name")),
-        mcp.WithString("color", mcp.Description("new label color (hex code, e.g., #RRGGBB)")),
-        mcp.WithString("description", mcp.Description("new label description")),
-        mcp.WithBoolean("exclusive", mcp.Description("whether the label is exclusive")),
-    )
-
-    DeleteOrgLabelTool = mcp.NewTool(
-        DeleteOrgLabelToolName,
-        mcp.WithDescription("Deletes an organization label by ID"),
-        mcp.WithString("org", mcp.Required(), mcp.Description("organization name")),
-        mcp.WithNumber("id", mcp.Required(), mcp.Description("label ID")),
-    )
-
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    ListRepoLabelsTool,
-		Handler: ListRepoLabelsFn,
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    LabelReadTool,
+		Handler: labelReadFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    GetRepoLabelTool,
-		Handler: GetRepoLabelFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    CreateRepoLabelTool,
-		Handler: CreateRepoLabelFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    EditRepoLabelTool,
-		Handler: EditRepoLabelFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    DeleteRepoLabelTool,
-		Handler: DeleteRepoLabelFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    AddIssueLabelsTool,
-		Handler: AddIssueLabelsFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    ReplaceIssueLabelsTool,
-		Handler: ReplaceIssueLabelsFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    ClearIssueLabelsTool,
-		Handler: ClearIssueLabelsFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    RemoveIssueLabelTool,
-		Handler: RemoveIssueLabelFn,
-	})
-    Tool.RegisterRead(server.ServerTool{
-        Tool:    ListOrgLabelsTool,
-        Handler: ListOrgLabelsFn,
-    })
-    Tool.RegisterWrite(server.ServerTool{
-        Tool:    CreateOrgLabelTool,
-        Handler: CreateOrgLabelFn,
-    })
-    Tool.RegisterWrite(server.ServerTool{
-        Tool:    EditOrgLabelTool,
-        Handler: EditOrgLabelFn,
-    })
-    Tool.RegisterWrite(server.ServerTool{
-        Tool:    DeleteOrgLabelTool,
-        Handler: DeleteOrgLabelFn,
+	Tool.RegisterWrite(tool.ServerTool{
+		Tool:    LabelWriteTool,
+		Handler: labelWriteFn,
 	})
 }
 
-func ListRepoLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoLabelsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func labelReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	switch method {
+	case "list_repo_labels":
+		return listRepoLabelsFn(ctx, args)
+	case "get_repo_label":
+		return getRepoLabelFn(ctx, args)
+	case "list_org_labels":
+		return listOrgLabelsFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
 	}
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
+}
+
+func labelWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
+	switch method {
+	case "create_repo_label":
+		return createRepoLabelFn(ctx, args)
+	case "edit_repo_label":
+		return editRepoLabelFn(ctx, args)
+	case "delete_repo_label":
+		return deleteRepoLabelFn(ctx, args)
+	case "create_org_label":
+		return createOrgLabelFn(ctx, args)
+	case "edit_org_label":
+		return editOrgLabelFn(ctx, args)
+	case "delete_org_label":
+		return deleteOrgLabelFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
 	}
+}
+
+func listRepoLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	page, pageSize := params.GetPagination(args, 30)
 
 	opt := gitea_sdk.ListLabelsOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	labels, _, err := client.ListRepoLabels(owner, repo, opt)
+	labels, _, err := client.Repositories.ListRepoLabels(ctx, owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list %v/%v/labels err: %v", owner, repo, err))
 	}
-	return to.TextResult(labels)
+	return to.TextResult(slim.Labels(labels))
 }
 
-func GetRepoLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetRepoLabelFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func getRepoLabelFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("label ID is required"))
+	id, err := params.GetIndex(args, "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))
 	}
-	label, _, err := client.GetRepoLabel(owner, repo, int64(id))
+	label, _, err := client.Repositories.GetRepoLabel(ctx, owner, repo, id)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get %v/%v/label/%v err: %v", owner, repo, int64(id), err))
+		return to.ErrorResult(fmt.Errorf("get %v/%v/label/%v err: %v", owner, repo, id, err))
 	}
-	return to.TextResult(label)
+	return to.TextResult(slim.Label(label))
 }
 
-func CreateRepoLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateRepoLabelFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func createRepoLabelFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("name is required"))
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	color, ok := req.GetArguments()["color"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("color is required"))
+	color, err := params.GetString(args, "color")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	description, _ := req.GetArguments()["description"].(string) // Optional
+	description, _ := args["description"].(string) // Optional
+
+	isArchived, _ := args["is_archived"].(bool)
 
 	opt := gitea_sdk.CreateLabelOption{
 		Name:        name,
 		Color:       color,
 		Description: description,
+		IsArchived:  isArchived,
 	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	label, _, err := client.CreateLabel(owner, repo, opt)
+	label, _, err := client.Repositories.CreateLabel(ctx, owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("create %v/%v/label err: %v", owner, repo, err))
 	}
-	return to.TextResult(label)
+	return to.TextResult(slim.Label(label))
 }
 
-func EditRepoLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called EditRepoLabelFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func editRepoLabelFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("label ID is required"))
+	id, err := params.GetIndex(args, "id")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	opt := gitea_sdk.EditLabelOption{}
-	if name, ok := req.GetArguments()["name"].(string); ok {
-		opt.Name = ptr.To(name)
-	}
-	if color, ok := req.GetArguments()["color"].(string); ok {
-		opt.Color = ptr.To(color)
-	}
-	if description, ok := req.GetArguments()["description"].(string); ok {
-		opt.Description = ptr.To(description)
+	opt := gitea_sdk.EditLabelOption{
+		Name:        params.GetOptionalStringPtr(args, "name"),
+		Color:       params.GetOptionalStringPtr(args, "color"),
+		Description: params.GetPresentStringPtr(args, "description"),
+		IsArchived:  params.GetOptionalBoolPtr(args, "is_archived"),
 	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	label, _, err := client.EditLabel(owner, repo, int64(id), opt)
+	label, _, err := client.Repositories.EditLabel(ctx, owner, repo, id, opt)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("edit %v/%v/label/%v err: %v", owner, repo, int64(id), err))
+		return to.ErrorResult(fmt.Errorf("edit %v/%v/label/%v err: %v", owner, repo, id, err))
 	}
-	return to.TextResult(label)
+	return to.TextResult(slim.Label(label))
 }
 
-func DeleteRepoLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteRepoLabelFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func deleteRepoLabelFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("label ID is required"))
+	id, err := params.GetIndex(args, "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))
 	}
-	_, err = client.DeleteLabel(owner, repo, int64(id))
+	_, err = client.Repositories.DeleteLabel(ctx, owner, repo, id)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("delete %v/%v/label/%v err: %v", owner, repo, int64(id), err))
+		return to.ErrorResult(fmt.Errorf("delete %v/%v/label/%v err: %v", owner, repo, id, err))
 	}
 	return to.TextResult("Label deleted successfully")
 }
 
-func AddIssueLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called AddIssueLabelsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("issue index is required"))
-	}
-	labelsRaw, ok := req.GetArguments()["labels"].([]interface{})
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("labels (array of IDs) is required"))
-	}
-	var labels []int64
-	for _, l := range labelsRaw {
-		if labelID, ok := l.(float64); ok {
-			labels = append(labels, int64(labelID))
-		} else {
-			return to.ErrorResult(fmt.Errorf("invalid label ID in labels array"))
-		}
-	}
-
-	opt := gitea_sdk.IssueLabelsOption{
-		Labels: labels,
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
+func listOrgLabelsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	issueLabels, _, err := client.AddIssueLabels(owner, repo, int64(index), opt)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("add labels to %v/%v/issue/%v err: %v", owner, repo, int64(index), err))
-	}
-	return to.TextResult(issueLabels)
-}
-
-func ReplaceIssueLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ReplaceIssueLabelsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("issue index is required"))
-	}
-	labelsRaw, ok := req.GetArguments()["labels"].([]interface{})
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("labels (array of IDs) is required"))
-	}
-	var labels []int64
-	for _, l := range labelsRaw {
-		if labelID, ok := l.(float64); ok {
-			labels = append(labels, int64(labelID))
-		} else {
-			return to.ErrorResult(fmt.Errorf("invalid label ID in labels array"))
-		}
-	}
-
-	opt := gitea_sdk.IssueLabelsOption{
-		Labels: labels,
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	issueLabels, _, err := client.ReplaceIssueLabels(owner, repo, int64(index), opt)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("replace labels on %v/%v/issue/%v err: %v", owner, repo, int64(index), err))
-	}
-	return to.TextResult(issueLabels)
-}
-
-func ClearIssueLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ClearIssueLabelsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("issue index is required"))
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	_, err = client.ClearIssueLabels(owner, repo, int64(index))
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("clear labels on %v/%v/issue/%v err: %v", owner, repo, int64(index), err))
-	}
-	return to.TextResult("Labels cleared successfully")
-}
-
-func RemoveIssueLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called RemoveIssueLabelFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("issue index is required"))
-	}
-	labelID, ok := req.GetArguments()["label_id"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("label ID is required"))
-	}
-
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	_, err = client.DeleteIssueLabel(owner, repo, int64(index), int64(labelID))
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("remove label %v from %v/%v/issue/%v err: %v", int64(labelID), owner, repo, int64(index), err))
-	}
-	return to.TextResult("Label removed successfully")
-}
-
-func ListOrgLabelsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-    log.Debugf("Called ListOrgLabelsFn")
-    org, ok := req.GetArguments()["org"].(string)
-    if !ok {
-        return to.ErrorResult(fmt.Errorf("org is required"))
-    }
-    page, ok := req.GetArguments()["page"].(float64)
-    if !ok {
-        page = 1
-    }
-    pageSize, ok := req.GetArguments()["pageSize"].(float64)
-    if !ok {
-        pageSize = 100
+		return to.ErrorResult(err)
 	}
+	page, pageSize := params.GetPagination(args, 30)
 
 	opt := gitea_sdk.ListOrgLabelsOptions{
 		ListOptions: gitea_sdk.ListOptions{
-            Page:     int(page),
-            PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-    labels, _, err := client.ListOrgLabels(org, opt)
+	labels, _, err := client.Organizations.ListOrgLabels(ctx, org, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list %v/labels err: %v", org, err))
 	}
-    return to.TextResult(labels)
+	return to.TextResult(slim.Labels(labels))
 }
 
-func CreateOrgLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-    log.Debugf("Called CreateOrgLabelFn")
-    org, ok := req.GetArguments()["org"].(string)
-    if !ok {
-        return to.ErrorResult(fmt.Errorf("org is required"))
+func createOrgLabelFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-    name, ok := req.GetArguments()["name"].(string)
-    if !ok {
-        return to.ErrorResult(fmt.Errorf("name is required"))
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-    color, ok := req.GetArguments()["color"].(string)
-    if !ok {
-        return to.ErrorResult(fmt.Errorf("color is required"))
+	color, err := params.GetString(args, "color")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-    description, _ := req.GetArguments()["description"].(string)
-    exclusive, _ := req.GetArguments()["exclusive"].(bool)
+	description, _ := args["description"].(string)
+	exclusive, _ := args["exclusive"].(bool)
 
 	opt := gitea_sdk.CreateOrgLabelOption{
 		Name:        name,
@@ -570,67 +304,58 @@ func CreateOrgLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-    label, _, err := client.CreateOrgLabel(org, opt)
+	label, _, err := client.Organizations.CreateOrgLabel(ctx, org, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("create %v/labels err: %v", org, err))
 	}
-    return to.TextResult(label)
+	return to.TextResult(slim.Label(label))
 }
 
-func EditOrgLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-    log.Debugf("Called EditOrgLabelFn")
-    org, ok := req.GetArguments()["org"].(string)
-    if !ok {
-        return to.ErrorResult(fmt.Errorf("org is required"))
+func editOrgLabelFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-    id, ok := req.GetArguments()["id"].(float64)
-    if !ok {
-        return to.ErrorResult(fmt.Errorf("label ID is required"))
+	id, err := params.GetIndex(args, "id")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-    opt := gitea_sdk.EditOrgLabelOption{}
-    if name, ok := req.GetArguments()["name"].(string); ok {
-        opt.Name = ptr.To(name)
-    }
-    if color, ok := req.GetArguments()["color"].(string); ok {
-        opt.Color = ptr.To(color)
-    }
-    if description, ok := req.GetArguments()["description"].(string); ok {
-        opt.Description = ptr.To(description)
-    }
-    if exclusive, ok := req.GetArguments()["exclusive"].(bool); ok {
-        opt.Exclusive = ptr.To(exclusive)
+	opt := gitea_sdk.EditOrgLabelOption{
+		Name:        params.GetOptionalStringPtr(args, "name"),
+		Color:       params.GetOptionalStringPtr(args, "color"),
+		Description: params.GetPresentStringPtr(args, "description"),
+		Exclusive:   params.GetOptionalBoolPtr(args, "exclusive"),
 	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-    label, _, err := client.EditOrgLabel(org, int64(id), opt)
+	label, _, err := client.Organizations.EditOrgLabel(ctx, org, id, opt)
 	if err != nil {
-        return to.ErrorResult(fmt.Errorf("edit %v/labels/%v err: %v", org, int64(id), err))
+		return to.ErrorResult(fmt.Errorf("edit %v/labels/%v err: %v", org, id, err))
 	}
-    return to.TextResult(label)
+	return to.TextResult(slim.Label(label))
 }
 
-func DeleteOrgLabelFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-    log.Debugf("Called DeleteOrgLabelFn")
-    org, ok := req.GetArguments()["org"].(string)
-    if !ok {
-        return to.ErrorResult(fmt.Errorf("org is required"))
+func deleteOrgLabelFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-    id, ok := req.GetArguments()["id"].(float64)
-    if !ok {
-        return to.ErrorResult(fmt.Errorf("label ID is required"))
+	id, err := params.GetIndex(args, "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))
 	}
-    _, err = client.DeleteOrgLabel(org, int64(id))
+	_, err = client.Organizations.DeleteOrgLabel(ctx, org, id)
 	if err != nil {
-        return to.ErrorResult(fmt.Errorf("delete %v/labels/%v err: %v", org, int64(id), err))
+		return to.ErrorResult(fmt.Errorf("delete %v/labels/%v err: %v", org, id, err))
 	}
 	return to.TextResult("Label deleted successfully")
 }

operation/label/slim.go

@@ -0,0 +1 @@
+package label

operation/milestone/milestone.go

@@ -4,271 +4,248 @@ 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/ptr"
+	"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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var Tool = tool.New()
+var Tool = tool.New("milestone")
 
 const (
-	GetMilestoneToolName    = "get_milestone"
-	ListMilestonesToolName  = "list_milestones"
-	CreateMilestoneToolName = "create_milestone"
-	EditMilestoneToolName   = "edit_milestone"
-	DeleteMilestoneToolName = "delete_milestone"
+	MilestoneReadToolName  = "milestone_read"
+	MilestoneWriteToolName = "milestone_write"
 )
 
 var (
-	GetMilestoneTool = mcp.NewTool(
-		GetMilestoneToolName,
-		mcp.WithDescription("get milestone by id"),
-		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("milestone id")),
+	MilestoneReadTool = tool.NewDefinition(
+		MilestoneReadToolName,
+		"Read milestones: get one or list.",
+		annotation.ReadOnly("Read milestones"),
+		tool.String("method", tool.Required(), tool.Enum("get", "list")),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Number("id", tool.Description("for 'get'")),
+		tool.String("state", tool.Default("all")),
+		tool.String("name", tool.Description("name filter (for 'list')")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 
-	ListMilestonesTool = mcp.NewTool(
-		ListMilestonesToolName,
-		mcp.WithDescription("List milestones"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("state", mcp.Description("milestone state"), mcp.DefaultString("all")),
-		mcp.WithString("name", mcp.Description("milestone name")),
-		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100)),
-	)
-
-	CreateMilestoneTool = mcp.NewTool(
-		CreateMilestoneToolName,
-		mcp.WithDescription("create milestone"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("title", mcp.Required(), mcp.Description("milestone title")),
-		mcp.WithString("description", mcp.Description("milestone description")),
-		mcp.WithString("due_on", mcp.Description("due date")),
-	)
-
-	EditMilestoneTool = mcp.NewTool(
-		EditMilestoneToolName,
-		mcp.WithDescription("edit milestone"),
-		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("milestone id")),
-		mcp.WithString("title", mcp.Description("milestone title")),
-		mcp.WithString("description", mcp.Description("milestone description")),
-		mcp.WithString("due_on", mcp.Description("due date")),
-		mcp.WithString("state", mcp.Description("milestone state, one of open, closed")),
-	)
-
-	DeleteMilestoneTool = mcp.NewTool(
-		DeleteMilestoneToolName,
-		mcp.WithDescription("delete milestone"),
-		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("milestone id")),
+	MilestoneWriteTool = tool.NewDefinition(
+		MilestoneWriteToolName,
+		"Write milestones: create, update, delete.",
+		annotation.Destructive("Create, update, or delete milestones"),
+		tool.String("method", tool.Required(), tool.Enum("create", "update", "edit", "delete")),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Number("id", tool.Description("for 'update'/'delete'")),
+		tool.String("title", tool.Description("for 'create'")),
+		tool.String("description"),
+		tool.String("due_on", tool.Description("due date")),
+		tool.String("state", tool.Enum("open", "closed")),
 	)
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    GetMilestoneTool,
-		Handler: GetMilestoneFn,
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    MilestoneReadTool,
+		Handler: milestoneReadFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    ListMilestonesTool,
-		Handler: ListMilestonesFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    CreateMilestoneTool,
-		Handler: CreateMilestoneFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    EditMilestoneTool,
-		Handler: EditMilestoneFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    DeleteMilestoneTool,
-		Handler: DeleteMilestoneFn,
+	Tool.RegisterWrite(tool.ServerTool{
+		Tool:    MilestoneWriteTool,
+		Handler: milestoneWriteFn,
 	})
 }
 
-func GetMilestoneFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetMilestoneFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func milestoneReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	switch method {
+	case "get":
+		return getMilestoneFn(ctx, args)
+	case "list":
+		return listMilestonesFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("id is required"))
+}
+
+func milestoneWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "create":
+		return createMilestoneFn(ctx, args)
+	case "update":
+		return editMilestoneFn(ctx, args)
+	case "edit":
+		return editMilestoneFn(ctx, args)
+	case "delete":
+		return deleteMilestoneFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func getMilestoneFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	id, err := params.GetIndex(args, "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))
 	}
-	milestone, _, err := client.GetMilestone(owner, repo, int64(id))
+	milestone, _, err := client.Repositories.GetMilestone(ctx, owner, repo, id)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get %v/%v/milestone/%v err: %v", owner, repo, int64(id), err))
+		return to.ErrorResult(fmt.Errorf("get %v/%v/milestone/%v err: %v", owner, repo, id, err))
 	}
 
-	return to.TextResult(milestone)
+	return to.TextResult(slimMilestone(milestone))
 }
 
-func ListMilestonesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListMilestonesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func listMilestonesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	state, ok := req.GetArguments()["state"].(string)
-	if !ok {
-		state = "all"
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok {
-		name = ""
-	}
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
+	state := params.GetOptionalString(args, "state", "all")
+	name := params.GetOptionalString(args, "name", "")
+	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListMilestoneOption{
 		State: gitea_sdk.StateType(state),
 		Name:  name,
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	milestones, _, err := client.ListRepoMilestones(owner, repo, opt)
+	milestones, _, err := client.Repositories.ListMilestones(ctx, owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get %v/%v/milestones err: %v", owner, repo, err))
 	}
-	return to.TextResult(milestones)
+	return to.TextResult(slimMilestones(milestones))
 }
 
-func CreateMilestoneFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateMilestoneFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func createMilestoneFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	title, ok := req.GetArguments()["title"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("title is required"))
+	title, err := params.GetString(args, "title")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
 	opt := gitea_sdk.CreateMilestoneOption{
 		Title: title,
 	}
 
-	description, ok := req.GetArguments()["description"].(string)
+	description, ok := args["description"].(string)
 	if ok {
 		opt.Description = description
 	}
+	opt.Deadline = params.GetOptionalTime(args, "due_on")
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	milestone, _, err := client.CreateMilestone(owner, repo, opt)
+	milestone, _, err := client.Repositories.CreateMilestone(ctx, owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("create %v/%v/milestone err: %v", owner, repo, err))
 	}
 
-	return to.TextResult(milestone)
+	return to.TextResult(slimMilestone(milestone))
 }
 
-func EditMilestoneFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called EditMilestoneFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func editMilestoneFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("id is required"))
+	id, err := params.GetIndex(args, "id")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	opt := gitea_sdk.EditMilestoneOption{}
-
-	title, ok := req.GetArguments()["title"].(string)
-	if ok {
+	opt := gitea_sdk.EditMilestoneOption{
+		Description: params.GetPresentStringPtr(args, "description"),
+		Deadline:    params.GetOptionalTime(args, "due_on"),
+	}
+	if title, ok := args["title"].(string); ok {
 		opt.Title = title
 	}
-	description, ok := req.GetArguments()["description"].(string)
-	if ok {
-		opt.Description = ptr.To(description)
-	}
-	state, ok := req.GetArguments()["state"].(string)
-	if ok {
-		opt.State = ptr.To(gitea_sdk.StateType(state))
+	if state, ok := args["state"].(string); ok {
+		s := gitea_sdk.StateType(state)
+		opt.State = &s
 	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	milestone, _, err := client.EditMilestone(owner, repo, int64(id), opt)
+	milestone, _, err := client.Repositories.EditMilestone(ctx, owner, repo, id, opt)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("edit %v/%v/milestone/%v err: %v", owner, repo, int64(id), err))
+		return to.ErrorResult(fmt.Errorf("edit %v/%v/milestone/%v err: %v", owner, repo, id, err))
 	}
 
-	return to.TextResult(milestone)
+	return to.TextResult(slimMilestone(milestone))
 }
 
-func DeleteMilestoneFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteMilestoneFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func deleteMilestoneFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("id is required"))
+	id, err := params.GetIndex(args, "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))
 	}
-	_, err = client.DeleteMilestone(owner, repo, int64(id))
+	_, err = client.Repositories.DeleteMilestone(ctx, owner, repo, id)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("delete %v/%v/milestone/%v err: %v", owner, repo, int64(id), err))
+		return to.ErrorResult(fmt.Errorf("delete %v/%v/milestone/%v err: %v", owner, repo, id, err))
 	}
 
 	return to.TextResult("Milestone deleted successfully")

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/modelcontextprotocol/go-sdk/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, map[string]any) (*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(), 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/milestone/slim.go

@@ -0,0 +1,28 @@
+package milestone
+
+import (
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func slimMilestone(m *gitea_sdk.Milestone) map[string]any {
+	if m == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":            m.ID,
+		"title":         m.Title,
+		"description":   m.Description,
+		"state":         m.State,
+		"open_issues":   m.OpenIssues,
+		"closed_issues": m.ClosedIssues,
+		"due_on":        m.Deadline,
+	}
+}
+
+func slimMilestones(milestones []*gitea_sdk.Milestone) []map[string]any {
+	out := make([]map[string]any, 0, len(milestones))
+	for _, m := range milestones {
+		out = append(out, slimMilestone(m))
+	}
+	return out
+}

operation/notification/notification.go

@@ -0,0 +1,208 @@
+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/params"
+	"gitea.com/gitea/gitea-mcp/pkg/to"
+	"gitea.com/gitea/gitea-mcp/pkg/tool"
+
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+var Tool = tool.New("notification")
+
+const (
+	NotificationReadToolName  = "notification_read"
+	NotificationWriteToolName = "notification_write"
+)
+
+var (
+	NotificationReadTool = tool.NewDefinition(
+		NotificationReadToolName,
+		"Read notifications: list (optionally scoped to a repo) or get a thread by ID.",
+		annotation.ReadOnly("Read notifications"),
+		tool.String("method", tool.Required(), tool.Enum("list", "get")),
+		tool.String("owner", tool.Description("scope 'list' to a repo")),
+		tool.String("repo", tool.Description("scope 'list' to a repo")),
+		tool.Number("id", tool.Description("thread ID (for 'get')")),
+		tool.String("status", tool.Enum("unread", "read", "pinned")),
+		tool.String("subject_type", tool.Enum("Issue", "Pull", "Commit", "Repository")),
+		tool.String("since", tool.Description("updated after ISO 8601")),
+		tool.String("before", tool.Description("updated before ISO 8601")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
+	)
+
+	NotificationWriteTool = tool.NewDefinition(
+		NotificationWriteToolName,
+		"Mark a notification or all notifications as read.",
+		annotation.Write("Manage notifications"),
+		tool.String("method", tool.Required(), tool.Enum("mark_read", "mark_all_read")),
+		tool.Number("id", tool.Description("thread ID (for 'mark_read')")),
+		tool.String("owner", tool.Description("scope 'mark_all_read' to a repo")),
+		tool.String("repo", tool.Description("scope 'mark_all_read' to a repo")),
+		tool.String("last_read_at", tool.Description("ISO 8601; defaults to now")),
+	)
+)
+
+func init() {
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    NotificationReadTool,
+		Handler: notificationReadFn,
+	})
+	Tool.RegisterWrite(tool.ServerTool{
+		Tool:    NotificationWriteTool,
+		Handler: notificationWriteFn,
+	})
+}
+
+func notificationReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "list":
+		return listNotificationsFn(ctx, args)
+	case "get":
+		return getNotificationFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func notificationWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "mark_read":
+		return markNotificationReadFn(ctx, args)
+	case "mark_all_read":
+		return markAllNotificationsReadFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func listNotificationsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	page, pageSize := params.GetPagination(args, 30)
+	opt := gitea_sdk.ListNotificationOptions{
+		ListOptions: gitea_sdk.ListOptions{
+			Page:     page,
+			PageSize: pageSize,
+		},
+	}
+	if status, ok := args["status"].(string); ok {
+		opt.Status = []gitea_sdk.NotificationStatus{gitea_sdk.NotificationStatus(status)}
+	}
+	if subjectType, ok := args["subject_type"].(string); ok {
+		opt.SubjectTypes = []gitea_sdk.NotificationSubjectType{gitea_sdk.NotificationSubjectType(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.Notifications.ListByRepo(ctx, 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.Notifications.List(ctx, opt)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list notifications err: %v", err))
+	}
+	return to.TextResult(slimThreads(threads))
+}
+
+func getNotificationFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	id, err := params.GetIndex(args, "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.Notifications.GetByID(ctx, 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, args map[string]any) (*mcp.CallToolResult, error) {
+	id, err := params.GetIndex(args, "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.Notifications.MarkReadByID(ctx, 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, args map[string]any) (*mcp.CallToolResult, error) {
+	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.Notifications.MarkReadByRepo(ctx, 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.Notifications.MarkRead(ctx, 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 "gitea.dev/sdk"
+)
+
+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

@@ -2,6 +2,7 @@ package operation
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net/http"
 	"os"
@@ -10,86 +11,86 @@ import (
 	"syscall"
 	"time"
 
+	"gitea.com/gitea/gitea-mcp/operation/actions"
 	"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/timetracking"
-	"gitea.com/gitea/gitea-mcp/operation/actions"
+	"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"
+	"gitea.com/gitea/gitea-mcp/operation/timetracking"
 	"gitea.com/gitea/gitea-mcp/operation/user"
 	"gitea.com/gitea/gitea-mcp/operation/version"
 	"gitea.com/gitea/gitea-mcp/operation/wiki"
 	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"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var mcpServer *server.MCPServer
+// maxRequestBodyBytes raises the SDK's 4 MiB default, which is too tight for the
+// base64 file content create_or_update_file accepts.
+const maxRequestBodyBytes = 32 << 20
 
-func RegisterTool(s *server.MCPServer) {
-	// User Tool
-	s.AddTools(user.Tool.Tools()...)
+// sessionTimeout expires idle sessions, which the SDK otherwise keeps for the
+// process lifetime: a client that goes away without DELETE /mcp leaks its
+// session, and initialize takes no token. Clients re-initialize on the 404.
+const sessionTimeout = 30 * time.Minute
 
-	// Actions Tool
-	s.AddTools(actions.Tool.Tools()...)
+// httpReadHeaderTimeout bounds slow header reads without limiting SSE writes.
+const httpReadHeaderTimeout = 10 * time.Second
 
-	// Repo Tool
-	s.AddTools(repo.Tool.Tools()...)
+var (
+	mcpServer *mcp.Server
 
-	// Issue Tool
-	s.AddTools(issue.Tool.Tools()...)
+	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,
+		repo.FileTool, repo.BranchTool, repo.TagTool, repo.CommitTool, repo.ReleaseTool,
+	}
+)
 
-	// 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()...)
-
-	s.DeleteTools("")
+func RegisterTool(s *mcp.Server) {
+	for _, t := range domainTools {
+		for _, registeredTool := range t.Tools() {
+			s.AddTool(registeredTool.Tool, registeredTool.MCPHandler())
+		}
+	}
+	tool.WarnUnmatchedAllowedTools(domainTools...)
+	tool.WarnUnmatchedAllowedScopes(domainTools...)
 }
 
-// parseBearerToken extracts the Bearer token from an Authorization header.
+// parseAuthToken extracts the token from an Authorization header.
+// Supports "Bearer <token>" (case-insensitive per RFC 7235) and
+// Gitea-style "token <token>" formats.
 // Returns the token and true if valid, empty string and false otherwise.
-func parseBearerToken(authHeader string) (string, bool) {
-	const bearerPrefix = "Bearer "
-	if len(authHeader) < len(bearerPrefix) || !strings.HasPrefix(authHeader, bearerPrefix) {
-		return "", false
-	}
-
-	token := strings.TrimSpace(authHeader[len(bearerPrefix):])
-	if token == "" {
-		return "", false
-	}
-
+func parseAuthToken(authHeader string) (string, bool) {
+	if len(authHeader) > 7 && strings.EqualFold(authHeader[:7], "Bearer ") {
+		token := strings.TrimSpace(authHeader[7:])
+		if token != "" {
 			return token, true
+		}
+	}
+	if len(authHeader) > 6 && strings.EqualFold(authHeader[:6], "token ") {
+		token := strings.TrimSpace(authHeader[6:])
+		if token != "" {
+			return token, true
+		}
+	}
+	return "", false
 }
 
-func getContextWithToken(ctx context.Context, r *http.Request) context.Context {
-	authHeader := r.Header.Get("Authorization")
+func getContextWithToken(ctx context.Context, authHeader string) context.Context {
 	if authHeader == "" {
 		return ctx
 	}
 
-	token, ok := parseBearerToken(authHeader)
+	token, ok := parseAuthToken(authHeader)
 	if !ok {
 		return ctx
 	}
@@ -97,23 +98,43 @@ func getContextWithToken(ctx context.Context, r *http.Request) context.Context {
 	return context.WithValue(ctx, mcpContext.TokenContextKey, token)
 }
 
+func authTokenMiddleware(next mcp.MethodHandler) mcp.MethodHandler {
+	return func(ctx context.Context, method string, req mcp.Request) (mcp.Result, error) {
+		if extra := req.GetExtra(); extra != nil {
+			ctx = getContextWithToken(ctx, extra.Header.Get("Authorization"))
+		}
+		return next(ctx, method, req)
+	}
+}
+
+func newHTTPServer(addr string, s *mcp.Server) *http.Server {
+	mux := http.NewServeMux()
+	mux.Handle("/mcp", mcp.NewStreamableHTTPHandler(
+		func(*http.Request) *mcp.Server { return s },
+		&mcp.StreamableHTTPOptions{
+			Logger:              log.Slog(),
+			MaxRequestBodyBytes: maxRequestBodyBytes,
+			Stateless:           false, // SessionTimeout requires stateful sessions.
+			SessionTimeout:      sessionTimeout,
+		},
+	))
+	return &http.Server{
+		Addr:              addr,
+		Handler:           mux,
+		ReadHeaderTimeout: httpReadHeaderTimeout,
+	}
+}
+
 func Run() error {
 	mcpServer = newMCPServer(flag.Version)
 	RegisterTool(mcpServer)
 	switch flag.Mode {
 	case "stdio":
-		if err := server.ServeStdio(
-			mcpServer,
-		); err != nil {
+		if err := mcpServer.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
 			return err
 		}
 	case "http":
-		httpServer := server.NewStreamableHTTPServer(
-			mcpServer,
-			server.WithLogger(log.New()),
-			server.WithHeartbeatInterval(30*time.Second),
-			server.WithHTTPContextFunc(getContextWithToken),
-		)
+		httpServer := newHTTPServer(fmt.Sprintf(":%d", flag.Port), mcpServer)
 		log.Infof("Gitea MCP HTTP server listening on :%d", flag.Port)
 
 		// Graceful shutdown setup
@@ -132,7 +153,7 @@ func Run() error {
 			close(shutdownDone)
 		}()
 
-		if err := httpServer.Start(fmt.Sprintf(":%d", flag.Port)); err != nil {
+		if err := httpServer.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
 			return err
 		}
 		<-shutdownDone // Wait for shutdown to finish
@@ -142,12 +163,16 @@ func Run() error {
 	return nil
 }
 
-func newMCPServer(version string) *server.MCPServer {
-	return server.NewMCPServer(
-		"Gitea MCP Server",
-		version,
-		server.WithToolCapabilities(true),
-		server.WithLogging(),
-		server.WithRecovery(),
+func newMCPServer(version string) *mcp.Server {
+	// SDK keepalives send MCP ping requests and disconnect clients without a
+	// server-to-client channel, so KeepAlive stays disabled.
+	s := mcp.NewServer(
+		&mcp.Implementation{
+			Name:    "Gitea MCP Server",
+			Version: version,
+		},
+		&mcp.ServerOptions{Logger: log.Slog()},
 	)
+	s.AddReceivingMiddleware(authTokenMiddleware)
+	return s
 }

operation/operation_test.go

@@ -1,10 +1,24 @@
 package operation
 
-import (
-	"testing"
-)
+import "testing"
 
-func TestParseBearerToken(t *testing.T) {
+func TestNewHTTPServerConfig(t *testing.T) {
+	server := newHTTPServer(":12345", newMCPServer("test"))
+	if server.Addr != ":12345" {
+		t.Errorf("Addr = %q, want %q", server.Addr, ":12345")
+	}
+	if server.Handler == nil {
+		t.Error("Handler is nil")
+	}
+	if server.ReadHeaderTimeout != httpReadHeaderTimeout {
+		t.Errorf("ReadHeaderTimeout = %v, want %v", server.ReadHeaderTimeout, httpReadHeaderTimeout)
+	}
+	if server.WriteTimeout != 0 {
+		t.Errorf("WriteTimeout = %v, want zero for SSE", server.WriteTimeout)
+	}
+}
+
+func TestParseAuthToken(t *testing.T) {
 	tests := []struct {
 		name      string
 		header    string
@@ -12,23 +26,29 @@ func TestParseBearerToken(t *testing.T) {
 		wantOK    bool
 	}{
 		{
-			name:      "valid token",
+			name:      "valid Bearer token",
 			header:    "Bearer validtoken",
 			wantToken: "validtoken",
 			wantOK:    true,
 		},
+		{
+			name:      "lowercase bearer",
+			header:    "bearer lowercase",
+			wantToken: "lowercase",
+			wantOK:    true,
+		},
+		{
+			name:      "uppercase BEARER",
+			header:    "BEARER uppercase",
+			wantToken: "uppercase",
+			wantOK:    true,
+		},
 		{
 			name:      "token with spaces trimmed",
 			header:    "Bearer   spacedToken ",
 			wantToken: "spacedToken",
 			wantOK:    true,
 		},
-		{
-			name:      "lowercase bearer should fail",
-			header:    "bearer lowercase",
-			wantToken: "",
-			wantOK:    false,
-		},
 		{
 			name:      "bearer with no token",
 			header:    "Bearer ",
@@ -47,6 +67,24 @@ func TestParseBearerToken(t *testing.T) {
 			wantToken: "",
 			wantOK:    false,
 		},
+		{
+			name:      "Gitea token format",
+			header:    "token giteaapitoken",
+			wantToken: "giteaapitoken",
+			wantOK:    true,
+		},
+		{
+			name:      "Gitea Token format capitalized",
+			header:    "Token giteaapitoken",
+			wantToken: "giteaapitoken",
+			wantOK:    true,
+		},
+		{
+			name:      "token with no value",
+			header:    "token ",
+			wantToken: "",
+			wantOK:    false,
+		},
 		{
 			name:      "different auth type",
 			header:    "Basic dXNlcjpwYXNz",
@@ -60,7 +98,7 @@ func TestParseBearerToken(t *testing.T) {
 			wantOK:    false,
 		},
 		{
-			name:      "token with internal spaces",
+			name:      "bearer token with internal spaces",
 			header:    "Bearer token with spaces",
 			wantToken: "token with spaces",
 			wantOK:    true,
@@ -69,12 +107,12 @@ func TestParseBearerToken(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			gotToken, gotOK := parseBearerToken(tt.header)
+			gotToken, gotOK := parseAuthToken(tt.header)
 			if gotToken != tt.wantToken {
-				t.Errorf("parseBearerToken() token = %q, want %q", gotToken, tt.wantToken)
+				t.Errorf("parseAuthToken() token = %q, want %q", gotToken, tt.wantToken)
 			}
 			if gotOK != tt.wantOK {
-				t.Errorf("parseBearerToken() ok = %v, want %v", gotOK, tt.wantOK)
+				t.Errorf("parseAuthToken() ok = %v, want %v", gotOK, tt.wantOK)
 			}
 		})
 	}

operation/packages/packages.go

@@ -0,0 +1,213 @@
+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/params"
+	"gitea.com/gitea/gitea-mcp/pkg/to"
+	"gitea.com/gitea/gitea-mcp/pkg/tool"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+var Tool = tool.New("packages")
+
+const (
+	PackageReadToolName  = "package_read"
+	PackageWriteToolName = "package_write"
+)
+
+var (
+	PackageReadTool = tool.NewDefinition(
+		PackageReadToolName,
+		"Read package registry: list packages (one entry per version, filter via 'q'/'type'), list versions, or get a version.",
+		annotation.ReadOnly("Read package registry"),
+		tool.String("method", tool.Required(), tool.Enum("list", "list_versions", "get")),
+		tool.String("owner", tool.Required(), tool.Description("user or org")),
+		tool.String("type", tool.Description("container/npm/maven/pypi/cargo/generic; required except 'list'")),
+		tool.String("name", tool.Description("slashes auto-encoded; required except 'list'")),
+		tool.String("version", tool.Description("for 'get'")),
+		tool.String("q", tool.Description("search query")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1), tool.Minimum(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30), tool.Minimum(1)),
+	)
+
+	PackageWriteTool = tool.NewDefinition(
+		PackageWriteToolName,
+		"Delete a package version (irreversible).",
+		annotation.Destructive("Delete a package version"),
+		tool.String("method", tool.Required(), tool.Enum("delete")),
+		tool.String("owner", tool.Required(), tool.Description("user or org")),
+		tool.String("type", tool.Required(), tool.Description("container/npm/maven/pypi/cargo/generic")),
+		tool.String("name", tool.Required(), tool.Description("slashes auto-encoded")),
+		tool.String("version", tool.Required()),
+	)
+)
+
+func init() {
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    PackageReadTool,
+		Handler: packageReadFn,
+	})
+	Tool.RegisterWrite(tool.ServerTool{
+		Tool:    PackageWriteTool,
+		Handler: packageWriteFn,
+	})
+}
+
+func packageReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "list":
+		return listPackagesFn(ctx, args)
+	case "list_versions":
+		return listPackageVersionsFn(ctx, args)
+	case "get":
+		return getPackageFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func packageWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "delete":
+		return deletePackageVersionFn(ctx, args)
+	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, args map[string]any) (*mcp.CallToolResult, error) {
+	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, args map[string]any) (*mcp.CallToolResult, error) {
+	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, args map[string]any) (*mcp.CallToolResult, error) {
+	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, args map[string]any) (*mcp.CallToolResult, error) {
+	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,373 @@
+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/modelcontextprotocol/go-sdk/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) {
+		args := map[string]any{
+			"method": "list",
+			"owner":  "test-org",
+		}
+
+		result, err := packageReadFn(ctx, args)
+		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) {
+		args := map[string]any{
+			"method": "list",
+			"owner":  "test-org",
+			"type":   "container",
+			"q":      "myimage",
+		}
+
+		_, err := packageReadFn(ctx, args)
+		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) {
+		args := map[string]any{
+			"method":   "list",
+			"owner":    "test-org",
+			"page":     float64(2),
+			"per_page": float64(10),
+		}
+
+		_, err := packageReadFn(ctx, args)
+		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) {
+			args := map[string]any{
+				"method": "list_versions",
+				"owner":  "test-org",
+				"type":   "container",
+				"name":   tt.name,
+			}
+
+			result, err := packageReadFn(ctx, args)
+			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) {
+			args := map[string]any{
+				"method":  "get",
+				"owner":   "test-org",
+				"type":    "container",
+				"name":    tt.name,
+				"version": "v1.0.0",
+			}
+
+			result, err := packageReadFn(ctx, args)
+			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")
+
+	args := map[string]any{
+		"method":  "delete",
+		"owner":   "test-org",
+		"type":    "container",
+		"name":    "myrepo/myimage",
+		"version": "v1.0.0",
+	}
+
+	result, err := packageWriteFn(ctx, args)
+	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()
+	args := map[string]any{
+		"method": "bogus",
+		"owner":  "test-org",
+	}
+	if _, err := packageReadFn(ctx, args); err == nil {
+		t.Fatal("expected error for unknown method")
+	}
+}
+
+func TestPackageWriteUnknownMethod(t *testing.T) {
+	ctx := context.Background()
+	args := map[string]any{
+		"method": "bogus",
+		"owner":  "test-org",
+	}
+	if _, err := packageWriteFn(ctx, args); 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/slim.go

@@ -0,0 +1,166 @@
+package pull
+
+import (
+	"gitea.com/gitea/gitea-mcp/pkg/slim"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func repoRef(r *gitea_sdk.Repository) map[string]any {
+	if r == nil {
+		return nil
+	}
+	return map[string]any{
+		"full_name":   r.FullName,
+		"description": r.Description,
+	}
+}
+
+func slimPullRequest(pr *gitea_sdk.PullRequest) map[string]any {
+	if pr == nil {
+		return nil
+	}
+	m := map[string]any{
+		"number":     pr.Index,
+		"title":      pr.Title,
+		"body":       pr.Body,
+		"state":      pr.State,
+		"draft":      pr.Draft,
+		"merged":     pr.HasMerged,
+		"mergeable":  pr.Mergeable,
+		"html_url":   pr.HTMLURL,
+		"user":       slim.UserLogin(pr.Poster),
+		"labels":     slim.LabelNames(pr.Labels),
+		"comments":   pr.Comments,
+		"created_at": pr.Created,
+		"updated_at": pr.Updated,
+		"closed_at":  pr.Closed,
+	}
+	if pr.HasMerged {
+		m["merged_at"] = pr.Merged
+		m["merge_commit_sha"] = pr.MergedCommitID
+		m["merged_by"] = slim.UserLogin(pr.MergedBy)
+	}
+	if pr.Head != nil {
+		head := map[string]any{"ref": pr.Head.Ref, "sha": pr.Head.Sha}
+		if pr.Head.Repository != nil {
+			head["repo"] = repoRef(pr.Head.Repository)
+		}
+		m["head"] = head
+	}
+	if pr.Base != nil {
+		base := map[string]any{"ref": pr.Base.Ref, "sha": pr.Base.Sha}
+		if pr.Base.Repository != nil {
+			base["repo"] = repoRef(pr.Base.Repository)
+		}
+		m["base"] = base
+	}
+	if pr.Additions != nil {
+		m["additions"] = *pr.Additions
+	}
+	if pr.Deletions != nil {
+		m["deletions"] = *pr.Deletions
+	}
+	if pr.ChangedFiles != nil {
+		m["changed_files"] = *pr.ChangedFiles
+	}
+	if len(pr.Assignees) > 0 {
+		m["assignees"] = slim.UserLogins(pr.Assignees)
+	}
+	if pr.Milestone != nil {
+		m["milestone"] = pr.Milestone.Title
+	}
+	if pr.ReviewComments > 0 {
+		m["review_comments"] = pr.ReviewComments
+	}
+	return m
+}
+
+func slimPullRequests(prs []*gitea_sdk.PullRequest) []map[string]any {
+	out := make([]map[string]any, 0, len(prs))
+	for _, pr := range prs {
+		if pr == nil {
+			continue
+		}
+		m := map[string]any{
+			"number":     pr.Index,
+			"title":      pr.Title,
+			"state":      pr.State,
+			"draft":      pr.Draft,
+			"merged":     pr.HasMerged,
+			"html_url":   pr.HTMLURL,
+			"user":       slim.UserLogin(pr.Poster),
+			"created_at": pr.Created,
+			"updated_at": pr.Updated,
+		}
+		if pr.Head != nil {
+			m["head"] = pr.Head.Ref
+		}
+		if pr.Base != nil {
+			m["base"] = pr.Base.Ref
+		}
+		if len(pr.Labels) > 0 {
+			m["labels"] = slim.LabelNames(pr.Labels)
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+func slimReview(r *gitea_sdk.PullReview) map[string]any {
+	if r == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":             r.ID,
+		"state":          r.State,
+		"body":           r.Body,
+		"user":           slim.UserLogin(r.Reviewer),
+		"comments_count": r.CodeCommentsCount,
+		"submitted_at":   r.Submitted,
+		"html_url":       r.HTMLURL,
+		"stale":          r.Stale,
+		"official":       r.Official,
+		"dismissed":      r.Dismissed,
+	}
+}
+
+func slimReviews(reviews []*gitea_sdk.PullReview) []map[string]any {
+	out := make([]map[string]any, 0, len(reviews))
+	for _, r := range reviews {
+		out = append(out, slimReview(r))
+	}
+	return out
+}
+
+func slimReviewComment(c *gitea_sdk.PullReviewComment) map[string]any {
+	if c == nil {
+		return nil
+	}
+	m := map[string]any{
+		"id":           c.ID,
+		"review_id":    c.ReviewID,
+		"body":         c.Body,
+		"path":         c.Path,
+		"position":     c.LineNum,
+		"old_position": c.OldLineNum,
+		"diff_hunk":    c.DiffHunk,
+		"user":         slim.UserLogin(c.Reviewer),
+		"html_url":     c.HTMLURL,
+		"created_at":   c.Created,
+		"updated_at":   c.Updated,
+	}
+	// the thread's first comment carries the resolver
+	if c.Resolver != nil {
+		m["resolved_by"] = slim.UserLogin(c.Resolver)
+	}
+	return m
+}
+
+func slimReviewComments(comments []*gitea_sdk.PullReviewComment) []map[string]any {
+	out := make([]map[string]any, 0, len(comments))
+	for _, c := range comments {
+		out = append(out, slimReviewComment(c))
+	}
+	return out
+}

operation/pull/slim_test.go

@@ -0,0 +1,124 @@
+package pull
+
+import (
+	"testing"
+	"time"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func TestSlimPullRequest(t *testing.T) {
+	now := time.Now()
+	additions := 10
+	deletions := 5
+	changedFiles := 3
+	pr := &gitea_sdk.PullRequest{
+		Index:     1,
+		Title:     "Fix bug",
+		Body:      "Fixes #123",
+		State:     "open",
+		Draft:     false,
+		HasMerged: false,
+		Mergeable: true,
+		HTMLURL:   "https://gitea.com/org/repo/pulls/1",
+		Poster:    &gitea_sdk.User{UserName: "bob"},
+		Labels: []*gitea_sdk.Label{
+			{Name: "bug"},
+			{Name: "priority"},
+		},
+		Comments:     2,
+		Created:      &now,
+		Updated:      &now,
+		Additions:    &additions,
+		Deletions:    &deletions,
+		ChangedFiles: &changedFiles,
+		Head: &gitea_sdk.PRBranchInfo{
+			Ref: "fix-branch",
+			Sha: "abc123",
+		},
+		Base: &gitea_sdk.PRBranchInfo{
+			Ref: "main",
+			Sha: "def456",
+		},
+		Assignees: []*gitea_sdk.User{
+			{UserName: "alice"},
+		},
+		Milestone: &gitea_sdk.Milestone{Title: "v1.0"},
+	}
+
+	m := slimPullRequest(pr)
+
+	if m["number"] != int64(1) {
+		t.Errorf("expected number 1, got %v", m["number"])
+	}
+	if m["title"] != "Fix bug" {
+		t.Errorf("expected title Fix bug, got %v", m["title"])
+	}
+	if m["user"] != "bob" {
+		t.Errorf("expected user bob, got %v", m["user"])
+	}
+	if m["additions"] != 10 {
+		t.Errorf("expected additions 10, got %v", m["additions"])
+	}
+	if m["milestone"] != "v1.0" {
+		t.Errorf("expected milestone v1.0, got %v", m["milestone"])
+	}
+
+	labels := m["labels"].([]string)
+	if len(labels) != 2 || labels[0] != "bug" {
+		t.Errorf("expected labels [bug priority], got %v", labels)
+	}
+
+	head := m["head"].(map[string]any)
+	if head["ref"] != "fix-branch" {
+		t.Errorf("expected head ref fix-branch, got %v", head["ref"])
+	}
+
+	assignees := m["assignees"].([]string)
+	if len(assignees) != 1 || assignees[0] != "alice" {
+		t.Errorf("expected assignees [alice], got %v", assignees)
+	}
+
+	// merged fields should not be present for unmerged PR
+	if _, ok := m["merged_at"]; ok {
+		t.Error("merged_at should not be present for unmerged PR")
+	}
+}
+
+func TestSlimPullRequests_ListIsSlimmer(t *testing.T) {
+	pr := &gitea_sdk.PullRequest{
+		Index:   1,
+		Title:   "PR title",
+		State:   "open",
+		HTMLURL: "https://gitea.com/org/repo/pulls/1",
+		Poster:  &gitea_sdk.User{UserName: "bob"},
+		Body:    "Full body text here",
+		Head:    &gitea_sdk.PRBranchInfo{Ref: "feature"},
+		Base:    &gitea_sdk.PRBranchInfo{Ref: "main"},
+	}
+
+	single := slimPullRequest(pr)
+	list := slimPullRequests([]*gitea_sdk.PullRequest{pr})
+
+	// Single has body, list does not
+	if _, ok := single["body"]; !ok {
+		t.Error("single PR should have body")
+	}
+	if _, ok := list[0]["body"]; ok {
+		t.Error("list PR should not have body")
+	}
+
+	// List has head as string ref, single has head as map
+	if _, ok := single["head"].(map[string]any); !ok {
+		t.Error("single PR head should be a map")
+	}
+	if list[0]["head"] != "feature" {
+		t.Errorf("list PR head should be string ref, got %v", list[0]["head"])
+	}
+}
+
+func TestSlimPullRequests_Nil(t *testing.T) {
+	if r := slimPullRequests(nil); len(r) != 0 {
+		t.Errorf("expected empty slice, got %v", r)
+	}
+}

operation/readme_test.go

@@ -0,0 +1,82 @@
+package operation
+
+import (
+	"maps"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+	"testing"
+)
+
+// toolTableRow matches a row of the "Available Tools" table in the README
+// files, capturing the tool name, the scope cell and the access cell, e.g.
+// "| get_me | user | Read | Get the current authenticated user |".
+var toolTableRow = regexp.MustCompile(`^\|\s*([a-z_]+)\s*\|\s*([a-z_]+)\s*\|\s*(\S+)\s*\|`)
+
+// readmeAccessLabels maps each README to the access-column labels it uses.
+var readmeAccessLabels = map[string]map[string]string{
+	"../README.md":       {"Read": "read", "Write": "write"},
+	"../README.zh-cn.md": {"读取": "read", "写入": "write"},
+	"../README.zh-tw.md": {"讀取": "read", "寫入": "write"},
+}
+
+// toolInfo is what TestReadmeToolTables tracks per tool, both as registered
+// in code and as documented in a README, so the two can be compared.
+type toolInfo struct {
+	scope  string
+	access string
+}
+
+// TestReadmeToolTables ensures the tool tables in the README files stay in sync
+// with the registered tools, in both directions and for every translation.
+// The tables listed tools that no longer existed for several releases before
+// anyone noticed.
+// The scope names in the README are the canonical, lowercase snake_case names
+// returned by (*tool.Tool).Scope(), so no translation is needed to compare them.
+func TestReadmeToolTables(t *testing.T) {
+	registered := map[string]toolInfo{}
+	for _, d := range domainTools {
+		scope := d.Scope()
+		for _, st := range d.ReadTools() {
+			registered[st.Tool.Name] = toolInfo{scope: scope, access: "read"}
+		}
+		for _, st := range d.WriteTools() {
+			registered[st.Tool.Name] = toolInfo{scope: scope, access: "write"}
+		}
+	}
+
+	for path, labels := range readmeAccessLabels {
+		t.Run(filepath.Base(path), func(t *testing.T) {
+			content, err := os.ReadFile(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			documented := map[string]toolInfo{}
+			for line := range strings.SplitSeq(string(content), "\n") {
+				if match := toolTableRow.FindStringSubmatch(line); match != nil {
+					documented[match[1]] = toolInfo{scope: match[2], access: labels[match[3]]}
+				}
+			}
+
+			for _, name := range slices.Sorted(maps.Keys(registered)) {
+				got, ok := documented[name]
+				want := registered[name]
+				switch {
+				case !ok:
+					t.Errorf("tool %q is registered but missing from the tool table", name)
+				case got.access != want.access:
+					t.Errorf("tool %q is documented with %q access, want %q", name, got.access, want.access)
+				case got.scope != want.scope:
+					t.Errorf("tool %q is documented with scope %q, want %q", name, got.scope, want.scope)
+				}
+			}
+			for _, name := range slices.Sorted(maps.Keys(documented)) {
+				if _, ok := registered[name]; !ok {
+					t.Errorf("tool %q is in the tool table but is not registered", name)
+				}
+			}
+		})
+	}
+}

operation/repo/branch.go

@@ -4,15 +4,19 @@ 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.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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
+// BranchTool holds the branch-related tools (scope "branch").
+var BranchTool = tool.New("branch")
+
 const (
 	CreateBranchToolName = "create_branch"
 	DeleteBranchToolName = "delete_branch"
@@ -20,67 +24,71 @@ const (
 )
 
 var (
-	CreateBranchTool = mcp.NewTool(
+	CreateBranchTool = tool.NewDefinition(
 		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")),
+		"Create a new branch in a repository, optionally from a specific source branch (defaults to the repository's default branch).",
+		annotation.Write("Create a new branch"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("branch", tool.Required()),
+		tool.String("old_branch", tool.Description("source branch (default: repo default)")),
 	)
 
-	DeleteBranchTool = mcp.NewTool(
+	DeleteBranchTool = tool.NewDefinition(
 		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")),
+		"Permanently delete a branch from a repository. This action is destructive and cannot be undone.",
+		annotation.Destructive("Delete a branch"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("branch", tool.Required()),
 	)
 
-	ListBranchesTool = mcp.NewTool(
+	ListBranchesTool = tool.NewDefinition(
 		ListBranchesToolName,
-		mcp.WithDescription("List branches"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+		"List all branches in a repository, paginated.",
+		annotation.ReadOnly("List repository branches"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 )
 
 func init() {
-	Tool.RegisterWrite(server.ServerTool{
+	BranchTool.RegisterWrite(tool.ServerTool{
 		Tool:    CreateBranchTool,
 		Handler: CreateBranchFn,
 	})
-	Tool.RegisterWrite(server.ServerTool{
+	BranchTool.RegisterWrite(tool.ServerTool{
 		Tool:    DeleteBranchTool,
 		Handler: DeleteBranchFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	BranchTool.RegisterRead(tool.ServerTool{
 		Tool:    ListBranchesTool,
 		Handler: ListBranchesFn,
 	})
 }
 
-func CreateBranchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateBranchFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func CreateBranchFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	branch, ok := req.GetArguments()["branch"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("branch is required"))
+	branch, err := params.GetString(args, "branch")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	oldBranch, _ := req.GetArguments()["old_branch"].(string)
+	oldBranch, _ := args["old_branch"].(string)
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	_, _, err = client.CreateBranch(owner, repo, gitea_sdk.CreateBranchOption{
+	_, _, err = client.Repositories.CreateBranch(ctx, owner, repo, gitea_sdk.CreateBranchOption{
 		BranchName:    branch,
 		OldBranchName: oldBranch,
 	})
@@ -88,28 +96,27 @@ func CreateBranchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTool
 		return to.ErrorResult(fmt.Errorf("create branch error: %v", err))
 	}
 
-	return mcp.NewToolResultText("Branch Created"), nil
+	return to.TextResult("Branch Created")
 }
 
-func DeleteBranchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteBranchFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func DeleteBranchFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	branch, ok := req.GetArguments()["branch"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("branch is required"))
+	branch, err := params.GetString(args, "branch")
+	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))
 	}
-	_, _, err = client.DeleteRepoBranch(owner, repo, branch)
+	_, _, err = client.Repositories.DeleteRepoBranch(ctx, owner, repo, branch)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("delete branch error: %v", err))
 	}
@@ -117,30 +124,30 @@ func DeleteBranchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTool
 	return to.TextResult("Branch Deleted")
 }
 
-func ListBranchesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListBranchesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func ListBranchesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
+	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListRepoBranchesOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     1,
-			PageSize: 100,
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	branches, _, err := client.ListRepoBranches(owner, repo, opt)
+	branches, _, err := client.Repositories.ListRepoBranches(ctx, owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list branches error: %v", err))
 	}
 
-	return to.TextResult(branches)
+	return to.TextResult(slimBranches(branches))
 }

operation/repo/commit.go

@@ -4,61 +4,74 @@ 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.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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
+// CommitTool holds the commit-related tools (scope "commit").
+var CommitTool = tool.New("commit")
+
 const (
-	ListRepoCommitsToolName = "list_repo_commits"
+	ListRepoCommitsToolName = "list_commits"
+	GetCommitToolName       = "get_commit"
 )
 
-var ListRepoCommitsTool = mcp.NewTool(
+var (
+	ListRepoCommitsTool = tool.NewDefinition(
 		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("page_size", mcp.Required(), mcp.Description("page size"), mcp.DefaultNumber(50), mcp.Min(1)),
+		"List commits in a repository, optionally starting from a specific branch or SHA and filtered to commits touching a given file path.",
+		annotation.ReadOnly("List repository commits"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("sha", tool.Description("starting SHA or branch")),
+		tool.String("path", tool.Description("only commits touching this path")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1), tool.Minimum(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30), tool.Minimum(1)),
+	)
+
+	GetCommitTool = tool.NewDefinition(
+		GetCommitToolName,
+		"Get details for a single commit in a repository by its SHA.",
+		annotation.ReadOnly("Get commit details"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("sha", tool.Required()),
+	)
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{
+	CommitTool.RegisterRead(tool.ServerTool{
 		Tool:    ListRepoCommitsTool,
 		Handler: ListRepoCommitsFn,
 	})
+	CommitTool.RegisterRead(tool.ServerTool{
+		Tool:    GetCommitTool,
+		Handler: GetCommitFn,
+	})
 }
 
-func ListRepoCommitsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoCommitsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func ListRepoCommitsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("page is required"))
-	}
-	pageSize, ok := req.GetArguments()["page_size"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("page_size is required"))
-	}
-	sha, _ := req.GetArguments()["sha"].(string)
-	path, _ := req.GetArguments()["path"].(string)
+	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,
@@ -67,9 +80,33 @@ func ListRepoCommitsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallT
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	commits, _, err := client.ListRepoCommits(owner, repo, opt)
+	commits, _, err := client.Repositories.ListRepoCommits(ctx, owner, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list repo commits err: %v", err))
 	}
-	return to.TextResult(commits)
+	return to.TextResult(slimCommits(commits))
+}
+
+func GetCommitFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	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.Repositories.GetSingleCommit(ctx, 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,97 +8,89 @@ 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"
 	"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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
+// FileTool holds the file-related tools (scope "file").
+var FileTool = tool.New("file")
+
 const (
-	GetFileToolName    = "get_file_content"
-	GetDirToolName     = "get_dir_content"
-	CreateFileToolName = "create_file"
-	UpdateFileToolName = "update_file"
+	GetFileToolName            = "get_file_contents"
+	GetDirToolName             = "get_dir_contents"
+	CreateOrUpdateFileToolName = "create_or_update_file"
 	DeleteFileToolName         = "delete_file"
 )
 
 var (
-	GetFileContentTool = mcp.NewTool(
+	GetFileContentTool = tool.NewDefinition(
 		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")),
+		"Get file content and metadata",
+		annotation.ReadOnly("Get file content"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("ref", tool.Required(), tool.Description("branch, tag, or commit SHA")),
+		tool.String("path", tool.Required()),
+		tool.Boolean("withLines", tool.Description("return numbered lines")),
 	)
 
-	GetDirContentTool = mcp.NewTool(
+	GetDirContentTool = tool.NewDefinition(
 		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")),
+		"List the entries (files and subdirectories) in a repository directory at a given ref (branch, tag, or commit SHA).",
+		annotation.ReadOnly("Get directory contents"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("ref", tool.Required(), tool.Description("branch, tag, or commit SHA")),
+		tool.String("path", tool.Required()),
 	)
 
-	CreateFileTool = mcp.NewTool(
-		CreateFileToolName,
-		mcp.WithDescription("Create 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.WithString("message", mcp.Required(), mcp.Description("commit message")),
-		mcp.WithString("branch_name", mcp.Required(), mcp.Description("branch name")),
-		mcp.WithString("new_branch_name", mcp.Description("new branch name")),
+	CreateOrUpdateFileTool = tool.NewDefinition(
+		CreateOrUpdateFileToolName,
+		"Create or update a file (provide sha to update an existing file).",
+		annotation.Write("Create or update a file"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("path", tool.Required()),
+		tool.String("content", tool.Required()),
+		tool.String("message", tool.Required(), tool.Description("commit message")),
+		tool.String("branch_name", tool.Required()),
+		tool.String("sha", tool.Description("existing file SHA (omit to create)")),
+		tool.String("new_branch_name", tool.Description("new branch (create only)")),
 	)
 
-	UpdateFileTool = mcp.NewTool(
-		UpdateFileToolName,
-		mcp.WithDescription("Update 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("sha", mcp.Required(), mcp.Description("sha is the SHA for the file that already exists")),
-		mcp.WithString("content", mcp.Required(), mcp.Description("file content")),
-		mcp.WithString("message", mcp.Required(), mcp.Description("commit message")),
-		mcp.WithString("branch_name", mcp.Required(), mcp.Description("branch name")),
-	)
-
-	DeleteFileTool = mcp.NewTool(
+	DeleteFileTool = tool.NewDefinition(
 		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.WithString("message", mcp.Required(), mcp.Description("commit message")),
-		mcp.WithString("branch_name", mcp.Required(), mcp.Description("branch name")),
-		mcp.WithString("sha", mcp.Description("sha")),
+		"Delete a file from a repository by committing the removal to a branch. Requires the file's current SHA and a commit message.",
+		annotation.Destructive("Delete a file"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("path", tool.Required()),
+		tool.String("message", tool.Required(), tool.Description("commit message")),
+		tool.String("branch_name", tool.Required()),
+		tool.String("sha", tool.Required()),
 	)
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{
+	FileTool.RegisterRead(tool.ServerTool{
 		Tool:    GetFileContentTool,
 		Handler: GetFileContentFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	FileTool.RegisterRead(tool.ServerTool{
 		Tool:    GetDirContentTool,
 		Handler: GetDirContentFn,
 	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    CreateFileTool,
-		Handler: CreateFileFn,
+	FileTool.RegisterWrite(tool.ServerTool{
+		Tool:    CreateOrUpdateFileTool,
+		Handler: CreateOrUpdateFileFn,
 	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    UpdateFileTool,
-		Handler: UpdateFileFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
+	FileTool.RegisterWrite(tool.ServerTool{
 		Tool:    DeleteFileTool,
 		Handler: DeleteFileFn,
 	})
@@ -109,30 +101,29 @@ type ContentLine struct {
 	Content    string `json:"content"`
 }
 
-func GetFileContentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetFileFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func GetFileContentFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	ref, _ := req.GetArguments()["ref"].(string)
-	filePath, ok := req.GetArguments()["filePath"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("filePath is required"))
+	ref, _ := args["ref"].(string)
+	filePath, err := params.GetString(args, "path")
+	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))
 	}
-	content, _, err := client.GetContents(owner, repo, ref, filePath)
+	content, _, err := client.Repositories.GetContents(ctx, owner, repo, ref, filePath)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get file err: %v", err))
 	}
-	withLines, _ := req.GetArguments()["withLines"].(bool)
+	withLines, _ := args["withLines"].(bool)
 	if withLines {
 		rawContent, err := base64.StdEncoding.DecodeString(*content.Content)
 		if err != nil {
@@ -151,7 +142,6 @@ func GetFileContentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 				LineNumber: line,
 				Content:    scanner.Text(),
 			})
-
 		}
 		if err := scanner.Err(); err != nil {
 			return to.ErrorResult(fmt.Errorf("scan content err: %v", err))
@@ -159,7 +149,7 @@ func GetFileContentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 
 		// remove the last blank line if exists
 		// git does not consider the last line as a new line
-		if contentLines[len(contentLines)-1].Content == "" {
+		if len(contentLines) > 0 && contentLines[len(contentLines)-1].Content == "" {
 			contentLines = contentLines[:len(contentLines)-1]
 		}
 
@@ -170,93 +160,59 @@ func GetFileContentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 		contentStr := string(contentBytes)
 		content.Content = &contentStr
 	}
-	return to.TextResult(content)
+	return to.TextResult(slimContents(content))
 }
 
-func GetDirContentFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetDirContentFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func GetDirContentFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	ref, _ := req.GetArguments()["ref"].(string)
-	filePath, ok := req.GetArguments()["filePath"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("filePath is required"))
+	ref, _ := args["ref"].(string)
+	filePath, err := params.GetString(args, "path")
+	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))
 	}
-	content, _, err := client.ListContents(owner, repo, ref, filePath)
+	content, _, err := client.Repositories.ListContents(ctx, owner, repo, ref, filePath)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get dir content err: %v", err))
 	}
-	return to.TextResult(content)
+	return to.TextResult(slimDirEntries(content))
 }
 
-func CreateFileFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateFileFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func CreateOrUpdateFileFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	filePath, ok := req.GetArguments()["filePath"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("filePath is required"))
-	}
-	content, _ := req.GetArguments()["content"].(string)
-	message, _ := req.GetArguments()["message"].(string)
-	branchName, _ := req.GetArguments()["branch_name"].(string)
-	opt := gitea_sdk.CreateFileOptions{
-		Content: base64.StdEncoding.EncodeToString([]byte(content)),
-		FileOptions: gitea_sdk.FileOptions{
-			Message:    message,
-			BranchName: branchName,
-		},
+	filePath, err := params.GetString(args, "path")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
+	content, _ := args["content"].(string)
+	message, _ := args["message"].(string)
+	branchName, _ := args["branch_name"].(string)
+	sha, _ := args["sha"].(string)
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	_, _, err = client.CreateFile(owner, repo, filePath, opt)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("create file err: %v", err))
-	}
-	return to.TextResult("Create file success")
-}
-
-func UpdateFileFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called UpdateFileFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
-	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
-	}
-	filePath, ok := req.GetArguments()["filePath"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("filePath is required"))
-	}
-	sha, ok := req.GetArguments()["sha"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("sha is required"))
-	}
-	content, _ := req.GetArguments()["content"].(string)
-	message, _ := req.GetArguments()["message"].(string)
-	branchName, _ := req.GetArguments()["branch_name"].(string)
 
+	if sha != "" {
+		// Update existing file
 		opt := gitea_sdk.UpdateFileOptions{
 			SHA:     sha,
 			Content: base64.StdEncoding.EncodeToString([]byte(content)),
@@ -265,36 +221,49 @@ func UpdateFileFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRe
 				BranchName: branchName,
 			},
 		}
-	client, err := gitea.ClientFromContext(ctx)
-	if err != nil {
-		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
-	}
-	_, _, err = client.UpdateFile(owner, repo, filePath, opt)
+		_, _, err = client.Repositories.UpdateFile(ctx, owner, repo, filePath, opt)
 		if err != nil {
 			return to.ErrorResult(fmt.Errorf("update file err: %v", err))
 		}
 		return to.TextResult("Update file success")
+	}
+
+	// Create new file
+	opt := gitea_sdk.CreateFileOptions{
+		Content: base64.StdEncoding.EncodeToString([]byte(content)),
+		FileOptions: gitea_sdk.FileOptions{
+			Message:    message,
+			BranchName: branchName,
+		},
+	}
+	if newBranch, ok := args["new_branch_name"].(string); ok && newBranch != "" {
+		opt.NewBranchName = newBranch
+	}
+	_, _, err = client.Repositories.CreateFile(ctx, owner, repo, filePath, opt)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("create file err: %v", err))
+	}
+	return to.TextResult("Create file success")
 }
 
-func DeleteFileFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteFileFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func DeleteFileFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	filePath, ok := req.GetArguments()["filePath"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("filePath is required"))
+	filePath, err := params.GetString(args, "path")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	message, _ := req.GetArguments()["message"].(string)
-	branchName, _ := req.GetArguments()["branch_name"].(string)
-	sha, ok := req.GetArguments()["sha"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("sha is required"))
+	message, _ := args["message"].(string)
+	branchName, _ := args["branch_name"].(string)
+	sha, err := params.GetString(args, "sha")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 	opt := gitea_sdk.DeleteFileOptions{
 		FileOptions: gitea_sdk.FileOptions{
@@ -307,7 +276,7 @@ func DeleteFileFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRe
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	_, err = client.DeleteFile(owner, repo, filePath, opt)
+	_, err = client.Repositories.DeleteFile(ctx, owner, repo, filePath, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("delete file err: %v", err))
 	}

operation/repo/release.go

@@ -3,18 +3,20 @@ package repo
 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/ptr"
+	"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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
+// ReleaseTool holds the release-related tools (scope "release").
+var ReleaseTool = tool.New("release")
+
 const (
 	CreateReleaseToolName    = "create_release"
 	DeleteReleaseToolName    = "delete_release"
@@ -24,121 +26,112 @@ const (
 )
 
 var (
-	CreateReleaseTool = mcp.NewTool(
+	CreateReleaseTool = tool.NewDefinition(
 		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")),
+		"Create a new release in a repository from a tag, optionally marking it as a draft or pre-release.",
+		annotation.Write("Create a release"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("tag_name", tool.Required()),
+		tool.String("target", tool.Required(), tool.Description("commitish")),
+		tool.String("title", tool.Required()),
+		tool.Boolean("is_draft"),
+		tool.Boolean("is_pre_release"),
+		tool.String("body"),
 	)
 
-	DeleteReleaseTool = mcp.NewTool(
+	DeleteReleaseTool = tool.NewDefinition(
 		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")),
+		"Delete a release from a repository by its numeric ID. This action is destructive and cannot be undone.",
+		annotation.Destructive("Delete a release"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Number("id", tool.Required()),
 	)
 
-	GetReleaseTool = mcp.NewTool(
+	GetReleaseTool = tool.NewDefinition(
 		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")),
+		"Get a release by ID",
+		annotation.ReadOnly("Get release details"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Number("id", tool.Required()),
 	)
 
-	GetLatestReleaseTool = mcp.NewTool(
+	GetLatestReleaseTool = tool.NewDefinition(
 		GetLatestReleaseToolName,
-		mcp.WithDescription("Get latest release"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+		"Get the most recent published (non-draft) release in a repository.",
+		annotation.ReadOnly("Get latest release"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
 	)
 
-	ListReleasesTool = mcp.NewTool(
+	ListReleasesTool = tool.NewDefinition(
 		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("pageSize", mcp.Description("page size"), mcp.DefaultNumber(20), mcp.Min(1)),
+		"List releases in a repository, optionally filtered to drafts or pre-releases.",
+		annotation.ReadOnly("List releases"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Boolean("is_draft"),
+		tool.Boolean("is_pre_release"),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1), tool.Minimum(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(20), tool.Minimum(1)),
 	)
 )
 
 func init() {
-	Tool.RegisterWrite(server.ServerTool{
+	ReleaseTool.RegisterWrite(tool.ServerTool{
 		Tool:    CreateReleaseTool,
 		Handler: CreateReleaseFn,
 	})
-	Tool.RegisterWrite(server.ServerTool{
+	ReleaseTool.RegisterWrite(tool.ServerTool{
 		Tool:    DeleteReleaseTool,
 		Handler: DeleteReleaseFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	ReleaseTool.RegisterRead(tool.ServerTool{
 		Tool:    GetReleaseTool,
 		Handler: GetReleaseFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	ReleaseTool.RegisterRead(tool.ServerTool{
 		Tool:    GetLatestReleaseTool,
 		Handler: GetLatestReleaseFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	ReleaseTool.RegisterRead(tool.ServerTool{
 		Tool:    ListReleasesTool,
 		Handler: ListReleasesFn,
 	})
 }
 
-// To avoid return too many tokens, we need to provide at least information as possible
-// llm can call get release to get more information
-type ListReleaseResult struct {
-	ID           int64     `json:"id"`
-	TagName      string    `json:"tag_name"`
-	Target       string    `json:"target_commitish"`
-	Title        string    `json:"title"`
-	IsDraft      bool      `json:"draft"`
-	IsPrerelease bool      `json:"prerelease"`
-	CreatedAt    time.Time `json:"created_at"`
-	PublishedAt  time.Time `json:"published_at"`
-}
-
-func CreateReleaseFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateReleasesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func CreateReleaseFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	tagName, ok := req.GetArguments()["tag_name"].(string)
-	if !ok {
-		return nil, fmt.Errorf("tag_name is required")
+	tagName, err := params.GetString(args, "tag_name")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	target, ok := req.GetArguments()["target"].(string)
-	if !ok {
-		return nil, fmt.Errorf("target is required")
+	target, err := params.GetString(args, "target")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	title, ok := req.GetArguments()["title"].(string)
-	if !ok {
-		return nil, fmt.Errorf("title is required")
+	title, err := params.GetString(args, "title")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	isDraft, _ := req.GetArguments()["is_draft"].(bool)
-	isPreRelease, _ := req.GetArguments()["is_pre_release"].(bool)
-	body, _ := req.GetArguments()["body"].(string)
+	isDraft, _ := args["is_draft"].(bool)
+	isPreRelease, _ := args["is_pre_release"].(bool)
+	body, _ := args["body"].(string)
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	_, _, err = client.CreateRelease(owner, repo, gitea_sdk.CreateReleaseOption{
+	_, _, err = client.Releases.CreateRelease(ctx, owner, repo, gitea_sdk.CreateReleaseOption{
 		TagName:      tagName,
 		Target:       target,
 		Title:        title,
@@ -147,140 +140,112 @@ func CreateReleaseFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToo
 		IsPrerelease: isPreRelease,
 	})
 	if err != nil {
-		return nil, fmt.Errorf("create release error: %v", err)
+		return to.ErrorResult(fmt.Errorf("create release error: %v", err))
 	}
 
-	return mcp.NewToolResultText("Release Created"), nil
+	return to.TextResult("Release Created")
 }
 
-func DeleteReleaseFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteReleaseFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func DeleteReleaseFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return nil, fmt.Errorf("id is required")
+	id, err := params.GetIndex(args, "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))
 	}
-	_, err = client.DeleteRelease(owner, repo, int64(id))
+	_, err = client.Releases.DeleteRelease(ctx, owner, repo, id)
 	if err != nil {
-		return nil, fmt.Errorf("delete release error: %v", err)
+		return to.ErrorResult(fmt.Errorf("delete release error: %v", err))
 	}
 
 	return to.TextResult("Release deleted successfully")
 }
 
-func GetReleaseFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetReleaseFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func GetReleaseFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return nil, fmt.Errorf("id is required")
+	id, err := params.GetIndex(args, "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))
 	}
-	release, _, err := client.GetRelease(owner, repo, int64(id))
+	release, _, err := client.Releases.GetRelease(ctx, owner, repo, id)
 	if err != nil {
-		return nil, fmt.Errorf("get release error: %v", err)
+		return to.ErrorResult(fmt.Errorf("get release error: %v", err))
 	}
 
-	return to.TextResult(release)
+	return to.TextResult(slimRelease(release))
 }
 
-func GetLatestReleaseFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetLatestReleaseFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func GetLatestReleaseFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	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))
 	}
-	release, _, err := client.GetLatestRelease(owner, repo)
+	release, _, err := client.Releases.GetLatestRelease(ctx, owner, repo)
 	if err != nil {
-		return nil, fmt.Errorf("get latest release error: %v", err)
+		return to.ErrorResult(fmt.Errorf("get latest release error: %v", err))
 	}
 
-	return to.TextResult(release)
+	return to.TextResult(slimRelease(release))
 }
 
-func ListReleasesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListReleasesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func ListReleasesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	var pIsDraft *bool
-	isDraft, ok := req.GetArguments()["is_draft"].(bool)
-	if ok {
-		pIsDraft = ptr.To(isDraft)
-	}
-	var pIsPreRelease *bool
-	isPreRelease, ok := req.GetArguments()["is_pre_release"].(bool)
-	if ok {
-		pIsPreRelease = ptr.To(isPreRelease)
-	}
-	page, _ := req.GetArguments()["page"].(float64)
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
+	page, pageSize := params.GetPagination(args, 20)
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	releases, _, err := client.ListReleases(owner, repo, gitea_sdk.ListReleasesOptions{
+	releases, _, err := client.Releases.ListReleases(ctx, owner, repo, gitea_sdk.ListReleasesOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
-		IsDraft:      pIsDraft,
-		IsPreRelease: pIsPreRelease,
+		IsDraft:      params.GetOptionalBoolPtr(args, "is_draft"),
+		IsPreRelease: params.GetOptionalBoolPtr(args, "is_pre_release"),
 	})
 	if err != nil {
-		return nil, fmt.Errorf("list releases error: %v", err)
+		return to.ErrorResult(fmt.Errorf("list releases error: %v", err))
 	}
 
-	results := make([]ListReleaseResult, len(releases))
-	for _, release := range releases {
-		results = append(results, ListReleaseResult{
-			ID:           release.ID,
-			TagName:      release.TagName,
-			Target:       release.Target,
-			Title:        release.Title,
-			IsDraft:      release.IsDraft,
-			IsPrerelease: release.IsPrerelease,
-			CreatedAt:    release.CreatedAt,
-			PublishedAt:  release.PublishedAt,
-		})
-	}
-	return to.TextResult(results)
+	return to.TextResult(slimReleases(releases))
 }

operation/repo/repo.go

@@ -2,126 +2,112 @@ package repo
 
 import (
 	"context"
-	"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/ptr"
+	"gitea.com/gitea/gitea-mcp/pkg/params"
+	"gitea.com/gitea/gitea-mcp/pkg/slim"
 	"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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var Tool = tool.New()
+var Tool = tool.New("repository")
 
 const (
 	CreateRepoToolName   = "create_repo"
 	ForkRepoToolName     = "fork_repo"
 	ListMyReposToolName  = "list_my_repos"
+	ListOrgReposToolName = "list_org_repos"
 )
 
 var (
-	CreateRepoTool = mcp.NewTool(
+	CreateRepoTool = tool.NewDefinition(
 		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)")),
+		"Create a new Git repository, optionally under an organization (defaults to the authenticated user's account), with options for visibility, template, license, .gitignore, and initial README.",
+		annotation.Write("Create a new repository"),
+		tool.String("name", tool.Required()),
+		tool.String("description"),
+		tool.Boolean("private"),
+		tool.String("issue_labels"),
+		tool.Boolean("auto_init"),
+		tool.Boolean("template"),
+		tool.String("gitignores"),
+		tool.String("license"),
+		tool.String("readme"),
+		tool.String("default_branch"),
+		tool.String("trust_model", tool.Enum("default", "collaborator", "committer", "collaboratorcommitter")),
+		tool.String("object_format_name", tool.Enum("sha1", "sha256")),
+		tool.String("organization", tool.Description("defaults to personal account")),
 	)
 
-	ForkRepoTool = mcp.NewTool(
+	ForkRepoTool = tool.NewDefinition(
 		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")),
+		"Fork an existing repository into the authenticated user's account or a target organization, optionally under a new name.",
+		annotation.Write("Fork a repository"),
+		tool.String("user", tool.Required(), tool.Description("owner of source repo")),
+		tool.String("repo", tool.Required()),
+		tool.String("organization", tool.Description("target org")),
+		tool.String("name", tool.Description("fork name")),
 	)
 
-	ListMyReposTool = mcp.NewTool(
+	ListMyReposTool = tool.NewDefinition(
 		ListMyReposToolName,
-		mcp.WithDescription("List my repositories"),
-		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)),
+		"List repositories owned by the authenticated user.",
+		annotation.ReadOnly("List my repositories"),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1), tool.Minimum(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30), tool.Minimum(1)),
+	)
+
+	ListOrgReposTool = tool.NewDefinition(
+		ListOrgReposToolName,
+		"List repositories belonging to an organization.",
+		annotation.ReadOnly("List organization repositories"),
+		tool.String("org", tool.Required()),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1), tool.Minimum(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(100), tool.Minimum(1)),
 	)
 )
 
 func init() {
-	Tool.RegisterWrite(server.ServerTool{
+	Tool.RegisterWrite(tool.ServerTool{
 		Tool:    CreateRepoTool,
 		Handler: CreateRepoFn,
 	})
-	Tool.RegisterWrite(server.ServerTool{
+	Tool.RegisterWrite(tool.ServerTool{
 		Tool:    ForkRepoTool,
 		Handler: ForkRepoFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	Tool.RegisterRead(tool.ServerTool{
 		Tool:    ListMyReposTool,
 		Handler: ListMyReposFn,
 	})
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    ListOrgReposTool,
+		Handler: ListOrgReposFn,
+	})
 }
 
-func RegisterTool(s *server.MCPServer) {
-	s.AddTool(CreateRepoTool, CreateRepoFn)
-	s.AddTool(ForkRepoTool, ForkRepoFn)
-	s.AddTool(ListMyReposTool, ListMyReposFn)
-
-	// File
-	s.AddTool(GetFileContentTool, GetFileContentFn)
-	s.AddTool(CreateFileTool, CreateFileFn)
-	s.AddTool(UpdateFileTool, UpdateFileFn)
-	s.AddTool(DeleteFileTool, DeleteFileFn)
-
-	// Branch
-	s.AddTool(CreateBranchTool, CreateBranchFn)
-	s.AddTool(DeleteBranchTool, DeleteBranchFn)
-	s.AddTool(ListBranchesTool, ListBranchesFn)
-
-	// Release
-	s.AddTool(CreateReleaseTool, CreateReleaseFn)
-	s.AddTool(DeleteReleaseTool, DeleteReleaseFn)
-	s.AddTool(GetReleaseTool, GetReleaseFn)
-	s.AddTool(GetLatestReleaseTool, GetLatestReleaseFn)
-	s.AddTool(ListReleasesTool, ListReleasesFn)
-
-	// Tag
-	s.AddTool(CreateTagTool, CreateTagFn)
-	s.AddTool(DeleteTagTool, DeleteTagFn)
-	s.AddTool(GetTagTool, GetTagFn)
-	s.AddTool(ListTagsTool, ListTagsFn)
-
-	// Commit
-	s.AddTool(ListRepoCommitsTool, ListRepoCommitsFn)
-}
-
-func CreateRepoFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateRepoFn")
-	name, ok := req.GetArguments()["name"].(string)
-	if !ok {
-		return to.ErrorResult(errors.New("repository name is required"))
+func CreateRepoFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	name, err := params.GetString(args, "name")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	description, _ := req.GetArguments()["description"].(string)
-	private, _ := req.GetArguments()["private"].(bool)
-	issueLabels, _ := req.GetArguments()["issue_labels"].(string)
-	autoInit, _ := req.GetArguments()["auto_init"].(bool)
-	template, _ := req.GetArguments()["template"].(bool)
-	gitignores, _ := req.GetArguments()["gitignores"].(string)
-	license, _ := req.GetArguments()["license"].(string)
-	readme, _ := req.GetArguments()["readme"].(string)
-	defaultBranch, _ := req.GetArguments()["default_branch"].(string)
-	organization, _ := req.GetArguments()["organization"].(string)
+	description, _ := args["description"].(string)
+	private, _ := args["private"].(bool)
+	issueLabels, _ := args["issue_labels"].(string)
+	autoInit, _ := args["auto_init"].(bool)
+	template, _ := args["template"].(bool)
+	gitignores, _ := args["gitignores"].(string)
+	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,
@@ -134,6 +120,8 @@ func CreateRepoFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRe
 		License:          license,
 		Readme:           readme,
 		DefaultBranch:    defaultBranch,
+		TrustModel:       gitea_sdk.TrustModel(trustModel),
+		ObjectFormatName: objectFormatName,
 	}
 
 	var repo *gitea_sdk.Repository
@@ -142,78 +130,82 @@ func CreateRepoFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolRe
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
 	if organization != "" {
-		repo, _, err = client.CreateOrgRepo(organization, opt)
+		repo, _, err = client.Repositories.CreateOrgRepo(ctx, organization, opt)
 		if err != nil {
 			return to.ErrorResult(fmt.Errorf("create organization repository '%s' in '%s' err: %v", name, organization, err))
 		}
 	} else {
-		repo, _, err = client.CreateRepo(opt)
+		repo, _, err = client.Repositories.CreateRepo(ctx, opt)
 		if err != nil {
 			return to.ErrorResult(fmt.Errorf("create repository '%s' err: %v", name, err))
 		}
 	}
-	return to.TextResult(repo)
+	return to.TextResult(slim.Repo(repo))
 }
 
-func ForkRepoFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ForkRepoFn")
-	user, ok := req.GetArguments()["user"].(string)
-	if !ok {
-		return to.ErrorResult(errors.New("user name is required"))
+func ForkRepoFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	user, err := params.GetString(args, "user")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(errors.New("repository name is required"))
-	}
-	organization, ok := req.GetArguments()["organization"].(string)
-	organizationPtr := ptr.To(organization)
-	if !ok || organization == "" {
-		organizationPtr = nil
-	}
-	name, ok := req.GetArguments()["name"].(string)
-	namePtr := ptr.To(name)
-	if !ok || name == "" {
-		namePtr = nil
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 	opt := gitea_sdk.CreateForkOption{
-		Organization: organizationPtr,
-		Name:         namePtr,
+		Organization: params.GetOptionalStringPtr(args, "organization"),
+		Name:         params.GetOptionalStringPtr(args, "name"),
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	_, _, err = client.CreateFork(user, repo, opt)
+	_, _, err = client.Repositories.CreateFork(ctx, user, repo, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("fork repository error: %v", err))
 	}
 	return to.TextResult("Fork success")
 }
 
-func ListMyReposFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListMyReposFn")
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
-	}
+func ListMyReposFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.ListReposOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	repos, _, err := client.ListMyRepos(opt)
+	repos, _, err := client.Repositories.ListMyRepos(ctx, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list my repositories error: %v", err))
 	}
 
+	return to.TextResult(slim.Repos(repos))
+}
+
+func ListOrgReposFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	page, pageSize := params.GetPagination(args, 100)
+	opt := gitea_sdk.ListOrgReposOptions{
+		ListOptions: gitea_sdk.ListOptions{
+			Page:     page,
+			PageSize: pageSize,
+		},
+	}
+	client, err := gitea.ClientFromContext(ctx)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
+	}
+	repos, _, err := client.Repositories.ListOrgRepos(ctx, org, opt)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("list organization '%s' repositories error: %v", org, err))
+	}
 	return to.TextResult(repos)
 }

operation/repo/slim.go

@@ -0,0 +1,178 @@
+package repo
+
+import (
+	"gitea.com/gitea/gitea-mcp/pkg/slim"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func slimBranch(b *gitea_sdk.Branch) map[string]any {
+	if b == nil {
+		return nil
+	}
+	m := map[string]any{
+		"name":      b.Name,
+		"protected": b.Protected,
+	}
+	if b.Commit != nil {
+		m["commit_sha"] = b.Commit.ID
+	}
+	return m
+}
+
+func slimBranches(branches []*gitea_sdk.Branch) []map[string]any {
+	out := make([]map[string]any, 0, len(branches))
+	for _, b := range branches {
+		out = append(out, slimBranch(b))
+	}
+	return out
+}
+
+func slimCommit(c *gitea_sdk.Commit) map[string]any {
+	if c == nil {
+		return nil
+	}
+	m := map[string]any{
+		"sha":      c.SHA,
+		"html_url": c.HTMLURL,
+		"created":  c.Created,
+	}
+	if c.RepoCommit != nil {
+		m["message"] = c.RepoCommit.Message
+		if c.RepoCommit.Author != nil {
+			m["author"] = map[string]any{
+				"name":  c.RepoCommit.Author.Name,
+				"email": c.RepoCommit.Author.Email,
+				"date":  c.RepoCommit.Author.Date,
+			}
+		}
+	}
+	return m
+}
+
+func slimCommits(commits []*gitea_sdk.Commit) []map[string]any {
+	out := make([]map[string]any, 0, len(commits))
+	for _, c := range commits {
+		out = append(out, slimCommit(c))
+	}
+	return out
+}
+
+func slimTag(t *gitea_sdk.Tag) map[string]any {
+	if t == nil {
+		return nil
+	}
+	m := map[string]any{
+		"name":    t.Name,
+		"message": t.Message,
+	}
+	if t.Commit != nil {
+		m["commit_sha"] = t.Commit.SHA
+	}
+	return m
+}
+
+func slimTags(tags []*gitea_sdk.Tag) []map[string]any {
+	out := make([]map[string]any, 0, len(tags))
+	for _, t := range tags {
+		m := map[string]any{
+			"name": t.Name,
+		}
+		if t.Commit != nil {
+			m["commit_sha"] = t.Commit.SHA
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+func slimRelease(r *gitea_sdk.Release) map[string]any {
+	if r == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":           r.ID,
+		"tag_name":     r.TagName,
+		"target":       r.Target,
+		"title":        r.Title,
+		"body":         r.Note,
+		"draft":        r.IsDraft,
+		"prerelease":   r.IsPrerelease,
+		"html_url":     r.HTMLURL,
+		"author":       slim.UserLogin(r.Publisher),
+		"created_at":   r.CreatedAt,
+		"published_at": r.PublishedAt,
+	}
+}
+
+func slimReleases(releases []*gitea_sdk.Release) []map[string]any {
+	out := make([]map[string]any, 0, len(releases))
+	for _, r := range releases {
+		out = append(out, slimRelease(r))
+	}
+	return out
+}
+
+func slimContents(c *gitea_sdk.ContentsResponse) map[string]any {
+	if c == nil {
+		return nil
+	}
+	m := map[string]any{
+		"name": c.Name,
+		"path": c.Path,
+		"sha":  c.SHA,
+		"type": c.Type,
+		"size": c.Size,
+	}
+	if c.Content != nil {
+		m["content"] = *c.Content
+	}
+	if c.Encoding != nil {
+		m["encoding"] = *c.Encoding
+	}
+	if c.HTMLURL != nil {
+		m["html_url"] = *c.HTMLURL
+	}
+	if c.DownloadURL != nil {
+		m["download_url"] = *c.DownloadURL
+	}
+	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 {
+		if c == nil {
+			continue
+		}
+		out = append(out, map[string]any{
+			"name": c.Name,
+			"path": c.Path,
+			"type": c.Type,
+			"size": c.Size,
+		})
+	}
+	return out
+}

operation/repo/slim_test.go

@@ -0,0 +1,109 @@
+package repo
+
+import (
+	"testing"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func TestSlimTag(t *testing.T) {
+	tag := &gitea_sdk.Tag{
+		Name:    "v1.0.0",
+		Message: "Release v1.0.0",
+		Commit:  &gitea_sdk.CommitMeta{SHA: "abc123"},
+	}
+
+	m := slimTag(tag)
+	if m["name"] != "v1.0.0" {
+		t.Errorf("expected name v1.0.0, got %v", m["name"])
+	}
+	if m["message"] != "Release v1.0.0" {
+		t.Errorf("expected message, got %v", m["message"])
+	}
+
+	// List variant omits message
+	list := slimTags([]*gitea_sdk.Tag{tag})
+	if _, ok := list[0]["message"]; ok {
+		t.Error("Tags list should omit message")
+	}
+	if list[0]["name"] != "v1.0.0" {
+		t.Errorf("expected name in list, got %v", list[0]["name"])
+	}
+}
+
+func TestSlimRelease(t *testing.T) {
+	r := &gitea_sdk.Release{
+		ID:        1,
+		TagName:   "v1.0.0",
+		Title:     "First Release",
+		Note:      "Release notes",
+		IsDraft:   false,
+		Publisher: &gitea_sdk.User{UserName: "alice"},
+	}
+
+	m := slimRelease(r)
+	if m["tag_name"] != "v1.0.0" {
+		t.Errorf("expected tag_name v1.0.0, got %v", m["tag_name"])
+	}
+	if m["body"] != "Release notes" {
+		t.Errorf("expected body from Note field, got %v", m["body"])
+	}
+	if m["author"] != "alice" {
+		t.Errorf("expected author alice, got %v", m["author"])
+	}
+}
+
+func TestSlimContents(t *testing.T) {
+	content := "package main"
+	encoding := "base64"
+	htmlURL := "https://gitea.com/org/repo/src/branch/main/main.go"
+	c := &gitea_sdk.ContentsResponse{
+		Name:     "main.go",
+		Path:     "main.go",
+		SHA:      "abc123",
+		Type:     "file",
+		Size:     12,
+		Content:  &content,
+		Encoding: &encoding,
+		HTMLURL:  &htmlURL,
+	}
+
+	m := slimContents(c)
+	if m["name"] != "main.go" {
+		t.Errorf("expected name main.go, got %v", m["name"])
+	}
+	if m["content"] != "package main" {
+		t.Errorf("expected content, got %v", m["content"])
+	}
+}
+
+func TestSlimDirEntries(t *testing.T) {
+	entries := []*gitea_sdk.ContentsResponse{
+		{Name: "src", Path: "src", Type: "dir", Size: 0},
+		{Name: "main.go", Path: "main.go", Type: "file", Size: 100},
+	}
+
+	result := slimDirEntries(entries)
+	if len(result) != 2 {
+		t.Fatalf("expected 2 entries, got %d", len(result))
+	}
+	if result[0]["name"] != "src" {
+		t.Errorf("expected first entry name src, got %v", result[0]["name"])
+	}
+	// Dir entries should not have content
+	if _, ok := result[0]["content"]; ok {
+		t.Error("dir entries should not have content field")
+	}
+}
+
+func TestSlimTags_Nil(t *testing.T) {
+	if r := slimTags(nil); len(r) != 0 {
+		t.Errorf("expected empty slice, got %v", r)
+	}
+}
+
+func TestSlimReleases_Nil(t *testing.T) {
+	if r := slimReleases(nil); len(r) != 0 {
+		t.Errorf("expected empty slice, got %v", r)
+	}
+}

operation/repo/tag.go

@@ -4,15 +4,19 @@ 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.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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
+// TagTool holds the tag-related tools (scope "tag").
+var TagTool = tool.New("tag")
+
 const (
 	CreateTagToolName = "create_tag"
 	DeleteTagToolName = "delete_tag"
@@ -21,191 +25,174 @@ const (
 )
 
 var (
-	CreateTagTool = mcp.NewTool(
+	CreateTagTool = tool.NewDefinition(
 		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("")),
+		"Create a new Git tag in a repository at a target commit, branch, or existing tag, with an optional annotation message.",
+		annotation.Write("Create a tag"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("tag_name", tool.Required()),
+		tool.String("target", tool.Description("commitish")),
+		tool.String("message", tool.Description("tag message")),
 	)
 
-	DeleteTagTool = mcp.NewTool(
+	DeleteTagTool = tool.NewDefinition(
 		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")),
+		"Permanently delete a tag from a repository. This action is destructive and cannot be undone.",
+		annotation.Destructive("Delete a tag"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("tag_name", tool.Required()),
 	)
 
-	GetTagTool = mcp.NewTool(
+	GetTagTool = tool.NewDefinition(
 		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")),
+		"Get details for a single tag in a repository by name.",
+		annotation.ReadOnly("Get tag details"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("tag_name", tool.Required()),
 	)
 
-	ListTagsTool = mcp.NewTool(
+	ListTagsTool = tool.NewDefinition(
 		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("pageSize", mcp.Description("page size"), mcp.DefaultNumber(20), mcp.Min(1)),
+		"List all tags in a repository, paginated.",
+		annotation.ReadOnly("List tags"),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1), tool.Minimum(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(20), tool.Minimum(1)),
 	)
 )
 
 func init() {
-	Tool.RegisterWrite(server.ServerTool{
+	TagTool.RegisterWrite(tool.ServerTool{
 		Tool:    CreateTagTool,
 		Handler: CreateTagFn,
 	})
-	Tool.RegisterWrite(server.ServerTool{
+	TagTool.RegisterWrite(tool.ServerTool{
 		Tool:    DeleteTagTool,
 		Handler: DeleteTagFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	TagTool.RegisterRead(tool.ServerTool{
 		Tool:    GetTagTool,
 		Handler: GetTagFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	TagTool.RegisterRead(tool.ServerTool{
 		Tool:    ListTagsTool,
 		Handler: ListTagsFn,
 	})
 }
 
-// To avoid return too many tokens, we need to provide at least information as possible
-// llm can call get tag to get more information
-type ListTagResult struct {
-	ID     string                `json:"id"`
-	Name   string                `json:"name"`
-	Commit *gitea_sdk.CommitMeta `json:"commit"`
-	// message may be a long text, so we should not provide it here
-}
-
-func CreateTagFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateTagFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func CreateTagFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	tagName, ok := req.GetArguments()["tag_name"].(string)
-	if !ok {
-		return nil, fmt.Errorf("tag_name is required")
+	tagName, err := params.GetString(args, "tag_name")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	target, _ := req.GetArguments()["target"].(string)
-	message, _ := req.GetArguments()["message"].(string)
+	target, _ := args["target"].(string)
+	message, _ := args["message"].(string)
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	_, _, err = client.CreateTag(owner, repo, gitea_sdk.CreateTagOption{
+	_, _, err = client.Repositories.CreateTag(ctx, owner, repo, gitea_sdk.CreateTagOption{
 		TagName: tagName,
 		Target:  target,
 		Message: message,
 	})
 	if err != nil {
-		return nil, fmt.Errorf("create tag error: %v", err)
+		return to.ErrorResult(fmt.Errorf("create tag error: %v", err))
 	}
 
-	return mcp.NewToolResultText("Tag Created"), nil
+	return to.TextResult("Tag Created")
 }
 
-func DeleteTagFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteTagFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func DeleteTagFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	tagName, ok := req.GetArguments()["tag_name"].(string)
-	if !ok {
-		return nil, fmt.Errorf("tag_name is required")
+	tagName, err := params.GetString(args, "tag_name")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	_, err = client.DeleteTag(owner, repo, tagName)
+	_, err = client.Repositories.DeleteTag(ctx, owner, repo, tagName)
 	if err != nil {
-		return nil, fmt.Errorf("delete tag error: %v", err)
+		return to.ErrorResult(fmt.Errorf("delete tag error: %v", err))
 	}
 
 	return to.TextResult("Tag deleted")
 }
 
-func GetTagFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetTagFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func GetTagFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	tagName, ok := req.GetArguments()["tag_name"].(string)
-	if !ok {
-		return nil, fmt.Errorf("tag_name is required")
+	tagName, err := params.GetString(args, "tag_name")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	tag, _, err := client.GetTag(owner, repo, tagName)
+	tag, _, err := client.Repositories.GetTag(ctx, owner, repo, tagName)
 	if err != nil {
-		return nil, fmt.Errorf("get tag error: %v", err)
+		return to.ErrorResult(fmt.Errorf("get tag error: %v", err))
 	}
 
-	return to.TextResult(tag)
+	return to.TextResult(slimTag(tag))
 }
 
-func ListTagsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListTagsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return nil, fmt.Errorf("owner is required")
+func ListTagsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return nil, fmt.Errorf("repo is required")
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	page, _ := req.GetArguments()["page"].(float64)
-	pageSize, _ := req.GetArguments()["pageSize"].(float64)
+	page := params.GetOptionalInt(args, "page", 1)
+	pageSize := params.GetOptionalInt(args, "per_page", 20)
 
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	tags, _, err := client.ListRepoTags(owner, repo, gitea_sdk.ListRepoTagsOptions{
+	tags, _, err := client.Repositories.ListRepoTags(ctx, owner, repo, gitea_sdk.ListRepoTagsOptions{
 		ListOptions: gitea_sdk.ListOptions{
 			Page:     int(page),
 			PageSize: int(pageSize),
 		},
 	})
 	if err != nil {
-		return nil, fmt.Errorf("list tags error: %v", err)
+		return to.ErrorResult(fmt.Errorf("list tags error: %v", err))
 	}
 
-	results := make([]ListTagResult, 0, len(tags))
-	for _, tag := range tags {
-		results = append(results, ListTagResult{
-			ID:     tag.ID,
-			Name:   tag.Name,
-			Commit: tag.Commit,
-		})
-	}
-	return to.TextResult(results)
+	return to.TextResult(slimTags(tags))
 }

operation/repo/tree.go

@@ -0,0 +1,73 @@
+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/params"
+	"gitea.com/gitea/gitea-mcp/pkg/to"
+	"gitea.com/gitea/gitea-mcp/pkg/tool"
+
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+const (
+	GetRepoTreeToolName = "get_repository_tree"
+)
+
+var GetRepoTreeTool = tool.NewDefinition(
+	GetRepoTreeToolName,
+	"Get the file tree of a repository at a given ref (SHA, branch, or tag), optionally recursively.",
+	annotation.ReadOnly("Get repository file tree"),
+	tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+	tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+	tool.String("tree_sha", tool.Required(), tool.Description("SHA, branch, or tag")),
+	tool.Boolean("recursive"),
+	tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+	tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
+)
+
+func init() {
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    GetRepoTreeTool,
+		Handler: GetRepoTreeFn,
+	})
+}
+
+func GetRepoTreeFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	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.Git.GetTrees(ctx, 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,54 @@
+package repo
+
+import (
+	"slices"
+	"testing"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+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) {
+	inputSchema := GetRepoTreeTool.InputSchema.(map[string]any)
+	required, _ := inputSchema["required"].([]string)
+	for _, field := range []string{"owner", "repo", "tree_sha"} {
+		if !slices.Contains(required, field) {
+			t.Errorf("expected %q to be required", field)
+		}
+	}
+}

operation/sdk_integration_test.go

@@ -0,0 +1,404 @@
+package operation
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	mcpContext "gitea.com/gitea/gitea-mcp/pkg/context"
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// Pin negotiated versions so SDK upgrades require compatibility review.
+const (
+	testServerVersion                   = "test-version"
+	expectedProtocolVersion             = "2026-07-28"
+	expectedStatefulHTTPProtocolVersion = "2025-11-25"
+)
+
+func exposeAllTools(t *testing.T) {
+	t.Helper()
+	originalReadOnly := flag.ReadOnly
+	originalAllowedTools := flag.AllowedTools
+	originalAllowedScopes := flag.AllowedScopes
+	originalVersion := flag.Version
+	t.Cleanup(func() {
+		flag.ReadOnly = originalReadOnly
+		flag.AllowedTools = originalAllowedTools
+		flag.AllowedScopes = originalAllowedScopes
+		flag.Version = originalVersion
+	})
+	flag.ReadOnly = false
+	flag.AllowedTools = nil
+	flag.AllowedScopes = nil
+	flag.Version = testServerVersion
+}
+
+// registeredToolCount is what the registry exposes under the current flags, so
+// the transport assertions track tool additions without being edited.
+func registeredToolCount() int {
+	count := 0
+	for _, domain := range domainTools {
+		count += len(domain.Tools())
+	}
+	return count
+}
+
+// stdioCommandEnvironment removes variables that override subprocess flags.
+func stdioCommandEnvironment() []string {
+	environment := os.Environ()
+	filtered := make([]string, 0, len(environment))
+	for _, entry := range environment {
+		name, _, _ := strings.Cut(entry, "=")
+		switch name {
+		case "GITEA_READONLY", "GITEA_SCOPES", "GITEA_TOOLS", "MCP_MODE":
+			continue
+		}
+		filtered = append(filtered, entry)
+	}
+	return filtered
+}
+
+func textContent(t *testing.T, result *mcp.CallToolResult) string {
+	t.Helper()
+	if len(result.Content) != 1 {
+		t.Fatalf("content count = %d, want 1", len(result.Content))
+	}
+	content, ok := result.Content[0].(*mcp.TextContent)
+	if !ok {
+		t.Fatalf("content type = %T, want *mcp.TextContent", result.Content[0])
+	}
+	return content.Text
+}
+
+// listAndCallVersion is the round trip every transport must support. wantText
+// differs per transport: the stdio subprocess resolves its version from the VCS
+// build info (main.go:14), so only the in-process servers have a known one.
+func listAndCallVersion(ctx context.Context, t *testing.T, session *mcp.ClientSession, wantText string) {
+	t.Helper()
+	result, err := session.ListTools(ctx, nil)
+	if err != nil {
+		t.Fatalf("ListTools() error = %v", err)
+	}
+	if want := registeredToolCount(); len(result.Tools) != want {
+		t.Fatalf("ListTools() count = %d, want %d", len(result.Tools), want)
+	}
+	callResult, err := session.CallTool(ctx, &mcp.CallToolParams{
+		Name: "get_gitea_mcp_server_version",
+	})
+	if err != nil {
+		t.Fatalf("CallTool() error = %v", err)
+	}
+	if got := textContent(t, callResult); !strings.Contains(got, wantText) {
+		t.Errorf("version tool result = %q, want it to contain %q", got, wantText)
+	}
+}
+
+func TestOfficialSDKInMemory(t *testing.T) {
+	exposeAllTools(t)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	serverTransport, clientTransport := mcp.NewInMemoryTransports()
+	server := newMCPServer(testServerVersion)
+	RegisterTool(server)
+	serverDone := make(chan error, 1)
+	go func() {
+		serverDone <- server.Run(ctx, serverTransport)
+	}()
+
+	client := mcp.NewClient(&mcp.Implementation{Name: "gitea-mcp-test", Version: "1"}, nil)
+	session, err := client.Connect(ctx, clientTransport, nil)
+	if err != nil {
+		t.Fatalf("Connect() error = %v", err)
+	}
+	if got := session.InitializeResult().ProtocolVersion; got != expectedProtocolVersion {
+		t.Errorf("protocol version = %q, want %q", got, expectedProtocolVersion)
+	}
+	listAndCallVersion(ctx, t, session, testServerVersion)
+	if err := session.Close(); err != nil {
+		t.Fatalf("Close() error = %v", err)
+	}
+	select {
+	case err := <-serverDone:
+		if err != nil && !errors.Is(err, context.Canceled) {
+			t.Fatalf("server Run() error = %v", err)
+		}
+	case <-ctx.Done():
+		t.Fatal("server did not stop after the client session closed")
+	}
+}
+
+func TestStreamableHTTPStateful(t *testing.T) {
+	exposeAllTools(t)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	server := newMCPServer(testServerVersion)
+	RegisterTool(server)
+	httpTestServer := httptest.NewServer(newHTTPServer("", server).Handler)
+	defer httpTestServer.Close()
+
+	client := mcp.NewClient(&mcp.Implementation{Name: "gitea-mcp-http-test", Version: "1"}, nil)
+	session, err := client.Connect(ctx, &mcp.StreamableClientTransport{
+		Endpoint:             httpTestServer.URL + "/mcp",
+		HTTPClient:           httpTestServer.Client(),
+		DisableStandaloneSSE: true,
+		MaxRetries:           -1,
+	}, nil)
+	if err != nil {
+		t.Fatalf("Connect() error = %v", err)
+	}
+	defer session.Close()
+	// Stateful Streamable HTTP cannot negotiate the sessionless 2026 protocol.
+	if got := session.InitializeResult().ProtocolVersion; got != expectedStatefulHTTPProtocolVersion {
+		t.Errorf("protocol version = %q, want %q", got, expectedStatefulHTTPProtocolVersion)
+	}
+	listAndCallVersion(ctx, t, session, testServerVersion)
+
+	response, err := httpTestServer.Client().Get(httpTestServer.URL + "/not-mcp")
+	if err != nil {
+		t.Fatalf("GET outside /mcp error = %v", err)
+	}
+	defer response.Body.Close()
+	if response.StatusCode != http.StatusNotFound {
+		t.Errorf("GET outside /mcp status = %d, want %d", response.StatusCode, http.StatusNotFound)
+	}
+}
+
+// spaceReader yields an endless run of spaces, so oversized bodies can be sent
+// without allocating them.
+type spaceReader struct{}
+
+func (spaceReader) Read(p []byte) (int, error) {
+	for index := range p {
+		p[index] = ' '
+	}
+	return len(p), nil
+}
+
+func TestStreamableHTTPRequestBodyLimit(t *testing.T) {
+	server := newMCPServer(testServerVersion)
+	httpTestServer := httptest.NewServer(newHTTPServer("", server).Handler)
+	defer httpTestServer.Close()
+
+	for _, test := range []struct {
+		name     string
+		size     int64
+		tooLarge bool
+	}{
+		{name: "above the SDK default", size: mcp.DefaultMaxRequestBodyBytes + 1},
+		{name: "above our own limit", size: maxRequestBodyBytes + 1, tooLarge: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			request, err := http.NewRequest(http.MethodPost, httpTestServer.URL+"/mcp", io.LimitReader(spaceReader{}, test.size))
+			if err != nil {
+				t.Fatalf("NewRequest() error = %v", err)
+			}
+			request.ContentLength = test.size
+			request.Header.Set("Content-Type", "application/json")
+			request.Header.Set("Accept", "application/json, text/event-stream")
+			response, err := httpTestServer.Client().Do(request)
+			if err != nil {
+				t.Fatalf("POST %d bytes error = %v", test.size, err)
+			}
+			defer response.Body.Close()
+			if gotTooLarge := response.StatusCode == http.StatusRequestEntityTooLarge; gotTooLarge != test.tooLarge {
+				t.Errorf("POST %d bytes status = %d, want %d = %v", test.size, response.StatusCode, http.StatusRequestEntityTooLarge, test.tooLarge)
+			}
+		})
+	}
+}
+
+type authorizationTransport struct {
+	base  http.RoundTripper
+	mu    sync.RWMutex
+	value string
+}
+
+func (t *authorizationTransport) set(value string) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.value = value
+}
+
+func (t *authorizationTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+	clone := request.Clone(request.Context()) // Clone already copies the header
+	t.mu.RLock()
+	value := t.value
+	t.mu.RUnlock()
+	if value != "" {
+		clone.Header.Set("Authorization", value)
+	}
+	return t.base.RoundTrip(clone)
+}
+
+func authContextValue(ctx context.Context, session *mcp.ClientSession) (string, error) {
+	result, err := session.CallTool(ctx, &mcp.CallToolParams{Name: "test_auth_context"})
+	if err != nil {
+		return "", err
+	}
+	if len(result.Content) != 1 {
+		return "", fmt.Errorf("content count = %d, want 1", len(result.Content))
+	}
+	content, ok := result.Content[0].(*mcp.TextContent)
+	if !ok {
+		return "", fmt.Errorf("content type = %T, want *mcp.TextContent", result.Content[0])
+	}
+	return content.Text, nil
+}
+
+func TestHTTPAuthPerRequest(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	server := newMCPServer(testServerVersion)
+	server.AddTool(
+		&mcp.Tool{
+			Name:        "test_auth_context",
+			Description: "Return the request-scoped authentication token.",
+			InputSchema: map[string]any{"type": "object", "properties": map[string]any{}},
+		},
+		func(ctx context.Context, _ *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			token, _ := ctx.Value(mcpContext.TokenContextKey).(string)
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{&mcp.TextContent{Text: token}},
+			}, nil
+		},
+	)
+	httpTestServer := httptest.NewServer(newHTTPServer("", server).Handler)
+	defer httpTestServer.Close()
+
+	baseTransport := httpTestServer.Client().Transport
+	auth := &authorizationTransport{base: baseTransport}
+	auth.set("Bearer first-token")
+	baseClient := &http.Client{Transport: auth}
+	client := mcp.NewClient(&mcp.Implementation{Name: "gitea-mcp-auth-test", Version: "1"}, nil)
+	session, err := client.Connect(ctx, &mcp.StreamableClientTransport{
+		Endpoint:             httpTestServer.URL + "/mcp",
+		HTTPClient:           baseClient,
+		DisableStandaloneSSE: true,
+		MaxRetries:           -1,
+	}, nil)
+	if err != nil {
+		t.Fatalf("Connect() error = %v", err)
+	}
+	defer session.Close()
+
+	for _, test := range []struct {
+		header string
+		want   string
+	}{
+		{header: "Bearer first-token", want: "first-token"},
+		{header: "token second-token", want: "second-token"},
+		{header: "Basic ignored", want: ""},
+	} {
+		auth.set(test.header)
+		token, err := authContextValue(ctx, session)
+		if err != nil {
+			t.Fatalf("CallTool() with %q error = %v", test.header, err)
+		}
+		if token != test.want {
+			t.Errorf("CallTool() token = %q, want %q", token, test.want)
+		}
+	}
+
+	type authenticatedSession struct {
+		session *mcp.ClientSession
+		want    string
+	}
+	concurrentSessions := make([]authenticatedSession, 0, 2)
+	for index, token := range []string{"parallel-one", "parallel-two"} {
+		transport := &authorizationTransport{base: baseTransport}
+		transport.set("Bearer " + token)
+		httpClient := &http.Client{Transport: transport}
+		parallelClient := mcp.NewClient(&mcp.Implementation{
+			Name:    fmt.Sprintf("gitea-mcp-auth-parallel-%d", index),
+			Version: "1",
+		}, nil)
+		parallelSession, err := parallelClient.Connect(ctx, &mcp.StreamableClientTransport{
+			Endpoint:             httpTestServer.URL + "/mcp",
+			HTTPClient:           httpClient,
+			DisableStandaloneSSE: true,
+			MaxRetries:           -1,
+		}, nil)
+		if err != nil {
+			t.Fatalf("parallel Connect() error = %v", err)
+		}
+		defer parallelSession.Close()
+		concurrentSessions = append(concurrentSessions, authenticatedSession{session: parallelSession, want: token})
+	}
+
+	var waitGroup sync.WaitGroup
+	errorsCh := make(chan error, 20)
+	for _, authenticated := range concurrentSessions {
+		for range 10 {
+			waitGroup.Go(func() {
+				got, err := authContextValue(ctx, authenticated.session)
+				if err != nil {
+					errorsCh <- err
+					return
+				}
+				if got != authenticated.want {
+					errorsCh <- fmt.Errorf("parallel token = %q, want %q", got, authenticated.want)
+				}
+			})
+		}
+	}
+	waitGroup.Wait()
+	close(errorsCh)
+	for err := range errorsCh {
+		t.Error(err)
+	}
+}
+
+func TestStdioCommandTransport(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping subprocess build in short mode")
+	}
+	for name, value := range map[string]string{
+		"GITEA_READONLY": "true",
+		"GITEA_SCOPES":   "user",
+		"GITEA_TOOLS":    "get_me",
+		"MCP_MODE":       "http",
+	} {
+		t.Setenv(name, value)
+	}
+	exposeAllTools(t)
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	binary := filepath.Join(t.TempDir(), "gitea-mcp")
+	build := exec.CommandContext(ctx, "go", "build", "-o", binary, "..")
+	if output, err := build.CombinedOutput(); err != nil {
+		t.Fatalf("build stdio test binary: %v\n%s", err, output)
+	}
+
+	client := mcp.NewClient(&mcp.Implementation{Name: "gitea-mcp-stdio-test", Version: "1"}, nil)
+	command := exec.CommandContext(ctx, binary, "--transport", "stdio")
+	command.Env = stdioCommandEnvironment()
+	session, err := client.Connect(ctx, &mcp.CommandTransport{
+		Command:           command,
+		TerminateDuration: 2 * time.Second,
+	}, nil)
+	if err != nil {
+		t.Fatalf("Connect() error = %v", err)
+	}
+	defer session.Close()
+	if got := session.InitializeResult().ProtocolVersion; got != expectedProtocolVersion {
+		t.Errorf("protocol version = %q, want %q", got, expectedProtocolVersion)
+	}
+	listAndCallVersion(ctx, t, session, "Gitea MCP Server version:")
+}

operation/search/search.go

@@ -3,196 +3,220 @@ 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/ptr"
+	"gitea.com/gitea/gitea-mcp/pkg/params"
+	"gitea.com/gitea/gitea-mcp/pkg/slim"
 	"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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var Tool = tool.New()
+var Tool = tool.New("search")
 
 const (
 	SearchUsersToolName    = "search_users"
 	SearchOrgTeamsToolName = "search_org_teams"
 	SearchReposToolName    = "search_repos"
+	SearchIssuesToolName   = "search_issues"
 )
 
 var (
-	SearchUsersTool = mcp.NewTool(
+	SearchUsersTool = tool.NewDefinition(
 		SearchUsersToolName,
-		mcp.WithDescription("search users"),
-		mcp.WithString("keyword", mcp.Description("Keyword")),
-		mcp.WithNumber("page", mcp.Description("Page"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("pageSize", mcp.Description("PageSize"), mcp.DefaultNumber(100)),
+		"Search for Gitea users by username or full name.",
+		annotation.ReadOnly("Search users"),
+		tool.String("query", tool.Required()),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 
-	SearOrgTeamsTool = mcp.NewTool(
+	SearOrgTeamsTool = tool.NewDefinition(
 		SearchOrgTeamsToolName,
-		mcp.WithDescription("search organization teams"),
-		mcp.WithString("org", mcp.Description("organization name")),
-		mcp.WithString("query", mcp.Description("search organization teams")),
-		mcp.WithBoolean("includeDescription", mcp.Description("include description?")),
-		mcp.WithNumber("page", mcp.Description("Page"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("pageSize", mcp.Description("PageSize"), mcp.DefaultNumber(100)),
+		"Search for teams within an organization by name, optionally including each team's description in the results.",
+		annotation.ReadOnly("Search organization teams"),
+		tool.String("org", tool.Required()),
+		tool.String("query", tool.Required()),
+		tool.Boolean("includeDescription"),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 
-	SearchReposTool = mcp.NewTool(
+	SearchReposTool = tool.NewDefinition(
 		SearchReposToolName,
-		mcp.WithDescription("search repos"),
-		mcp.WithString("keyword", 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("pageSize", mcp.Description("PageSize"), mcp.DefaultNumber(100)),
+		"Search for repositories by keyword, with filters for topic/description matching, owner, visibility, archived status, and sort order.",
+		annotation.ReadOnly("Search repositories"),
+		tool.String("query", tool.Required()),
+		tool.Boolean("keywordIsTopic"),
+		tool.Boolean("keywordInDescription"),
+		tool.Number("ownerID"),
+		tool.Boolean("isPrivate"),
+		tool.Boolean("isArchived"),
+		tool.String("sort"),
+		tool.String("order"),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
+	)
+
+	SearchIssuesTool = tool.NewDefinition(
+		SearchIssuesToolName,
+		"Search issues and PRs across repositories",
+		annotation.ReadOnly("Search issues"),
+		tool.String("query", tool.Required()),
+		tool.String("state", tool.Enum("open", "closed", "all")),
+		tool.String("type", tool.Enum("issues", "pulls")),
+		tool.String("labels", tool.Description("comma-separated")),
+		tool.String("owner", tool.Description("filter by owner")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{
+	Tool.RegisterRead(tool.ServerTool{
 		Tool:    SearchUsersTool,
-		Handler: SearchUsersFn,
+		Handler: UsersFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	Tool.RegisterRead(tool.ServerTool{
 		Tool:    SearOrgTeamsTool,
-		Handler: SearchOrgTeamsFn,
+		Handler: OrgTeamsFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
+	Tool.RegisterRead(tool.ServerTool{
 		Tool:    SearchReposTool,
-		Handler: SearchReposFn,
+		Handler: ReposFn,
+	})
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    SearchIssuesTool,
+		Handler: IssuesFn,
 	})
 }
 
-func SearchUsersFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called SearchUsersFn")
-	keyword, ok := req.GetArguments()["keyword"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("keyword is required"))
-	}
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
+func UsersFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	keyword, err := params.GetString(args, "query")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
+	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.SearchUsersOption{
 		KeyWord: keyword,
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	users, _, err := client.SearchUsers(opt)
+	users, _, err := client.Users.SearchUsers(ctx, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("search users err: %v", err))
 	}
-	return to.TextResult(users)
+	return to.TextResult(slimUserDetails(users))
 }
 
-func SearchOrgTeamsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called SearchOrgTeamsFn")
-	org, ok := req.GetArguments()["org"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("organization is required"))
+func OrgTeamsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	org, err := params.GetString(args, "org")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	query, ok := req.GetArguments()["query"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("query is required"))
-	}
-	includeDescription, _ := req.GetArguments()["includeDescription"].(bool)
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
+	query, err := params.GetString(args, "query")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
+	includeDescription, _ := args["includeDescription"].(bool)
+	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.SearchTeamsOptions{
 		Query:              query,
 		IncludeDescription: includeDescription,
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	teams, _, err := client.SearchOrgTeams(org, &opt)
+	teams, _, err := client.Organizations.SearchOrgTeams(ctx, org, &opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("search organization teams error: %v", err))
 	}
-	return to.TextResult(teams)
+	return to.TextResult(slimTeams(teams))
 }
 
-func SearchReposFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called SearchReposFn")
-	keyword, ok := req.GetArguments()["keyword"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("keyword is required"))
-	}
-	keywordIsTopic, _ := req.GetArguments()["keywordIsTopic"].(bool)
-	keywordInDescription, _ := req.GetArguments()["keywordInDescription"].(bool)
-	ownerID, _ := req.GetArguments()["ownerID"].(float64)
-	var pIsPrivate *bool
-	isPrivate, ok := req.GetArguments()["isPrivate"].(bool)
-	if ok {
-		pIsPrivate = ptr.To(isPrivate)
-	}
-	var pIsArchived *bool
-	isArchived, ok := req.GetArguments()["isArchived"].(bool)
-	if ok {
-		pIsArchived = ptr.To(isArchived)
-	}
-	sort, _ := req.GetArguments()["sort"].(string)
-	order, _ := req.GetArguments()["order"].(string)
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
+func ReposFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	keyword, err := params.GetString(args, "query")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
+	keywordIsTopic, _ := args["keywordIsTopic"].(bool)
+	keywordInDescription, _ := args["keywordInDescription"].(bool)
+	sort, _ := args["sort"].(string)
+	order, _ := args["order"].(string)
+	page, pageSize := params.GetPagination(args, 30)
 	opt := gitea_sdk.SearchRepoOptions{
 		Keyword:              keyword,
 		KeywordIsTopic:       keywordIsTopic,
 		KeywordInDescription: keywordInDescription,
-		OwnerID:              int64(ownerID),
-		IsPrivate:            pIsPrivate,
-		IsArchived:           pIsArchived,
+		OwnerID:              params.GetOptionalInt(args, "ownerID", 0),
+		IsPrivate:            params.GetOptionalBoolPtr(args, "isPrivate"),
+		IsArchived:           params.GetOptionalBoolPtr(args, "isArchived"),
 		Sort:                 sort,
 		Order:                order,
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	repos, _, err := client.SearchRepos(opt)
+	repos, _, err := client.Repositories.SearchRepos(ctx, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("search repos error: %v", err))
 	}
-	return to.TextResult(repos)
+	return to.TextResult(slim.Repos(repos))
+}
+
+func IssuesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	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.Issues.ListIssues(ctx, opt)
+	if err != nil {
+		return to.ErrorResult(fmt.Errorf("search issues err: %v", err))
+	}
+	return to.TextResult(slimIssues(issues))
 }

operation/search/search_test.go

@@ -0,0 +1,44 @@
+package search
+
+import (
+	"slices"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestSearchToolsRequiredFields(t *testing.T) {
+	tests := []struct {
+		name     string
+		tool     *mcp.Tool
+		required []string
+	}{
+		{
+			name:     "search_users",
+			tool:     SearchUsersTool,
+			required: []string{"query"},
+		},
+		{
+			name:     "search_org_teams",
+			tool:     SearOrgTeamsTool,
+			required: []string{"org", "query"},
+		},
+		{
+			name:     "search_repos",
+			tool:     SearchReposTool,
+			required: []string{"query"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			inputSchema := tt.tool.InputSchema.(map[string]any)
+			required, _ := inputSchema["required"].([]string)
+			for _, field := range tt.required {
+				if !slices.Contains(required, field) {
+					t.Errorf("tool %s: expected %q to be required, got required=%v", tt.name, field, required)
+				}
+			}
+		})
+	}
+}

operation/search/slim.go

@@ -0,0 +1,71 @@
+package search
+
+import (
+	"gitea.com/gitea/gitea-mcp/pkg/slim"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func slimUserDetails(users []*gitea_sdk.User) []map[string]any {
+	out := make([]map[string]any, 0, len(users))
+	for _, u := range users {
+		out = append(out, slim.UserDetail(u))
+	}
+	return out
+}
+
+func slimTeam(t *gitea_sdk.Team) map[string]any {
+	if t == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":          t.ID,
+		"name":        t.Name,
+		"description": t.Description,
+		"permission":  t.Permission,
+	}
+}
+
+func slimTeams(teams []*gitea_sdk.Team) []map[string]any {
+	out := make([]map[string]any, 0, len(teams))
+	for _, t := range teams {
+		out = append(out, slimTeam(t))
+	}
+	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":       slim.UserLogin(i.Poster),
+			"comments":   i.Comments,
+			"created_at": i.Created,
+			"updated_at": i.Updated,
+		}
+		if len(i.Labels) > 0 {
+			m["labels"] = slim.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,56 @@
+package search
+
+import (
+	"slices"
+	"testing"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+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) {
+	inputSchema := SearchIssuesTool.InputSchema.(map[string]any)
+	required, _ := inputSchema["required"].([]string)
+	if !slices.Contains(required, "query") {
+		t.Error("search_issues should require query")
+	}
+}

operation/timetracking/slim.go

@@ -0,0 +1,47 @@
+package timetracking
+
+import (
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func slimStopWatch(s *gitea_sdk.StopWatch) map[string]any {
+	if s == nil {
+		return nil
+	}
+	return map[string]any{
+		"issue_index": s.IssueIndex,
+		"issue_title": s.IssueTitle,
+		"repo_name":   s.RepoName,
+		"repo_owner":  s.RepoOwnerName,
+		"created":     s.Created,
+		"seconds":     s.Seconds,
+	}
+}
+
+func slimStopWatches(watches []*gitea_sdk.StopWatch) []map[string]any {
+	out := make([]map[string]any, 0, len(watches))
+	for _, s := range watches {
+		out = append(out, slimStopWatch(s))
+	}
+	return out
+}
+
+func slimTrackedTime(t *gitea_sdk.TrackedTime) map[string]any {
+	if t == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":        t.ID,
+		"time":      t.Time,
+		"user_name": t.UserName,
+		"created":   t.Created,
+	}
+}
+
+func slimTrackedTimes(times []*gitea_sdk.TrackedTime) []map[string]any {
+	out := make([]map[string]any, 0, len(times))
+	for _, t := range times {
+		out = append(out, slimTrackedTime(t))
+	}
+	return out
+}

operation/timetracking/timetracking.go

@@ -5,349 +5,294 @@ 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"
 
-	"github.com/mark3labs/mcp-go/mcp"
-	"github.com/mark3labs/mcp-go/server"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var Tool = tool.New()
+var Tool = tool.New("timetracking")
 
 const (
-	// Stopwatch tools
-	StartStopwatchToolName   = "start_stopwatch"
-	StopStopwatchToolName    = "stop_stopwatch"
-	DeleteStopwatchToolName  = "delete_stopwatch"
-	GetMyStopwatchesToolName = "get_my_stopwatches"
-
-	// Tracked time tools
-	ListTrackedTimesToolName  = "list_tracked_times"
-	AddTrackedTimeToolName    = "add_tracked_time"
-	DeleteTrackedTimeToolName = "delete_tracked_time"
-	ListRepoTimesToolName     = "list_repo_times"
-	GetMyTimesToolName        = "get_my_times"
+	TimetrackingReadToolName  = "timetracking_read"
+	TimetrackingWriteToolName = "timetracking_write"
 )
 
 var (
-	// Stopwatch tools
-	StartStopwatchTool = mcp.NewTool(
-		StartStopwatchToolName,
-		mcp.WithDescription("Start a stopwatch on an issue to track time spent"),
-		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("issue index")),
+	TimetrackingReadTool = tool.NewDefinition(
+		TimetrackingReadToolName,
+		"Read time tracking: issue times, repo times, active stopwatches, your tracked times.",
+		annotation.ReadOnly("Read tracked time"),
+		tool.String("method", tool.Required(), tool.Enum("list_issue_times", "list_repo_times", "get_my_stopwatches", "get_my_times")),
+		tool.String("owner", tool.Description("for list_* methods")),
+		tool.String("repo", tool.Description("for list_* methods")),
+		tool.Number("issue_number", tool.Description("for 'list_issue_times'")),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 
-	StopStopwatchTool = mcp.NewTool(
-		StopStopwatchToolName,
-		mcp.WithDescription("Stop a running stopwatch on an issue and record the tracked time"),
-		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("issue index")),
-	)
-
-	DeleteStopwatchTool = mcp.NewTool(
-		DeleteStopwatchToolName,
-		mcp.WithDescription("Delete/cancel a running stopwatch without recording time"),
-		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("issue index")),
-	)
-
-	GetMyStopwatchesTool = mcp.NewTool(
-		GetMyStopwatchesToolName,
-		mcp.WithDescription("Get all currently running stopwatches for the authenticated user"),
-	)
-
-	// Tracked time tools
-	ListTrackedTimesTool = mcp.NewTool(
-		ListTrackedTimesToolName,
-		mcp.WithDescription("List tracked times for a specific issue"),
-		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("issue index")),
-		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100)),
-	)
-
-	AddTrackedTimeTool = mcp.NewTool(
-		AddTrackedTimeToolName,
-		mcp.WithDescription("Manually add tracked time to an issue"),
-		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("issue index")),
-		mcp.WithNumber("time", mcp.Required(), mcp.Description("time to add in seconds")),
-	)
-
-	DeleteTrackedTimeTool = mcp.NewTool(
-		DeleteTrackedTimeToolName,
-		mcp.WithDescription("Delete a tracked time entry from an issue"),
-		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("issue index")),
-		mcp.WithNumber("id", mcp.Required(), mcp.Description("tracked time entry ID")),
-	)
-
-	ListRepoTimesTool = mcp.NewTool(
-		ListRepoTimesToolName,
-		mcp.WithDescription("List all tracked times for a repository"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(1)),
-		mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(100)),
-	)
-
-	GetMyTimesTool = mcp.NewTool(
-		GetMyTimesToolName,
-		mcp.WithDescription("Get all tracked times for the authenticated user"),
+	TimetrackingWriteTool = tool.NewDefinition(
+		TimetrackingWriteToolName,
+		"Write time tracking: stopwatches and entries.",
+		annotation.Write("Add or manage tracked time"),
+		tool.String("method", tool.Required(), tool.Enum("start_stopwatch", "stop_stopwatch", "delete_stopwatch", "add_time", "delete_time")),
+		tool.String("owner", tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Description(params.RepoDesc)),
+		tool.Number("issue_number"),
+		tool.Number("time", tool.Description("seconds (for 'add_time')")),
+		tool.Number("id", tool.Description("entry ID (for 'delete_time')")),
 	)
 )
 
 func init() {
-	// Stopwatch tools
-	Tool.RegisterWrite(server.ServerTool{Tool: StartStopwatchTool, Handler: StartStopwatchFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: StopStopwatchTool, Handler: StopStopwatchFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: DeleteStopwatchTool, Handler: DeleteStopwatchFn})
-	Tool.RegisterRead(server.ServerTool{Tool: GetMyStopwatchesTool, Handler: GetMyStopwatchesFn})
-
-	// Tracked time tools
-	Tool.RegisterRead(server.ServerTool{Tool: ListTrackedTimesTool, Handler: ListTrackedTimesFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: AddTrackedTimeTool, Handler: AddTrackedTimeFn})
-	Tool.RegisterWrite(server.ServerTool{Tool: DeleteTrackedTimeTool, Handler: DeleteTrackedTimeFn})
-	Tool.RegisterRead(server.ServerTool{Tool: ListRepoTimesTool, Handler: ListRepoTimesFn})
-	Tool.RegisterRead(server.ServerTool{Tool: GetMyTimesTool, Handler: GetMyTimesFn})
+	Tool.RegisterRead(tool.ServerTool{Tool: TimetrackingReadTool, Handler: readFn})
+	Tool.RegisterWrite(tool.ServerTool{Tool: TimetrackingWriteTool, Handler: writeFn})
 }
 
-// Stopwatch handler functions
+func readFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "list_issue_times":
+		return listTrackedTimesFn(ctx, args)
+	case "list_repo_times":
+		return listRepoTimesFn(ctx, args)
+	case "get_my_stopwatches":
+		return getMyStopwatchesFn(ctx, args)
+	case "get_my_times":
+		return getMyTimesFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
 
-func StartStopwatchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called StartStopwatchFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func writeFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	switch method {
+	case "start_stopwatch":
+		return startStopwatchFn(ctx, args)
+	case "stop_stopwatch":
+		return stopStopwatchFn(ctx, args)
+	case "delete_stopwatch":
+		return deleteStopwatchFn(ctx, args)
+	case "add_time":
+		return addTrackedTimeFn(ctx, args)
+	case "delete_time":
+		return deleteTrackedTimeFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
 	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
+}
+
+func startStopwatchFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	_, err = client.StartIssueStopWatch(owner, repo, int64(index))
+	_, err = client.Issues.StartIssueStopWatch(ctx, owner, repo, index)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("start stopwatch on %s/%s#%d err: %v", owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("start stopwatch on %s/%s#%d err: %v", owner, repo, index, err))
 	}
-	return to.TextResult(fmt.Sprintf("Stopwatch started on issue %s/%s#%d", owner, repo, int64(index)))
+	return to.TextResult(fmt.Sprintf("Stopwatch started on issue %s/%s#%d", owner, repo, index))
 }
 
-func StopStopwatchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called StopStopwatchFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func stopStopwatchFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
+	index, err := params.GetIndex(args, "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))
 	}
-	_, err = client.StopIssueStopWatch(owner, repo, int64(index))
+	_, err = client.Issues.StopIssueStopWatch(ctx, owner, repo, index)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("stop stopwatch on %s/%s#%d err: %v", owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("stop stopwatch on %s/%s#%d err: %v", owner, repo, index, err))
 	}
-	return to.TextResult(fmt.Sprintf("Stopwatch stopped on issue %s/%s#%d - time recorded", owner, repo, int64(index)))
+	return to.TextResult(fmt.Sprintf("Stopwatch stopped on issue %s/%s#%d - time recorded", owner, repo, index))
 }
 
-func DeleteStopwatchFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteStopwatchFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func deleteStopwatchFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
+	index, err := params.GetIndex(args, "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))
 	}
-	_, err = client.DeleteIssueStopwatch(owner, repo, int64(index))
+	_, err = client.Issues.DeleteIssueStopwatch(ctx, owner, repo, index)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("delete stopwatch on %s/%s#%d err: %v", owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("delete stopwatch on %s/%s#%d err: %v", owner, repo, index, err))
 	}
-	return to.TextResult(fmt.Sprintf("Stopwatch deleted/cancelled on issue %s/%s#%d", owner, repo, int64(index)))
+	return to.TextResult(fmt.Sprintf("Stopwatch deleted/cancelled on issue %s/%s#%d", owner, repo, index))
 }
 
-func GetMyStopwatchesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetMyStopwatchesFn")
+func getMyStopwatchesFn(ctx context.Context, _ map[string]any) (*mcp.CallToolResult, error) {
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	stopwatches, _, err := client.GetMyStopwatches()
+	stopwatches, _, err := client.Issues.ListMyStopwatches(ctx, gitea_sdk.ListStopwatchesOptions{})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get stopwatches err: %v", err))
 	}
 	if len(stopwatches) == 0 {
 		return to.TextResult("No active stopwatches")
 	}
-	return to.TextResult(stopwatches)
+	return to.TextResult(slimStopWatches(stopwatches))
 }
 
-// Tracked time handler functions
-
-func ListTrackedTimesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListTrackedTimesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func listTrackedTimesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
-	}
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
+	index, err := params.GetIndex(args, "issue_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))
 	}
 
-	times, _, err := client.ListIssueTrackedTimes(owner, repo, int64(index), gitea_sdk.ListTrackedTimesOptions{
+	times, _, err := client.Issues.ListIssueTrackedTimes(ctx, owner, repo, index, gitea_sdk.ListTrackedTimesOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	})
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("list tracked times for %s/%s#%d err: %v", owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("list tracked times for %s/%s#%d err: %v", owner, repo, index, err))
 	}
 	if len(times) == 0 {
-		return to.TextResult(fmt.Sprintf("No tracked times for issue %s/%s#%d", owner, repo, int64(index)))
+		return to.TextResult(fmt.Sprintf("No tracked times for issue %s/%s#%d", owner, repo, index))
 	}
-	return to.TextResult(times)
+	return to.TextResult(slimTrackedTimes(times))
 }
 
-func AddTrackedTimeFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called AddTrackedTimeFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func addTrackedTimeFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	timeSeconds, ok := req.GetArguments()["time"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("time is required"))
+	timeSeconds, err := params.GetIndex(args, "time")
+	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))
 	}
-	trackedTime, _, err := client.AddTime(owner, repo, int64(index), gitea_sdk.AddTimeOption{
-		Time: int64(timeSeconds),
+	trackedTime, _, err := client.Issues.AddTime(ctx, owner, repo, index, gitea_sdk.AddTimeOption{
+		Time: timeSeconds,
 	})
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("add tracked time to %s/%s#%d err: %v", owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("add tracked time to %s/%s#%d err: %v", owner, repo, index, err))
 	}
-	return to.TextResult(trackedTime)
+	return to.TextResult(slimTrackedTime(trackedTime))
 }
 
-func DeleteTrackedTimeFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteTrackedTimeFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func deleteTrackedTimeFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	index, ok := req.GetArguments()["index"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("index is required"))
+	index, err := params.GetIndex(args, "issue_number")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	id, ok := req.GetArguments()["id"].(float64)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("id is required"))
+	id, err := params.GetIndex(args, "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))
 	}
-	_, err = client.DeleteTime(owner, repo, int64(index), int64(id))
+	_, err = client.Issues.DeleteTime(ctx, owner, repo, index, id)
 	if err != nil {
-		return to.ErrorResult(fmt.Errorf("delete tracked time %d from %s/%s#%d err: %v", int64(id), owner, repo, int64(index), err))
+		return to.ErrorResult(fmt.Errorf("delete tracked time %d from %s/%s#%d err: %v", id, owner, repo, index, err))
 	}
-	return to.TextResult(fmt.Sprintf("Tracked time entry %d deleted from issue %s/%s#%d", int64(id), owner, repo, int64(index)))
+	return to.TextResult(fmt.Sprintf("Tracked time entry %d deleted from issue %s/%s#%d", id, owner, repo, index))
 }
 
-func ListRepoTimesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListRepoTimesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func listRepoTimesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	page, ok := req.GetArguments()["page"].(float64)
-	if !ok {
-		page = 1
-	}
-	pageSize, ok := req.GetArguments()["pageSize"].(float64)
-	if !ok {
-		pageSize = 100
-	}
+	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))
 	}
-	times, _, err := client.ListRepoTrackedTimes(owner, repo, gitea_sdk.ListTrackedTimesOptions{
+	times, _, err := client.Issues.ListRepoTrackedTimes(ctx, owner, repo, gitea_sdk.ListTrackedTimesOptions{
 		ListOptions: gitea_sdk.ListOptions{
-			Page:     int(page),
-			PageSize: int(pageSize),
+			Page:     page,
+			PageSize: pageSize,
 		},
 	})
 	if err != nil {
@@ -356,21 +301,20 @@ func ListRepoTimesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToo
 	if len(times) == 0 {
 		return to.TextResult(fmt.Sprintf("No tracked times for repository %s/%s", owner, repo))
 	}
-	return to.TextResult(times)
+	return to.TextResult(slimTrackedTimes(times))
 }
 
-func GetMyTimesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetMyTimesFn")
+func getMyTimesFn(ctx context.Context, _ map[string]any) (*mcp.CallToolResult, error) {
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	times, _, err := client.GetMyTrackedTimes()
+	times, _, err := client.Issues.ListMyTrackedTimes(ctx, gitea_sdk.ListTrackedTimesOptions{})
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get tracked times err: %v", err))
 	}
 	if len(times) == 0 {
 		return to.TextResult("No tracked times found")
 	}
-	return to.TextResult(times)
+	return to.TextResult(slimTrackedTimes(times))
 }

operation/tool_contract_test.go

@@ -0,0 +1,142 @@
+package operation
+
+import (
+	"encoding/json"
+	"slices"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// TestToolContract checks the properties every exposed tool must hold, rather
+// than a snapshot of the current surface, so adding a tool needs no fixture
+// update and a malformed schema fails here instead of panicking in AddTool.
+func TestToolContract(t *testing.T) {
+	scopeByName := map[string]string{}
+	seenScopes := map[string]struct{}{}
+	for _, domain := range domainTools {
+		scope := domain.Scope()
+		if scope == "" {
+			t.Error("domainTools contains a domain with an empty scope")
+		}
+		// Tools() filters one domain by exactly one scope name, so a shared
+		// scope would make --scope select more than the caller asked for.
+		if _, duplicate := seenScopes[scope]; duplicate {
+			t.Errorf("domainTools contains a duplicate scope %q", scope)
+		}
+		seenScopes[scope] = struct{}{}
+
+		for _, registered := range domain.ReadTools() {
+			assertToolContract(t, scope, registered.Tool, true, scopeByName)
+		}
+		for _, registered := range domain.WriteTools() {
+			assertToolContract(t, scope, registered.Tool, false, scopeByName)
+		}
+	}
+	if len(scopeByName) == 0 {
+		t.Fatal("no tools are registered")
+	}
+}
+
+func assertToolContract(t *testing.T, scope string, definition *mcp.Tool, readOnly bool, scopeByName map[string]string) {
+	t.Helper()
+
+	t.Run(definition.Name, func(t *testing.T) {
+		if previous, duplicate := scopeByName[definition.Name]; duplicate {
+			t.Errorf("tool name is already registered in scope %q; AddTool would silently replace it", previous)
+		}
+		scopeByName[definition.Name] = scope
+
+		// Strict MCP clients reject a tools/list entry without a description.
+		if definition.Description == "" {
+			t.Error("tool has no description")
+		}
+
+		// A write tool registered as read stays exposed under --read-only.
+		if definition.Annotations == nil || definition.Annotations.ReadOnlyHint != readOnly {
+			t.Errorf("annotations = %+v, want readOnlyHint %v", definition.Annotations, readOnly)
+		}
+
+		schema := decodeJSON(t, definition.InputSchema)
+		if schema["type"] != "object" {
+			t.Fatalf("input schema type = %v, want object", schema["type"])
+		}
+		properties, ok := schema["properties"].(map[string]any)
+		if !ok {
+			t.Fatalf("input schema properties = %T, want a JSON object", schema["properties"])
+		}
+
+		for name, raw := range properties {
+			property, ok := raw.(map[string]any)
+			if !ok {
+				t.Errorf("property %q = %T, want a JSON object", name, raw)
+				continue
+			}
+			assertPropertyContract(t, name, property)
+		}
+	})
+}
+
+func assertPropertyContract(t *testing.T, name string, property map[string]any) {
+	t.Helper()
+
+	propertyType, ok := property["type"].(string)
+	if !ok {
+		t.Errorf("property %q has no type", name)
+		return
+	}
+
+	enum, hasEnum := property["enum"].([]any)
+	if _, declared := property["enum"]; declared && len(enum) == 0 {
+		t.Errorf("property %q has an empty enum", name)
+	}
+
+	defaultValue, hasDefault := property["default"]
+	if !hasDefault {
+		return
+	}
+	if !matchesJSONType(defaultValue, propertyType) {
+		t.Errorf("property %q default %#v is not a %s", name, defaultValue, propertyType)
+	}
+	if hasEnum && !slices.Contains(enum, defaultValue) {
+		t.Errorf("property %q default %#v is not one of its enum values %#v", name, defaultValue, enum)
+	}
+}
+
+func matchesJSONType(value any, propertyType string) bool {
+	switch propertyType {
+	case "string":
+		_, ok := value.(string)
+		return ok
+	case "number":
+		_, ok := value.(float64)
+		return ok
+	case "boolean":
+		_, ok := value.(bool)
+		return ok
+	case "array":
+		_, ok := value.([]any)
+		return ok
+	case "object":
+		_, ok := value.(map[string]any)
+		return ok
+	default:
+		return false
+	}
+}
+
+// decodeJSON round-trips through JSON so the assertions see what an MCP client
+// receives rather than the Go values behind it.
+func decodeJSON(t *testing.T, value any) map[string]any {
+	t.Helper()
+
+	encoded, err := json.Marshal(value)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	var decoded map[string]any
+	if err := json.Unmarshal(encoded, &decoded); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	return decoded
+}

operation/user/slim.go

@@ -0,0 +1,27 @@
+package user
+
+import (
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func slimOrg(o *gitea_sdk.Organization) map[string]any {
+	if o == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":          o.ID,
+		"name":        o.Name,
+		"full_name":   o.FullName,
+		"description": o.Description,
+		"avatar_url":  o.AvatarURL,
+		"website":     o.Website,
+	}
+}
+
+func slimOrgs(orgs []*gitea_sdk.Organization) []map[string]any {
+	out := make([]map[string]any, 0, len(orgs))
+	for _, o := range orgs {
+		out = append(out, slimOrg(o))
+	}
+	return out
+}

operation/user/user.go

@@ -4,99 +4,59 @@ 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/slim"
 	"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"
+	gitea_sdk "gitea.dev/sdk"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
 const (
-	// GetMyUserInfoToolName is the unique tool name used for MCP registration and lookup of the get_my_user_info command.
-	GetMyUserInfoToolName = "get_my_user_info"
-	// GetUserOrgsToolName is the unique tool name used for MCP registration and lookup of the get_user_orgs command.
+	GetMyUserInfoToolName = "get_me"
 	GetUserOrgsToolName   = "get_user_orgs"
-
-	// defaultPage is the default starting page number used for paginated organization listings.
-	defaultPage = 1
-	// defaultPageSize is the default number of organizations per page for paginated queries.
-	defaultPageSize = 100
 )
 
-// Tool is the MCP tool manager instance for registering all MCP tools in this package.
-var Tool = tool.New()
+var Tool = tool.New("user")
 
 var (
-	// GetMyUserInfoTool is the MCP tool for retrieving the current user's info.
-	// It is registered with a specific name and a description string.
-	GetMyUserInfoTool = mcp.NewTool(
+	GetMyUserInfoTool = tool.NewDefinition(
 		GetMyUserInfoToolName,
-		mcp.WithDescription("Get my user info"),
+		"Get current user",
+		annotation.ReadOnly("Get current user information"),
 	)
 
-	// GetUserOrgsTool is the MCP tool for listing organizations for the authenticated user.
-	// It supports pagination via "page" and "pageSize" arguments with default values specified above.
-	GetUserOrgsTool = mcp.NewTool(
+	GetUserOrgsTool = tool.NewDefinition(
 		GetUserOrgsToolName,
-		mcp.WithDescription("Get organizations associated with the authenticated user"),
-		mcp.WithNumber("page", mcp.Description("page number"), mcp.DefaultNumber(defaultPage)),
-		mcp.WithNumber("pageSize", mcp.Description("page size"), mcp.DefaultNumber(defaultPageSize)),
+		"List current user's organizations",
+		annotation.ReadOnly("Get user organizations"),
+		tool.Number("page", tool.Description(params.PageDesc), tool.Default(1)),
+		tool.Number("per_page", tool.Description(params.PaginationDesc), tool.Default(30)),
 	)
 )
 
-// init registers all MCP tools in Tool at package initialization.
-// This function ensures the handler functions are registered before server usage.
 func init() {
-	registerTools()
+	Tool.RegisterRead(tool.ServerTool{Tool: GetMyUserInfoTool, Handler: GetUserInfoFn})
+	Tool.RegisterRead(tool.ServerTool{Tool: GetUserOrgsTool, Handler: GetUserOrgsFn})
 }
 
-// registerTools registers all local MCP tool definitions and their handler functions.
-// To add new functionality, append your tool/handler pair to the tools slice below.
-func registerTools() {
-	tools := []server.ServerTool{
-		{Tool: GetMyUserInfoTool, Handler: GetUserInfoFn},
-		{Tool: GetUserOrgsTool, Handler: GetUserOrgsFn},
-	}
-	for _, t := range tools {
-		Tool.RegisterRead(t)
-	}
-}
-
-// getIntArg parses an integer argument from the MCP request arguments map.
-// Returns def if missing, not a number, or less than 1. Used for pagination arguments.
-func getIntArg(req mcp.CallToolRequest, name string, def int) int {
-	val, ok := req.GetArguments()[name].(float64)
-	if !ok || val < 1 {
-		return def
-	}
-	return int(val)
-}
-
-// GetUserInfoFn is the handler for "get_my_user_info" MCP tool requests.
-// Logs invocation, fetches current user info from gitea, wraps result for MCP.
-func GetUserInfoFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("[User] Called GetUserInfoFn")
+func GetUserInfoFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
 	client, err := gitea.ClientFromContext(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	user, _, err := client.GetMyUserInfo()
+	user, _, err := client.Users.GetMyUserInfo(ctx)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get user info err: %v", err))
 	}
-	return to.TextResult(user)
+	return to.TextResult(slim.UserDetail(user))
 }
 
-// GetUserOrgsFn is the handler for "get_user_orgs" MCP tool requests.
-// Logs invocation, pulls validated pagination arguments from request,
-// performs Gitea organization listing, and wraps the result for MCP.
-func GetUserOrgsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("[User] Called GetUserOrgsFn")
-	page := getIntArg(req, "page", defaultPage)
-	pageSize := getIntArg(req, "pageSize", defaultPageSize)
+func GetUserOrgsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	page, pageSize := params.GetPagination(args, 30)
 
 	opt := gitea_sdk.ListOrgsOptions{
 		ListOptions: gitea_sdk.ListOptions{
@@ -108,9 +68,9 @@ func GetUserOrgsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolR
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get gitea client err: %v", err))
 	}
-	orgs, _, err := client.ListMyOrgs(opt)
+	orgs, _, err := client.Organizations.ListMyOrgs(ctx, opt)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get user orgs err: %v", err))
 	}
-	return to.TextResult(orgs)
+	return to.TextResult(slimOrgs(orgs))
 }

operation/version/version.go

@@ -4,35 +4,34 @@ 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"
 	"gitea.com/gitea/gitea-mcp/pkg/tool"
 
-	"github.com/mark3labs/mcp-go/mcp"
-	"github.com/mark3labs/mcp-go/server"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var Tool = tool.New()
+var Tool = tool.New("version")
 
 const (
 	GetGiteaMCPServerVersion = "get_gitea_mcp_server_version"
 )
 
-var GetGiteaMCPServerVersionTool = mcp.NewTool(
+var GetGiteaMCPServerVersionTool = tool.NewDefinition(
 	GetGiteaMCPServerVersion,
-	mcp.WithDescription("Get Gitea MCP Server Version"),
+	"Get the running version of the Gitea MCP Server itself (not the Gitea instance it connects to).",
+	annotation.ReadOnly("Get server version"),
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{
+	Tool.RegisterRead(tool.ServerTool{
 		Tool:    GetGiteaMCPServerVersionTool,
 		Handler: GetGiteaMCPServerVersionFn,
 	})
 }
 
-func GetGiteaMCPServerVersionFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetGiteaMCPServerVersionFn")
+func GetGiteaMCPServerVersionFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
 	version := flag.Version
 	if version == "" {
 		version = "dev"

operation/wiki/wiki.go

@@ -2,124 +2,108 @@ 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"
 	"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"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-var Tool = tool.New()
+var Tool = tool.New("wiki")
 
 const (
-	ListWikiPagesToolName    = "list_wiki_pages"
-	GetWikiPageToolName      = "get_wiki_page"
-	GetWikiRevisionsToolName = "get_wiki_revisions"
-	CreateWikiPageToolName   = "create_wiki_page"
-	UpdateWikiPageToolName   = "update_wiki_page"
-	DeleteWikiPageToolName   = "delete_wiki_page"
+	WikiReadToolName  = "wiki_read"
+	WikiWriteToolName = "wiki_write"
 )
 
 var (
-	ListWikiPagesTool = mcp.NewTool(
-		ListWikiPagesToolName,
-		mcp.WithDescription("List all wiki pages in a repository"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
+	WikiReadTool = tool.NewDefinition(
+		WikiReadToolName,
+		"Read wiki: list pages, get content, revision history.",
+		annotation.ReadOnly("Read wiki pages"),
+		tool.String("method", tool.Required(), tool.Enum("list", "get", "get_revisions")),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("pageName", tool.Description("for 'get'/'get_revisions'")),
 	)
 
-	GetWikiPageTool = mcp.NewTool(
-		GetWikiPageToolName,
-		mcp.WithDescription("Get a wiki page content and metadata"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("pageName", mcp.Required(), mcp.Description("wiki page name")),
-	)
-
-	GetWikiRevisionsTool = mcp.NewTool(
-		GetWikiRevisionsToolName,
-		mcp.WithDescription("Get revisions history of a wiki page"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("pageName", mcp.Required(), mcp.Description("wiki page name")),
-	)
-
-	CreateWikiPageTool = mcp.NewTool(
-		CreateWikiPageToolName,
-		mcp.WithDescription("Create a new wiki page"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("title", mcp.Required(), mcp.Description("wiki page title")),
-		mcp.WithString("content_base64", mcp.Required(), mcp.Description("page content, base64 encoded")),
-		mcp.WithString("message", mcp.Description("commit message (optional)")),
-	)
-
-	UpdateWikiPageTool = mcp.NewTool(
-		UpdateWikiPageToolName,
-		mcp.WithDescription("Update an existing wiki page"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("pageName", mcp.Required(), mcp.Description("current wiki page name")),
-		mcp.WithString("title", mcp.Description("new page title (optional)")),
-		mcp.WithString("content_base64", mcp.Required(), mcp.Description("page content, base64 encoded")),
-		mcp.WithString("message", mcp.Description("commit message (optional)")),
-	)
-
-	DeleteWikiPageTool = mcp.NewTool(
-		DeleteWikiPageToolName,
-		mcp.WithDescription("Delete a wiki page"),
-		mcp.WithString("owner", mcp.Required(), mcp.Description("repository owner")),
-		mcp.WithString("repo", mcp.Required(), mcp.Description("repository name")),
-		mcp.WithString("pageName", mcp.Required(), mcp.Description("wiki page name to delete")),
+	WikiWriteTool = tool.NewDefinition(
+		WikiWriteToolName,
+		"Write wiki pages: create, update, delete.",
+		annotation.Destructive("Create, update, or delete wiki pages"),
+		tool.String("method", tool.Required(), tool.Enum("create", "update", "delete")),
+		tool.String("owner", tool.Required(), tool.Description(params.OwnerDesc)),
+		tool.String("repo", tool.Required(), tool.Description(params.RepoDesc)),
+		tool.String("pageName", tool.Description("for 'update'/'delete'")),
+		tool.String("title", tool.Description("for 'create'")),
+		tool.String("content", tool.Description("for 'create'/'update'")),
+		tool.String("message", tool.Description("commit message")),
 	)
 )
 
 func init() {
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    ListWikiPagesTool,
-		Handler: ListWikiPagesFn,
+	Tool.RegisterRead(tool.ServerTool{
+		Tool:    WikiReadTool,
+		Handler: wikiReadFn,
 	})
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    GetWikiPageTool,
-		Handler: GetWikiPageFn,
-	})
-	Tool.RegisterRead(server.ServerTool{
-		Tool:    GetWikiRevisionsTool,
-		Handler: GetWikiRevisionsFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    CreateWikiPageTool,
-		Handler: CreateWikiPageFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    UpdateWikiPageTool,
-		Handler: UpdateWikiPageFn,
-	})
-	Tool.RegisterWrite(server.ServerTool{
-		Tool:    DeleteWikiPageTool,
-		Handler: DeleteWikiPageFn,
+	Tool.RegisterWrite(tool.ServerTool{
+		Tool:    WikiWriteTool,
+		Handler: wikiWriteFn,
 	})
 }
 
-func ListWikiPagesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called ListWikiPagesFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func wikiReadFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	switch method {
+	case "list":
+		return listWikiPagesFn(ctx, args)
+	case "get":
+		return getWikiPageFn(ctx, args)
+	case "get_revisions":
+		return getWikiRevisionsFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func wikiWriteFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	method, err := params.GetString(args, "method")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	switch method {
+	case "create":
+		return createWikiPageFn(ctx, args)
+	case "update":
+		return updateWikiPageFn(ctx, args)
+	case "delete":
+		return deleteWikiPageFn(ctx, args)
+	default:
+		return to.ErrorResult(fmt.Errorf("unknown method: %s", method))
+	}
+}
+
+func listWikiPagesFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
+	}
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	// Use direct HTTP request because SDK does not support yet wikis
 	var result any
-	_, err := gitea.DoJSON(ctx, "GET", fmt.Sprintf("repos/%s/%s/wiki/pages", url.QueryEscape(owner), url.QueryEscape(repo)), nil, nil, &result)
+	_, err = gitea.DoJSON(ctx, "GET", fmt.Sprintf("repos/%s/%s/wiki/pages", url.PathEscape(owner), url.PathEscape(repo)), nil, nil, &result)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("list wiki pages err: %v", err))
 	}
@@ -127,23 +111,22 @@ func ListWikiPagesFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToo
 	return to.TextResult(result)
 }
 
-func GetWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetWikiPageFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func getWikiPageFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	pageName, ok := req.GetArguments()["pageName"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("pageName is required"))
+	pageName, err := params.GetString(args, "pageName")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
 	var result any
-	_, err := gitea.DoJSON(ctx, "GET", fmt.Sprintf("repos/%s/%s/wiki/page/%s", url.QueryEscape(owner), url.QueryEscape(repo), url.QueryEscape(pageName)), nil, nil, &result)
+	_, err = gitea.DoJSON(ctx, "GET", fmt.Sprintf("repos/%s/%s/wiki/page/%s", url.PathEscape(owner), url.PathEscape(repo), url.PathEscape(pageName)), nil, nil, &result)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get wiki page err: %v", err))
 	}
@@ -151,23 +134,22 @@ func GetWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolR
 	return to.TextResult(result)
 }
 
-func GetWikiRevisionsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called GetWikiRevisionsFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func getWikiRevisionsFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	pageName, ok := req.GetArguments()["pageName"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("pageName is required"))
+	pageName, err := params.GetString(args, "pageName")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
 	var result any
-	_, err := gitea.DoJSON(ctx, "GET", fmt.Sprintf("repos/%s/%s/wiki/revisions/%s", url.QueryEscape(owner), url.QueryEscape(repo), url.QueryEscape(pageName)), nil, nil, &result)
+	_, err = gitea.DoJSON(ctx, "GET", fmt.Sprintf("repos/%s/%s/wiki/revisions/%s", url.PathEscape(owner), url.PathEscape(repo), url.PathEscape(pageName)), nil, nil, &result)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("get wiki revisions err: %v", err))
 	}
@@ -175,38 +157,37 @@ func GetWikiRevisionsFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.Call
 	return to.TextResult(result)
 }
 
-func CreateWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called CreateWikiPageFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func createWikiPageFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	title, ok := req.GetArguments()["title"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("title is required"))
+	title, err := params.GetString(args, "title")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	contentBase64, ok := req.GetArguments()["content_base64"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("content_base64 is required"))
+	content, err := params.GetString(args, "content")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	message, _ := req.GetArguments()["message"].(string)
+	message, _ := args["message"].(string)
 	if message == "" {
 		message = fmt.Sprintf("Create wiki page '%s'", title)
 	}
 
 	requestBody := map[string]string{
 		"title":          title,
-		"content_base64": contentBase64,
+		"content_base64": base64.StdEncoding.EncodeToString([]byte(content)),
 		"message":        message,
 	}
 
 	var result any
-	_, err := gitea.DoJSON(ctx, "POST", fmt.Sprintf("repos/%s/%s/wiki/new", url.QueryEscape(owner), url.QueryEscape(repo)), nil, requestBody, &result)
+	_, err = gitea.DoJSON(ctx, "POST", fmt.Sprintf("repos/%s/%s/wiki/new", url.PathEscape(owner), url.PathEscape(repo)), nil, requestBody, &result)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("create wiki page err: %v", err))
 	}
@@ -214,45 +195,43 @@ func CreateWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	return to.TextResult(result)
 }
 
-func UpdateWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called UpdateWikiPageFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func updateWikiPageFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	pageName, ok := req.GetArguments()["pageName"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("pageName is required"))
+	pageName, err := params.GetString(args, "pageName")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	contentBase64, ok := req.GetArguments()["content_base64"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("content_base64 is required"))
+	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
-	if title, ok := req.GetArguments()["title"].(string); ok && title != "" {
+	if title, ok := args["title"].(string); ok && title != "" {
 		requestBody["title"] = title
 	} else {
-		// Utiliser pageName comme fallback pour éviter "unnamed"
 		requestBody["title"] = pageName
 	}
 
-	if message, ok := req.GetArguments()["message"].(string); ok && message != "" {
+	if message, ok := args["message"].(string); ok && message != "" {
 		requestBody["message"] = message
 	} else {
 		requestBody["message"] = fmt.Sprintf("Update wiki page '%s'", pageName)
 	}
 
 	var result any
-	_, err := gitea.DoJSON(ctx, "PATCH", fmt.Sprintf("repos/%s/%s/wiki/page/%s", url.QueryEscape(owner), url.QueryEscape(repo), url.QueryEscape(pageName)), nil, requestBody, &result)
+	_, err = gitea.DoJSON(ctx, "PATCH", fmt.Sprintf("repos/%s/%s/wiki/page/%s", url.PathEscape(owner), url.PathEscape(repo), url.PathEscape(pageName)), nil, requestBody, &result)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("update wiki page err: %v", err))
 	}
@@ -260,22 +239,21 @@ func UpdateWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallTo
 	return to.TextResult(result)
 }
 
-func DeleteWikiPageFn(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-	log.Debugf("Called DeleteWikiPageFn")
-	owner, ok := req.GetArguments()["owner"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("owner is required"))
+func deleteWikiPageFn(ctx context.Context, args map[string]any) (*mcp.CallToolResult, error) {
+	owner, err := params.GetString(args, "owner")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	repo, ok := req.GetArguments()["repo"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("repo is required"))
+	repo, err := params.GetString(args, "repo")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
-	pageName, ok := req.GetArguments()["pageName"].(string)
-	if !ok {
-		return to.ErrorResult(fmt.Errorf("pageName is required"))
+	pageName, err := params.GetString(args, "pageName")
+	if err != nil {
+		return to.ErrorResult(err)
 	}
 
-	_, err := gitea.DoJSON(ctx, "DELETE", fmt.Sprintf("repos/%s/%s/wiki/page/%s", url.QueryEscape(owner), url.QueryEscape(repo), url.QueryEscape(pageName)), nil, nil, nil)
+	_, err = gitea.DoJSON(ctx, "DELETE", fmt.Sprintf("repos/%s/%s/wiki/page/%s", url.PathEscape(owner), url.PathEscape(repo), url.PathEscape(pageName)), nil, nil, nil)
 	if err != nil {
 		return to.ErrorResult(fmt.Errorf("delete wiki page err: %v", err))
 	}

operation/wiki/wiki_test.go

@@ -0,0 +1,70 @@
+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"
+)
+
+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",
+			}
+
+			result, err := wikiWriteFn(ctx, args)
+			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,16 @@
+package annotation
+
+import "github.com/modelcontextprotocol/go-sdk/mcp"
+
+func ReadOnly(title string) *mcp.ToolAnnotations {
+	return &mcp.ToolAnnotations{Title: title, ReadOnlyHint: true}
+}
+
+func Write(title string) *mcp.ToolAnnotations {
+	return &mcp.ToolAnnotations{Title: title}
+}
+
+func Destructive(title string) *mcp.ToolAnnotations {
+	t := true
+	return &mcp.ToolAnnotations{Title: title, DestructiveHint: &t}
+}

pkg/annotation/annotation_test.go

@@ -0,0 +1,50 @@
+package annotation
+
+import (
+	"encoding/json"
+	"maps"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// The hints are what clients use to decide whether a tool needs confirmation, so
+// assert the encoded form: an omitted readOnlyHint reads as false either way, but
+// only the explicit form survives a client that checks for the key.
+func TestAnnotations(t *testing.T) {
+	for _, test := range []struct {
+		name        string
+		annotations *mcp.ToolAnnotations
+		want        map[string]any
+	}{
+		{
+			name:        "ReadOnly",
+			annotations: ReadOnly("Read"),
+			want:        map[string]any{"title": "Read", "readOnlyHint": true, "idempotentHint": false},
+		},
+		{
+			name:        "Write",
+			annotations: Write("Write"),
+			want:        map[string]any{"title": "Write", "readOnlyHint": false, "idempotentHint": false},
+		},
+		{
+			name:        "Destructive",
+			annotations: Destructive("Delete"),
+			want:        map[string]any{"title": "Delete", "readOnlyHint": false, "idempotentHint": false, "destructiveHint": true},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			encoded, err := json.Marshal(test.annotations)
+			if err != nil {
+				t.Fatalf("json.Marshal() error = %v", err)
+			}
+			var got map[string]any
+			if err := json.Unmarshal(encoded, &got); err != nil {
+				t.Fatalf("json.Unmarshal() error = %v", err)
+			}
+			if !maps.Equal(got, test.want) {
+				t.Errorf("annotations = %s, want %v", encoded, test.want)
+			}
+		})
+	}
+}

pkg/flag/flag.go

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

pkg/gitea/attachment_test.go

@@ -0,0 +1,208 @@
+package gitea
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+)
+
+func TestBuildAttachmentURLRejectsExternalURL(t *testing.T) {
+	origHost := flag.Host
+	flag.Host = "https://example.com"
+	defer func() { flag.Host = origHost }()
+
+	if _, err := buildAttachmentURL("https://evil.example.com/attachments/1"); err == nil {
+		t.Fatal("expected error for full URL attachment path")
+	}
+}
+
+func TestBuildAttachmentURLPreservesHostPathPrefix(t *testing.T) {
+	origHost := flag.Host
+	flag.Host = "https://example.com/gitea"
+	defer func() { flag.Host = origHost }()
+
+	got, err := buildAttachmentURL("/attachments/uuid-1")
+	if err != nil {
+		t.Fatalf("buildAttachmentURL() error = %v", err)
+	}
+	if got != "https://example.com/gitea/attachments/uuid-1" {
+		t.Fatalf("buildAttachmentURL() = %q", got)
+	}
+}
+
+func TestDownloadAttachmentUsesTokenAndReturnsContentType(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/attachments/uuid-1" {
+			t.Fatalf("path = %s", r.URL.Path)
+		}
+		if got := r.Header.Get("Authorization"); got != "token secret-token" {
+			t.Fatalf("Authorization = %q", got)
+		}
+		if got := r.Header.Get("Accept"); got != "*/*" {
+			t.Fatalf("Accept = %q", got)
+		}
+		w.Header().Set("Content-Type", "image/png")
+		_, _ = w.Write([]byte("png-bytes"))
+	}))
+	defer server.Close()
+
+	origHost, origToken := flag.Host, flag.Token
+	flag.Host, flag.Token = server.URL, "secret-token"
+	defer func() { flag.Host, flag.Token = origHost, origToken }()
+
+	raw, contentType, status, err := DownloadAttachment(context.Background(), "/attachments/uuid-1", "*/*")
+	if err != nil {
+		t.Fatalf("DownloadAttachment() error = %v", err)
+	}
+	if status != http.StatusOK {
+		t.Fatalf("DownloadAttachment() status = %d, want %d", status, http.StatusOK)
+	}
+	if contentType != "image/png" {
+		t.Fatalf("contentType = %q", contentType)
+	}
+	if string(raw) != "png-bytes" {
+		t.Fatalf("body = %q", string(raw))
+	}
+}
+
+func TestDownloadAttachmentRejectsCrossOriginRedirect(t *testing.T) {
+	redirected := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("cross-origin redirect should not be followed: %s", r.URL.String())
+	}))
+	defer redirected.Close()
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, redirected.URL+"/attachments/uuid-1", http.StatusFound)
+	}))
+	defer server.Close()
+
+	origHost, origToken := flag.Host, flag.Token
+	flag.Host, flag.Token = server.URL, "secret-token"
+	defer func() { flag.Host, flag.Token = origHost, origToken }()
+
+	_, _, _, err := DownloadAttachment(context.Background(), "/attachments/uuid-1", "*/*")
+	if err == nil {
+		t.Fatal("expected error for cross-origin redirect")
+	}
+	want := "do request: Get \"" + redirected.URL + "/attachments/uuid-1\": attachment redirect changed origin"
+	if err.Error() != want {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDownloadAttachmentRejectsSameOriginRedirectLoopAtHopLimit(t *testing.T) {
+	var serverURL string
+	redirects := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		redirects++
+		http.Redirect(w, r, serverURL+"/attachments/uuid-1", http.StatusFound)
+	}))
+	defer server.Close()
+	serverURL = server.URL
+
+	origHost := flag.Host
+	flag.Host = server.URL
+	defer func() { flag.Host = origHost }()
+
+	_, _, _, err := DownloadAttachment(context.Background(), "/attachments/uuid-1", "*/*")
+	if err == nil {
+		t.Fatal("expected redirect limit error")
+	}
+	if !strings.Contains(err.Error(), "stopped after 10 redirects") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if redirects != 10 {
+		t.Fatalf("redirects = %d, want 10", redirects)
+	}
+}
+
+func TestWriteAttachmentStreamsBodyToFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "attachment.bin")
+	written, err := WriteAttachment(strings.NewReader(strings.Repeat("z", 64)), path)
+	if err != nil {
+		t.Fatalf("WriteAttachment() error = %v", err)
+	}
+	if written != 64 {
+		t.Fatalf("written = %d, want 64", written)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	if string(data) != strings.Repeat("z", 64) {
+		t.Fatalf("body mismatch")
+	}
+}
+
+func TestWriteAttachmentCreatesPrivateFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "attachment.bin")
+
+	if _, err := WriteAttachment(strings.NewReader("secret"), path); err != nil {
+		t.Fatalf("WriteAttachment() error = %v", err)
+	}
+
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("Stat() error = %v", err)
+	}
+	if got := info.Mode().Perm() & 0o077; got != 0 {
+		t.Fatalf("permissions = %03o, want no group/other bits", info.Mode().Perm())
+	}
+}
+
+func TestWriteAttachmentTightensExistingFilePermissions(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "attachment.bin")
+	if err := os.WriteFile(path, []byte("public"), 0o644); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	if _, err := WriteAttachment(strings.NewReader("secret"), path); err != nil {
+		t.Fatalf("WriteAttachment() error = %v", err)
+	}
+
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("Stat() error = %v", err)
+	}
+	if got := info.Mode().Perm(); got != 0o600 {
+		t.Fatalf("permissions = %03o, want 600", got)
+	}
+}
+
+func TestDownloadAttachmentErrorsOnNon2xx(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "nope", http.StatusForbidden)
+	}))
+	defer server.Close()
+
+	origHost := flag.Host
+	flag.Host = server.URL
+	defer func() { flag.Host = origHost }()
+
+	_, _, status, err := DownloadAttachment(context.Background(), "/attachments/uuid-1", "*/*")
+	if status != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d", status, http.StatusForbidden)
+	}
+	var httpErr *HTTPError
+	if !errors.As(err, &httpErr) {
+		t.Fatalf("expected HTTPError, got %T", err)
+	}
+}
+
+func TestAttachmentHTTPClientHasNoTotalTimeout(t *testing.T) {
+	origin := &url.URL{Scheme: "https", Host: "example.com"}
+
+	client := attachmentHTTPClient(origin)
+
+	if client.Timeout != 0 {
+		t.Fatalf("Timeout = %v, want 0", client.Timeout)
+	}
+}

pkg/gitea/gitea.go

@@ -3,28 +3,50 @@ package gitea
 import (
 	"context"
 	"crypto/tls"
+	"errors"
 	"fmt"
 	"net/http"
+	"sync"
 
-	"code.gitea.io/sdk/gitea"
 	mcpContext "gitea.com/gitea/gitea-mcp/pkg/context"
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"gitea.dev/sdk"
 )
 
+var (
+	clientCache     sync.Map // token -> *gitea.Client
+	sharedTransOnce sync.Once
+	sharedTrans     *http.Transport
+)
+
+func sharedTransport() *http.Transport {
+	sharedTransOnce.Do(func() {
+		sharedTrans = http.DefaultTransport.(*http.Transport).Clone()
+		if flag.Insecure {
+			sharedTrans.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} //nolint:gosec // user-requested insecure mode
+		}
+	})
+	return sharedTrans
+}
+
+// NewClient returns a cached *gitea.Client keyed by host+token. The SDK's per-client
+// version cache and the shared transport let us reuse keep-alive connections
+// and avoid the SDK's /api/v1/version preflight on every tool call.
 func NewClient(token string) (*gitea.Client, error) {
-	httpClient := &http.Client{
-		Transport: http.DefaultTransport,
+	key := flag.Host + "\x00" + token
+	if v, ok := clientCache.Load(key); ok {
+		return v.(*gitea.Client), nil
 	}
 
+	httpClient := &http.Client{
+		Transport:     sharedTransport(),
+		CheckRedirect: checkRedirect,
+	}
 	opts := []gitea.ClientOption{
 		gitea.SetToken(token),
+		gitea.SetHTTPClient(httpClient),
 	}
-	if flag.Insecure {
-		httpClient.Transport.(*http.Transport).TLSClientConfig = &tls.Config{
-			InsecureSkipVerify: true,
-		}
-	}
-	opts = append(opts, gitea.SetHTTPClient(httpClient))
 	if flag.Debug {
 		opts = append(opts, gitea.SetDebugMode())
 	}
@@ -32,10 +54,23 @@ func NewClient(token string) (*gitea.Client, error) {
 	if err != nil {
 		return nil, fmt.Errorf("create gitea client err: %w", err)
 	}
+	client.SetUserAgent("gitea-mcp-server/" + flag.Version)
 
-	// Set user agent for the client
-	client.SetUserAgent(fmt.Sprintf("gitea-mcp-server/%s", flag.Version))
-	return client, nil
+	actual, _ := clientCache.LoadOrStore(key, client)
+	return actual.(*gitea.Client), nil
+}
+
+// checkRedirect prevents Go from silently changing mutating requests (POST, PATCH, etc.)
+// to GET when following 301/302/303 redirects, which would drop the request body and
+// make writes appear to succeed when they didn't.
+func checkRedirect(_ *http.Request, via []*http.Request) error {
+	if len(via) >= 10 {
+		return errors.New("stopped after 10 redirects")
+	}
+	if via[0].Method != http.MethodGet && via[0].Method != http.MethodHead {
+		return http.ErrUseLastResponse
+	}
+	return nil
 }
 
 func ClientFromContext(ctx context.Context) (*gitea.Client, error) {

pkg/gitea/redirect_test.go

@@ -0,0 +1,120 @@
+package gitea
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+)
+
+func TestCheckRedirect(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		method  string
+		wantErr error
+	}{
+		{"allows GET", http.MethodGet, nil},
+		{"allows HEAD", http.MethodHead, nil},
+		{"blocks PATCH", http.MethodPatch, http.ErrUseLastResponse},
+		{"blocks POST", http.MethodPost, http.ErrUseLastResponse},
+		{"blocks PUT", http.MethodPut, http.ErrUseLastResponse},
+		{"blocks DELETE", http.MethodDelete, http.ErrUseLastResponse},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			via := []*http.Request{{Method: tc.method}}
+			err := checkRedirect(nil, via)
+			if err != tc.wantErr {
+				t.Fatalf("expected %v, got %v", tc.wantErr, err)
+			}
+		})
+	}
+
+	t.Run("stops after 10 redirects", func(t *testing.T) {
+		via := make([]*http.Request, 10)
+		for i := range via {
+			via[i] = &http.Request{Method: http.MethodGet}
+		}
+		err := checkRedirect(nil, via)
+		if err == nil || err == http.ErrUseLastResponse {
+			t.Fatalf("expected redirect limit error, got %v", err)
+		}
+	})
+}
+
+// TestDoJSON_RepoRenameRedirect is a regression test for the bug where a PATCH
+// request to a renamed repo got a 301 redirect, Go's http.Client silently
+// changed the method to GET, and the write appeared to succeed without error.
+func TestDoJSON_RepoRenameRedirect(t *testing.T) {
+	// Simulate a Gitea API that returns 301 for the old repo name (like a renamed repo).
+	mux := http.NewServeMux()
+	mux.HandleFunc("PATCH /api/v1/repos/owner/old-name/pulls/1", func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "/api/v1/repos/owner/new-name/pulls/1", http.StatusMovedPermanently)
+	})
+	mux.HandleFunc("PATCH /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)
+		fmt.Fprint(w, `{"id":1,"title":"updated"}`)
+	})
+	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)
+		fmt.Fprint(w, `{"id":1,"title":"not-updated"}`)
+	})
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	origHost := flag.Host
+	defer func() { flag.Host = origHost }()
+	flag.Host = srv.URL
+
+	var result map[string]any
+	status, err := DoJSON(context.Background(), http.MethodPatch, "repos/owner/old-name/pulls/1", nil, map[string]string{"title": "updated"}, &result)
+	if err != nil {
+		// The redirect should be blocked, returning the 301 response directly.
+		// DoJSON treats non-2xx as an error, which is the correct behavior.
+		if status != http.StatusMovedPermanently {
+			t.Fatalf("expected status 301, got %d (err: %v)", status, err)
+		}
+		return
+	}
+
+	// If we reach here without error, the redirect was followed. Verify the
+	// method was preserved (title should be "updated", not "not-updated").
+	title, _ := result["title"].(string)
+	if title == "not-updated" {
+		t.Fatal("PATCH was silently converted to GET on 301 redirect — write was lost")
+	}
+}
+
+// TestDoJSON_GETRedirectFollowed verifies that GET requests still follow redirects normally.
+func TestDoJSON_GETRedirectFollowed(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /api/v1/repos/owner/old-name/pulls/1", func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "/api/v1/repos/owner/new-name/pulls/1", http.StatusMovedPermanently)
+	})
+	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"})
+	})
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	origHost := flag.Host
+	defer func() { flag.Host = origHost }()
+	flag.Host = srv.URL
+
+	var result map[string]any
+	status, err := DoJSON(context.Background(), http.MethodGet, "repos/owner/old-name/pulls/1", nil, nil, &result)
+	if err != nil {
+		t.Fatalf("GET redirect should be followed, got error: %v (status %d)", err, status)
+	}
+	title, _ := result["title"].(string)
+	if title != "found" {
+		t.Fatalf("expected title 'found', got %q", title)
+	}
+}

pkg/gitea/rest.go

@@ -3,19 +3,27 @@ package gitea
 import (
 	"bytes"
 	"context"
-	"crypto/tls"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
 	"net/url"
+	"os"
+	"path"
 	"strings"
+	"sync"
 	"time"
 
 	mcpContext "gitea.com/gitea/gitea-mcp/pkg/context"
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
 )
 
+const (
+	httpClientTimeout  = 60 * time.Second
+	errBodySnippetSize = 8192
+)
+
 type HTTPError struct {
 	StatusCode int
 	Body       string
@@ -28,6 +36,12 @@ func (e *HTTPError) Error() string {
 	return fmt.Sprintf("request failed with status %d: %s", e.StatusCode, e.Body)
 }
 
+type AttachmentResponse struct {
+	Body        io.ReadCloser
+	ContentType string
+	StatusCode  int
+}
+
 func tokenFromContext(ctx context.Context) string {
 	if ctx != nil {
 		if token, ok := ctx.Value(mcpContext.TokenContextKey).(string); ok && token != "" {
@@ -37,21 +51,26 @@ func tokenFromContext(ctx context.Context) string {
 	return flag.Token
 }
 
-func newRESTHTTPClient() *http.Client {
-	transport := http.DefaultTransport.(*http.Transport).Clone()
-	if flag.Insecure {
-		transport.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} //nolint:gosec
-	}
-	return &http.Client{
-		Transport: transport,
-		Timeout:   60 * time.Second,
+var (
+	restClientOnce sync.Once
+	restClient     *http.Client
+)
+
+func restHTTPClient() *http.Client {
+	restClientOnce.Do(func() {
+		restClient = &http.Client{
+			Transport:     sharedTransport(),
+			Timeout:       httpClientTimeout,
+			CheckRedirect: checkRedirect,
 		}
+	})
+	return restClient
 }
 
 func buildAPIURL(path string, query url.Values) (string, error) {
 	host := strings.TrimRight(flag.Host, "/")
 	if host == "" {
-		return "", fmt.Errorf("gitea host is empty")
+		return "", errors.New("gitea host is empty")
 	}
 	p := strings.TrimLeft(path, "/")
 	u, err := url.Parse(fmt.Sprintf("%s/api/v1/%s", host, p))
@@ -64,9 +83,43 @@ func buildAPIURL(path string, query url.Values) (string, error) {
 	return u.String(), nil
 }
 
+func buildAttachmentURL(attachmentPath string) (string, error) {
+	host := strings.TrimRight(flag.Host, "/")
+	if host == "" {
+		return "", errors.New("gitea host is empty")
+	}
+	baseURL, err := url.Parse(host)
+	if err != nil {
+		return "", err
+	}
+	if attachmentPath == "" {
+		return "", errors.New("attachment path is empty")
+	}
+	if strings.Contains(attachmentPath, "://") {
+		return "", errors.New("attachment path must not be a URL")
+	}
+	if !strings.HasPrefix(attachmentPath, "/attachments/") {
+		return "", errors.New("attachment path must start with /attachments/")
+	}
+	cleanPath := path.Clean(attachmentPath)
+	if !strings.HasPrefix(cleanPath, "/attachments/") {
+		return "", errors.New("attachment path must stay within /attachments/")
+	}
+	if cleanPath == "/attachments" || cleanPath == "/attachments/" {
+		return "", errors.New("attachment uuid is required")
+	}
+	joinedPath := strings.TrimRight(baseURL.Path, "/") + cleanPath
+	if joinedPath == "" {
+		joinedPath = cleanPath
+	}
+	baseURL.Path = joinedPath
+	baseURL.RawPath = joinedPath
+	return baseURL.String(), nil
+}
+
 // DoJSON performs an API request and decodes a JSON response into respOut (if non-nil).
 // It returns the HTTP status code.
-func DoJSON(ctx context.Context, method, path string, query url.Values, body any, respOut any) (int, error) {
+func DoJSON(ctx context.Context, method, path string, query url.Values, body, respOut any) (int, error) {
 	var bodyReader io.Reader
 	if body != nil {
 		b, err := json.Marshal(body)
@@ -80,45 +133,142 @@ func DoJSON(ctx context.Context, method, path string, query url.Values, body any
 	if err != nil {
 		return 0, err
 	}
+
 	req, err := http.NewRequestWithContext(ctx, method, u, bodyReader)
 	if err != nil {
 		return 0, fmt.Errorf("create request: %w", err)
 	}
-
 	token := tokenFromContext(ctx)
 	if token != "" {
-		req.Header.Set("Authorization", fmt.Sprintf("token %s", token))
+		req.Header.Set("Authorization", "token "+token)
 	}
-	req.Header.Set("Accept", "application/json")
 	if body != nil {
 		req.Header.Set("Content-Type", "application/json")
 	}
+	if respOut != nil {
+		req.Header.Set("Accept", "application/json")
+	}
 
-	client := newRESTHTTPClient()
-	resp, err := client.Do(req)
+	resp, err := restHTTPClient().Do(req)
 	if err != nil {
 		return 0, fmt.Errorf("do request: %w", err)
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		bodySnippet, _ := io.ReadAll(io.LimitReader(resp.Body, 8192))
+		bodySnippet, err := io.ReadAll(io.LimitReader(resp.Body, errBodySnippetSize+1))
+		if err != nil {
+			return resp.StatusCode, fmt.Errorf("read response: %w", err)
+		}
+		if len(bodySnippet) > errBodySnippetSize {
+			bodySnippet = bodySnippet[:errBodySnippetSize]
+		}
 		return resp.StatusCode, &HTTPError{StatusCode: resp.StatusCode, Body: strings.TrimSpace(string(bodySnippet))}
 	}
 
 	if respOut == nil {
-		io.Copy(io.Discard, resp.Body) // best-effort
+		_, _ = io.Copy(io.Discard, resp.Body)
 		return resp.StatusCode, nil
 	}
 
 	if err := json.NewDecoder(resp.Body).Decode(respOut); err != nil {
 		return resp.StatusCode, fmt.Errorf("decode response: %w", err)
 	}
+
 	return resp.StatusCode, nil
 }
 
+func attachmentHTTPClient(origin *url.URL) *http.Client {
+	return &http.Client{
+		Transport: sharedTransport(),
+		CheckRedirect: func(req *http.Request, via []*http.Request) error {
+			if err := checkRedirect(req, via); err != nil {
+				return err
+			}
+			if req.URL.Scheme != origin.Scheme || req.URL.Host != origin.Host {
+				return errors.New("attachment redirect changed origin")
+			}
+			return nil
+		},
+	}
+}
+
+func OpenAttachment(ctx context.Context, attachmentPath, accept string) (*AttachmentResponse, error) {
+	u, err := buildAttachmentURL(attachmentPath)
+	if err != nil {
+		return nil, err
+	}
+	origin, err := url.Parse(u)
+	if err != nil {
+		return nil, err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	token := tokenFromContext(ctx)
+	if token != "" {
+		req.Header.Set("Authorization", "token "+token)
+	}
+	if accept != "" {
+		req.Header.Set("Accept", accept)
+	}
+
+	resp, err := attachmentHTTPClient(origin).Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("do request: %w", err)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		defer resp.Body.Close()
+		bodySnippet, readErr := io.ReadAll(io.LimitReader(resp.Body, errBodySnippetSize+1))
+		if readErr != nil {
+			return nil, fmt.Errorf("read response: %w", readErr)
+		}
+		if len(bodySnippet) > errBodySnippetSize {
+			bodySnippet = bodySnippet[:errBodySnippetSize]
+		}
+		return nil, &HTTPError{StatusCode: resp.StatusCode, Body: strings.TrimSpace(string(bodySnippet))}
+	}
+	return &AttachmentResponse{Body: resp.Body, ContentType: resp.Header.Get("Content-Type"), StatusCode: resp.StatusCode}, nil
+}
+
+// DownloadAttachment downloads attachment bytes from a same-host attachment path.
+func DownloadAttachment(ctx context.Context, attachmentPath, accept string) ([]byte, string, int, error) {
+	resp, err := OpenAttachment(ctx, attachmentPath, accept)
+	if err != nil {
+		var httpErr *HTTPError
+		if errors.As(err, &httpErr) {
+			return nil, "", httpErr.StatusCode, err
+		}
+		return nil, "", 0, err
+	}
+	defer resp.Body.Close()
+
+	respBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, "", resp.StatusCode, fmt.Errorf("read response: %w", err)
+	}
+	return respBytes, resp.ContentType, resp.StatusCode, nil
+}
+
+func WriteAttachment(body io.Reader, outputPath string) (int64, error) {
+	file, err := os.OpenFile(outputPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o600)
+	if err != nil {
+		return 0, err
+	}
+	defer file.Close()
+	if err := file.Chmod(0o600); err != nil {
+		return 0, err
+	}
+
+	written, err := io.Copy(file, body)
+	if err != nil {
+		return written, err
+	}
+	return written, file.Close()
+}
+
 // DoBytes performs an API request and returns the raw response bytes.
-// It returns the HTTP status code.
 func DoBytes(ctx context.Context, method, path string, query url.Values, body any, accept string) ([]byte, int, error) {
 	var bodyReader io.Reader
 	if body != nil {
@@ -133,24 +283,23 @@ func DoBytes(ctx context.Context, method, path string, query url.Values, body an
 	if err != nil {
 		return nil, 0, err
 	}
+
 	req, err := http.NewRequestWithContext(ctx, method, u, bodyReader)
 	if err != nil {
 		return nil, 0, fmt.Errorf("create request: %w", err)
 	}
-
 	token := tokenFromContext(ctx)
 	if token != "" {
-		req.Header.Set("Authorization", fmt.Sprintf("token %s", token))
-	}
-	if accept != "" {
-		req.Header.Set("Accept", accept)
+		req.Header.Set("Authorization", "token "+token)
 	}
 	if body != nil {
 		req.Header.Set("Content-Type", "application/json")
 	}
+	if accept != "" {
+		req.Header.Set("Accept", accept)
+	}
 
-	client := newRESTHTTPClient()
-	resp, err := client.Do(req)
+	resp, err := restHTTPClient().Do(req)
 	if err != nil {
 		return nil, 0, fmt.Errorf("do request: %w", err)
 	}
@@ -160,16 +309,12 @@ func DoBytes(ctx context.Context, method, path string, query url.Values, body an
 	if err != nil {
 		return nil, resp.StatusCode, fmt.Errorf("read response: %w", err)
 	}
-
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		bodySnippet := respBytes
-		if len(bodySnippet) > 8192 {
-			bodySnippet = bodySnippet[:8192]
+		if len(bodySnippet) > errBodySnippetSize {
+			bodySnippet = bodySnippet[:errBodySnippetSize]
 		}
 		return nil, resp.StatusCode, &HTTPError{StatusCode: resp.StatusCode, Body: strings.TrimSpace(string(bodySnippet))}
 	}
-
 	return respBytes, resp.StatusCode, nil
 }
-
-

pkg/gitea/rest_test.go

@@ -2,6 +2,11 @@ package gitea
 
 import (
 	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
 	"testing"
 
 	mcpContext "gitea.com/gitea/gitea-mcp/pkg/context"
@@ -29,4 +34,31 @@ func TestTokenFromContext(t *testing.T) {
 	})
 }
 
+func TestDoJSON_LimitsErrorResponseBody(t *testing.T) {
+	payload := strings.Repeat("x", errBodySnippetSize+100)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = io.WriteString(w, payload)
+	}))
+	defer srv.Close()
 
+	origHost := flag.Host
+	defer func() { flag.Host = origHost }()
+	flag.Host = srv.URL
+
+	status, err := DoJSON(context.Background(), http.MethodGet, "repos/owner/repo", nil, nil, nil)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if status != http.StatusBadRequest {
+		t.Fatalf("expected status %d, got %d", http.StatusBadRequest, status)
+	}
+
+	var httpErr *HTTPError
+	if !errors.As(err, &httpErr) {
+		t.Fatalf("expected HTTPError, got %T", err)
+	}
+	if len(httpErr.Body) != errBodySnippetSize {
+		t.Fatalf("expected body length %d, got %d", errBodySnippetSize, len(httpErr.Body))
+	}
+}

pkg/log/log.go

@@ -1,13 +1,15 @@
 package log
 
 import (
-	"fmt"
+	"log/slog"
 	"os"
 	"sync"
 	"time"
 
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
 	"go.uber.org/zap"
+	"go.uber.org/zap/exp/zapslog"
 	"go.uber.org/zap/zapcore"
 	"gopkg.in/natefinch/lumberjack.v2"
 )
@@ -35,14 +37,14 @@ func Default() *zap.Logger {
 			home = os.TempDir()
 		}
 
-		logDir := fmt.Sprintf("%s/.gitea-mcp", home)
+		logDir := home + "/.gitea-mcp"
 		if err := os.MkdirAll(logDir, 0o700); err != nil {
 			// Fallback to temp directory if creation fails
 			logDir = os.TempDir()
 		}
 
 		wss = append(wss, zapcore.AddSync(&lumberjack.Logger{
-			Filename:   fmt.Sprintf("%s/gitea-mcp.log", logDir),
+			Filename:   logDir + "/gitea-mcp.log",
 			MaxSize:    100,
 			MaxBackups: 10,
 			MaxAge:     30,
@@ -79,22 +81,11 @@ func SetDefault(logger *zap.Logger) {
 	}
 }
 
-func New() *Logger {
-	return &Logger{
-		defaultLogger: Default(),
-	}
-}
-
-type Logger struct {
-	defaultLogger *zap.Logger
-}
-
-func (l *Logger) Infof(msg string, args ...any) {
-	l.defaultLogger.Sugar().Infof(msg, args...)
-}
-
-func (l *Logger) Errorf(msg string, args ...any) {
-	l.defaultLogger.Sugar().Errorf(msg, args...)
+// Slog returns a *slog.Logger that writes through the default zap logger,
+// so structured logging from dependencies (e.g. the MCP HTTP transport) shares
+// the same destination and formatting as the rest of the server.
+func Slog() *slog.Logger {
+	return slog.New(zapslog.NewHandler(Default().Core()))
 }
 
 func Debug(msg string, fields ...zap.Field) {

pkg/params/params.go

@@ -0,0 +1,156 @@
+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. Empty strings are treated as missing.
+func GetString(args map[string]any, key string) (string, error) {
+	val, ok := args[key].(string)
+	if !ok || val == "" {
+		return "", fmt.Errorf("%s is required", key)
+	}
+	return val, nil
+}
+
+func GetOptionalString(args map[string]any, key, defaultVal string) string {
+	if val, ok := args[key].(string); ok {
+		return val
+	}
+	return defaultVal
+}
+
+func GetStringSlice(args map[string]any, key string) []string {
+	val, ok := args[key]
+	if !ok {
+		return nil
+	}
+	sliceVal, ok := val.([]any)
+	if !ok {
+		return nil
+	}
+	out := make([]string, 0, len(sliceVal))
+	for _, item := range sliceVal {
+		if s, ok := item.(string); ok {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+func GetPagination(args map[string]any, defaultPageSize int64) (page, pageSize int) {
+	return int(GetOptionalInt(args, "page", 1)), int(GetOptionalInt(args, "per_page", defaultPageSize))
+}
+
+// ToInt64 accepts float64 (JSON number) and string representations.
+func ToInt64(val any) (int64, bool) {
+	switch v := val.(type) {
+	case float64:
+		return int64(v), true
+	case string:
+		i, err := strconv.ParseInt(v, 10, 64)
+		if err != nil {
+			return 0, false
+		}
+		return i, true
+	default:
+		return 0, false
+	}
+}
+
+// GetIndex extracts a required integer. Accepts numeric or string forms — LLM callers
+// often pass identifiers like issue/PR numbers as strings.
+func GetIndex(args map[string]any, key string) (int64, error) {
+	val, exists := args[key]
+	if !exists {
+		return 0, fmt.Errorf("%s is required", key)
+	}
+
+	if i, ok := ToInt64(val); ok {
+		return i, nil
+	}
+
+	if s, ok := val.(string); ok {
+		return 0, fmt.Errorf("%s must be a valid integer (got %q)", key, s)
+	}
+
+	return 0, fmt.Errorf("%s must be a number or numeric string", key)
+}
+
+func GetInt64Slice(args map[string]any, key string) ([]int64, error) {
+	raw, ok := args[key].([]any)
+	if !ok {
+		return nil, fmt.Errorf("%s (array of IDs) is required", key)
+	}
+	out := make([]int64, 0, len(raw))
+	for _, v := range raw {
+		id, ok := ToInt64(v)
+		if !ok {
+			return nil, fmt.Errorf("invalid ID in %s array", key)
+		}
+		out = append(out, id)
+	}
+	return out, nil
+}
+
+// GetOptionalTime parses RFC3339, 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
+}
+
+func GetOptionalInt(args map[string]any, key string, defaultVal int64) int64 {
+	val, exists := args[key]
+	if !exists {
+		return defaultVal
+	}
+	if i, ok := ToInt64(val); ok {
+		return i
+	}
+	return defaultVal
+}
+
+// GetOptionalBoolPtr is for SDK fields where nil/false/true are distinct (e.g. "no change" vs "set to false").
+func GetOptionalBoolPtr(args map[string]any, key string) *bool {
+	if v, ok := args[key].(bool); ok {
+		return &v
+	}
+	return nil
+}
+
+// GetOptionalStringPtr returns nil when the key is missing OR the value is an empty string.
+// Use this for create/fork-style fields where "" is meaningless (e.g. fork target name).
+func GetOptionalStringPtr(args map[string]any, key string) *string {
+	if v, ok := args[key].(string); ok && v != "" {
+		return &v
+	}
+	return nil
+}
+
+// GetPresentStringPtr returns &v whenever the key is present as a string, including "".
+// Use this for PATCH-style fields where the SDK distinguishes "no change" (nil) from
+// "set to empty" (&""), e.g. clearing an issue body or label description.
+func GetPresentStringPtr(args map[string]any, key string) *string {
+	if v, ok := args[key].(string); ok {
+		return &v
+	}
+	return nil
+}

pkg/params/params_test.go

@@ -0,0 +1,208 @@
+package params
+
+import (
+	"strings"
+	"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
+		val  any
+		want int64
+		ok   bool
+	}{
+		{"float64", float64(42), 42, true},
+		{"float64 zero", float64(0), 0, true},
+		{"float64 negative", float64(-5), -5, true},
+		{"string", "123", 123, true},
+		{"string zero", "0", 0, true},
+		{"string negative", "-10", -10, true},
+		{"invalid string", "abc", 0, false},
+		{"decimal string", "1.5", 0, false},
+		{"bool", true, 0, false},
+		{"nil", nil, 0, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := ToInt64(tt.val)
+			if ok != tt.ok {
+				t.Errorf("ToInt64() ok = %v, want %v", ok, tt.ok)
+			}
+			if got != tt.want {
+				t.Errorf("ToInt64() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestGetOptionalInt(t *testing.T) {
+	tests := []struct {
+		name       string
+		args       map[string]any
+		key        string
+		defaultVal int64
+		want       int64
+	}{
+		{"present float64", map[string]any{"page": float64(3)}, "page", 1, 3},
+		{"present string", map[string]any{"page": "5"}, "page", 1, 5},
+		{"missing key", map[string]any{}, "page", 1, 1},
+		{"invalid string", map[string]any{"page": "abc"}, "page", 1, 1},
+		{"invalid type", map[string]any{"page": true}, "page", 1, 1},
+		{"zero value", map[string]any{"id": float64(0)}, "id", 99, 0},
+		{"string zero", map[string]any{"id": "0"}, "id", 99, 0},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := GetOptionalInt(tt.args, tt.key, tt.defaultVal)
+			if got != tt.want {
+				t.Errorf("GetOptionalInt() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestGetOptionalStringPtr(t *testing.T) {
+	if p := GetOptionalStringPtr(map[string]any{}, "k"); p != nil {
+		t.Errorf("missing key: got %v, want nil", p)
+	}
+	if p := GetOptionalStringPtr(map[string]any{"k": ""}, "k"); p != nil {
+		t.Errorf("empty string: got %v, want nil", p)
+	}
+	if p := GetOptionalStringPtr(map[string]any{"k": 42}, "k"); p != nil {
+		t.Errorf("non-string: got %v, want nil", p)
+	}
+	if p := GetOptionalStringPtr(map[string]any{"k": nil}, "k"); p != nil {
+		t.Errorf("nil value (JSON null): got %v, want nil", p)
+	}
+	if p := GetOptionalStringPtr(map[string]any{"k": "x"}, "k"); p == nil || *p != "x" {
+		t.Errorf("non-empty: got %v, want &\"x\"", p)
+	}
+}
+
+func TestGetPresentStringPtr(t *testing.T) {
+	if p := GetPresentStringPtr(map[string]any{}, "k"); p != nil {
+		t.Errorf("missing key: got %v, want nil", p)
+	}
+	if p := GetPresentStringPtr(map[string]any{"k": 42}, "k"); p != nil {
+		t.Errorf("non-string: got %v, want nil", p)
+	}
+	if p := GetPresentStringPtr(map[string]any{"k": nil}, "k"); p != nil {
+		t.Errorf("nil value (JSON null): got %v, want nil", p)
+	}
+	if p := GetPresentStringPtr(map[string]any{"k": ""}, "k"); p == nil || *p != "" {
+		t.Errorf("empty string: got %v, want &\"\"", p)
+	}
+	if p := GetPresentStringPtr(map[string]any{"k": "x"}, "k"); p == nil || *p != "x" {
+		t.Errorf("non-empty: got %v, want &\"x\"", p)
+	}
+}
+
+func TestGetIndex(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      map[string]any
+		key       string
+		wantIndex int64
+		wantErr   bool
+		errMsg    string
+	}{
+		{
+			name:      "valid float64",
+			args:      map[string]any{"index": float64(123)},
+			key:       "index",
+			wantIndex: 123,
+			wantErr:   false,
+		},
+		{
+			name:      "valid string",
+			args:      map[string]any{"index": "456"},
+			key:       "index",
+			wantIndex: 456,
+			wantErr:   false,
+		},
+		{
+			name:      "valid string with large number",
+			args:      map[string]any{"index": "999999"},
+			key:       "index",
+			wantIndex: 999999,
+			wantErr:   false,
+		},
+		{
+			name:    "missing parameter",
+			args:    map[string]any{},
+			key:     "index",
+			wantErr: true,
+			errMsg:  "index is required",
+		},
+		{
+			name:    "invalid string (not a number)",
+			args:    map[string]any{"index": "abc"},
+			key:     "index",
+			wantErr: true,
+			errMsg:  "must be a valid integer",
+		},
+		{
+			name:    "invalid string (decimal)",
+			args:    map[string]any{"index": "12.34"},
+			key:     "index",
+			wantErr: true,
+			errMsg:  "must be a valid integer",
+		},
+		{
+			name:    "invalid type (bool)",
+			args:    map[string]any{"index": true},
+			key:     "index",
+			wantErr: true,
+			errMsg:  "must be a number or numeric string",
+		},
+		{
+			name:    "invalid type (map)",
+			args:    map[string]any{"index": map[string]string{"foo": "bar"}},
+			key:     "index",
+			wantErr: true,
+			errMsg:  "must be a number or numeric string",
+		},
+		{
+			name:      "custom key name",
+			args:      map[string]any{"pr_index": "789"},
+			key:       "pr_index",
+			wantIndex: 789,
+			wantErr:   false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotIndex, err := GetIndex(tt.args, tt.key)
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("GetIndex() expected error but got nil")
+					return
+				}
+				if tt.errMsg != "" && !strings.Contains(err.Error(), tt.errMsg) {
+					t.Errorf("GetIndex() error = %v, want error containing %q", err, tt.errMsg)
+				}
+				return
+			}
+			if err != nil {
+				t.Errorf("GetIndex() unexpected error = %v", err)
+				return
+			}
+			if gotIndex != tt.wantIndex {
+				t.Errorf("GetIndex() = %v, want %v", gotIndex, tt.wantIndex)
+			}
+		})
+	}
+}

pkg/ptr/ptr.go

@@ -1,73 +0,0 @@
-/*
-Copyright 2023 The Kubernetes Authors.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-package ptr
-
-import (
-	"fmt"
-	"reflect"
-)
-
-// AllPtrFieldsNil tests whether all pointer fields in a struct are nil.  This is useful when,
-// for example, an API struct is handled by plugins which need to distinguish
-// "no plugin accepted this spec" from "this spec is empty".
-//
-// This function is only valid for structs and pointers to structs.  Any other
-// type will cause a panic.  Passing a typed nil pointer will return true.
-func AllPtrFieldsNil(obj interface{}) bool {
-	v := reflect.ValueOf(obj)
-	if !v.IsValid() {
-		panic(fmt.Sprintf("reflect.ValueOf() produced a non-valid Value for %#v", obj))
-	}
-	if v.Kind() == reflect.Ptr {
-		if v.IsNil() {
-			return true
-		}
-		v = v.Elem()
-	}
-	for i := 0; i < v.NumField(); i++ {
-		if v.Field(i).Kind() == reflect.Ptr && !v.Field(i).IsNil() {
-			return false
-		}
-	}
-	return true
-}
-
-// To returns a pointer to the given value.
-func To[T any](v T) *T {
-	return &v
-}
-
-// Deref dereferences ptr and returns the value it points to if no nil, or else
-// returns def.
-func Deref[T any](ptr *T, def T) T {
-	if ptr != nil {
-		return *ptr
-	}
-	return def
-}
-
-// Equal returns true if both arguments are nil or both arguments
-// dereference to the same value.
-func Equal[T comparable](a, b *T) bool {
-	if (a == nil) != (b == nil) {
-		return false
-	}
-	if a == nil {
-		return true
-	}
-	return *a == *b
-}

pkg/slim/slim.go

@@ -0,0 +1,135 @@
+package slim
+
+import (
+	"fmt"
+	"strings"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func UserLogin(u *gitea_sdk.User) string {
+	if u == nil {
+		return ""
+	}
+	return u.UserName
+}
+
+func UserLogins(users []*gitea_sdk.User) []string {
+	if len(users) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(users))
+	for _, u := range users {
+		if u != nil {
+			out = append(out, u.UserName)
+		}
+	}
+	return out
+}
+
+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 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 UserDetail(u *gitea_sdk.User) map[string]any {
+	if u == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":         u.ID,
+		"login":      u.UserName,
+		"full_name":  u.FullName,
+		"email":      u.Email,
+		"avatar_url": u.AvatarURL,
+		"html_url":   u.HTMLURL,
+		"is_admin":   u.IsAdmin,
+	}
+}
+
+func Repo(r *gitea_sdk.Repository) map[string]any {
+	if r == nil {
+		return nil
+	}
+	m := map[string]any{
+		"id":                r.ID,
+		"full_name":         r.FullName,
+		"description":       r.Description,
+		"html_url":          r.HTMLURL,
+		"clone_url":         r.CloneURL,
+		"ssh_url":           r.SSHURL,
+		"default_branch":    r.DefaultBranch,
+		"private":           r.Private,
+		"fork":              r.Fork,
+		"archived":          r.Archived,
+		"language":          r.Language,
+		"stars_count":       r.Stars,
+		"forks_count":       r.Forks,
+		"open_issues_count": r.OpenIssues,
+		"open_pr_counter":   r.OpenPulls,
+		"created_at":        r.Created,
+		"updated_at":        r.Updated,
+	}
+	if r.Owner != nil {
+		m["owner"] = r.Owner.UserName
+	}
+	if len(r.Topics) > 0 {
+		m["topics"] = r.Topics
+	}
+	return m
+}
+
+func Repos(repos []*gitea_sdk.Repository) []map[string]any {
+	out := make([]map[string]any, 0, len(repos))
+	for _, r := range repos {
+		out = append(out, Repo(r))
+	}
+	return out
+}
+
+func Label(l *gitea_sdk.Label) map[string]any {
+	if l == nil {
+		return nil
+	}
+	return map[string]any{
+		"id":          l.ID,
+		"name":        l.Name,
+		"color":       l.Color,
+		"description": l.Description,
+		"exclusive":   l.Exclusive,
+	}
+}
+
+func Labels(labels []*gitea_sdk.Label) []map[string]any {
+	out := make([]map[string]any, 0, len(labels))
+	for _, l := range labels {
+		out = append(out, Label(l))
+	}
+	return out
+}

pkg/slim/slim_test.go

@@ -0,0 +1,110 @@
+package slim
+
+import (
+	"testing"
+
+	gitea_sdk "gitea.dev/sdk"
+)
+
+func TestUserDetail(t *testing.T) {
+	u := &gitea_sdk.User{
+		ID:        42,
+		UserName:  "alice",
+		FullName:  "Alice Smith",
+		Email:     "alice@example.com",
+		AvatarURL: "https://gitea.com/avatars/42",
+		HTMLURL:   "https://gitea.com/alice",
+		IsAdmin:   true,
+	}
+	m := UserDetail(u)
+
+	if m["id"] != int64(42) {
+		t.Errorf("expected id 42, got %v", m["id"])
+	}
+	if m["login"] != "alice" {
+		t.Errorf("expected login alice, got %v", m["login"])
+	}
+	if m["full_name"] != "Alice Smith" {
+		t.Errorf("expected full_name Alice Smith, got %v", m["full_name"])
+	}
+	if m["is_admin"] != true {
+		t.Errorf("expected is_admin true, got %v", m["is_admin"])
+	}
+}
+
+func TestUserDetail_Nil(t *testing.T) {
+	if m := UserDetail(nil); m != nil {
+		t.Errorf("expected nil for nil user, got %v", m)
+	}
+}
+
+func TestLabel(t *testing.T) {
+	l := &gitea_sdk.Label{
+		ID:          1,
+		Name:        "bug",
+		Color:       "#d73a4a",
+		Description: "Something isn't working",
+		Exclusive:   false,
+	}
+
+	m := Label(l)
+	if m["name"] != "bug" {
+		t.Errorf("expected name bug, got %v", m["name"])
+	}
+	if m["color"] != "#d73a4a" {
+		t.Errorf("expected color, got %v", m["color"])
+	}
+}
+
+func TestRepo(t *testing.T) {
+	r := &gitea_sdk.Repository{
+		ID:            1,
+		FullName:      "org/repo",
+		Description:   "A test repo",
+		HTMLURL:       "https://gitea.com/org/repo",
+		CloneURL:      "https://gitea.com/org/repo.git",
+		SSHURL:        "git@gitea.com:org/repo.git",
+		DefaultBranch: "main",
+		Language:      "Go",
+		Stars:         10,
+		Forks:         2,
+		Owner:         &gitea_sdk.User{UserName: "org"},
+		Topics:        []string{"mcp", "gitea"},
+	}
+
+	m := Repo(r)
+
+	if m["full_name"] != "org/repo" {
+		t.Errorf("expected full_name org/repo, got %v", m["full_name"])
+	}
+	if m["owner"] != "org" {
+		t.Errorf("expected owner org, got %v", m["owner"])
+	}
+	topics := m["topics"].([]string)
+	if len(topics) != 2 {
+		t.Errorf("expected 2 topics, got %d", len(topics))
+	}
+}
+
+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)
+	}
+}

pkg/to/to.go

@@ -4,25 +4,26 @@ import (
 	"encoding/json"
 	"fmt"
 
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
 	"gitea.com/gitea/gitea-mcp/pkg/log"
-	"github.com/mark3labs/mcp-go/mcp"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-type textResult struct {
-	Result any
-}
-
 func TextResult(v any) (*mcp.CallToolResult, error) {
-	result := textResult{v}
-	resultBytes, err := json.Marshal(result)
+	resultBytes, err := json.Marshal(v)
 	if err != nil {
 		return nil, fmt.Errorf("marshal result err: %v", err)
 	}
+	if flag.Debug {
 		log.Debugf("Text Result: %s", string(resultBytes))
-	return mcp.NewToolResultText(string(resultBytes)), nil
+	}
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{&mcp.TextContent{Text: string(resultBytes)}},
+	}, nil
 }
 
 func ErrorResult(err error) (*mcp.CallToolResult, error) {
-	log.Errorf(err.Error())
+	log.Errorf("%s", err.Error())
 	return nil, err
 }

pkg/to/to_test.go

@@ -0,0 +1,33 @@
+package to
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestTextResult(t *testing.T) {
+	result, err := TextResult(map[string]any{"name": "gitea"})
+	if err != nil {
+		t.Fatalf("TextResult() error = %v", err)
+	}
+	if len(result.Content) != 1 {
+		t.Fatalf("len(Content) = %d, want 1", len(result.Content))
+	}
+	content, ok := result.Content[0].(*mcp.TextContent)
+	if !ok {
+		t.Fatalf("Content[0] type = %T, want *mcp.TextContent", result.Content[0])
+	}
+	if content.Text != `{"name":"gitea"}` {
+		t.Errorf("Text = %q, want JSON object", content.Text)
+	}
+}
+
+func TestErrorResult(t *testing.T) {
+	want := errors.New("failed")
+	result, err := ErrorResult(want)
+	if result != nil || !errors.Is(err, want) {
+		t.Errorf("ErrorResult() = (%#v, %v), want (nil, %v)", result, err, want)
+	}
+}

pkg/tool/definition.go

@@ -0,0 +1,106 @@
+package tool
+
+import "github.com/modelcontextprotocol/go-sdk/mcp"
+
+// Property describes one property in a tool's input schema.
+type Property struct {
+	name     string
+	schema   map[string]any
+	required bool
+}
+
+// PropertyOption configures one property in a tool's input schema.
+type PropertyOption func(*Property)
+
+// NewDefinition builds a tool definition without enabling SDK-side validation.
+func NewDefinition(name, description string, annotations *mcp.ToolAnnotations, properties ...Property) *mcp.Tool {
+	inputProperties := make(map[string]any, len(properties))
+	required := make([]string, 0, len(properties))
+	for _, property := range properties {
+		inputProperties[property.name] = property.schema
+		if property.required {
+			required = append(required, property.name)
+		}
+	}
+
+	inputSchema := map[string]any{
+		"type":       "object",
+		"properties": inputProperties,
+	}
+	if len(required) > 0 {
+		inputSchema["required"] = required
+	}
+
+	return &mcp.Tool{
+		Name:        name,
+		Description: description,
+		Annotations: annotations,
+		InputSchema: inputSchema,
+	}
+}
+
+func String(name string, options ...PropertyOption) Property {
+	return newProperty(name, map[string]any{"type": "string"}, options...)
+}
+
+func Number(name string, options ...PropertyOption) Property {
+	return newProperty(name, map[string]any{"type": "number"}, options...)
+}
+
+func Boolean(name string, options ...PropertyOption) Property {
+	return newProperty(name, map[string]any{"type": "boolean"}, options...)
+}
+
+func Array(name string, options ...PropertyOption) Property {
+	return newProperty(name, map[string]any{"type": "array"}, options...)
+}
+
+func Object(name string, options ...PropertyOption) Property {
+	return newProperty(name, map[string]any{"type": "object", "properties": map[string]any{}}, options...)
+}
+
+func newProperty(name string, schema map[string]any, options ...PropertyOption) Property {
+	property := Property{name: name, schema: schema}
+	for _, option := range options {
+		option(&property)
+	}
+	return property
+}
+
+// Required marks the property as required on the parent schema. It is not a
+// property-level keyword, so it never touches the emitted property schema.
+func Required() PropertyOption {
+	return func(property *Property) {
+		property.required = true
+	}
+}
+
+func Description(description string) PropertyOption {
+	return func(property *Property) {
+		property.schema["description"] = description
+	}
+}
+
+func Enum(values ...string) PropertyOption {
+	return func(property *Property) {
+		property.schema["enum"] = values
+	}
+}
+
+func Default(value any) PropertyOption {
+	return func(property *Property) {
+		property.schema["default"] = value
+	}
+}
+
+func Minimum(value float64) PropertyOption {
+	return func(property *Property) {
+		property.schema["minimum"] = value
+	}
+}
+
+func Items(schema any) PropertyOption {
+	return func(property *Property) {
+		property.schema["items"] = schema
+	}
+}

pkg/tool/definition_test.go

@@ -0,0 +1,71 @@
+package tool
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestNewDefinition(t *testing.T) {
+	annotations := &mcp.ToolAnnotations{Title: "Example", ReadOnlyHint: true}
+	definition := NewDefinition(
+		"example",
+		"Example tool",
+		annotations,
+		String("owner", Required(), Description("repository owner"), Enum("one", "two"), Default("one")),
+		Number("page", Required(), Default(1), Minimum(1)),
+		Boolean("draft"),
+		Array("labels", Items(map[string]any{"type": "string"})),
+		Object("inputs", Description("workflow inputs")),
+	)
+
+	if definition.Name != "example" || definition.Description != "Example tool" {
+		t.Fatalf("definition = %#v", definition)
+	}
+	if definition.Annotations != annotations {
+		t.Fatal("NewDefinition did not preserve annotations")
+	}
+
+	want := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"owner": map[string]any{
+				"type":        "string",
+				"description": "repository owner",
+				"enum":        []string{"one", "two"},
+				"default":     "one",
+			},
+			"page": map[string]any{
+				"type":    "number",
+				"default": 1,
+				"minimum": float64(1),
+			},
+			"draft": map[string]any{"type": "boolean"},
+			"labels": map[string]any{
+				"type":  "array",
+				"items": map[string]any{"type": "string"},
+			},
+			"inputs": map[string]any{
+				"type":        "object",
+				"properties":  map[string]any{},
+				"description": "workflow inputs",
+			},
+		},
+		"required": []string{"owner", "page"},
+	}
+	if !reflect.DeepEqual(definition.InputSchema, want) {
+		t.Errorf("InputSchema = %#v, want %#v", definition.InputSchema, want)
+	}
+}
+
+func TestNewDefinitionWithoutRequiredProperties(t *testing.T) {
+	definition := NewDefinition("empty", "", nil)
+	schema := definition.InputSchema.(map[string]any)
+	if _, ok := schema["required"]; ok {
+		t.Errorf("InputSchema unexpectedly contains required: %#v", schema)
+	}
+	if got := schema["properties"]; !reflect.DeepEqual(got, map[string]any{}) {
+		t.Errorf("properties = %#v, want empty map", got)
+	}
+}

pkg/tool/handler_test.go

@@ -0,0 +1,105 @@
+package tool
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/jsonrpc"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func callTool(handler Handler, arguments json.RawMessage) (*mcp.CallToolResult, error) {
+	serverTool := ServerTool{Tool: &mcp.Tool{Name: "example"}, Handler: handler}
+	return serverTool.MCPHandler()(context.Background(), &mcp.CallToolRequest{
+		Params: &mcp.CallToolParamsRaw{Arguments: arguments},
+	})
+}
+
+func captureArguments(into *map[string]any) Handler {
+	return func(_ context.Context, arguments map[string]any) (*mcp.CallToolResult, error) {
+		*into = arguments
+		return &mcp.CallToolResult{}, nil
+	}
+}
+
+func TestMCPHandler(t *testing.T) {
+	var got map[string]any
+	result, err := callTool(captureArguments(&got), json.RawMessage(`{"count":2,"nested":{"enabled":true}}`))
+	if err != nil {
+		t.Fatalf("MCPHandler() error = %v", err)
+	}
+	if result == nil {
+		t.Fatal("MCPHandler() result is nil")
+	}
+	if got["count"] != float64(2) {
+		t.Errorf("count type/value = %T(%v), want float64(2)", got["count"], got["count"])
+	}
+}
+
+func TestMCPHandlerRejectsInvalidArguments(t *testing.T) {
+	called := false
+	handler := func(context.Context, map[string]any) (*mcp.CallToolResult, error) {
+		called = true
+		return &mcp.CallToolResult{}, nil
+	}
+
+	for _, arguments := range []json.RawMessage{json.RawMessage(`[]`), json.RawMessage(`"text"`), json.RawMessage(`{"broken"`)} {
+		_, err := callTool(handler, arguments)
+		assertProtocolErrorCode(t, err, jsonrpc.CodeInvalidParams)
+	}
+	if called {
+		t.Fatal("handler was called with invalid arguments")
+	}
+}
+
+// Tools without parameters are callable with an omitted or null "arguments",
+// which is what clients send and what mcp-go accepted before the SDK migration.
+func TestMCPHandlerAcceptsAbsentArguments(t *testing.T) {
+	for _, arguments := range []json.RawMessage{nil, json.RawMessage(`null`)} {
+		var got map[string]any
+		if _, err := callTool(captureArguments(&got), arguments); err != nil {
+			t.Fatalf("MCPHandler() with arguments %s error = %v", arguments, err)
+		}
+		if got == nil || len(got) != 0 {
+			t.Errorf("arguments = %#v, want an empty map", got)
+		}
+	}
+}
+
+func TestMCPHandlerConvertsErrorsAndRecoversPanics(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		handler Handler
+	}{
+		{
+			name: "handler error",
+			handler: func(context.Context, map[string]any) (*mcp.CallToolResult, error) {
+				return nil, errors.New("failed")
+			},
+		},
+		{
+			name: "panic",
+			handler: func(context.Context, map[string]any) (*mcp.CallToolResult, error) {
+				panic("failed")
+			},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := callTool(test.handler, nil)
+			assertProtocolErrorCode(t, err, jsonrpc.CodeInternalError)
+		})
+	}
+}
+
+func assertProtocolErrorCode(t *testing.T, err error, want int64) {
+	t.Helper()
+	var protocolErr *jsonrpc.Error
+	if !errors.As(err, &protocolErr) {
+		t.Fatalf("error = %v, want *jsonrpc.Error", err)
+	}
+	if protocolErr.Code != want {
+		t.Errorf("error code = %d, want %d", protocolErr.Code, want)
+	}
+}

pkg/tool/tool.go

@@ -1,37 +1,192 @@
 package tool
 
 import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"slices"
+	"strings"
+
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
-	"github.com/mark3labs/mcp-go/server"
+	"gitea.com/gitea/gitea-mcp/pkg/log"
+
+	"github.com/modelcontextprotocol/go-sdk/jsonrpc"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-type Tool struct {
-	write []server.ServerTool
-	read  []server.ServerTool
+type Handler func(context.Context, map[string]any) (*mcp.CallToolResult, error)
+
+type ServerTool struct {
+	Tool    *mcp.Tool
+	Handler Handler
 }
 
-func New() *Tool {
+type Tool struct {
+	scope string
+	write []ServerTool
+	read  []ServerTool
+}
+
+func New(scope string) *Tool {
 	return &Tool{
-		write: make([]server.ServerTool, 0, 100),
-		read:  make([]server.ServerTool, 0, 100),
+		scope: scope,
+		write: make([]ServerTool, 0, 100),
+		read:  make([]ServerTool, 0, 100),
 	}
 }
 
-func (t *Tool) RegisterWrite(s server.ServerTool) {
+// Scope returns the canonical scope name this domain of tools was registered under.
+func (t *Tool) Scope() string {
+	return t.scope
+}
+
+func (t *Tool) RegisterWrite(s ServerTool) {
 	t.write = append(t.write, s)
 }
 
-func (t *Tool) RegisterRead(s server.ServerTool) {
+func (t *Tool) RegisterRead(s ServerTool) {
 	t.read = append(t.read, s)
 }
 
-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
-	}
-	tools = append(tools, t.write...)
-	tools = append(tools, t.read...)
-	return tools
+// ReadTools returns the read-only tools registered on this domain, ignoring
+// the read-only and allowlist flags that Tools applies.
+func (t *Tool) ReadTools() []ServerTool {
+	return t.read
+}
+
+// WriteTools returns the write tools registered on this domain, ignoring the
+// read-only and allowlist flags that Tools applies.
+func (t *Tool) WriteTools() []ServerTool {
+	return t.write
+}
+
+// Tools returns the tools registered on this domain after applying the
+// read-only filter and the scope/tool allowlists (union semantics: a tool is
+// kept if its domain's scope is in AllowedScopes OR its name is in
+// AllowedTools). With no allowlists set, all tools pass through unchanged.
+func (t *Tool) Tools() []ServerTool {
+	all := make([]ServerTool, 0, len(t.write)+len(t.read))
+	if !flag.ReadOnly {
+		all = append(all, t.write...)
+	}
+	all = append(all, t.read...)
+	if len(flag.AllowedScopes) == 0 && len(flag.AllowedTools) == 0 {
+		return all
+	}
+	_, scopeAllowed := flag.AllowedScopes[t.scope]
+	filtered := make([]ServerTool, 0, len(all))
+	for _, st := range all {
+		_, toolAllowed := flag.AllowedTools[st.Tool.Name]
+		if scopeAllowed || toolAllowed {
+			filtered = append(filtered, st)
+		}
+	}
+	return filtered
+}
+
+// MCPHandler adapts a project handler to the official SDK's low-level handler.
+func (s ServerTool) MCPHandler() mcp.ToolHandler {
+	return func(ctx context.Context, req *mcp.CallToolRequest) (result *mcp.CallToolResult, err error) {
+		defer func() {
+			if recovered := recover(); recovered != nil {
+				panicErr := fmt.Errorf("panic recovered in %s tool handler: %v", s.Tool.Name, recovered)
+				log.Errorf("%s", panicErr)
+				err = internalError(panicErr)
+			}
+		}()
+
+		arguments, err := decodeArguments(req.Params.Arguments)
+		if err != nil {
+			return nil, err
+		}
+
+		result, err = s.Handler(ctx, arguments)
+		if err != nil {
+			var protocolErr *jsonrpc.Error
+			if errors.As(err, &protocolErr) {
+				return nil, err
+			}
+			// Preserve mcp-go behavior; tool-result errors are a separate change.
+			return nil, internalError(err)
+		}
+		return result, nil
+	}
+}
+
+func decodeArguments(raw json.RawMessage) (map[string]any, error) {
+	// An omitted and a null "arguments" both mean the tool was called without any.
+	if len(raw) == 0 || string(raw) == "null" {
+		return map[string]any{}, nil
+	}
+
+	var arguments map[string]any
+	if err := json.Unmarshal(raw, &arguments); err != nil {
+		return nil, &jsonrpc.Error{
+			Code:    jsonrpc.CodeInvalidParams,
+			Message: fmt.Sprintf("invalid tool arguments: %v", err),
+		}
+	}
+	return arguments, nil
+}
+
+func internalError(err error) error {
+	return &jsonrpc.Error{Code: jsonrpc.CodeInternalError, Message: err.Error()}
+}
+
+// warnUnmatched logs the names present in allowlist but absent from known,
+// via logUnmatched, so WarnUnmatchedAllowedTools and WarnUnmatchedAllowedScopes
+// share the same "collect, sort, no-op when empty" logic and can't drift.
+// No-op if allowlist is empty or every name in it is known.
+func warnUnmatched(allowlist, known map[string]struct{}, logUnmatched func(unmatched []string)) {
+	if len(allowlist) == 0 {
+		return
+	}
+	var unmatched []string
+	for name := range allowlist {
+		if _, ok := known[name]; !ok {
+			unmatched = append(unmatched, name)
+		}
+	}
+	if len(unmatched) == 0 {
+		return
+	}
+	slices.Sort(unmatched)
+	logUnmatched(unmatched)
+}
+
+// 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) {
+	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{}{}
+		}
+	}
+	warnUnmatched(flag.AllowedTools, known, func(unmatched []string) {
+		log.Warnf("Unknown tools in --tools allowlist (ignored): %s", strings.Join(unmatched, ", "))
+	})
+}
+
+// WarnUnmatchedAllowedScopes logs any names in flag.AllowedScopes that don't
+// match the scope of any of the given domains. No-op if the allowlist is
+// empty.
+func WarnUnmatchedAllowedScopes(domains ...*Tool) {
+	knownSet := map[string]struct{}{}
+	known := make([]string, 0, len(domains))
+	for _, d := range domains {
+		if _, ok := knownSet[d.scope]; !ok {
+			knownSet[d.scope] = struct{}{}
+			known = append(known, d.scope)
+		}
+	}
+	warnUnmatched(flag.AllowedScopes, knownSet, func(unmatched []string) {
+		slices.Sort(known)
+		log.Warnf("Unknown scopes in --scope allowlist (ignored): %s. Valid scopes: %s", strings.Join(unmatched, ", "), strings.Join(known, ", "))
+	})
 }

pkg/tool/tool_test.go

@@ -0,0 +1,226 @@
+package tool
+
+import (
+	"slices"
+	"testing"
+
+	"gitea.com/gitea/gitea-mcp/pkg/flag"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func makeTool(name string) ServerTool {
+	return ServerTool{Tool: &mcp.Tool{Name: name}}
+}
+
+func names(sts []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("scope1")
+			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)
+			}
+		})
+	}
+}
+
+func TestToolsScopeFiltering(t *testing.T) {
+	tests := []struct {
+		name          string
+		toolScope     string
+		readOnly      bool
+		allowedScopes map[string]struct{}
+		allowedTools  map[string]struct{}
+		read          []string
+		write         []string
+		want          []string
+	}{
+		{
+			name:      "no scope or tool filters returns all",
+			toolScope: "repository",
+			read:      []string{"r1"},
+			write:     []string{"w1"},
+			want:      []string{"w1", "r1"},
+		},
+		{
+			name:          "matching scope keeps everything",
+			toolScope:     "repository",
+			allowedScopes: map[string]struct{}{"repository": {}},
+			read:          []string{"r1"},
+			write:         []string{"w1"},
+			want:          []string{"w1", "r1"},
+		},
+		{
+			name:          "non-matching scope drops everything not in allowed tools",
+			toolScope:     "repository",
+			allowedScopes: map[string]struct{}{"file": {}},
+			read:          []string{"r1"},
+			write:         []string{"w1"},
+			want:          []string{},
+		},
+		{
+			name:         "tools-only allowlist behaves as before scopes existed",
+			toolScope:    "repository",
+			allowedTools: map[string]struct{}{"r1": {}},
+			read:         []string{"r1", "r2"},
+			write:        []string{"w1"},
+			want:         []string{"r1"},
+		},
+		{
+			name:          "scope and tools allowlists are unioned",
+			toolScope:     "repository",
+			allowedScopes: map[string]struct{}{"file": {}},
+			allowedTools:  map[string]struct{}{"r1": {}},
+			read:          []string{"r1", "r2"},
+			write:         []string{"w1"},
+			want:          []string{"r1"},
+		},
+		{
+			name:          "matching scope combined with read-only drops write entries",
+			toolScope:     "repository",
+			readOnly:      true,
+			allowedScopes: map[string]struct{}{"repository": {}},
+			read:          []string{"r1"},
+			write:         []string{"w1"},
+			want:          []string{"r1"},
+		},
+		{
+			name:          "unknown scope name matches nothing",
+			toolScope:     "repository",
+			allowedScopes: map[string]struct{}{"unknown_scope": {}},
+			read:          []string{"r1"},
+			write:         []string{"w1"},
+			want:          []string{},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			origRO, origAllowScopes, origAllowTools := flag.ReadOnly, flag.AllowedScopes, flag.AllowedTools
+			t.Cleanup(func() {
+				flag.ReadOnly, flag.AllowedScopes, flag.AllowedTools = origRO, origAllowScopes, origAllowTools
+			})
+			flag.ReadOnly = tt.readOnly
+			flag.AllowedScopes = tt.allowedScopes
+			flag.AllowedTools = tt.allowedTools
+
+			tr := New(tt.toolScope)
+			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)
+			}
+		})
+	}
+}
+
+func TestScope(t *testing.T) {
+	tr := New("repository")
+	if got := tr.Scope(); got != "repository" {
+		t.Errorf("Scope() = %q, want %q", got, "repository")
+	}
+}
+
+func TestWarnUnmatchedAllowedScopes(t *testing.T) {
+	origAllowScopes := flag.AllowedScopes
+	t.Cleanup(func() {
+		flag.AllowedScopes = origAllowScopes
+	})
+
+	repoTool := New("repository")
+	fileTool := New("file")
+
+	t.Run("empty allowlist is a no-op", func(t *testing.T) {
+		flag.AllowedScopes = nil
+		WarnUnmatchedAllowedScopes(repoTool, fileTool)
+	})
+
+	t.Run("known scopes produce no warning", func(t *testing.T) {
+		flag.AllowedScopes = map[string]struct{}{"repository": {}, "file": {}}
+		WarnUnmatchedAllowedScopes(repoTool, fileTool)
+	})
+
+	t.Run("unknown scope is tolerated", func(t *testing.T) {
+		flag.AllowedScopes = map[string]struct{}{"not_a_real_scope": {}}
+		WarnUnmatchedAllowedScopes(repoTool, fileTool)
+	})
+}

renovate.json5

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "local>gitea/renovate-config"
+  ],
+}