diff --git a/README.md b/README.md index 02e71a9d65409a655e03552794432b3ce3336bd1..8f92c4f9720e755a53aaa90b117f985fed7e1ce6 100644 --- a/README.md +++ b/README.md @@ -1,187 +1,148 @@ -# 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. -## Features +# Gitee Enterprise MCP Server -- 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 +Gitee Enterprise MCP Server 是一个面向企业用户的 Model Context Provider (MCP) 服务，专为 Gitee 企业版设计。它支持多种工具操作，包括但不限于项目管理、代码仓库管理、Issue 追踪、Pull Request 处理等，旨在为开发者提供便捷的上下文访问接口。 -
-Scenario Example +## Features -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) -
+- 支持 Gitee 企业版的项目管理、代码仓库管理等核心功能 +- 提供完整的 Issue 生命周期管理：创建、更新、评论、获取详情等 +- Pull Request 操作支持：创建、更新、评论、获取差异等 +- Scrum 相关工具：冲刺（Sprint）和版本（Version）管理 +- 企业成员、组织、项目等元数据获取 +- 文件内容与仓库树结构访问 +- 通过 MCP 协议为 IDE 插件提供服务支持 -## Installation(This step can be skipped directly when starting npx) +## Installation ### Prerequisites -- Go 1.23.0 or higher -- MCP token, [Go to get](https://gitee.com/profile/mcp_gitee_ent_access_tokens) +- Golang 1.23 或以上版本（用于从源码构建） +- Node.js（用于通过 `npx` 启动） +- Gitee 企业版账户及访问权限 +- 网络访问权限以连接 Gitee 企业 API ### Building from Source -1. Clone the repository: +1. 克隆仓库： ```bash - git clone https://gitee.com/oschina/mcp-gitee-ent.git - cd mcp-gitee-ent + git clone https://github.com/your-repo/gitee-mcp-server.git + cd gitee-mcp-server ``` -2. Build the project: +2. 安装依赖并构建： ```bash - make build + go mod download + go build -o mcp-gitee-ent main.go ``` - Move ./bin/mcp-gitee-ent PATH env -### Use go install +3. 启动服务： ```bash - go install gitee.com/oschina/mcp-gitee-ent@latest + ./mcp-gitee-ent ``` -## Usage +### Use `go install` -Check mcp-gitee-ent version: +如果你只想快速安装，可以通过以下命令： ```bash -mcp-gitee-ent --version +go install github.com/gitee-enterprise/mcp-gitee-ent@latest ``` -## 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": "", - } - } - } -} +然后运行： + +```bash +mcp-gitee-ent ``` +## Usage + +### MCP Hosts Configuration + +你需要配置 MCP 客户端以连接 Gitee Enterprise MCP Server。通常通过 IDE 插件或 MCP 客户端配置主机地址和端口（默认 `localhost:8000`）。 + ### 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 +支持的命令行参数包括： + +```bash +mcp-gitee-ent --help +``` + +- `--transport`: 指定传输协议（默认为 `tcp`） +- `--address`: 指定监听地址（默认为 `:8000`） +- `--enable-tools`: 指定启用的工具集（以逗号分隔） +- `--disable-tools`: 指定禁用的工具集（以逗号分隔） ### 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 | +- `GITEE_ACCESS_TOKEN`: Gitee 企业版访问令牌 +- `GITEE_API_BASE`: Gitee 企业 API 地址（默认为 `https://gitee.com/api/v5/`） + +## Toolset Management + +### Available Tools + +- **Issue 相关** + - `create_issue` - 创建 Issue + - `update_issue` - 更新 Issue + - `get_issue_detail` - 获取 Issue 详情 + - `list_issues` - 列出 Issues + - `list_issue_comments` - 列出 Issue 的评论 + - `comment_issue` - 评论 Issue + +- **Pull Request 相关** + - `create_pull` - 创建 Pull Request + - `update_pull` - 更新 Pull Request + - `get_pull_detail` - 获取 Pull Request 详情 + - `get_pull_diff` - 获取 Pull Request 差异 + - `list_pulls` - 列出 Pull Request + - `list_pull_comments` - 列出 Pull Request 的评论 + - `comment_pull` - 评论 Pull Request + - `merge_pull` - 合并 Pull Request + +- **仓库相关** + - `list_repository` - 列出企业项目 + - `create_repository` - 创建仓库 + - `get_file_content` - 获取文件内容 + - `get_repo_tree` - 获取仓库目录树 + - `create_release` - 创建发布版本 + - `list_releases` - 列出发布版本 + +- **组织与成员** + - `list_enterprises` - 列出企业 + - `list_ent_groups` - 列出企业组 + - `list_ent_members` - 列出企业成员 + - `get_user_info` - 获取用户信息 + +- **Scrum 支持** + - `list_scrum_versions` - 列出 Scrum 版本 + - `list_scrum_sprints` - 列出 Scrum 冲刺 + - `create_scrum_sprint` - 创建 Scrum 冲刺 + +- **元数据** + - `list_labels` - 列出企业标签 + - `list_issue_types` - 列出 Issue 类型 + - `list_issue_type_states` - 列出 Issue 状态 + - `list_programs` - 列出项目计划 ## Contribution -We welcome contributions from the open-source community! If you'd like to contribute to this project, please follow these guidelines: +我们欢迎社区贡献！请参考 [CONTRIBUTING.md](CONTRIBUTING.md) 获取详细的贡献指南。 + +## License + +本项目遵循 MIT License。详情请参阅 [LICENSE](LICENSE) 文件。 + +## Contact + +如有问题或建议，请通过以下方式联系我们： + +- GitHub Issue 跟踪 +- Gitee 企业支持邮箱 +- 开发者社区论坛 -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. +**Note**: 本 README 的中文版本请参考 [README_CN.md](README_CN.md)。 \ No newline at end of file