diff --git a/Makefile b/Makefile index ca032f557777ca27eca6b4d017968f24831b65cd..c824c51061b32e7920dd77cc04a1aac1f023b20f 100644 --- a/Makefile +++ b/Makefile @@ -6,6 +6,11 @@ GO = go GITEE_OWNER ?= "oschina" GITEE_REPO ?= "mcp-gitee" +# Docker related +DOCKER_REGISTRY ?= docker.io +DOCKER_IMAGE = $(DOCKER_REGISTRY)/$(GITEE_OWNER)/$(GITEE_REPO) +DOCKER_TAG ?= latest + # Flags LDFLAGS = -ldflags "-s -w" BUILD_FLAGS = -o bin/mcp-gitee $(LDFLAGS) @@ -83,3 +88,29 @@ upload-gitee-release: https://gitee.com/api/v5/repos/$(GITEE_OWNER)/$(GITEE_REPO)/releases/$(GITEE_RELEASE_ID)/attach_files; \ done @echo "Upload complete." + +# Docker targets +.PHONY: docker-build docker-push docker-run + +# Build docker image +docker-build: + @echo "Building docker image $(DOCKER_IMAGE):$(DOCKER_TAG)..." + docker build -t $(DOCKER_IMAGE):$(DOCKER_TAG) . + @echo "Docker image build complete." + +# Push docker image to registry +docker-push: + @echo "Pushing docker image $(DOCKER_IMAGE):$(DOCKER_TAG)..." + docker push $(DOCKER_IMAGE):$(DOCKER_TAG) + @echo "Docker image push complete." + +# Run docker container +docker-run: + @echo "Running docker container..." + docker run -it --rm \ + -e GITEE_ACCESS_TOKEN=$(GITEE_ACCESS_TOKEN) \ + -e GITEE_API_BASE=$(GITEE_API_BASE) \ + $(DOCKER_IMAGE):$(DOCKER_TAG) + +# Build and push docker image +docker-release: docker-build docker-push diff --git a/README.md b/README.md index c729c93f8e1659c7cf3cd1d14dd986b789f33d86..b46ac67d8d794fa043303ec9100f516e9a85065b 100644 --- a/README.md +++ b/README.md @@ -64,14 +64,18 @@ mcp-gitee --version **Cursor**: -stdio mode -```bash -mcp-gitee -token -``` - -sse mode -```bash -mcp-gitee -transport sse -token +```json +{ + "mcpServers": { + "gitee": { + "command": "mcp-gitee", + "env": { + "GITEE_API_BASE": "https://gitee.com/api/v5", + "GITEE_ACCESS_TOKEN": "" + } + } + } +} ``` **Windsurf**: @@ -104,6 +108,77 @@ You can also configure the server using environment variables: - `GITEE_ACCESS_TOKEN`: Gitee access token - `GITEE_API_BASE`: Gitee API base URL +## FAQ + +### Connection Issues with MCP Server + +When configuring the MCP client to connect to the MCP server, you might encounter connection issues. Here are the common causes and solutions: + +#### 1. Configuration Issues +##### Access Token Configuration +- `GITEE_ACCESS_TOKEN` environment variable not set or incorrectly set +- Token expired or invalid +- Insufficient token permissions + +##### API Base URL Configuration +- Default: `https://gitee.com/api/v5` +- Custom API address might be misconfigured + +#### 2. Transport Mode Issues +The server supports two transport modes: +- stdio mode (default): +```bash +mcp-gitee -token +``` +- sse mode: +```bash +mcp-gitee -transport sse -token -sse-address localhost:8000 +``` + +Common issues: +- Port occupied in sse mode +- Incorrect transport mode selection +- Network connectivity problems + +#### 3. Environment Configuration Issues +##### Configuration File Location +- Project-level config: `.cursor/mcp.json` +- Global config: `~/.cursor/mcp.json` + +##### Example Configuration +```json +{ + "mcpServers": { + "gitee": { + "command": "mcp-gitee", + "env": { + "GITEE_API_BASE": "https://gitee.com/api/v5", + "GITEE_ACCESS_TOKEN": "" + } + } + } +} +``` + +#### 4. Network-Related Issues +- Firewall blocking connections +- Incorrect proxy configuration +- Unstable network connection +- Server port not open + +#### 5. Permission Issues +- Insufficient file system permissions +- Missing execution permissions +- Limited API access permissions + +#### Troubleshooting Steps +1. Verify configuration file format and location +2. Confirm Access Token validity and permissions +3. Try different transport modes (stdio/sse) +4. Check network connection and firewall settings +5. Review server logs for specific error messages +6. Verify all necessary permissions + ## License This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details. diff --git a/README_CN.md b/README_CN.md index 5b7a136cd4fcb31976efce77e53ab31598eedcd9..7d8291d85d9339e127f37aaa29e3b13b0ffba182 100644 --- a/README_CN.md +++ b/README_CN.md @@ -105,6 +105,77 @@ mcp-gitee -transport sse -token - `GITEE_ACCESS_TOKEN`：Gitee 访问令牌 - `GITEE_API_BASE`：Gitee API 基础 URL +## 常见问题 + +### MCP Server 连接问题 + +在配置 MCP 客户端连接到 MCP 服务器时，您可能会遇到连接问题。以下是常见原因和解决方案： + +#### 1. 配置相关问题 +##### Access Token 配置 +- 环境变量 `GITEE_ACCESS_TOKEN` 未设置或设置错误 +- Token 可能已过期或无效 +- Token 权限不足 + +##### API Base URL 配置 +- 默认使用 `https://gitee.com/api/v5` +- 自定义 API 地址可能配置错误 + +#### 2. 传输模式问题 +服务器支持两种传输模式： +- stdio 模式（默认）： +```bash +mcp-gitee -token +``` +- sse 模式： +```bash +mcp-gitee -transport sse -token -sse-address localhost:8000 +``` + +常见问题： +- sse 模式下端口被占用 +- 传输模式选择不当 +- 网络连接问题 + +#### 3. 环境配置问题 +##### 配置文件位置 +- 项目级配置：`.cursor/mcp.json` +- 全局配置：`~/.cursor/mcp.json` + +##### 配置文件示例 +```json +{ + "mcpServers": { + "gitee": { + "command": "mcp-gitee", + "env": { + "GITEE_API_BASE": "https://gitee.com/api/v5", + "GITEE_ACCESS_TOKEN": "" + } + } + } +} +``` + +#### 4. 网络相关问题 +- 防火墙设置阻止连接 +- 代理配置不正确 +- 网络连接不稳定 +- 服务器端口未开放 + +#### 5. 权限问题 +- 文件系统权限不足 +- 执行权限缺失 +- API 访问权限受限 + +#### 排查步骤 +1. 验证配置文件格式和位置是否正确 +2. 确认 Access Token 的有效性和权限 +3. 尝试不同的传输模式（stdio/sse） +4. 检查网络连接和防火墙设置 +5. 查看服务器日志以获取具体错误信息 +6. 验证所有必要的权限设置 + ## 许可证 本项目采用 MIT 许可证。有关更多详细信息，请参阅 [LICENSE](LICENSE) 文件。 diff --git a/docs/install/cursor.md b/docs/install/cursor.md index f88b28d879722fe72efcc7775655943222f03072..2c71260d689f0317ff4da5739c21486d18d1b6c2 100644 --- a/docs/install/cursor.md +++ b/docs/install/cursor.md @@ -1,11 +1,23 @@ -stdio mode -```bash -mcp-gitee -token -``` -![stdio](./images/cursor_stdio.png) +# 在 Cursor 中配置 mcp-gitee + +根据 [Cursor MCP 文档](https://docs.cursor.com/context/model-context-protocol)，使用 JSON 配置： -sse mode -```bash -mcp-gitee -transport sse -token +```json +{ + "mcpServers": { + "gitee": { + "command": "mcp-gitee", + "env": { + "GITEE_API_BASE": "https://gitee.com/api/v5", + "GITEE_ACCESS_TOKEN": "" + } + } + } +} ``` -![sse](./images/cursor_sse.png) \ No newline at end of file + +将此配置添加到以下位置之一： +- **项目级配置**: 在项目根目录下创建 `.cursor/mcp.json` 文件 +- **全局配置**: 在你的主目录下创建 `~/.cursor/mcp.json` 文件 + +![cursor-config](./images/cursor_stdio.png) \ No newline at end of file