diff --git a/README.md b/README.md index 2ada402869d7155068ca37f911475aa425eddde6..9a1a45fb6b9be87a6f14251dd6ece857aa1dd8b3 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,63 @@ # Gitee MCP Server -Gitee MCP Server is a Model Context Protocol (MCP) server implementation for Gitee. It provides a set of tools for interacting with Gitee's API, allowing AI assistants to manage repositories, issues, pull requests, and more. +Gitee MCP Server 是一个面向 Gitee 的 Model Context Protocol (MCP) 服务器实现。它提供了一组工具用于与 Gitee API 进行交互,使 AI 助手能够管理仓库、问题、拉取请求等内容。 -[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gitee&config=eyJ1cmwiOiJodHRwczovL2FwaS5naXRlZS5jb20vbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIDx5b3VyIHBlcnNvbmFsIGFjY2VzcyB0b2tlbj4ifX0%3D) +[![安装 MCP 服务器](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gitee&config=eyJ1cmwiOiJodHRwczovL2FwaS5naXRlZS5jb20vbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIDx5b3VyIHBlcnNvbmFsIGFjY2VzcyB0b2tlbj4ifX0%3D) -## Features +## 功能特点 -- Interact with Gitee repositories, issues, pull requests, and notifications -- Configurable API base URL to support different Gitee instances -- Command-line flags for easy configuration -- Supports both personal, organization, and enterprise operations -- Dynamic toolset enable/disable +- 与 Gitee 仓库、问题、拉取请求和通知进行交互 +- 可配置的 API 基础 URL,支持不同的 Gitee 实例 +- 命令行参数便于配置 +- 支持个人、组织和企业操作 +- 工具集动态启用/禁用
-Practical scenario: Obtain Issue from the repository, implement and create a Pull Request +实际场景:获取仓库问题,实现编码并创建拉取请求 -1. Get repository Issues +1. 获取仓库问题 ![get_repo_issues](./docs/images/get_repo_issues.jpg) -2. Implement coding & create Pull Request based on Issue details +2. 根据问题详情实现编码并创建拉取请求 ![implement_issue](./docs/images/implement_issue.jpg) -3. Comment & Close Issue +3. 评论并关闭问题 ![comment_and_close_issue](./docs/images/comment_and_close_issue.jpg)
-## Installation(This step can be skipped directly when starting npx) +## 安装(npx 启动可直接跳过该步骤) -### Prerequisites +### 前提条件 -- Go 1.23.0 or higher -- Gitee account with an access token, [Go to get](https://gitee.com/profile/personal_access_tokens) +- Go 1.23.0 或更高版本 +- 拥有访问令牌的 Gitee 账号,[前往获取](https://gitee.com/profile/personal_access_tokens) -### Building from Source +### 从源码构建 -1. Clone the repository: +1. 克隆仓库: ```bash git clone https://gitee.com/oschina/mcp-gitee.git cd mcp-gitee ``` -2. Build the project: +2. 构建项目: ```bash make build ``` - Move ./bin/mcp-gitee PATH env + 将 ./bin/mcp-gitee 添加到 PATH 环境变量 -### Use go install +### 使用 go install 安装 ```bash go install gitee.com/oschina/mcp-gitee@latest ``` -## Usage +## 使用方法 -Check mcp-gitee version: +检查 mcp-gitee 版本: ```bash mcp-gitee --version ``` -## MCP Hosts Configuration +## MCP 主机配置
@@ -66,8 +66,8 @@ mcp-gitee --version
-config example: [Click to view more application configuration](./docs/install/) -- Connect to the official remote mcp-gitee server (no installation required) +配置示例:[点击查看更多应用配置](./docs/install/) +- 连接到官方远程 mcp-gitee 服务器(无需安装) ```json { "mcpServers": { @@ -99,7 +99,7 @@ config example: [Click to view more application configuration](./docs/install/) } } ``` -- executable +- 可执行文件 ```json { "mcpServers": { @@ -114,87 +114,87 @@ config example: [Click to view more application configuration](./docs/install/) } ``` -### Command-line Options - -- `--token`: Gitee access token -- `--api-base`: Gitee API base URL (default: https://gitee.com/api/v5) -- `--version`: Show version information -- `--transport`: Transport type (stdio、sse or http, default: stdio) -- `--address`: The host and port to start the server on (default: localhost:8000) -- `--enabled-toolsets`: Comma-separated list of tools to enable (if specified, only these tools will be enabled) -- `--disabled-toolsets`: Comma-separated list of tools to disable - -### Environment Variables - -You can also configure the server using environment variables: - -- `GITEE_ACCESS_TOKEN`: Gitee access token -- `GITEE_API_BASE`: Gitee API base URL -- `ENABLED_TOOLSETS`: Comma-separated list of tools to enable -- `DISABLED_TOOLSETS`: Comma-separated list of tools to disable - -### Toolset Management - -Toolset management supports two modes: - -1. Enable specified tools (whitelist mode): - - Use `--enabled-toolsets` parameter or `ENABLED_TOOLSETS` environment variable - - Specify after, only listed tools will be enabled, others will be disabled - - Example: `--enabled-toolsets="list_user_repos,get_file_content"` - -2. Disable specified tools (blacklist mode): - - Use `--disabled-toolsets` parameter or `DISABLED_TOOLSETS` environment variable - - Specify after, listed tools will be disabled, others will be enabled - - Example: `--disabled-toolsets="list_user_repos,get_file_content"` - -Note: -- If both `enabled-toolsets` and `disabled-toolsets` are specified, `enabled-toolsets` takes precedence -- Tool names are case-sensitive - -## License - -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details. - -## Available Tools - -The server provides various tools for interacting with Gitee: - -| Tool | Category | Description | -|-------------------------------------|----------|-------------| -| **list_user_repos** | Repository | List user authorized repositories | -| **get_file_content** | Repository | Get the content of a file in a repository | -| **create_user_repo** | Repository | Create a user repository | -| **create_org_repo** | Repository | Create an organization repository | -| **create_enter_repo** | Repository | Create an enterprise repository | -| **fork_repository** | Repository | Fork a repository | -| **create_release** | Repository | Create a release for a repository | -| **list_releases** | Repository | List repository releases | -| **search_open_source_repositories** | Repository | Search open source repositories on Gitee | -| **list_repo_pulls** | Pull Request | List pull requests in a repository | -| **merge_pull** | Pull Request | Merge a pull request | -| **create_pull** | Pull Request | Create a pull request | -| **update_pull** | Pull Request | Update a pull request | -| **get_pull_detail** | Pull Request | Get details of a pull request | -| **comment_pull** | Pull Request | Comment on a pull request | -| **list_pull_comments** | Pull Request | List all comments for a pull request | -| **get_diff_files** | Pull Request | Get a pull request diff files | -| **create_issue** | Issue | Create an issue | -| **update_issue** | Issue | Update an issue | -| **get_repo_issue_detail** | Issue | Get details of a repository issue | -| **list_repo_issues** | Issue | List repository issues | -| **comment_issue** | Issue | Comment on an issue | -| **list_issue_comments** | Issue | List comments on an issue | -| **get_user_info** | User | Get current authenticated user information | -| **search_users** | User | Search for users | -| **list_user_notifications** | Notification | List user notifications | - -## Contribution - -We welcome contributions from the open-source community! If you'd like to contribute to this project, please follow these guidelines: - -1. Fork the repository. -2. Create a new branch for your feature or bug fix. -3. Make your changes and ensure the code is well-documented. -4. Submit a pull request with a clear description of your changes. - -For more information, please refer to the [CONTRIBUTING](CONTRIBUTING.md) file. +### 命令行选项 + +- `--token`: Gitee 访问令牌 +- `--api-base`: Gitee API 基础 URL (默认: https://gitee.com/api/v5) +- `--version`: 显示版本信息 +- `--transport`: 传输类型 (stdio、sse 或 http,默认: stdio) +- `--address`: 启动服务器的主机和端口 (默认: localhost:8000) +- `--enabled-toolsets`: 启用的工具集列表(如果指定,仅启用这些工具) +- `--disabled-toolsets`: 禁用的工具集列表 + +### 环境变量 + +您也可以使用环境变量配置服务器: + +- `GITEE_ACCESS_TOKEN`: Gitee 访问令牌 +- `GITEE_API_BASE`: Gitee API 基础 URL +- `ENABLED_TOOLSETS`: 要启用的工具集列表 +- `DISABLED_TOOLSETS`: 要禁用的工具集列表 + +### 工具集管理 + +工具集管理支持两种模式: + +1. 启用指定工具(白名单模式): + - 使用 `--enabled-toolsets` 参数或 `ENABLED_TOOLSETS` 环境变量 + - 指定后,仅列出的工具会被启用,其他工具将被禁用 + - 示例: `--enabled-toolsets="list_user_repos,get_file_content"` + +2. 禁用指定工具(黑名单模式): + - 使用 `--disabled-toolsets` 参数或 `DISABLED_TOOLSETS` 环境变量 + - 指定后,列出的工具将被禁用,其他工具将被启用 + - 示例: `--disabled-toolsets="list_user_repos,get_file_content"` + +注意: +- 如果同时指定了 `enabled-toolsets` 和 `disabled-toolsets`,`enabled-toolsets` 优先 +- 工具名称区分大小写 + +## 许可证 + +本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。 + +## 可用工具 + +服务器提供多种工具与 Gitee 进行交互: + +| 工具 | 分类 | 描述 | +|-------------------------------------|------------|------| +| **list_user_repos** | 仓库 | 列出用户授权的仓库 | +| **get_file_content** | 仓库 | 获取仓库中文件的内容 | +| **create_user_repo** | 仓库 | 创建用户仓库 | +| **create_org_repo** | 仓库 | 创建组织仓库 | +| **create_enter_repo** | 仓库 | 创建企业仓库 | +| **fork_repository** | 仓库 | 分叉一个仓库 | +| **create_release** | 仓库 | 为仓库创建发布 | +| **list_releases** | 仓库 | 列出仓库发布 | +| **search_open_source_repositories** | 仓库 | 在 Gitee 上搜索开源仓库 | +| **list_repo_pulls** | 拉取请求 | 列出仓库的拉取请求 | +| **merge_pull** | 拉取请求 | 合并拉取请求 | +| **create_pull** | 拉取请求 | 创建拉取请求 | +| **update_pull** | 拉取请求 | 更新拉取请求 | +| **get_pull_detail** | 拉取请求 | 获取拉取请求的详细信息 | +| **comment_pull** | 拉取请求 | 对拉取请求进行评论 | +| **list_pull_comments** | 拉取请求 | 列出拉取请求的所有评论 | +| **get_diff_files** | 拉取请求 | 获取拉取请求的差异文件 | +| **create_issue** | 问题 | 创建问题 | +| **update_issue** | 问题 | 更新问题 | +| **get_repo_issue_detail** | 问题 | 获取仓库问题的详细信息 | +| **list_repo_issues** | 问题 | 列出仓库问题 | +| **comment_issue** | 问题 | 对问题进行评论 | +| **list_issue_comments** | 问题 | 列出问题的评论 | +| **get_user_info** | 用户 | 获取当前认证用户的信息 | +| **search_users** | 用户 | 搜索用户 | +| **list_user_notifications** | 通知 | 列出用户通知 | + +## 贡献 + +我们欢迎开源社区的贡献!如果您想为本项目做贡献,请遵循以下指南: + +1. Fork 仓库。 +2. 为您的功能或 bug 修复创建一个新分支。 +3. 进行修改并确保代码有良好的文档说明。 +4. 提交一个包含清晰描述更改的拉取请求。 + +更多详情请参阅 [CONTRIBUTING](CONTRIBUTING.md) 文件。 \ No newline at end of file