mirror of
https://gitea.com/gitea/gitea-mcp.git
synced 2026-08-03 07:39:22 +02:00
docs: rewrite the tool tables and slim down the READMEs (#215)
Fixes https://gitea.com/gitea/gitea-mcp/issues/214. The tool tables listed tools that had not existed for several releases. They are regenerated from the registry, gain an `Access` column so it is visible what disappears under `-r` / `GITEA_READONLY`, and get their fine-grained scopes back. `TestReadmeToolTables` now compares them against the registry in both directions, for every translation. Other corrections from verifying the prose against the source: the pagination parameter is `per_page`, not `perPage`; Go 1.26 is required, not 1.24; the Chinese READMEs were missing the OpenCode and Mistral Vibe sections. Also trimmed the drifted table of contents and the sections the intro and `gitea-mcp --help` already cover, and dropped the heading emoji. `CLAUDE.md` had its own stale tool list, so it now points at `AGENTS.md` like gitea/gitea does. --------- Co-authored-by: silverwind <me@silverwind.io> Reviewed-on: https://gitea.com/gitea/gitea-mcp/pulls/215 Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
This commit is contained in:
Lunny Xiao
@@ -1,8 +1,12 @@
|
|||||||
- Use `make help` to find available development targets
|
- 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 fmt` to format `.go` files, and run `make lint-go` to lint them
|
||||||
- Run `make tidy` after any `go.mod` changes
|
- 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
|
- 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
|
- 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
|
- Include authorship attribution in issue and pull request comments
|
||||||
- Add `Co-Authored-By` lines to all commits, indicating name and model used
|
- Add `Co-Authored-By` lines to all commits, indicating name and model used
|
||||||
|
|||||||
+1
-1
@@ -4,7 +4,7 @@ This project includes PowerShell and batch scripts to build the gitea-mcp applic
|
|||||||
|
|
||||||
## Prerequisites
|
## Prerequisites
|
||||||
|
|
||||||
- Go 1.24 or later
|
- Go 1.26 or later
|
||||||
- Git (for version information)
|
- Git (for version information)
|
||||||
- PowerShell 5.1 or later (included with Windows 10/11)
|
- PowerShell 5.1 or later (included with Windows 10/11)
|
||||||
|
|
||||||
|
|||||||
@@ -1,78 +1 @@
|
|||||||
# CLAUDE.md
|
@AGENTS.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
|
|
||||||
|
|||||||
@@ -2,58 +2,27 @@
|
|||||||
|
|
||||||
[繁體中文](README.zh-tw.md) | [简体中文](README.zh-cn.md)
|
[繁體中文](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.
|
||||||
|
|
||||||
[](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}}) [](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)
|
[](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}}) [](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)
|
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:
|
||||||
- [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)
|
|
||||||
|
|
||||||
## What is Gitea?
|
```bash
|
||||||
|
git clone https://gitea.com/gitea/gitea-mcp.git
|
||||||
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.
|
cd gitea-mcp
|
||||||
|
make install
|
||||||
## 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", "<your personal access token>"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
```bash
|
||||||
claude mcp add --transport stdio --scope user gitea \
|
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
|
-- 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.
|
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.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@@ -86,14 +49,7 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
|
|||||||
"servers": {
|
"servers": {
|
||||||
"gitea-mcp": {
|
"gitea-mcp": {
|
||||||
"command": "docker",
|
"command": "docker",
|
||||||
"args": [
|
"args": ["run", "-i", "--rm", "-e", "GITEA_ACCESS_TOKEN", "docker.gitea.com/gitea-mcp-server"],
|
||||||
"run",
|
|
||||||
"-i",
|
|
||||||
"--rm",
|
|
||||||
"-e",
|
|
||||||
"GITEA_ACCESS_TOKEN",
|
|
||||||
"docker.gitea.com/gitea-mcp-server"
|
|
||||||
],
|
|
||||||
"env": {
|
"env": {
|
||||||
"GITEA_ACCESS_TOKEN": "${input:gitea_token}"
|
"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", "<your personal access token>"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mistral Vibe
|
||||||
|
|
||||||
|
Add the following to `~/.vibe/config.toml`:
|
||||||
|
|
||||||
```toml
|
```toml
|
||||||
[[mcp_servers]]
|
[[mcp_servers]]
|
||||||
name = "gitea"
|
name = "gitea"
|
||||||
transport = "stdio"
|
transport = "stdio"
|
||||||
command = "docker"
|
command = "docker"
|
||||||
args = [
|
args = ["run", "--rm", "-i", "-e", "GITEA_ACCESS_TOKEN", "-e", "GITEA_HOST", "docker.gitea.com/gitea-mcp-server"]
|
||||||
"run",
|
|
||||||
"--rm",
|
|
||||||
"-i",
|
|
||||||
"-e",
|
|
||||||
"GITEA_ACCESS_TOKEN",
|
|
||||||
"-e",
|
|
||||||
"GITEA_HOST",
|
|
||||||
"docker.gitea.com/gitea-mcp-server",
|
|
||||||
]
|
|
||||||
|
|
||||||
[mcp_servers.env]
|
[mcp_servers.env]
|
||||||
GITEA_ACCESS_TOKEN = "TOKEN"
|
GITEA_ACCESS_TOKEN = "TOKEN"
|
||||||
GITEA_HOST = "https://gitea.com"
|
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).
|
Clients such as Cursor take either a stdio command:
|
||||||
|
|
||||||
### 🔧 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**
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"gitea": {
|
"gitea": {
|
||||||
"command": "gitea-mcp",
|
"command": "gitea-mcp",
|
||||||
"args": [
|
"args": ["-t", "stdio", "--host", "https://gitea.com"],
|
||||||
"-t",
|
|
||||||
"stdio",
|
|
||||||
"--host",
|
|
||||||
"https://gitea.com"
|
|
||||||
// "--token", "<your personal access token>"
|
|
||||||
],
|
|
||||||
"env": {
|
"env": {
|
||||||
// "GITEA_HOST": "https://gitea.com",
|
|
||||||
// "GITEA_INSECURE": "true",
|
|
||||||
"GITEA_ACCESS_TOKEN": "<your personal access token>"
|
"GITEA_ACCESS_TOKEN": "<your personal 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
|
```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]
|
## Available Tools
|
||||||
> You can provide your Gitea host and access token either as command-line arguments or environment variables.
|
|
||||||
> Command-line arguments have the highest priority
|
|
||||||
|
|
||||||
> [!NOTE]
|
| Tool | Scope | Access | Description |
|
||||||
> 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.
|
| :--------------------------- | :----------- | :----- | :----------------------------------------------------------------------------------------- |
|
||||||
|
| 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
|
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.
|
||||||
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 <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!
|
|
||||||
|
|||||||
+102
-171
@@ -2,40 +2,27 @@
|
|||||||
|
|
||||||
[English](README.md) | [繁體中文](README.zh-tw.md)
|
[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 的聊天界面中浏览和管理。
|
||||||
|
|
||||||
[](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}}) [](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)
|
[](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}}) [](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-服务器)
|
可从 [发布页面](https://gitea.com/gitea/gitea-mcp/releases) 下载二进制文件并放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 镜像，也可用 `make` 和 Go 1.26 及以上从源码构建到 `$GOPATH/bin`：
|
||||||
- [目录](#目录)
|
|
||||||
- [什么是 Gitea？](#什么是-gitea)
|
|
||||||
- [什么是 MCP？](#什么是-mcp)
|
|
||||||
- [🚧 安装](#-安装)
|
|
||||||
- [在 Claude Code 中使用](#在-claude-code-中使用)
|
|
||||||
- [在 VS Code 中使用](#在-vs-code-中使用)
|
|
||||||
- [📥 下载官方二进制版本](#-下载官方二进制版本)
|
|
||||||
- [🔧 从源码构建](#-从源码构建)
|
|
||||||
- [📁 加入 PATH](#-加入-path)
|
|
||||||
- [🚀 使用](#-使用)
|
|
||||||
- [✅ 可用工具](#-可用工具)
|
|
||||||
- [🐛 调试](#-调试)
|
|
||||||
- [🛠 疑难排解](#-疑难排解)
|
|
||||||
|
|
||||||
## 什么是 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
|
||||||
|
|
||||||
## 🚧 安装
|
通过 `go run` 运行服务器，需要安装 [Go](https://go.dev)：
|
||||||
|
|
||||||
### 在 Claude Code 中使用
|
|
||||||
|
|
||||||
此方式使用 `go run`，需要安装 [Go](https://go.dev)。
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
claude mcp add --transport stdio --scope user gitea \
|
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
|
-- go run gitea.com/gitea/gitea-mcp@latest -t stdio
|
||||||
```
|
```
|
||||||
|
|
||||||
### 在 VS Code 中使用
|
### VS Code
|
||||||
|
|
||||||
要快速安装，请使用本 README 顶部的安装按钮。
|
可使用本 README 顶部的安装按钮，或将下面的内容加入用户设置 (JSON)，按 `Ctrl + Shift + P` 并输入 `Preferences: Open User Settings (JSON)` 即可打开。也可放在工作区的 `.vscode/mcp.json` 中，此时无需 `mcp` 键。
|
||||||
|
|
||||||
如需手动安装，请将以下 JSON 块添加到 VS Code 的用户设置 (JSON) 文件。可通过按 `Ctrl + Shift + P` 并输入 `Preferences: Open User Settings (JSON)`。
|
|
||||||
|
|
||||||
也可添加到工作区的 `.vscode/mcp.json` 文件，方便与他人共享配置。
|
|
||||||
|
|
||||||
> `.vscode/mcp.json` 文件不需要 `mcp` 键。
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@@ -68,14 +49,7 @@ claude mcp add --transport stdio --scope user gitea \
|
|||||||
"servers": {
|
"servers": {
|
||||||
"gitea-mcp": {
|
"gitea-mcp": {
|
||||||
"command": "docker",
|
"command": "docker",
|
||||||
"args": [
|
"args": ["run", "-i", "--rm", "-e", "GITEA_ACCESS_TOKEN", "docker.gitea.com/gitea-mcp-server"],
|
||||||
"run",
|
|
||||||
"-i",
|
|
||||||
"--rm",
|
|
||||||
"-e",
|
|
||||||
"GITEA_ACCESS_TOKEN",
|
|
||||||
"docker.gitea.com/gitea-mcp-server"
|
|
||||||
],
|
|
||||||
"env": {
|
"env": {
|
||||||
"GITEA_ACCESS_TOKEN": "${input:gitea_token}"
|
"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` 对象：
|
||||||
|
|
||||||
### 🔧 从源码构建
|
```json
|
||||||
|
"gitea-mcp": {
|
||||||
可用 Git 下载源码：
|
"enabled": true,
|
||||||
|
"type": "local",
|
||||||
```bash
|
"command": [
|
||||||
git clone https://gitea.com/gitea/gitea-mcp.git
|
"gitea-mcp",
|
||||||
|
"-t", "stdio",
|
||||||
|
"-H", "https://gitea.com",
|
||||||
|
"-T", "<your personal access token>"
|
||||||
|
]
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
构建前请先安装：
|
### Mistral Vibe
|
||||||
|
|
||||||
- make
|
将下面的内容加入 `~/.vibe/config.toml`：
|
||||||
- Golang（建议 Go 1.24 及以上）
|
|
||||||
|
|
||||||
然后运行：
|
```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
|
[mcp_servers.env]
|
||||||
make install
|
GITEA_ACCESS_TOKEN = "TOKEN"
|
||||||
|
GITEA_HOST = "https://gitea.com"
|
||||||
```
|
```
|
||||||
|
|
||||||
### 📁 加入 PATH
|
### 其他客户端
|
||||||
|
|
||||||
安装后，将 gitea-mcp 可执行文件复制到系统 PATH 目录，例如：
|
Cursor 等客户端可使用 stdio 命令：
|
||||||
|
|
||||||
```bash
|
|
||||||
cp gitea-mcp /usr/local/bin/
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚀 使用
|
|
||||||
|
|
||||||
此示例适用于 Cursor，也可在 VSCode 使用插件。
|
|
||||||
要配置 Gitea MCP 服务器，请将以下内容添加到 MCP 配置文件：
|
|
||||||
|
|
||||||
- **stdio 模式**
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"gitea": {
|
"gitea": {
|
||||||
"command": "gitea-mcp",
|
"command": "gitea-mcp",
|
||||||
"args": [
|
"args": ["-t", "stdio", "--host", "https://gitea.com"],
|
||||||
"-t",
|
|
||||||
"stdio",
|
|
||||||
"--host",
|
|
||||||
"https://gitea.com"
|
|
||||||
// "--token", "<your personal access token>"
|
|
||||||
],
|
|
||||||
"env": {
|
"env": {
|
||||||
// "GITEA_HOST": "https://gitea.com",
|
|
||||||
// "GITEA_INSECURE": "true",
|
|
||||||
"GITEA_ACCESS_TOKEN": "<your personal access token>"
|
"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
|
```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
|
许多工具支持 `page` 和 `per_page` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认 **50**），超出的值会被静默截断。
|
||||||
列出我所有的仓库
|
|
||||||
```
|
|
||||||
|
|
||||||
## ✅ 可用工具
|
|
||||||
|
|
||||||
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 <your personal access token> -d
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🛠 疑难排解
|
|
||||||
|
|
||||||
如遇问题，可参考以下步骤：
|
|
||||||
|
|
||||||
1. **检查 PATH**：确保 `gitea-mcp` 可执行文件已在系统 PATH 目录中。
|
|
||||||
2. **验证依赖**：确认已安装 `make` 和 `Golang` 等必要依赖。
|
|
||||||
3. **检查配置**：仔细检查 MCP 配置文件是否有错误或遗漏。
|
|
||||||
4. **查看日志**：检查日志消息或警告以获取更多信息。
|
|
||||||
|
|
||||||
享受通过聊天探索和管理您的 Gitea 仓库！
|
|
||||||
|
|||||||
+102
-171
@@ -2,40 +2,27 @@
|
|||||||
|
|
||||||
[English](README.md) | [简体中文](README.zh-cn.md)
|
[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 的聊天介面中瀏覽與管理。
|
||||||
|
|
||||||
[](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}}) [](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)
|
[](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}}) [](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-伺服器)
|
可從 [發布頁面](https://gitea.com/gitea/gitea-mcp/releases) 下載二進位檔並放入 `PATH`，或使用 `docker.gitea.com/gitea-mcp-server` 映像檔，也可用 `make` 與 Go 1.26 以上從原始碼建置到 `$GOPATH/bin`：
|
||||||
- [目錄](#目錄)
|
|
||||||
- [什麼是 Gitea？](#什麼是-gitea)
|
|
||||||
- [什麼是 MCP？](#什麼是-mcp)
|
|
||||||
- [🚧 安裝](#-安裝)
|
|
||||||
- [在 Claude Code 中使用](#在-claude-code-中使用)
|
|
||||||
- [在 VS Code 中使用](#在-vs-code-中使用)
|
|
||||||
- [📥 下載官方二進位版本](#-下載官方二進位版本)
|
|
||||||
- [🔧 從原始碼建置](#-從原始碼建置)
|
|
||||||
- [📁 加入 PATH](#-加入-path)
|
|
||||||
- [🚀 使用](#-使用)
|
|
||||||
- [✅ 可用工具](#-可用工具)
|
|
||||||
- [🐛 調試](#-調試)
|
|
||||||
- [🛠 疑難排解](#-疑難排解)
|
|
||||||
|
|
||||||
## 什麼是 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
|
||||||
|
|
||||||
## 🚧 安裝
|
透過 `go run` 執行伺服器，需要安裝 [Go](https://go.dev)：
|
||||||
|
|
||||||
### 在 Claude Code 中使用
|
|
||||||
|
|
||||||
此方式使用 `go run`，需要安裝 [Go](https://go.dev)。
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
claude mcp add --transport stdio --scope user gitea \
|
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
|
-- go run gitea.com/gitea/gitea-mcp@latest -t stdio
|
||||||
```
|
```
|
||||||
|
|
||||||
### 在 VS Code 中使用
|
### VS Code
|
||||||
|
|
||||||
欲快速安裝，請使用本 README 頂部的安裝按鈕。
|
可使用本 README 頂部的安裝按鈕，或將下面的內容加入使用者設定 (JSON)，按 `Ctrl + Shift + P` 並輸入 `Preferences: Open User Settings (JSON)` 即可開啟。也可放在工作區的 `.vscode/mcp.json` 中，此時不需要 `mcp` 鍵。
|
||||||
|
|
||||||
如需手動安裝，請將下列 JSON 區塊加入 VS Code 的使用者設定 (JSON) 檔案。可按 `Ctrl + Shift + P` 並輸入 `Preferences: Open User Settings (JSON)`。
|
|
||||||
|
|
||||||
也可加入至工作區的 `.vscode/mcp.json` 檔案，方便與他人共享設定。
|
|
||||||
|
|
||||||
> `.vscode/mcp.json` 檔案不需 `mcp` 鍵。
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@@ -68,14 +49,7 @@ claude mcp add --transport stdio --scope user gitea \
|
|||||||
"servers": {
|
"servers": {
|
||||||
"gitea-mcp": {
|
"gitea-mcp": {
|
||||||
"command": "docker",
|
"command": "docker",
|
||||||
"args": [
|
"args": ["run", "-i", "--rm", "-e", "GITEA_ACCESS_TOKEN", "docker.gitea.com/gitea-mcp-server"],
|
||||||
"run",
|
|
||||||
"-i",
|
|
||||||
"--rm",
|
|
||||||
"-e",
|
|
||||||
"GITEA_ACCESS_TOKEN",
|
|
||||||
"docker.gitea.com/gitea-mcp-server"
|
|
||||||
],
|
|
||||||
"env": {
|
"env": {
|
||||||
"GITEA_ACCESS_TOKEN": "${input:gitea_token}"
|
"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` 物件：
|
||||||
|
|
||||||
### 🔧 從原始碼建置
|
```json
|
||||||
|
"gitea-mcp": {
|
||||||
可用 Git 下載原始碼：
|
"enabled": true,
|
||||||
|
"type": "local",
|
||||||
```bash
|
"command": [
|
||||||
git clone https://gitea.com/gitea/gitea-mcp.git
|
"gitea-mcp",
|
||||||
|
"-t", "stdio",
|
||||||
|
"-H", "https://gitea.com",
|
||||||
|
"-T", "<your personal access token>"
|
||||||
|
]
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
建置前請先安裝：
|
### Mistral Vibe
|
||||||
|
|
||||||
- make
|
將下面的內容加入 `~/.vibe/config.toml`：
|
||||||
- Golang（建議 Go 1.24 以上）
|
|
||||||
|
|
||||||
然後執行：
|
```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
|
[mcp_servers.env]
|
||||||
make install
|
GITEA_ACCESS_TOKEN = "TOKEN"
|
||||||
|
GITEA_HOST = "https://gitea.com"
|
||||||
```
|
```
|
||||||
|
|
||||||
### 📁 加入 PATH
|
### 其他客戶端
|
||||||
|
|
||||||
安裝後，將 gitea-mcp 執行檔複製到系統 PATH 目錄，例如：
|
Cursor 等客戶端可使用 stdio 命令：
|
||||||
|
|
||||||
```bash
|
|
||||||
cp gitea-mcp /usr/local/bin/
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚀 使用
|
|
||||||
|
|
||||||
此範例適用於 Cursor，也可在 VSCode 使用插件。
|
|
||||||
欲設定 Gitea MCP 伺服器，請將下列內容加入 MCP 設定檔：
|
|
||||||
|
|
||||||
- **stdio 模式**
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"gitea": {
|
"gitea": {
|
||||||
"command": "gitea-mcp",
|
"command": "gitea-mcp",
|
||||||
"args": [
|
"args": ["-t", "stdio", "--host", "https://gitea.com"],
|
||||||
"-t",
|
|
||||||
"stdio",
|
|
||||||
"--host",
|
|
||||||
"https://gitea.com"
|
|
||||||
// "--token", "<your personal access token>"
|
|
||||||
],
|
|
||||||
"env": {
|
"env": {
|
||||||
// "GITEA_HOST": "https://gitea.com",
|
|
||||||
// "GITEA_INSECURE": "true",
|
|
||||||
"GITEA_ACCESS_TOKEN": "<your personal access token>"
|
"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
|
```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
|
許多工具支援 `page` 和 `per_page` 分頁參數。最大有效頁面大小由 Gitea 伺服器的 `[api].MAX_RESPONSE_ITEMS` 設定決定（預設 **50**），超出的值會被靜默截斷。
|
||||||
列出我所有的倉庫
|
|
||||||
```
|
|
||||||
|
|
||||||
## ✅ 可用工具
|
|
||||||
|
|
||||||
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 <your personal access token> -d
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🛠 疑難排解
|
|
||||||
|
|
||||||
如遇問題，可參考以下步驟：
|
|
||||||
|
|
||||||
1. **檢查 PATH**：確保 `gitea-mcp` 執行檔已在系統 PATH 目錄中。
|
|
||||||
2. **驗證依賴**：確認已安裝 `make` 與 `Golang` 等必要依賴。
|
|
||||||
3. **檢查設定**：仔細檢查 MCP 設定檔是否有錯誤或遺漏。
|
|
||||||
4. **查看日誌**：檢查日誌訊息或警告以獲取更多資訊。
|
|
||||||
|
|
||||||
享受透過聊天探索與管理您的 Gitea 倉庫！
|
|
||||||
|
|||||||
@@ -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)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -30,6 +30,18 @@ func (t *Tool) RegisterRead(s server.ServerTool) {
|
|||||||
t.read = append(t.read, s)
|
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 {
|
func (t *Tool) Tools() []server.ServerTool {
|
||||||
all := make([]server.ServerTool, 0, len(t.write)+len(t.read))
|
all := make([]server.ServerTool, 0, len(t.write)+len(t.read))
|
||||||
if !flag.ReadOnly {
|
if !flag.ReadOnly {
|
||||||
|
|||||||
Reference in New Issue
Block a user