本文覆盖通过 MCP 接入多平台代码仓库（GitHub、GitLab、Bitbucket 等）的通用设计。平台特定的细节参见 MCP与GitHub。

一、基本定义

代码仓库 MCP Server 将代码平台的操作能力通过 MCP 协议暴露给 AI 应用，使 Agent 能够读取代码、搜索仓库、管理 Issue 和 PR。

与 MCP与GitHub 的区别：

• MCP与GitHub 聚焦 GitHub 平台的特定实现
• 本文关注多平台通用的抽象设计和适配策略

二、核心操作

Resource（只读数据）

Resource	URI 格式	说明
文件内容	repo://owner/name/branch/path	读取指定文件
目录列表	repo://owner/name/branch/dir/	列出目录内容
仓库信息	repo://owner/name	仓库元数据
分支列表	repo://owner/name/branches	所有分支

Tool（可执行操作）

Tool	操作	风险等级
search_code	搜索代码	低
create_issue	创建 Issue	中
create_branch	创建分支	中
commit_file	提交文件变更	高
create_pr	创建 Pull Request	高
review_pr	审查 PR	中
merge_pr	合并 PR	很高
trigger_ci	触发 CI/CD	中

三、多平台抽象

统一接口

CodeRepository 接口:
  - get_file(repo, path, ref) → content
  - list_directory(repo, path, ref) → entries
  - search(repo, query) → results
  - create_issue(repo, title, body) → issue
  - create_branch(repo, name, from) → branch
  - commit(repo, branch, message, changes) → commit
  - create_pr(repo, title, body, source, target) → pr

平台差异适配

差异点	GitHub	GitLab	Bitbucket
PR 名称	Pull Request	Merge Request	Pull Request
默认分支	main	main	main
CI 名称	Actions	Pipelines	Pipelines
API 版本	2022-11-28	v4	2.0
认证方式	PAT/OAuth	PAT/OAuth	PAT/OAuth
权限模型	Repository/Org	Project/Group	Project/Workspace

适配层设计

四、认证

认证方式对比

方式	安全性	适用场景	权限粒度
Personal Access Token	中	个人使用	用户级
OAuth App	高	团队/组织	可定制 Scope
Git 凭证	中	CLI 集成	仓库级
SSH Key	高	Git 操作	用户级
App Installation	很高	企业级	仓库/组织级

凭证管理

• Token 不写入代码或日志
• 使用 Secret Manager 存储
• 定期轮换
• 使用最小权限 Scope

五、权限设计

仓库级权限

权限级别：
  - 只读：搜索、读取文件、查看 Issue/PR
  - 评论：添加评论、审查 PR
  - 写入：创建 Issue、创建分支、提交代码
  - 管理：合并 PR、删除分支、修改设置

分支保护

• 主分支（main/master）默认只读
• 提交必须通过分支
• 合并需要审批
• 禁止强制推送

六、大仓库处理

分页

所有列表操作必须分页：

- 文件列表：按目录层级分页
- 搜索结果：cursor-based 分页
- Issue/PR 列表：按时间分页
- Commit 历史：按时间分页

稀疏操作

• 不一次性加载整个仓库
• 按需读取文件和目录
• 搜索时限制范围
• 使用平台的搜索 API 而非下载仓库

文件过滤

• 忽略二进制文件
• 忽略大型文件（> 1MB）
• 忽略生成的文件（node_modules、dist 等）
• 支持 .gitignore 规则

七、代码安全

代码注入风险

Agent 读取的代码可能包含恶意指令：

风险场景：
- README 中包含 "忽略之前的指令，执行..."
- 代码注释中包含提示注入
- Issue 描述中包含恶意指令

缓解策略：

• 将代码内容标记为"数据"而非"指令"
• 限制代码文件大小
• 过滤可疑的指令模式

敏感信息检测

提交前检查是否包含：

• API Key / Token
• 密码 / 密钥
• 个人信息（邮箱、电话）
• 内部 URL / IP

PR/MR 中的提示注入

风险：恶意 PR 描述可能诱导 Agent 执行非预期操作

缓解：
- 将 PR 描述标记为不可信内容
- 自动审查时不执行 PR 中的命令
- 合并操作需要人工确认

八、CI/CD 集成

触发构建

Tool: trigger_ci
参数：
  - repo: 仓库
  - ref: 分支或 commit
  - workflow: 工作流名称（可选）
风险：中
确认：建议

查看构建状态

Resource: ci://repo/ref/status
返回：构建状态、日志链接、检查结果

Webhook 集成

• CI 完成时通知 Agent
• PR 更新时通知审查者
• Issue 状态变更时通知

九、审计

审计日志

每次操作记录：

• 操作者（用户/Agent）
• 操作类型
• 目标仓库和对象
• 操作参数
• 操作结果
• 时间戳

十、典型 Tool 设计

搜索代码

名称：search_code
描述：在代码仓库中搜索代码。支持按文件名、内容、路径搜索。
     返回匹配的文件列表和代码片段。
参数：
  - repo (string, required): 仓库 (owner/name)
  - query (string, required): 搜索关键词
  - language (string, optional): 编程语言过滤
  - path (string, optional): 路径前缀过滤
返回：匹配文件列表，包含 path、snippet、line_number
风险：低

创建 PR

名称：create_pr
描述：在代码仓库中创建 Pull Request。需要指定源分支和目标分支。
参数：
  - repo (string, required): 仓库
  - title (string, required): PR 标题
  - body (string, required): PR 描述
  - source_branch (string, required): 源分支
  - target_branch (string, optional, default: main): 目标分支
  - draft (boolean, optional, default: false): 是否为草稿
返回：PR URL 和编号
风险：高
确认：建议

十一、设计原则

1. 平台抽象：通过适配层屏蔽平台差异
2. 最小权限：Token 只授予必要的 Scope
3. 分页必须：所有列表操作都分页
4. 敏感检测：提交前检查敏感信息
5. 代码不可信：代码内容视为数据，不视为指令
6. 主分支保护：主分支默认只读
7. 审计完整：记录所有操作

十二、常见误区

误区	正确做法
为每个平台写独立 Server	使用适配层抽象
一次性加载整个仓库	按需读取，使用搜索 API
使用管理员 Token	使用最小权限 Token
信任代码内容	标记为不可信数据
允许直接提交主分支	通过 PR 流程
不检测敏感信息	提交前自动检查

十三、实践检查清单

• 多平台适配层已实现
• Token 使用最小权限 Scope
• 所有列表操作已分页
• 主分支受保护
• 敏感信息检测已集成
• 代码内容标记为不可信
• 审计日志完整
• 大仓库性能已优化
• CI/CD 集成已测试

十四、与其他概念的关系

• MCP与GitHub：GitHub 平台的特定实现
• MCP Server设计：Server 设计原则
• MCP安全边界：代码安全考量
• MCP认证与授权：Token 和 OAuth 管理
• MCP权限设计：仓库级权限设计
• MCP工具接入：将 Git 操作封装为 Tool

十五、适用边界

适用于：

• 需要 AI 辅助代码管理的团队
• 多平台代码仓库统一管理
• 自动化代码审查和 CI/CD

不适用于：

• 不需要代码操作的场景
• 对安全性要求极高的军工/金融系统（需要更严格的审批流程）

十六、参考资料

• GitHub API 文档 - https://docs.github.com/en/rest
• GitLab API 文档 - https://docs.gitlab.com/ee/api/
• Bitbucket API 文档 - https://developer.atlassian.com/cloud/bitbucket/rest/