diff --git a/src/devstar/mcp-server.md b/src/devstar/mcp-server.md index 514af5c..9e97869 100644 --- 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 + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 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": "", - "GITEA_ACCESS_TOKEN": "${input:gitea_token}" - } + "mcpServers": { + "devstar": { + "url": "https://devstar.cn/api/mcp", + "headers": { + "Authorization": "Bearer " } } + } } ``` -### 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 " + } + } + } +} +``` + +**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 " + } + } + } +} +``` + +**Trae IDE（容器环境）** + +配置文件位置因具体部署环境而异，通常在容器内的某个配置目录中。具体路径请参考 Trae IDE 文档或联系管理员。 + +> **注意**： +> - 将 `` 替换为你的访问令牌 +> - 将 `https://devstar.cn` 替换为你的 DevStar 实例地址 +> - Windows 和 Linux 平台的具体配置路径可能因 IDE 版本而异，请参考对应 IDE 的官方文档 +> - 配置完成后需要重启 IDE 以使更改生效 + +## API 端点 + +DevStar MCP Server 通过以下端点提供服务： + +| 端点 | 方法 | 描述 | +|------|------|------| +| `/api/mcp` | POST | MCP JSON-RPC 请求入口 | + +### 认证方式 + +支持两种认证方式： + +**方式 1：Authorization Header（推荐）** +``` +Authorization: Bearer +``` + +**方式 2：URL 参数** +``` +/api/mcp?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) \ No newline at end of file +- **自动配置**：插件会自动检测环境并配置 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) \ No newline at end of file