From 9a921da9db8eff99a3287d5c17cdc276125d6e75 Mon Sep 17 00:00:00 2001 From: gitee-bot Date: Mon, 26 May 2025 06:16:53 +0000 Subject: [PATCH] Update README.md --- README.md | 267 +++++++++++++++++++++--------------------------------- 1 file changed, 102 insertions(+), 165 deletions(-) diff --git a/README.md b/README.md index 02e71a9..9529bac 100644 --- a/README.md +++ b/README.md @@ -1,187 +1,124 @@ # 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. +A Model Control Protocol (MCP) server implementation for seamless integration with Gitee Enterprise, enabling AI agents to interact with Gitee's enterprise features through standardized tool interfaces. ## Features +- **Comprehensive Tool Coverage** + - Issue Management: Create, update, comment, and list issues + - Pull Request Handling: Create, review, merge, and manage pull requests + - Repository Operations: Repository creation, file content access, and release management + - Enterprise Management: Member, group, and program administration + - Agile Tools: Scrum sprint and version tracking +- **Flexible Deployment** + - Docker-ready image with multi-architecture support + - Native binary execution via Go installation + - NPM package distribution for cross-platform compatibility +- **Security & Authentication** + - Bearer token and cookie-based authentication + - Configurable API endpoint support +- **Extensible Architecture** + - Modular toolset management + - Customizable request/response handling + +## Installation + +### Quick Start with Docker (Recommended) +```bash +# Build and run using Docker +docker build -t gitee-mcp-server . +docker run -p 8000:8000 gitee-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 - -
-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: +### Binary Installation +1. **From Source** ```bash - git clone https://gitee.com/oschina/mcp-gitee-ent.git - cd mcp-gitee-ent + # Clone repository first + go build -o mcp-gitee-ent main.go + ./mcp-gitee-ent --help ``` -2. Build the project: +2. **Using Go Install** ```bash - make build + go install github.com/gitee-enterprise/mcp-gitee-ent@latest ``` - Move ./bin/mcp-gitee-ent PATH env -### Use go install - ```bash - go install gitee.com/oschina/mcp-gitee-ent@latest - ``` +### NPM Package (Cross-platform) +```bash +npm install -g mcp-gitee-ent +mcp-gitee-ent --help +``` ## Usage -Check mcp-gitee-ent version: +### Configuration +Set required environment variables: +```bash +export GITEE_ACCESS_TOKEN=your_personal_token +export GITEE_API_BASE=https://api.gitee.com/enterprise +``` +### Command-line Options ```bash -mcp-gitee-ent --version +./mcp-gitee-ent --port 8000 --disabled-toolsets "scrum,enterprise" ``` -## 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": "" - } - } - } -} +**Available Options:** +- `--port`: Server port (default: 8000) +- `--disabled-toolsets`: Comma-separated list of toolsets to disable +- `--enabled-toolsets`: Comma-separated list of toolsets to enable exclusively + +### MCP Host Configuration +Configure your MCP client to connect to: ``` -- executable -```json -{ - "mcpServers": { - "gitee-ent": { - "command": "mcp-gitee-ent", - "env": { - "GITEE_ENT_API_BASE": "https://api.gitee.com/enterprises", - "GITEE_ENT_MCP_ACCESS_TOKEN": "", - } - } - } -} +http://localhost:8000 ``` -### Command-line Options +## Toolset Management + +### Available Toolsets +| Category | Operations | Status | +|----------------|-------------------------------------|--------| +| Issues | Create, Update, Comment, List | ✅ | +| Pull Requests | Create, Review, Merge, List | ✅ | +| Repositories | Create, File Access, Releases | ✅ | +| Enterprise | Members, Groups, Programs | ✅ | +| Agile | Scrum Sprints, Versions | ✅ | +| Labels | Enterprise-wide label management | ✅ | + +### Customization +Modify tool availability through: +1. Build-time configuration +2. Runtime flags (`--disabled-toolsets`, `--enabled-toolsets`) +3. Environment variables + +## Development + +### Contributing +Please follow the guidelines in [CONTRIBUTING.md](CONTRIBUTING.md) + +### Local Development +```bash +# Generate test binary +make build + +# Run tests +make test +``` + +## Documentation +Detailed installation guides and architecture diagrams are available in the [docs directory](docs/), including: +- Integration guides for Claude, Cline, Cursor, Trae, and Windsurf +- API reference documentation +- Architecture diagrams (PR workflow, issue lifecycle) + +## License +This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details + +## Contact +For questions or enterprise support, please reach out to gitee-enterprise-support@example.com + +--- -- `--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. +**Version:** 0.1.6 +**Architecture:** Multi-architecture Docker image support (AMD64/ARM64) +**Compatibility:** MCP v1 specification compliant \ No newline at end of file -- Gitee