diff --git a/README.md b/README.md index 0bb078520daef6f6a6465dbeab9ec57c8c9e314b..220ce40fdccae83e82d39d2f69b9b3519047c333 100644 --- a/README.md +++ b/README.md @@ -1,189 +1,189 @@ -# Gitee Enterprise MCP Server - -Gitee Enterprise MCP Server is a Model Context Protocol (MCP) server implementation for Gitee Enterprise. It provides a set of tools for interacting with Gitee Enterprise API, allowing AI assistants to manage enterprise repositories, issues, pull requests, and more. - -[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=gitee-ent&config=eyJjb21tYW5kIjoibnB4IC15IEBnaXRlZS9tY3AtZ2l0ZWUtZW50QGxhdGVzdCIsImVudiI6eyJHSVRFRV9FTlRfTUNQX0FDQ0VTU19UT0tFTiI6Inh4eHh4In19) - -## Features - -- Interact with Gitee Enterprise repositories, issues, pull requests -- Support for enterprise-level operations and management -- Configurable API base URL to support different Gitee Enterprise instances -- Support for SSE and Stdio transport -- Dynamic toolset enable/disable - -
-Scenario Example - -1. Get specific enterprise issues - ![get_issues](./docs/images/get_issues.png) -2. Improve the issue content - ![update_issue](./docs/images/update_issue.png) -3. Divide subtasks - ![create_sup_issues](./docs/images/create_sub_issues.png) -4. Create PR/Review PR - ![create_pr_and_review](./docs/images/pr_review.png) -
- -## Installation(This step can be skipped directly when starting npx) - -### Prerequisites - -- Go 1.23.0 or higher -- MCP token, [Go to get](https://gitee.com/profile/mcp_gitee_ent_access_tokens) - -### Building from Source - -1. Clone the repository: - ```bash - git clone https://gitee.com/oschina/mcp-gitee-ent.git - cd mcp-gitee-ent - ``` - -2. Build the project: - ```bash - make build - ``` - Move ./bin/mcp-gitee-ent PATH env - -### Use go install - ```bash - go install gitee.com/oschina/mcp-gitee-ent@latest - ``` - -## Usage - -Check mcp-gitee-ent version: - -```bash -mcp-gitee-ent --version -``` - -## MCP Hosts Configuration -
- - - - - -
- -Config example: -- npx -```json -{ - "mcpServers": { - "gitee-ent": { - "command": "npx", - "args": [ - "-y", - "@gitee/mcp-gitee-ent@latest" - ], - "env": { - "GITEE_ENT_API_BASE": "https://api.gitee.com/enterprises", - "GITEE_ENT_MCP_ACCESS_TOKEN": "" - } - } - } -} -``` -- executable -```json -{ - "mcpServers": { - "gitee-ent": { - "command": "mcp-gitee-ent", - "env": { - "GITEE_ENT_API_BASE": "https://api.gitee.com/enterprises", - "GITEE_ENT_MCP_ACCESS_TOKEN": "", - } - } - } -} -``` - -### Command-line Options - -- `--token`: access token -- `--api-base`: Gitee Ent API base URL (default: https://api.gitee.com/enterprises) -- `--version`: Show version information -- `--transport`: Transport type (stdio or sse, default: stdio) -- `--sse-address`: The host and port to start the SSE 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_ENT_MCP_ACCESS_TOKEN`: Gitee MCP ent access token -- `GITEE_ENT_API_BASE`: Gitee ENT 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="update_enterprise_issue,list_enterprise_repositories"` - -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="update_enterprise_issue,list_enterprise_repositories"` - -Note: -- If both `enabled-toolsets` and `disabled-toolsets` are specified, `enabled-toolsets` takes precedence -- Tool names are case-sensitive - -## Available Tools - -The server provides various tools for interacting with Gitee Enterprise: - -| Tool | Category | Description | -|----------------------------------------|---------------|-------------| -| **list_enterprises** | Enterprise | List user's enterprises | -| **list_enterprise_repositories** | Repository | List repositories in an enterprise | -| **create_enterprise_repository** | Repository | Create a repository in an enterprise | -| **create_enterprise_repo_release** | Repository | Create a release for repository | -| **list_enterprise_repo_releases** | Repository | List releases for repository | -| **get_enterprise_repository_file_content** | Repository | Get the content of a specific file in the repository | -| **get_enterprise_repo_tree** | Repository | Get the tree structure of a repository | -| **list_enterprise_pulls** | Pull Request | List enterprise pull requests | -| **create_enterprise_repo_pull** | Pull Request | Create a pull request for repository | -| **merge_enterprise_pull** | Pull Request | Merge a pull request | -| **get_enterprise_pull_detail** | Pull Request | Get pull request detail | -| **update_enterprise_pull** | Pull Request | Update a pull request | -| **get_enterprise_pull_diff** | Pull Request | Get pull request diff | -| **comment_enterprise_pull** | Pull Request | Comment on a pull request | -| **list_enterprise_pull_comments** | Pull Request | List pull request comments | -| **create_enterprise_issue** | Issue | Create an issue | -| **update_enterprise_issue** | Issue | Update an issue | -| **get_enterprise_issue_detail** | Issue | Get issue detail | -| **list_enterprise_issues** | Issue | List issues | -| **comment_enterprise_issue** | Issue | Comment on an issue | -| **list_enterprise_issue_comments** | Issue | List issue comments | -| **get_user_info** | User | Get user info | -| **list_enterprise_members** | Member | List members of an enterprise | -| **list_enterprise_groups** | Group | List groups in an enterprise | -| **list_enterprise_labels** | Label | List labels of an enterprise | -| **list_programs** | Program | List programs of an enterprise | -| **list_scrum_sprints** | Program | List Scrum Sprints | -| **create_scrum_sprint** | Program | Create a Scrum Sprint | -| **list_scrum_versions** | Program | List Scrum Versions | -| **list_issue_types** | Issue Type | List issue types | -| **list_issue_type_states** | Issue State | List issue states | - -## 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 企业版 MCP 服务器 + +Gitee 企业版 MCP 服务器是 Gitee 企业版的模型上下文协议（MCP）服务器实现。它提供了一组工具，用于与 Gitee 企业版 API 进行交互，使 AI 助手能够管理企业仓库、问题、拉取请求等。 + +[![安装 MCP 服务器](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=gitee-ent&config=eyJjb21tYW5kIjoibnB4IC15IEBnaXRlZS9tY3AtZ2l0ZWUtZW50QGxhdGVzdCIsImVudiI6eyJHSVRFRV9FTlRfTUNQX0FDQ0VTU19UT0tFTiI6Inh4eHh4In19) + +## 功能特性 + +- 与 Gitee 企业版仓库、问题、拉取请求进行交互 +- 支持企业级操作和管理 +- 可配置 API 基础 URL 以支持不同的 Gitee 企业版实例 +- 支持 SSE 和 Stdio 传输 +- 动态工具集启用/禁用 + +
+场景示例 + +1. 获取特定企业问题 + ![get_issues](./docs/images/get_issues.png) +2. 改进问题内容 + ![update_issue](./docs/images/update_issue.png) +3. 划分子任务 + ![create_sup_issues](./docs/images/create_sub_issues.png) +4. 创建 PR/审查 PR + ![create_pr_and_review](./docs/images/pr_review.png) +
+ +## 安装（npx 启动可直接跳过该步骤） + +### 前提条件 + +- Go 1.23.0 或更高版本 +- MCP 令牌，[前往获取](https://gitee.com/profile/mcp_gitee_ent_access_tokens) + +### 从源码构建 + +1. 克隆仓库： + ```bash + git clone https://gitee.com/oschina/mcp-gitee-ent.git + cd mcp-gitee-ent + ``` + +2. 构建项目： + ```bash + make build + ``` + 将 ./bin/mcp-gitee-ent 添加到 PATH 环境变量 + +### 使用 go install + ```bash + go install gitee.com/oschina/mcp-gitee-ent@latest + ``` + +## 使用方法 + +检查 mcp-gitee-ent 版本： + +```bash +mcp-gitee-ent --version +``` + +## MCP 主机配置 +
+ + + + + +
+ +配置示例： +- npx +```json +{ + "mcpServers": { + "gitee-ent": { + "command": "npx", + "args": [ + "-y", + "@gitee/mcp-gitee-ent@latest" + ], + "env": { + "GITEE_ENT_API_BASE": "https://api.gitee.com/enterprises", + "GITEE_ENT_MCP_ACCESS_TOKEN": "" + } + } + } +} +``` +- 可执行文件 +```json +{ + "mcpServers": { + "gitee-ent": { + "command": "mcp-gitee-ent", + "env": { + "GITEE_ENT_API_BASE": "https://api.gitee.com/enterprises", + "GITEE_ENT_MCP_ACCESS_TOKEN": "", + } + } + } +} +``` + +### 命令行选项 + +- `--token`: 访问令牌 +- `--api-base`: Gitee Ent API 基础 URL (默认: https://api.gitee.com/enterprises) +- `--version`: 显示版本信息 +- `--transport`: 传输类型 (stdio 或 sse, 默认: stdio) +- `--sse-address`: 启动 SSE 服务器的主机和端口 (默认: localhost:8000) +- `--enabled-toolsets`: 以逗号分隔的要启用的工具列表 (如果指定，仅启用这些工具) +- `--disabled-toolsets`: 以逗号分隔的要禁用的工具列表 + +### 环境变量 + +您还可以使用环境变量配置服务器： + +- `GITEE_ENT_MCP_ACCESS_TOKEN`: Gitee MCP 企业访问令牌 +- `GITEE_ENT_API_BASE`: Gitee ENT API 基础 URL +- `ENABLED_TOOLSETS`: 以逗号分隔的要启用的工具列表 +- `DISABLED_TOOLSETS`: 以逗号分隔的要禁用的工具列表 + +### 工具集管理 + +工具集管理支持两种模式： + +1. 启用指定工具（白名单模式）： + - 使用 `--enabled-toolsets` 参数或 `ENABLED_TOOLSETS` 环境变量 + - 指定后，仅列出的工具将被启用，其他工具将被禁用 + - 示例: `--enabled-toolsets="update_enterprise_issue,list_enterprise_repositories"` + +2. 禁用指定工具（黑名单模式）： + - 使用 `--disabled-toolsets` 参数或 `DISABLED_TOOLSETS` 环境变量 + - 指定后，列出的工具将被禁用，其他工具将被启用 + - 示例: `--disabled-toolsets="update_enterprise_issue,list_enterprise_repositories"` + +注意： +- 如果同时指定了 `enabled-toolsets` 和 `disabled-toolsets`，`enabled-toolsets` 优先 +- 工具名称区分大小写 + +## 可用工具 + +服务器提供各种工具用于与 Gitee 企业版交互： + +| 工具 | 类别 | 描述 | +|----------------------------------------|---------------|------| +| **list_enterprises** | 企业 | 列出用户的所属企业 | +| **list_enterprise_repositories** | 仓库 | 列出企业中的仓库 | +| **create_enterprise_repository** | 仓库 | 在企业中创建仓库 | +| **create_enterprise_repo_release** | 仓库 | 为仓库创建发布版本 | +| **list_enterprise_repo_releases** | 仓库 | 列出仓库的发布版本 | +| **get_enterprise_repository_file_content** | 仓库 | 获取仓库中特定文件的内容 | +| **get_enterprise_repo_tree** | 仓库 | 获取仓库的树状结构 | +| **list_enterprise_pulls** | 拉取请求 | 列出企业拉取请求 | +| **create_enterprise_repo_pull** | 拉取请求 | 为仓库创建拉取请求 | +| **merge_enterprise_pull** | 拉取请求 | 合并拉取请求 | +| **get_enterprise_pull_detail** | 拉取请求 | 获取拉取请求详情 | +| **update_enterprise_pull** | 拉取请求 | 更新拉取请求 | +| **get_enterprise_pull_diff** | 拉取请求 | 获取拉取请求差异 | +| **comment_enterprise_pull** | 拉取请求 | 评论拉取请求 | +| **list_enterprise_pull_comments** | 拉取请求 | 列出拉取请求评论 | +| **create_enterprise_issue** | 问题 | 创建问题 | +| **update_enterprise_issue** | 问题 | 更新问题 | +| **get_enterprise_issue_detail** | 问题 | 获取问题详情 | +| **list_enterprise_issues** | 问题 | 列出问题 | +| **comment_enterprise_issue** | 问题 | 评论问题 | +| **list_enterprise_issue_comments** | 问题 | 列出问题评论 | +| **get_user_info** | 用户 | 获取用户信息 | +| **list_enterprise_members** | 成员 | 列出企业成员 | +| **list_enterprise_groups** | 群组 | 列出企业群组 | +| **list_enterprise_labels** | 标签 | 列出企业标签 | +| **list_programs** | 项目 | 列出企业项目 | +| **list_scrum_sprints** | Scrum 迭代 | 列出 Scrum 迭代 | +| **create_scrum_sprint** | Scrum 迭代 | 创建 Scrum 迭代 | +| **list_scrum_versions** | Scrum 版本 | 列出 Scrum 版本 | +| **list_issue_types** | 问题类型 | 列出问题类型 | +| **list_issue_type_states** | 问题状态 | 列出问题状态 | + +## 贡献 + +我们欢迎开源社区的贡献！如果您想为该项目做贡献，请遵循以下指南： + +1. Fork 仓库。 +2. 为您的功能或 bug 修复创建一个新分支。 +3. 进行更改并确保代码有良好的文档说明。 +4. 提交带有清晰描述的拉取请求。 + +有关更多信息，请参阅 [CONTRIBUTING](CONTRIBUTING.md) 文件。 \ No newline at end of file