Merge pull request 'docs: refine DevStar MCP Server documentation' (#12) from feat/devstar-mcp-server-docs into main

Reviewed-on: #12
2026-01-07 10:27:36 +00:00
parent d1582d1bb9 735117b9bf
commit a6b4a454f2
1 changed files with 477 additions and 40 deletions
--- a/src/devstar/mcp-server.md
+++ b/src/devstar/mcp-server.md
@@ -1,63 +1,500 @@
+---
+outline: deep
+weight: 6
+---
+
 # MCP Server

-### 快速安装配置MCP Server
+DevStar 内置了 MCP (Model Context Protocol) Server，为 AI 编程助手提供对 DevStar 平台的完整访问能力，包括代码仓库、Issues、Pull Requests、Actions 等所有核心功能。

-在 VS Code 中使用，要快速安装，请使用如下安装按钮。
+## 概述

-[![在 VS Code 中使用 Docker 安装](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}) [![在 VS Code Insiders 中使用 Docker 安装](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=gitea&inputs=[{%22id%22:%22gitea_token%22,%22type%22:%22promptString%22,%22description%22:%22Gitea%20Personal%20Access%20Token%22,%22password%22:true}]&config={%22command%22:%22docker%22,%22args%22:[%22run%22,%22-i%22,%22--rm%22,%22-e%22,%22GITEA_ACCESS_TOKEN%22,%22docker.gitea.com/gitea-mcp-server%22],%22env%22:{%22GITEA_ACCESS_TOKEN%22:%22${input:gitea_token}%22}}&quality=insiders)
+DevStar MCP Server 是一个基于 [MCP 协议](https://modelcontextprotocol.io) 的服务端实现，允许 AI 编程助手（如 Claude Code、Cursor、VS Code Copilot）通过标准化的方式访问 DevStar 平台的各项功能。

-也可以在项目中添加到 .vscode/mcp.json 文件如下：
+### 核心特性
+
+- **内置集成**：无需额外部署，DevStar 平台直接提供 MCP Server
+- **完整功能覆盖**：支持仓库、Issue、PR、Actions、Wiki 等所有核心功能
+- **标准协议**：基于 MCP 2024-11-05 协议规范
+- **安全认证**：支持 Bearer Token 认证
+- **HTTP 传输**：通过标准 HTTP POST 请求进行通信
+
+## 架构设计

 ```
+┌─────────────────────────────────────────────────────────┐
+│                    MCP 客户端                           │
+│     (Claude Code / Cursor / VS Code Copilot)           │
+└─────────────────────┬───────────────────────────────────┘
+                      │ HTTP POST /api/mcp
+                      │ Authorization: Bearer <token>
+                      ▼
+┌─────────────────────────────────────────────────────────┐
+│              DevStar MCP Server                         │
+│  • JSON-RPC 消息处理                                     │
+│  • 方法路由: initialize/tools/list/tools/call            │
+│  • 工具执行调度                                          │
+└─────────────────────┬───────────────────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────────────────┐
+│          工具实现层 (10 大类，共 89 个工具)              │
+│  ┌──────────┬──────────┬─────────┬─────────┬────────┐  │
+│  │ actions  │   repo   │  issue  │   pull  │  label │  │
+│  │  (27个)  │  (16个)  │  (11个) │  (4个)  │  (9个) │  │
+│  └──────────┴──────────┴─────────┴─────────┴────────┘  │
+│  ┌──────────┬──────────┬─────────┬─────────┬────────┐  │
+│  │ milestone│  wiki    │ release │user/    │   org  │  │
+│  │  (5个)   │  (6个)   │  (5个)  │search   │ actions │  │
+│  │          │          │         │  (5个)  │ (12个) │  │
+│  └──────────┴──────────┴─────────┴─────────┴────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 快速开始
+
+DevStar MCP Server 提供开箱即用的体验，通过 DevStar VS Code 插件自动配置，无需手动配置。
+
+### 使用 DevStar VS Code 插件（推荐）
+
+**这是最简单的方式，完全自动化配置。**
+
+1. **安装 DevStar VS Code 插件**
+   - 在 VS Code 扩展市场搜索 "DevStar"
+   - 点击安装
+
+2. **登录 DevStar 账号**
+   - 点击 VS Code 左侧的 DevStar 图标
+   - 输入 DevStar 平台地址（如 `https://devstar.cn`）
+   - 输入用户名和访问令牌
+
+3. **自动配置 MCP Server**
+   - 登录后，插件会自动检测运行环境并配置 MCP Server
+   - 容器环境：配置到容器内的 MCP 配置文件（路径因环境而异）
+   - 本地环境：配置到本地 MCP 配置文件（路径因 IDE 而异）
+   - 配置内容自动包含正确的认证令牌和 API 地址
+
+4. **开始使用**
+   - 在 AI 助手中直接对话
+   - AI 助手可以访问 DevStar 平台的所有功能
+
+### 手动配置（高级用户）
+
+如果你需要手动配置（不使用 DevStar VS Code 插件），请按照以下步骤：
+
+#### 1. 获取访问令牌
+
+在 DevStar 平台创建 Personal Access Token：
+
+1. 登录 DevStar 平台
+2. 进入 **设置** → **应用** → **访问令牌**
+3. 点击 **生成新令牌**
+4. 设置令牌名称
+5. 选择权限范围（建议至少包含 `read:user`、`read:repository`、`write:issue` 等）
+6. 复制生成的令牌（注意：令牌只显示一次）
+
+#### 2. 根据你的 AI 编程环境配置
+
+**Claude Code**
+
+配置文件位置：
+- macOS/Linux: `~/.claude/mcp_servers.json`
+- Windows: `%APPDATA%\Claude\mcp_servers.json`
+
+```json
 {
-    "inputs": [
-      {
-        "type": "promptString",
-        "id": "gitea_token",
-        "description": "Gitea 个人访问令牌",
-        "password": true
-      }
-    ],
-    "servers": {
-      "gitea-mcp": {
-        "command": "docker",
-        "args": [
-          "run",
-          "-i",
-          "--rm",
-          "-e",
-          "GITEA_HOST",
-          "-e",
-          "GITEA_ACCESS_TOKEN",
-          "docker.gitea.com/gitea-mcp-server"
-        ],
-        "env": {
-          "GITEA_HOST": "<Your Gitea Host>",
-          "GITEA_ACCESS_TOKEN": "${input:gitea_token}"
-        }
+  "mcpServers": {
+    "devstar": {
+      "url": "https://devstar.cn/api/mcp",
+      "headers": {
+        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
+  }
 }
 ```

-### MCP Server使用注意事项
+**Cursor / Continue**

-#### Copilot（VS Code）
+配置文件位置：
+- macOS/Linux: `~/.cursor/mcp.json` 或 `~/.continue/mcpServers/mcp.json`
+- Windows: `%USERPROFILE%\.cursor\mcp.json` 或 `%USERPROFILE%\.continue\mcpServers\mcp.json`

- 配置放在 `.vscode/mcp.json`。重启 VS Code → Copilot 自动加载。
+```json
+{
+  "mcpServers": {
+    "devstar": {
+      "url": "https://devstar.cn/api/mcp",
+      "headers": {
+        "Authorization": "Bearer <YOUR_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+**VS Code Copilot**
+
+配置文件位置：
+- macOS/Linux: `~/.vscode/mcp.json`
+- Windows: `%USERPROFILE%\.vscode\mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "devstar": {
+      "type": "http",
+      "url": "https://devstar.cn/api/mcp",
+      "headers": {
+        "Authorization": "Bearer <YOUR_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+**Trae IDE（容器环境）**
+
+配置文件位置因具体部署环境而异，通常在容器内的某个配置目录中。具体路径请参考 Trae IDE 文档或联系管理员。
+
+> **注意**：
+> - 将 `<YOUR_TOKEN>` 替换为你的访问令牌
+> - 将 `https://devstar.cn` 替换为你的 DevStar 实例地址
+> - Windows 和 Linux 平台的具体配置路径可能因 IDE 版本而异，请参考对应 IDE 的官方文档
+> - 配置完成后需要重启 IDE 以使更改生效
+
+## API 端点
+
+DevStar MCP Server 通过以下端点提供服务：
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/mcp` | POST | MCP JSON-RPC 请求入口 |
+
+### 认证方式
+
+支持两种认证方式：
+
+**方式 1：Authorization Header（推荐）**
+```
+Authorization: Bearer <your_token>
+```
+
+**方式 2：URL 参数**
+```
+/api/mcp?token=<your_token>
+```
+
+## 可用工具
+
+DevStar MCP Server 提供了以下 10 大类工具，共 89 个具体功能：
+
+### 1. Actions 工具 (27个)
+
+**仓库 Actions：**
+| 工具名称 | 描述 |
+|---------|------|
+| `list_repo_action_runs` | 列出仓库 Actions 运行记录 |
+| `get_repo_action_run` | 获取单个 Action 运行详情 |
+| `rerun_repo_action_run` | 重新运行失败的 Action |
+| `cancel_repo_action_run` | 取消正在运行的 Action |
+| `list_repo_action_run_jobs` | 列出 Action 运行的作业 |
+| `get_repo_action_job_log_preview` | 获取 Action 日志预览 |
+| `download_repo_action_job_log` | 下载 Action 日志到文件 |
+| `list_repo_action_workflows` | 列出仓库 Actions 工作流 |
+| `get_repo_action_workflow` | 获取单个工作流详情 |
+| `dispatch_repo_action_workflow` | 触发 Actions 工作流 |
+| `list_repo_action_jobs` | 列出 Actions 作业 |
+| `list_repo_action_secrets` | 列出仓库 Actions 密钥 |
+| `list_repo_action_variables` | 列出仓库 Actions 变量 |
+| `get_repo_action_variable` | 获取仓库 Actions 变量 |
+| `create_repo_action_variable` | 创建仓库 Actions 变量 |
+| `update_repo_action_variable` | 更新仓库 Actions 变量 |
+| `delete_repo_action_variable` | 删除仓库 Actions 变量 |
+| `upsert_repo_action_secret` | 创建或更新仓库 Actions 密钥 |
+| `delete_repo_action_secret` | 删除仓库 Actions 密钥 |
+
+**组织 Actions：**
+| 工具名称 | 描述 |
+|---------|------|
+| `list_org_action_secrets` | 列出组织 Actions 密钥 |
+| `list_org_action_variables` | 列出组织 Actions 变量 |
+| `get_org_action_variable` | 获取组织 Actions 变量 |
+| `create_org_action_variable` | 创建组织 Actions 变量 |
+| `update_org_action_variable` | 更新组织 Actions 变量 |
+| `delete_org_action_variable` | 删除组织 Actions 变量 |
+| `upsert_org_action_secret` | 创建或更新组织 Actions 密钥 |
+| `delete_org_action_secret` | 删除组织 Actions 密钥 |
+
+### 2. 仓库/分支/标签工具 (16个)
+
+| 工具名称 | 描述 |
+|---------|------|
+| `create_branch` | 创建新分支 |
+| `delete_branch` | 删除分支 |
+| `list_branches` | 列出所有分支 |
+| `create_tag` | 创建标签 |
+| `delete_tag` | 删除标签 |
+| `get_tag` | 获取标签详情 |
+| `list_tags` | 列出所有标签 |
+| `list_repo_commits` | 列出仓库提交记录 |
+| `create_file` | 创建文件 |
+| `update_file` | 更新文件 |
+| `delete_file` | 删除文件 |
+| `get_file_content` | 获取文件内容和元数据 |
+| `get_dir_content` | 获取目录内容列表 |
+| `list_my_repos` | 列出我的仓库 |
+| `create_repo` | 创建仓库 |
+| `fork_repo` | Fork 仓库 |
+
+### 3. Issue 工具 (11个)
+
+| 工具名称 | 描述 |
+|---------|------|
+| `get_issue_by_index` | 根据索引获取 Issue |
+| `list_repo_issues` | 列出仓库 Issues |
+| `create_issue` | 创建 Issue |
+| `edit_issue` | 编辑 Issue |
+| `create_issue_comment` | 创建 Issue 评论 |
+| `edit_issue_comment` | 编辑 Issue 评论 |
+| `get_issue_comments_by_index` | 获取 Issue 评论 |
+| `add_issue_labels` | 添加 Issue 标签 |
+| `remove_issue_label` | 移除单个 Issue 标签 |
+| `replace_issue_labels` | 替换 Issue 标签 |
+| `clear_issue_labels` | 清除 Issue 标签 |
+
+### 4. Pull Request 工具 (4个)
+
+| 工具名称 | 描述 |
+|---------|------|
+| `get_pull_request_by_index` | 根据索引获取 Pull Request |
+| `list_repo_pull_requests` | 列出 Pull Requests |
+| `create_pull_request` | 创建 Pull Request |
+| `create_pull_request_reviewer` | 添加 PR 审查者 |
+
+### 5. 标签工具 (9个)
+
+**仓库标签：**
+| 工具名称 | 描述 |
+|---------|------|
+| `list_repo_labels` | 列出仓库标签 |
+| `get_repo_label` | 获取单个标签 |
+| `create_repo_label` | 创建仓库标签 |
+| `edit_repo_label` | 编辑仓库标签 |
+| `delete_repo_label` | 删除仓库标签 |
+
+**组织标签：**
+| 工具名称 | 描述 |
+|---------|------|
+| `list_org_labels` | 列出组织标签 |
+| `create_org_label` | 创建组织标签 |
+| `edit_org_label` | 编辑组织标签 |
+| `delete_org_label` | 删除组织标签 |
+
+### 6. 里程碑工具 (5个)
+
+| 工具名称 | 描述 |
+|---------|------|
+| `get_milestone` | 获取里程碑详情 |
+| `list_milestones` | 列出所有里程碑 |
+| `create_milestone` | 创建里程碑 |
+| `edit_milestone` | 编辑里程碑 |
+| `delete_milestone` | 删除里程碑 |
+
+### 7. Wiki 工具 (6个)
+
+| 工具名称 | 描述 |
+|---------|------|
+| `list_wiki_pages` | 列出所有 Wiki 页面 |
+| `get_wiki_page` | 获取 Wiki 页面内容 |
+| `get_wiki_revisions` | 获取 Wiki 页面修订历史 |
+| `create_wiki_page` | 创建 Wiki 页面 |
+| `update_wiki_page` | 更新 Wiki 页面 |
+| `delete_wiki_page` | 删除 Wiki 页面 |
+
+### 8. Release 工具 (5个)
+
+| 工具名称 | 描述 |
+|---------|------|
+| `list_releases` | 列出发布版本 |
+| `get_release` | 获取发布版本详情 |
+| `get_latest_release` | 获取最新发布版本 |
+| `create_release` | 创建发布版本 |
+| `delete_release` | 删除发布版本 |
+
+### 9. 用户与搜索工具 (5个)
+
+| 工具名称 | 描述 |
+|---------|------|
+| `get_my_user_info` | 获取当前用户信息 |
+| `get_user_orgs` | 获取用户所属组织 |
+| `search_users` | 搜索用户 |
+| `search_repos` | 搜索仓库 |
+| `search_org_teams` | 搜索组织团队 |
+
+### 10. 版本工具 (1个)
+
+| 工具名称 | 描述 |
+|---------|------|
+| `get_gitea_mcp_server_version` | 获取 MCP Server 版本 |
+
+## 使用示例
+
+### 示例 1：创建分支
+
+在 Claude Code 中：
+
+```
+请在仓库 devstar/demo 的 main 分支基础上创建一个新分支 feature/new-function
+```
+
+### 示例 2：创建 Issue
+
+在 Cursor 中：
+
+```
+帮我创建一个 Issue：
+- 仓库：devstar/docs
+- 标题：更新 MCP Server 文档
+- 描述：添加 DevStar 内置 MCP Server 的使用说明
+```
+
+### 示例 3：查看 PR 状态
+
+在 VS Code Copilot 中：
+
+```
+显示 devstar/devstar 仓库 #54 号 PR 的详细信息
+```
+
+## 独立部署Gitea MCP Server（Docker）
+
+DevStar 平台兼容 Gitea 官方的 Docker 方式独立部署Gitea MCP Server。如果你想使用Gitea MCP Server，请参考 [Gitea MCP Server 官方文档](https://docs.gitea.com/usage/mcp-server) 获取详细的部署和配置说明。
+
+## 支持的客户端
+
+DevStar MCP Server 支持所有遵循 MCP 协议的 AI 编程助手。以下是一些常用的客户端：
+
+### Claude Code
+
+- 配置文件：`~/.claude/mcp_servers.json` (macOS/Linux) 或 `%APPDATA%\Claude\mcp_servers.json` (Windows)
+- 原生支持 HTTP 传输模式
+- [官方文档](https://docs.anthropic.com/claude-code/mcp)
+
+### VS Code Copilot
+
+- 配置文件：`.vscode/mcp.json`
+- 重启 VS Code 后自动加载
 - [官方文档](https://vscode.js.cn/docs/copilot/customization/mcp-servers)

+### Cursor

-
-#### Cursor
-
- 配置放在 `.cursor/mcp.json` 或 `.vscode/mcp.json`。
- 打开 Cursor → 会提示“检测到 MCP Server”。点 Enable 即可。
+- 配置文件：`.cursor/mcp.json` 或 `.vscode/mcp.json`
+- 打开 Cursor 后会提示"检测到 MCP Server"，点击 Enable 即可
 - [官方文档](https://cursor.com/cn/docs/context/mcp)

+### Continue

+- 配置文件：`.continue/mcpServers/mcp.json`
+- [官方文档](https://docs.continue.dev/customize/deep-dives/mcp)

-#### Continue
+### DevStar VS Code 插件（推荐）

- 配置放在 `.continue/mcpServers/mcp.json`
- [官方文档](https://docs.continue.dev/customize/deep-dives/mcp)
+- **自动配置**：插件会自动检测环境并配置 MCP Server
+- **开箱即用**：登录 DevStar 账号后即可使用
+- **多环境支持**：支持本地和容器环境
+
+## 故障排除
+
+### 常见问题
+
+**Q: DevStar VS Code 插件无法自动配置 MCP**
+```
+A: 检查以下项：
+   - 确认已正确登录 DevStar 账号
+   - 检查配置文件是否有写入权限
+   - 查看插件日志（输出面板）
+   - 尝试手动配置（见上方"手动配置"部分）
+```
+
+**Q: MCP Server 连接失败**
+```
+A: 检查以下项：
+   - DevStar 实例地址是否正确
+   - 访问令牌是否有效且未过期
+   - 网络连接是否正常
+   - 防火墙是否允许访问
+   - IDE 是否已重启以加载配置
+```
+
+**Q: AI 助手无法访问 DevStar 功能**
+```
+A: 确认：
+   - MCP Server 配置文件路径正确
+   - Bearer Token 格式正确（以 "Bearer " 开头）
+   - 访问令牌具有足够的权限
+   - IDE 已重启以加载新配置
+```
+
+**Q: Token 过期或失效**
+```
+A: 访问令牌有过期时间。如果过期，需要：
+   1. 重新生成令牌
+   2. 更新 MCP 客户端配置
+   3. 重启 IDE
+```
+
+**Q: 配置文件路径在哪里？**
+```
+A: 配置文件路径取决于你使用的 IDE：
+   - Claude Code: ~/.claude/mcp_servers.json (macOS/Linux) 或 %APPDATA%\Claude\mcp_servers.json (Windows)
+   - Cursor: ~/.cursor/mcp.json (macOS/Linux) 或 %USERPROFILE%\.cursor\mcp.json (Windows)
+   - Continue: ~/.continue/mcpServers/mcp.json (macOS/Linux) 或 %USERPROFILE%\.continue\mcpServers\mcp.json (Windows)
+   - VS Code Copilot: ~/.vscode/mcp.json (macOS/Linux) 或 %USERPROFILE%\.vscode\mcp.json (Windows)
+
+   注：具体路径可能因 IDE 版本而异，请参考对应 IDE 的官方文档
+```
+
+**Q: 工具调用失败**
+```
+A: 确认：
+   - 访问令牌具有足够的权限
+   - 仓库名称和所有者名称正确
+   - 用户有相应操作的权限
+```
+
+## 技术实现
+
+DevStar MCP Server 基于 [mcp-go](https://github.com/mark3labs/mcp-go) 库实现，采用以下技术栈：
+
+- **协议版本**: MCP 2024-11-05
+- **传输方式**: HTTP POST
+- **认证方式**: Bearer Token
+- **数据格式**: JSON-RPC 2.0
+
+### 核心组件
+
+```
+services/mcp/
+├── config.go          # MCP 配置
+├── context/           # Token 上下文管理
+├── gitea/             # Gitea SDK 客户端
+├── operation/         # MCP 工具实现
+│   ├── actions/       # CI/CD Actions 工具
+│   ├── issue/         # Issue 工具
+│   ├── pull/          # Pull Request 工具
+│   ├── repo/          # 仓库工具
+│   └── ...
+└── log/               # 日志模块
+
+routers/api/mcp/
+├── mcp.go             # 请求处理入口
+└── server/            # MCP Server 实现
+```
+
+## 更多资源
+
+- [MCP 协议规范](https://modelcontextprotocol.io)
+- [DevStar 平台文档](https://devstar.cn/devstar/docs)
+- [Claude Code 文档](https://docs.anthropic.com/claude-code)
+- [Cursor MCP 文档](https://cursor.com/cn/docs/context/mcp)
+- [VS Code Copilot MCP 文档](https://vscode.js.cn/docs/copilot/customization/mcp-servers)