From 59667054a770b8ea47f752b17815ad44de5cd5c1 Mon Sep 17 00:00:00 2001 From: chasecyang <762563911@qq.com> Date: Thu, 20 Mar 2025 10:47:19 +0800 Subject: [PATCH 1/3] =?UTF-8?q?=E6=9B=B4=E6=96=B0Cursor=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E4=B8=BAJSON=E6=A0=BC=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 20 ++++++++++++-------- docs/install/cursor.md | 30 +++++++++++++++++++++--------- 2 files changed, 33 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index c729c93..67f510b 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**: diff --git a/docs/install/cursor.md b/docs/install/cursor.md index f88b28d..2c71260 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 -- Gitee From 9bcd86a1321d33781fe20d336e10dd9e62196297 Mon Sep 17 00:00:00 2001 From: chasecyang <762563911@qq.com> Date: Wed, 26 Mar 2025 21:32:16 +0800 Subject: [PATCH 2/3] docs: add FAQ section about MCP Server connection issues --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README_CN.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+) diff --git a/README.md b/README.md index 67f510b..b46ac67 100644 --- a/README.md +++ b/README.md @@ -108,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 5b7a136..7d8291d 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) 文件。 -- Gitee From fc25f39cb63cc0c72765997a3bf288cebd9786fe Mon Sep 17 00:00:00 2001 From: chasecyang <762563911@qq.com> Date: Wed, 26 Mar 2025 21:42:36 +0800 Subject: [PATCH 3/3] =?UTF-8?q?feat:=20makefile=20=E4=B8=AD=E6=B7=BB?= =?UTF-8?q?=E5=8A=A0=20Docker=20=E6=94=AF=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Makefile | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/Makefile b/Makefile index ca032f5..c824c51 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 -- Gitee