diff --git a/AGENTS.md b/AGENTS.md index ea22894..af4a376 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,12 @@ - Use `make help` to find available development targets - Run `make fmt` to format `.go` files, and run `make lint-go` to lint them - Run `make tidy` after any `go.mod` changes +- Run single go tests with `go test -run '^TestName$' ./modulepath/` - Ensure no trailing whitespace in edited files -- Use Conventional Commits format for commit messages and PR titles (e.g. `type(scope): subject`) +- 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. - Never force-push, amend, or squash unless asked. Use new commits and normal push for pull request updates +- Preserve existing code comments, do not remove or rewrite comments that are still relevant +- Keep comments short, prefer same-line, explain why, never narrate code +- 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` - Include authorship attribution in issue and pull request comments - Add `Co-Authored-By` lines to all commits, indicating name and model used diff --git a/BUILDING.md b/BUILDING.md index 3b25276..08bdc3f 100644 --- a/BUILDING.md +++ b/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) diff --git a/CLAUDE.md b/CLAUDE.md index 9d4ffe6..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,78 +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 45 MCP tools covering: - -- **User**: get_me, get_user_orgs -- **Search**: search_users, search_repos, search_org_teams -- **Repository**: create_repo, fork_repo, list_my_repos -- **Branches**: list_branches, create_branch, delete_branch -- **Tags**: list_tags, get_tag, create_tag, delete_tag -- **Files**: get_file_contents, get_dir_contents, create_or_update_file, delete_file -- **Commits**: list_commits -- **Issues**: list_issues, issue_read, issue_write -- **Pull Requests**: list_pull_requests, pull_request_read, pull_request_write, pull_request_review_write -- **Labels**: label_read, label_write -- **Milestones**: milestone_read, milestone_write -- **Releases**: list_releases, get_release, get_latest_release, create_release, delete_release -- **Wiki**: wiki_read, wiki_write -- **Time Tracking**: timetracking_read, timetracking_write -- **Actions Runs**: actions_run_read, actions_run_write -- **Actions Config**: actions_config_read, actions_config_write -- **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 diff --git a/README.md b/README.md index 6cc2b92..392b6a5 100644 --- a/README.md +++ b/README.md @@ -2,58 +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) - - [Usage with Mistral Vibe](#usage-with-mistral-vibe) - - [📥 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? - -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. - -## What is MCP? - -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. - -## 🚧 Installation - -### Usage with OpenCode (opencode.ai) - -Add a snippet like the following in the "mcp" top-level object (add one if you don't have any): - -```json - "gitea-mcp": { - "enabled": true, - "type": "local", - "command": [ - "gitea-mcp", - "-t", "stdio", - "-H", "https://git.your-domain.org", - "-T", "" - ] - } +```bash +git clone https://gitea.com/gitea/gitea-mcp.git +cd gitea-mcp +make install ``` -### Usage with Claude Code +## Configuration -This method uses `go run` and requires [Go](https://go.dev) to be installed. +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. + +### Claude Code + +Runs the server through `go run` and requires [Go](https://go.dev): ```bash claude mcp add --transport stdio --scope user gitea \ @@ -62,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 { @@ -86,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}" } @@ -103,84 +59,50 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace } ``` -### Usage with Mistral Vibe +### OpenCode -Add the following configuration to your Mistral Vibe MCP configuration file (`~/.vibe/config.toml`): +Add the following to the top-level `mcp` object of your [OpenCode](https://opencode.ai) config: + +```json + "gitea-mcp": { + "enabled": true, + "type": "local", + "command": [ + "gitea-mcp", + "-t", "stdio", + "-H", "https://gitea.com", + "-T", "" + ] + } +``` + +### Mistral Vibe + +Add the following to `~/.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", -] +args = ["run", "--rm", "-i", "-e", "GITEA_ACCESS_TOKEN", "-e", "GITEA_HOST", "docker.gitea.com/gitea-mcp-server"] [mcp_servers.env] GITEA_ACCESS_TOKEN = "TOKEN" GITEA_HOST = "https://gitea.com" ``` -### 📥 Download the official binary release +### Other clients -You can download the official release from [official Gitea MCP binary releases](https://gitea.com/gitea/gitea-mcp/releases). - -### 🔧 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 -``` - -Before building, make sure you have the following installed: - -- make -- Golang (Go 1.24 or later recommended) - -Then run: - -```bash -make install -``` - -### 📁 Add to PATH - -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", "" - ], + "args": ["-t", "stdio", "--host", "https://gitea.com"], "env": { - // "GITEA_HOST": "https://gitea.com", - // "GITEA_INSECURE": "true", "GITEA_ACCESS_TOKEN": "" } } @@ -188,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 { @@ -203,133 +125,66 @@ 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 -> [!NOTE] -> Many tools support `page` and `perPage` parameters for pagination. The maximum effective page size is determined by the Gitea server's `[api].MAX_RESPONSE_ITEMS` setting (default: **50**). Requesting a `perPage` value higher than this limit will be silently capped by the server. +| 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 | +| 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, changed files, head commit status, reviews | +| 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 | +| 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 | -Once everything is set up, try typing the following in your MCP-compatible chatbox: +> **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 with `-O` / `--tools` (`GITEA_TOOLS`). -```text -list all my repositories -``` - -## ✅ 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 | -| merge_pull_request | Pull Request | Merge a pull request | -| 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 | Actions | Get a single Actions job's detail | -| 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 | -| list_repo_action_artifacts | Actions | List repository Actions artifacts | -| list_repo_action_run_artifacts | Actions | List Actions artifacts for a run | -| get_repo_action_artifact | Actions | Get a repository Actions artifact | -| download_repo_action_artifact | Actions | Download an Actions artifact zip 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 -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. diff --git a/README.zh-cn.md b/README.zh-cn.md index f9266ec..30e53b7 100644 --- a/README.zh-cn.md +++ b/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", "" + ] + } ``` -构建前请先安装： +### 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", "" - ], + "args": ["-t", "stdio", "--host", "https://gitea.com"], "env": { - // "GITEA_HOST": "https://gitea.com", - // "GITEA_INSECURE": "true", "GITEA_ACCESS_TOKEN": "" } } @@ -145,7 +110,7 @@ cp gitea-mcp /usr/local/bin/ } ``` -- **http 模式** +或使用 http 端点，对应以 `gitea-mcp -t http --port 8080` 启动的服务器： ```json { @@ -160,100 +125,66 @@ cp gitea-mcp /usr/local/bin/ } ``` -**默认日志路径**: `$HOME/.gitea-mcp/gitea-mcp.log` +配置完成后，可在聊天框输入 `列出我所有的仓库` 试试。 -> [!注意] -> 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。 -> 命令行参数优先。 +## 可用工具 -> [!注意] -> 许多工具支持 `page` 和 `perPage` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认值：**50**）。请求超过此限制的 `perPage` 值将被服务器静默截断。 +| 工具 | 范围 | 访问 | 描述 | +| :--------------------------- | :------- | :--- | :------------------------------------------------------------------- | +| get_gitea_mcp_server_version | 版本 | 读取 | 获取 Gitea MCP 服务器版本 | +| get_me | 用户 | 读取 | 获取当前已认证用户 | +| get_user_orgs | 用户 | 读取 | 列出当前用户的组织 | +| search_users | 搜索 | 读取 | 搜索用户 | +| search_org_teams | 搜索 | 读取 | 搜索组织中的团队 | +| search_repos | 搜索 | 读取 | 搜索仓库 | +| search_issues | 搜索 | 读取 | 跨仓库搜索问题和拉取请求 | +| notification_read | 通知 | 读取 | 读取通知：列出（可限定仓库）或按 ID 获取会话 | +| notification_write | 通知 | 写入 | 将某条或全部通知标记为已读 | +| label_read | 标签 | 读取 | 读取仓库或组织标签 | +| label_write | 标签 | 写入 | 写入标签（仓库或组织）：创建、编辑、删除 | +| milestone_read | 里程碑 | 读取 | 读取里程碑：获取单个或列出 | +| milestone_write | 里程碑 | 写入 | 写入里程碑：创建、更新、删除 | +| wiki_read | Wiki | 读取 | 读取 Wiki：列出页面、获取内容、修订历史 | +| wiki_write | Wiki | 写入 | 写入 Wiki 页面：创建、更新、删除 | +| timetracking_read | 时间跟踪 | 读取 | 读取时间跟踪：问题/仓库耗时、活动计时器、我的跟踪记录 | +| timetracking_write | 时间跟踪 | 写入 | 写入时间跟踪：计时器和记录条目 | +| package_read | 软件包 | 读取 | 读取软件包注册表：列出软件包、列出版本或获取某个版本 | +| package_write | 软件包 | 写入 | 删除软件包版本（不可恢复） | +| list_issues | 问题 | 读取 | 列出仓库问题 | +| issue_read | 问题 | 读取 | 读取问题：详情、评论或标签 | +| issue_write | 问题 | 写入 | 写入问题：创建、更新、管理评论和标签 | +| list_pull_requests | 拉取请求 | 读取 | 列出仓库拉取请求 | +| pull_request_read | 拉取请求 | 读取 | 读取拉取请求：详情、差异、变更文件、头部提交状态、审查 | +| pull_request_write | 拉取请求 | 写入 | 写入拉取请求：创建、更新、关闭、重新打开、合并、更新分支、管理审查者 | +| pull_request_review_write | 拉取请求 | 写入 | 写入 PR 审查：创建、提交、删除、驳回 | +| actions_config_read | Actions | 读取 | 读取 Actions 密钥和变量 | +| actions_config_write | Actions | 写入 | 写入 Actions 密钥和变量：更新插入、创建、更新、删除 | +| actions_run_read | Actions | 读取 | 读取 Actions 工作流、运行、作业、日志和构件 | +| actions_run_write | Actions | 写入 | 写入 Actions 运行：触发、取消、重新运行 | +| create_repo | 仓库 | 写入 | 创建新仓库 | +| fork_repo | 仓库 | 写入 | 复刻仓库 | +| list_my_repos | 仓库 | 读取 | 列出当前用户拥有的仓库 | +| list_org_repos | 仓库 | 读取 | 列出组织中的仓库 | +| get_repository_tree | 仓库 | 读取 | 获取仓库文件树 | +| get_file_contents | 文件 | 读取 | 获取文件内容和元数据 | +| get_dir_contents | 文件 | 读取 | 获取目录中的条目 | +| create_or_update_file | 文件 | 写入 | 创建或更新文件（提供 sha 以更新现有文件） | +| delete_file | 文件 | 写入 | 删除文件 | +| create_branch | 分支 | 写入 | 创建新分支 | +| delete_branch | 分支 | 写入 | 删除分支 | +| list_branches | 分支 | 读取 | 列出仓库分支 | +| create_tag | Git 标签 | 写入 | 创建标签 | +| delete_tag | Git 标签 | 写入 | 删除标签 | +| get_tag | Git 标签 | 读取 | 获取标签详情 | +| list_tags | Git 标签 | 读取 | 列出仓库标签 | +| list_commits | 提交 | 读取 | 列出仓库提交 | +| get_commit | 提交 | 读取 | 获取提交详情 | +| create_release | 版本发布 | 写入 | 创建版本发布 | +| delete_release | 版本发布 | 写入 | 删除版本发布 | +| get_release | 版本发布 | 读取 | 按 ID 获取版本发布 | +| get_latest_release | 版本发布 | 读取 | 获取最新版本发布 | +| list_releases | 版本发布 | 读取 | 列出仓库版本发布 | -一切设置完成后，可在 MCP 聊天框输入： +> **说明：** 部分工具是聚合的、基于操作的工具，单个工具通过 `method` 参数暴露多个操作。当服务器以只读模式运行时（`-r` / `GITEA_READONLY`），访问为「写入」的工具会被隐藏；可通过 `-O` / `--tools`（`GITEA_TOOLS`）过滤对外暴露的工具集合。 -```text -列出我所有的仓库 -``` - -## ✅ 可用工具 - -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 | 拉取请求 | 驳回审查（可附消息） | -| merge_pull_request | 拉取请求 | 合并拉取请求 | -| 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 -d -``` - -## 🛠 疑难排解 - -如遇问题，可参考以下步骤： - -1. **检查 PATH**：确保 `gitea-mcp` 可执行文件已在系统 PATH 目录中。 -2. **验证依赖**：确认已安装 `make` 和 `Golang` 等必要依赖。 -3. **检查配置**：仔细检查 MCP 配置文件是否有错误或遗漏。 -4. **查看日志**：检查日志消息或警告以获取更多信息。 - -享受通过聊天探索和管理您的 Gitea 仓库！ +许多工具支持 `page` 和 `per_page` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认 **50**），超出的值会被静默截断。 diff --git a/README.zh-tw.md b/README.zh-tw.md index 6566353..74ab0e4 100644 --- a/README.zh-tw.md +++ b/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", "" + ] + } ``` -建置前請先安裝： +### 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", "" - ], + "args": ["-t", "stdio", "--host", "https://gitea.com"], "env": { - // "GITEA_HOST": "https://gitea.com", - // "GITEA_INSECURE": "true", "GITEA_ACCESS_TOKEN": "" } } @@ -145,7 +110,7 @@ cp gitea-mcp /usr/local/bin/ } ``` -- **http 模式** +或使用 http 端點，對應以 `gitea-mcp -t http --port 8080` 啟動的伺服器： ```json { @@ -160,100 +125,66 @@ cp gitea-mcp /usr/local/bin/ } ``` -**預設日誌路徑**: `$HOME/.gitea-mcp/gitea-mcp.log` +設定完成後，可在聊天框輸入 `列出我所有的倉庫` 試試。 -> [!注意] -> 可用命令列參數或環境變數提供 Gitea 主機與存取令牌。 -> 命令列參數優先。 +## 可用工具 -> [!注意] -> 許多工具支援 `page` 和 `perPage` 分頁參數。最大有效頁面大小由 Gitea 伺服器的 `[api].MAX_RESPONSE_ITEMS` 設定決定（預設值：**50**）。請求超過此限制的 `perPage` 值將被伺服器靜默截斷。 +| 工具 | 範圍 | 存取 | 描述 | +| :--------------------------- | :------- | :--- | :------------------------------------------------------------------- | +| get_gitea_mcp_server_version | 版本 | 讀取 | 取得 Gitea MCP 伺服器版本 | +| get_me | 用戶 | 讀取 | 取得目前已認證用戶 | +| get_user_orgs | 用戶 | 讀取 | 列出目前用戶的組織 | +| search_users | 搜尋 | 讀取 | 搜尋用戶 | +| search_org_teams | 搜尋 | 讀取 | 搜尋組織中的團隊 | +| search_repos | 搜尋 | 讀取 | 搜尋倉庫 | +| search_issues | 搜尋 | 讀取 | 跨倉庫搜尋問題和拉取請求 | +| notification_read | 通知 | 讀取 | 讀取通知：列出（可限定倉庫）或依 ID 取得會話 | +| notification_write | 通知 | 寫入 | 將某條或全部通知標記為已讀 | +| label_read | 標籤 | 讀取 | 讀取倉庫或組織標籤 | +| label_write | 標籤 | 寫入 | 寫入標籤（倉庫或組織）：創建、編輯、刪除 | +| milestone_read | 里程碑 | 讀取 | 讀取里程碑：取得單個或列出 | +| milestone_write | 里程碑 | 寫入 | 寫入里程碑：創建、更新、刪除 | +| wiki_read | Wiki | 讀取 | 讀取 Wiki：列出頁面、取得內容、修訂歷史 | +| wiki_write | Wiki | 寫入 | 寫入 Wiki 頁面：創建、更新、刪除 | +| timetracking_read | 時間追蹤 | 讀取 | 讀取時間追蹤：問題/倉庫耗時、活動計時器、我的追蹤記錄 | +| timetracking_write | 時間追蹤 | 寫入 | 寫入時間追蹤：計時器和記錄項目 | +| package_read | 軟體套件 | 讀取 | 讀取軟體套件註冊表：列出套件、列出版本或取得某個版本 | +| package_write | 軟體套件 | 寫入 | 刪除軟體套件版本（不可復原） | +| list_issues | 問題 | 讀取 | 列出倉庫問題 | +| issue_read | 問題 | 讀取 | 讀取問題：詳情、評論或標籤 | +| issue_write | 問題 | 寫入 | 寫入問題：創建、更新、管理評論和標籤 | +| list_pull_requests | 拉取請求 | 讀取 | 列出倉庫拉取請求 | +| pull_request_read | 拉取請求 | 讀取 | 讀取拉取請求：詳情、差異、變更檔案、頭部提交狀態、審查 | +| pull_request_write | 拉取請求 | 寫入 | 寫入拉取請求：創建、更新、關閉、重新開啟、合併、更新分支、管理審查者 | +| pull_request_review_write | 拉取請求 | 寫入 | 寫入 PR 審查：創建、提交、刪除、駁回 | +| actions_config_read | Actions | 讀取 | 讀取 Actions 密鑰和變數 | +| actions_config_write | Actions | 寫入 | 寫入 Actions 密鑰和變數：更新插入、創建、更新、刪除 | +| actions_run_read | Actions | 讀取 | 讀取 Actions 工作流程、執行、作業、日誌和產物 | +| actions_run_write | Actions | 寫入 | 寫入 Actions 執行：觸發、取消、重新執行 | +| create_repo | 倉庫 | 寫入 | 創建新倉庫 | +| fork_repo | 倉庫 | 寫入 | 復刻倉庫 | +| list_my_repos | 倉庫 | 讀取 | 列出目前用戶擁有的倉庫 | +| list_org_repos | 倉庫 | 讀取 | 列出組織中的倉庫 | +| get_repository_tree | 倉庫 | 讀取 | 取得倉庫檔案樹 | +| get_file_contents | 文件 | 讀取 | 取得檔案內容與中繼資料 | +| get_dir_contents | 文件 | 讀取 | 取得目錄中的項目 | +| create_or_update_file | 文件 | 寫入 | 創建或更新檔案（提供 sha 以更新現有檔案） | +| delete_file | 文件 | 寫入 | 刪除檔案 | +| create_branch | 分支 | 寫入 | 創建新分支 | +| delete_branch | 分支 | 寫入 | 刪除分支 | +| list_branches | 分支 | 讀取 | 列出倉庫分支 | +| create_tag | Git 標籤 | 寫入 | 創建標籤 | +| delete_tag | Git 標籤 | 寫入 | 刪除標籤 | +| get_tag | Git 標籤 | 讀取 | 取得標籤詳情 | +| list_tags | Git 標籤 | 讀取 | 列出倉庫標籤 | +| list_commits | 提交 | 讀取 | 列出倉庫提交 | +| get_commit | 提交 | 讀取 | 取得提交詳情 | +| create_release | 版本發布 | 寫入 | 創建版本發布 | +| delete_release | 版本發布 | 寫入 | 刪除版本發布 | +| get_release | 版本發布 | 讀取 | 依 ID 取得版本發布 | +| get_latest_release | 版本發布 | 讀取 | 取得最新版本發布 | +| list_releases | 版本發布 | 讀取 | 列出倉庫版本發布 | -一切設定完成後，可在 MCP 聊天框輸入： +> **說明：** 部分工具是聚合的、基於操作的工具，單個工具透過 `method` 參數暴露多個操作。當伺服器以唯讀模式執行時（`-r` / `GITEA_READONLY`），存取為「寫入」的工具會被隱藏；可透過 `-O` / `--tools`（`GITEA_TOOLS`）過濾對外暴露的工具集合。 -```text -列出我所有的倉庫 -``` - -## ✅ 可用工具 - -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 | 拉取請求 | 駁回審查（可附訊息） | -| merge_pull_request | 拉取請求 | 合併拉取請求 | -| 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 -d -``` - -## 🛠 疑難排解 - -如遇問題，可參考以下步驟： - -1. **檢查 PATH**：確保 `gitea-mcp` 執行檔已在系統 PATH 目錄中。 -2. **驗證依賴**：確認已安裝 `make` 與 `Golang` 等必要依賴。 -3. **檢查設定**：仔細檢查 MCP 設定檔是否有錯誤或遺漏。 -4. **查看日誌**：檢查日誌訊息或警告以獲取更多資訊。 - -享受透過聊天探索與管理您的 Gitea 倉庫！ +許多工具支援 `page` 和 `per_page` 分頁參數。最大有效頁面大小由 Gitea 伺服器的 `[api].MAX_RESPONSE_ITEMS` 設定決定（預設 **50**），超出的值會被靜默截斷。 diff --git a/operation/readme_test.go b/operation/readme_test.go new file mode 100644 index 0000000..7bc5f54 --- /dev/null +++ b/operation/readme_test.go @@ -0,0 +1,69 @@ +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 and the access cell, e.g. +// "| get_me | User | Read | Get the current authenticated user |". +var toolTableRow = regexp.MustCompile(`^\|\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"}, +} + +// 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. +func TestReadmeToolTables(t *testing.T) { + registered := map[string]string{} + for _, d := range domainTools { + for _, st := range d.ReadTools() { + registered[st.Tool.Name] = "read" + } + for _, st := range d.WriteTools() { + registered[st.Tool.Name] = "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]string{} + for line := range strings.SplitSeq(string(content), "\n") { + if match := toolTableRow.FindStringSubmatch(line); match != nil { + documented[match[1]] = labels[match[2]] + } + } + + for _, name := range slices.Sorted(maps.Keys(registered)) { + access, ok := documented[name] + switch { + case !ok: + t.Errorf("tool %q is registered but missing from the tool table", name) + case access != registered[name]: + t.Errorf("tool %q is documented with %q access, want %q", name, access, registered[name]) + } + } + 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) + } + } + }) + } +} diff --git a/pkg/tool/tool.go b/pkg/tool/tool.go index 84cc474..ce9bd4b 100644 --- a/pkg/tool/tool.go +++ b/pkg/tool/tool.go @@ -30,6 +30,18 @@ func (t *Tool) RegisterRead(s server.ServerTool) { t.read = append(t.read, s) } +// ReadTools returns the read-only tools registered on this domain, ignoring +// the read-only and allowlist flags that Tools applies. +func (t *Tool) ReadTools() []server.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() []server.ServerTool { + return t.write +} + func (t *Tool) Tools() []server.ServerTool { all := make([]server.ServerTool, 0, len(t.write)+len(t.read)) if !flag.ReadOnly {