diff --git a/.env b/.env new file mode 100644 index 0000000..20096f9 --- /dev/null +++ b/.env @@ -0,0 +1,2 @@ +https://gitea.tailnet-68f9.ts.net +8d7d70f324796be650b79415303c31f567bf459b \ No newline at end of file diff --git a/.gitea/workflows/test-runner.yml b/.gitea/workflows/test-runner.yml new file mode 100644 index 0000000..4860985 --- /dev/null +++ b/.gitea/workflows/test-runner.yml @@ -0,0 +1,37 @@ +name: Test DSW Runner + +on: + push: + branches: [main] + workflow_dispatch: + +jobs: + test-runner: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Test Runner Environment + run: | + echo "=== Runner Test Started ===" + echo "Runner hostname: $(hostname)" + echo "Runner OS: $(uname -a)" + echo "Current directory: $(pwd)" + echo "User: $(whoami)" + echo "Date: $(date)" + echo "=== Environment Variables ===" + env | grep -E '^(RUNNER|GITHUB|CI)' || echo "No CI env vars found" + echo "=== Runner Test Completed ===" + + - name: Check Docker availability + run: | + echo "Checking Docker..." + docker --version || echo "Docker not available" + docker ps || echo "Cannot list containers" + + - name: Test network connectivity + run: | + echo "Testing network..." + ping -c 2 gitea.tailnet-68f9.ts.net || echo "Cannot ping Gitea" + curl -s -o /dev/null -w "%{http_code}" https://gitea.tailnet-68f9.ts.net || echo "Cannot reach Gitea HTTPS" diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e98ecb2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 The Gitea Authors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index e69de29..d0ec24d 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,270 @@ +# Gitea MCP Server + +[繁體中文](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. + +[![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 + +- [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 VS Code](#usage-with-vs-code) + - [📥 Download the official binary release](#-download-the-official-binary-release) + - [🔧 Build from Source](#-build-from-source) + - [📁 Add to PATH](#-add-to-path) + - [🚀 Usage](#-usage) + - [✅ Available Tools](#-available-tools) + - [🐛 Debugging](#-debugging) + - [🛠 Troubleshooting](#-troubleshooting) + +## 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 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. + +```json +{ + "mcp": { + "inputs": [ + { + "type": "promptString", + "id": "gitea_token", + "description": "Gitea Personal Access Token", + "password": true + } + ], + "servers": { + "gitea-mcp": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITEA_ACCESS_TOKEN", + "docker.gitea.com/gitea-mcp-server" + ], + "env": { + "GITEA_ACCESS_TOKEN": "${input:gitea_token}" + } + } + } + } +} +``` + +### 📥 Download the official binary release + +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** + +```json +{ + "mcpServers": { + "gitea": { + "command": "gitea-mcp", + "args": [ + "-t", + "stdio", + "--host", + "https://gitea.com" + // "--token", "" + ], + "env": { + // "GITEA_HOST": "https://gitea.com", + // "GITEA_INSECURE": "true", + "GITEA_ACCESS_TOKEN": "" + } + } + } +} +``` + +- **http mode** + +```json +{ + "mcpServers": { + "gitea": { + "url": "http://localhost:8080/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +**Default log path**: `$HOME/.gitea-mcp/gitea-mcp.log` + +> [!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 + +Once everything is set up, try typing the following in your MCP-compatible chatbox: + +```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 | +| list_repo_pull_requests | Pull Request | List all pull requests in a repository | +| create_pull_request | Pull Request | Create a new pull request | +| create_pull_request_reviewer | Pull Request | Add reviewers to a pull request | +| delete_pull_request_reviewer | Pull Request | Remove reviewers from a pull request | +| list_pull_request_reviews | Pull Request | List all reviews for a pull request | +| get_pull_request_review | Pull Request | Get a specific review by ID | +| list_pull_request_review_comments | Pull Request | List inline comments for a review | +| create_pull_request_review | Pull Request | Create a review with optional inline comments | +| submit_pull_request_review | Pull Request | Submit a pending review | +| delete_pull_request_review | Pull Request | Delete a review | +| dismiss_pull_request_review | Pull Request | Dismiss a review with optional message | +| search_users | User | Search for users | +| search_org_teams | Organization | Search for teams in an organization | +| list_org_labels | Organization | List labels defined at organization level | +| create_org_label | Organization | Create a label in an organization | +| edit_org_label | Organization | Edit a label in an organization | +| delete_org_label | Organization | Delete a label in an organization | +| search_repos | Repository | Search for repositories | +| list_repo_action_secrets | Actions | List repository Actions secrets (metadata only) | +| upsert_repo_action_secret | Actions | Create/update (upsert) a repository Actions secret | +| delete_repo_action_secret | Actions | Delete a repository Actions secret | +| list_org_action_secrets | Actions | List organization Actions secrets (metadata only) | +| upsert_org_action_secret | Actions | Create/update (upsert) an organization Actions secret | +| delete_org_action_secret | Actions | Delete an organization Actions secret | +| list_repo_action_variables | Actions | List repository Actions variables | +| get_repo_action_variable | Actions | Get a repository Actions variable | +| create_repo_action_variable | Actions | Create a repository Actions variable | +| update_repo_action_variable | Actions | Update a repository Actions variable | +| delete_repo_action_variable | Actions | Delete a repository Actions variable | +| list_org_action_variables | Actions | List organization Actions variables | +| get_org_action_variable | Actions | Get an organization Actions variable | +| create_org_action_variable | Actions | Create an organization Actions variable | +| update_org_action_variable | Actions | Update an organization Actions variable | +| delete_org_action_variable | Actions | Delete an organization Actions variable | +| list_repo_action_workflows | Actions | List repository Actions workflows | +| get_repo_action_workflow | Actions | Get a repository Actions workflow | +| dispatch_repo_action_workflow | Actions | Trigger (dispatch) a repository Actions workflow | +| list_repo_action_runs | Actions | List repository Actions runs | +| get_repo_action_run | Actions | Get a repository Actions run | +| cancel_repo_action_run | Actions | Cancel a repository Actions run | +| rerun_repo_action_run | Actions | Rerun a repository Actions run | +| list_repo_action_jobs | Actions | List repository Actions jobs | +| list_repo_action_run_jobs | Actions | List Actions jobs for a run | +| get_repo_action_job_log_preview | Actions | Get a job log preview (tail/limited) | +| download_repo_action_job_log | Actions | Download a job log to a file | +| get_gitea_mcp_server_version | Server | Get the version of the Gitea MCP Server | +| list_wiki_pages | Wiki | List all wiki pages in a repository | +| get_wiki_page | Wiki | Get a wiki page content and metadata | +| get_wiki_revisions | Wiki | Get revisions history of a wiki page | +| create_wiki_page | Wiki | Create a new wiki page | +| update_wiki_page | Wiki | Update an existing wiki page | +| delete_wiki_page | Wiki | Delete a wiki page | + +## 🐛 Debugging + +To enable debug mode, add the `-d` flag when running the Gitea MCP Server with http mode: + +```sh +./gitea-mcp -t http [--port 8080] --token -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! diff --git a/README.zh-cn.md b/README.zh-cn.md new file mode 100644 index 0000000..e08ec7c --- /dev/null +++ b/README.zh-cn.md @@ -0,0 +1,243 @@ +# Gitea MCP 服务器 + +[English](README.md) | [繁體中文](README.zh-tw.md) + +**Gitea MCP 服务器** 是一个集成插件,旨在将 Gitea 与 Model Context Protocol (MCP) 系统连接起来。这允许通过 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) + - [🚧 安装](#-安装) + - [在 VS Code 中使用](#在-vs-code-中使用) + - [📥 下载官方二进制版本](#-下载官方二进制版本) + - [🔧 从源码构建](#-从源码构建) + - [📁 加入 PATH](#-加入-path) + - [🚀 使用](#-使用) + - [✅ 可用工具](#-可用工具) + - [🐛 调试](#-调试) + - [🛠 疑难排解](#-疑难排解) + +## 什么是 Gitea? + +Gitea 是一个由社区管理的轻量级代码托管解决方案,使用 Go 语言编写,采用 MIT 许可证。Gitea 提供 Git 托管,包括仓库浏览、问题追踪、拉取请求等功能。 + +## 什么是 MCP? + +Model Context Protocol (MCP) 是一种协议,允许通过聊天界面整合各种工具和系统。它能够无缝执行命令并管理仓库、用户及其他资源。 + +## 🚧 安装 + +### 在 VS Code 中使用 + +要快速安装,请使用本 README 顶部的安装按钮。 + +如需手动安装,请将以下 JSON 块添加到 VS Code 的用户设置 (JSON) 文件。可通过按 `Ctrl + Shift + P` 并输入 `Preferences: Open User Settings (JSON)`。 + +也可添加到工作区的 `.vscode/mcp.json` 文件,方便与他人共享配置。 + +> `.vscode/mcp.json` 文件不需要 `mcp` 键。 + +```json +{ + "mcp": { + "inputs": [ + { + "type": "promptString", + "id": "gitea_token", + "description": "Gitea 个人访问令牌", + "password": true + } + ], + "servers": { + "gitea-mcp": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITEA_ACCESS_TOKEN", + "docker.gitea.com/gitea-mcp-server" + ], + "env": { + "GITEA_ACCESS_TOKEN": "${input:gitea_token}" + } + } + } + } +} +``` + +### 📥 下载官方二进制版本 + +可在 [官方 Gitea MCP 二进制版本](https://gitea.com/gitea/gitea-mcp/releases) 下载。 + +### 🔧 从源码构建 + +可用 Git 下载源码: + +```bash +git clone https://gitea.com/gitea/gitea-mcp.git +``` + +构建前请先安装: + +- make +- Golang(建议 Go 1.24 及以上) + +然后运行: + +```bash +make install +``` + +### 📁 加入 PATH + +安装后,将 gitea-mcp 可执行文件复制到系统 PATH 目录,例如: + +```bash +cp gitea-mcp /usr/local/bin/ +``` + +## 🚀 使用 + +此示例适用于 Cursor,也可在 VSCode 使用插件。 +要配置 Gitea MCP 服务器,请将以下内容添加到 MCP 配置文件: + +- **stdio 模式** + +```json +{ + "mcpServers": { + "gitea": { + "command": "gitea-mcp", + "args": [ + "-t", + "stdio", + "--host", + "https://gitea.com" + // "--token", "" + ], + "env": { + // "GITEA_HOST": "https://gitea.com", + // "GITEA_INSECURE": "true", + "GITEA_ACCESS_TOKEN": "" + } + } + } +} +``` + +- **http 模式** + +```json +{ + "mcpServers": { + "gitea": { + "url": "http://localhost:8080/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +**默认日志路径**: `$HOME/.gitea-mcp/gitea-mcp.log` + +> [!注意] +> 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。 +> 命令行参数优先。 + +一切设置完成后,可在 MCP 聊天框输入: + +```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 | 拉取请求 | 驳回审查(可附消息) | +| 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 仓库! diff --git a/README.zh-tw.md b/README.zh-tw.md new file mode 100644 index 0000000..e471956 --- /dev/null +++ b/README.zh-tw.md @@ -0,0 +1,243 @@ +# Gitea MCP 伺服器 + +[English](README.md) | [简体中文](README.zh-cn.md) + +**Gitea MCP 伺服器** 是一個整合插件,旨在將 Gitea 與 Model Context Protocol (MCP) 系統連接起來。這允許通過 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) + - [🚧 安裝](#-安裝) + - [在 VS Code 中使用](#在-vs-code-中使用) + - [📥 下載官方二進位版本](#-下載官方二進位版本) + - [🔧 從原始碼建置](#-從原始碼建置) + - [📁 加入 PATH](#-加入-path) + - [🚀 使用](#-使用) + - [✅ 可用工具](#-可用工具) + - [🐛 調試](#-調試) + - [🛠 疑難排解](#-疑難排解) + +## 什麼是 Gitea? + +Gitea 是一個由社群管理的輕量級程式碼託管解決方案,使用 Go 語言編寫,採用 MIT 授權。Gitea 提供 Git 託管,包括倉庫瀏覽、議題追蹤、拉取請求等功能。 + +## 什麼是 MCP? + +Model Context Protocol (MCP) 是一種協議,允許透過聊天介面整合各種工具與系統。它能夠無縫執行命令並管理倉庫、使用者及其他資源。 + +## 🚧 安裝 + +### 在 VS Code 中使用 + +欲快速安裝,請使用本 README 頂部的安裝按鈕。 + +如需手動安裝,請將下列 JSON 區塊加入 VS Code 的使用者設定 (JSON) 檔案。可按 `Ctrl + Shift + P` 並輸入 `Preferences: Open User Settings (JSON)`。 + +也可加入至工作區的 `.vscode/mcp.json` 檔案,方便與他人共享設定。 + +> `.vscode/mcp.json` 檔案不需 `mcp` 鍵。 + +```json +{ + "mcp": { + "inputs": [ + { + "type": "promptString", + "id": "gitea_token", + "description": "Gitea 個人存取令牌", + "password": true + } + ], + "servers": { + "gitea-mcp": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITEA_ACCESS_TOKEN", + "docker.gitea.com/gitea-mcp-server" + ], + "env": { + "GITEA_ACCESS_TOKEN": "${input:gitea_token}" + } + } + } + } +} +``` + +### 📥 下載官方二進位版本 + +可至 [官方 Gitea MCP 二進位版本](https://gitea.com/gitea/gitea-mcp/releases) 下載。 + +### 🔧 從原始碼建置 + +可用 Git 下載原始碼: + +```bash +git clone https://gitea.com/gitea/gitea-mcp.git +``` + +建置前請先安裝: + +- make +- Golang(建議 Go 1.24 以上) + +然後執行: + +```bash +make install +``` + +### 📁 加入 PATH + +安裝後,將 gitea-mcp 執行檔複製到系統 PATH 目錄,例如: + +```bash +cp gitea-mcp /usr/local/bin/ +``` + +## 🚀 使用 + +此範例適用於 Cursor,也可在 VSCode 使用插件。 +欲設定 Gitea MCP 伺服器,請將下列內容加入 MCP 設定檔: + +- **stdio 模式** + +```json +{ + "mcpServers": { + "gitea": { + "command": "gitea-mcp", + "args": [ + "-t", + "stdio", + "--host", + "https://gitea.com" + // "--token", "" + ], + "env": { + // "GITEA_HOST": "https://gitea.com", + // "GITEA_INSECURE": "true", + "GITEA_ACCESS_TOKEN": "" + } + } + } +} +``` + +- **http 模式** + +```json +{ + "mcpServers": { + "gitea": { + "url": "http://localhost:8080/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +**預設日誌路徑**: `$HOME/.gitea-mcp/gitea-mcp.log` + +> [!注意] +> 可用命令列參數或環境變數提供 Gitea 主機與存取令牌。 +> 命令列參數優先。 + +一切設定完成後,可在 MCP 聊天框輸入: + +```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 | 拉取請求 | 駁回審查(可附訊息) | +| 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 倉庫! diff --git a/gitea-mcp b/gitea-mcp new file mode 100755 index 0000000..e8188d4 Binary files /dev/null and b/gitea-mcp differ diff --git a/gitea-mcp_Linux_x86_64.tar.gz b/gitea-mcp_Linux_x86_64.tar.gz new file mode 100644 index 0000000..74fd48e Binary files /dev/null and b/gitea-mcp_Linux_x86_64.tar.gz differ