diff --git a/README.md b/README.md index 4e9425e03e9bab9147f73c058c9ac40ae1073fc7..2698e75f7884b9df1986195b9632f28faaac8398 100644 --- a/README.md +++ b/README.md @@ -1,199 +1,107 @@ -# 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. -[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=gitee&config=eyJjb21tYW5kIjoibnB4IC15IEBnaXRlZS9tY3AtZ2l0ZWVAbGF0ZXN0IiwiZW52Ijp7IkdJVEVFX0FDQ0VTU19UT0tFTiI6Ijx5b3VyIHBlcnNvbmFsIGFjY2VzcyB0b2tlbj4ifX0%3D) +# Gitee MCP Server -## Features +MCP（Model Communication Protocol）服务器实现，专为与 Gitee 平台集成而设计，支持通过 MCP 工具操作 Gitee 仓库、问题、Pull Request 等资源。 -- 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 +## 功能特点 -
-Practical scenario: Obtain Issue from the repository, implement and create a Pull Request +- **问题管理**：创建、列出、更新问题，添加评论，列出评论。 +- **Pull Request 管理**：创建、列出、更新 Pull Request，添加评论，列出评论，合并 Pull Request。 +- **仓库管理**：创建仓库、Fork 仓库、列出用户仓库、搜索仓库。 +- **发布管理**：创建发布、列出发布。 +- **文件内容**：获取仓库中任意文件的内容。 +- **通知管理**：列出用户的通知。 +- **用户信息**：获取认证用户信息、搜索用户。 -1. Get repository Issues -![get_repo_issues](./docs/images/get_repo_issues.jpg) -2. Implement coding & create Pull Request based on Issue details -![implement_issue](./docs/images/implement_issue.jpg) -3. Comment & Close Issue -![comment_and_close_issue](./docs/images/comment_and_close_issue.jpg) -
+## 安装 -## Installation(This step can be skipped directly when starting npx) +### 使用 `go install` 安装 -### Prerequisites +如果已安装 Go 1.23 或更高版本，可以直接使用以下命令安装： -- Go 1.23.0 or higher -- Gitee account with an access token, [Go to get](https://gitee.com/profile/personal_access_tokens) +```bash +go install gitee.com/ai-assistant/mcp-gitee@latest +``` -### Building from Source +### 从源码构建 -1. Clone the repository: +1. 克隆仓库： ```bash - git clone https://gitee.com/oschina/mcp-gitee.git + git clone https://gitee.com/ai-assistant/mcp-gitee.git cd mcp-gitee ``` -2. Build the project: +2. 构建项目： ```bash make build ``` - Move ./bin/mcp-gitee PATH env -### Use go install - ```bash - go install gitee.com/oschina/mcp-gitee@latest - ``` +## 使用方法 + +### MCP Hosts 配置 + +在使用前，确保你的 MCP 客户端配置了正确的 Hosts 地址，默认服务运行在 `localhost:8000`。 -## Usage +### 启动服务 -Check mcp-gitee version: +服务默认使用 HTTP 协议运行在 `:8000` 端口： ```bash -mcp-gitee --version +mcp-gitee ``` -## MCP Hosts Configuration -
- - - - - -
- -config example: [Click to view more application configuration](./docs/install/) -- Connect to the official remote mcp-gitee server (no installation required) -```json -{ - "mcpServers": { - "gitee": { - "url": "https://api.gitee.com/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` +你也可以通过环境变量配置 Gitee 访问 Token 和 API 地址： -- npx -```json -{ - "mcpServers": { - "gitee": { - "command": "npx", - "args": [ - "-y", - "@gitee/mcp-gitee@latest" - ], - "env": { - "GITEE_API_BASE": "https://gitee.com/api/v5", - "GITEE_ACCESS_TOKEN": "" - } - } - } -} +```bash +GITEE_ACCESS_TOKEN=your_token mcp-gitee ``` -- executable -```json -{ - "mcpServers": { - "gitee": { - "command": "mcp-gitee", - "env": { - "GITEE_API_BASE": "https://gitee.com/api/v5", - "GITEE_ACCESS_TOKEN": "" - } - } - } -} + +### 命令行选项 + +- `--transport`：指定传输方式（如 `stdio`, `http`） +- `--addr`：指定监听地址（默认 `:8000`） + +## 工具集管理 + +可通过 `--enable-toolsets` 和 `--disable-toolsets` 参数控制启用或禁用的工具集，例如： + +```bash +mcp-gitee --disable-toolsets=pulls,notifications ``` -### 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 | -| **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. +## 可用工具 + +- `gitee.createIssue` - 创建问题 +- `gitee.listIssues` - 列出问题 +- `gitee.commentIssue` - 评论问题 +- `gitee.updateIssue` - 更新问题 +- `gitee.listIssueComments` - 列出问题评论 +- `gitee.getIssueDetail` - 获取问题详情 +- `gitee.createPull` - 创建 Pull Request +- `gitee.listPulls` - 列出 Pull Request +- `gitee.commentPull` - 评论 Pull Request +- `gitee.mergePull` - 合并 Pull Request +- `gitee.updatePull` - 更新 Pull Request +- `gitee.listPullComments` - 列出 Pull Request 评论 +- `gitee.getPullDetail` - 获取 Pull Request 详情 +- `gitee.createUserRepo` / `gitee.createOrgRepo` / `gitee.createEnterRepo` - 创建仓库 +- `gitee.forkRepository` - Fork 仓库 +- `gitee.listUserRepos` - 列出用户仓库 +- `gitee.searchOpenSourceRepositories` - 搜索开源仓库 +- `gitee.createRelease` - 创建发布 +- `gitee.listReleases` - 列出发布 +- `gitee.getFileContent` - 获取文件内容 +- `gitee.getUserInfo` - 获取用户信息 +- `gitee.searchUsers` - 搜索用户 +- `gitee.listUserNotifications` - 列出用户通知 + +## 协议与许可证 + +本项目遵循 [MIT License](LICENSE)。 + +## 贡献 + +欢迎贡献代码！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取贡献指南。 + +中文贡献者请参阅 [CONTRIBUTING_CN.md](CONTRIBUTING_CN.md)。 \ No newline at end of file