gitcode-mcp

面向智能体与使用者的缓存优先 GitCode 工具集。

gitcode-mcp 通过持久本地缓存，持续提供 GitCode 的 Issue、PR、Wiki 页面、评论和链接。它通过 CLI 和 MCP 服务器暴露该缓存，使智能体即便在网络访问缓慢或不稳定时，也能进行搜索、阅读、规划，并执行显式的实时写入。

该项目自包含且公开安全。源仓库、跟踪器和 Wiki 均为外部输入；示例使用占位符和已清洗的固定数据。完整安全契约见 安全清洗规则。

功能说明

• 将 GitCode 仓库绑定到本地缓存标识和别名。
• 将 Issue、PR、评论、Wiki 页面、标签和里程碑同步到 SQLite。
• 默认使用混合词法/语义检索搜索缓存来源，同时保留确定性全文检索模式。
• 基于按模型区分的嵌入，在缓存块上运行可选的本地 RAG 语义/混合检索。
• 直接从精确的本地 Git 修订版本搜索带版本控制的仓库文档，并持久化元数据和向量，而非文档副本。
• 维护多个已注册缓存，提供由守护进程托管的近期刷新、历史回填，以及感知内容生成的 RAG 修复。
• 为链接、片段、反向链接和导出解析稳定的本地 id 和远程别名。
• 面向智能体工作流，基于缓存数据运行 MCP 服务器。
• 仅通过包含幂等键和审计证据的显式命令执行实时写入。
• 通过可选的反馈入口，将智能体或人工内部试用中的摩擦转化为结构化、已脱敏、去重的反馈 Issue。
• 通过同一缓存优先服务层，支持 Issue、Wiki、评论和 PR 工作流。
• 通过官方 v5 API 检查仓库推送镜像，并在缓存、CLI 或 MCP 输出前移除目标凭据。

快速开始

go test ./...
go run ./cmd/gitcode-mcp --help
go run ./cmd/gitcode-mcp repo add --repo YOUR_OWNER/YOUR_REPO --owner YOUR_OWNER --name YOUR_REPO --scopes issues,wiki
go run ./cmd/gitcode-mcp sync --repo YOUR_OWNER/YOUR_REPO --issues --wiki --pulls --pr-comments
go run ./cmd/gitcode-mcp search --repo YOUR_OWNER/YOUR_REPO "cache-first"
go run ./cmd/gitcode-mcp maintenance plan --repo YOUR_OWNER/YOUR_REPO
go run ./cmd/gitcode-mcp maintenance enable --repo YOUR_OWNER/YOUR_REPO --yes --idempotency-key setup-1

search 和 search_sources 默认请求混合检索：全文检索始终执行，就绪的本地 RAG 命名空间会补充语义候选。结果按来源分组，并附带引用以及词法/语义排名溯源信息。若 RAG 不可用，响应将返回全文检索结果，并给出明确的回退原因。若需在不调用 embedding 提供方的前提下进行确定性的精确/词元检索，请使用 --mode full_text。

如需使用 MCP，请从 MCP 设置 开始。如需处理线上凭据，请从 Secrets 和 配置参考 开始。 如需语义检索，请从 RAG 设置与运行 开始。 如需跨 Git 修订检索 README/docs/，请从 仓库文档 RAG 开始。

常用工作流

• 从缓存读取：读取指南
• 执行显式写入：写入指南
• 处理 PR/MR 流程：PR/MR 工作流
• 安装或发布版本：安装、发布流程
• 审阅组件边界：组件架构
• 安排测试与测试夹具：测试架构
• 配置仓库：仓库绑定
• 理解同步行为：缓存与同步模型
• 执行守护进程维护：守护进程缓存与 RAG 维护
• 打开内嵌本地运维控制台：Admin UI
• 配置语义检索：RAG 设置与运行
• 检索版本化仓库文档：仓库文档 RAG
• 查看实时 API 发现结果：GitCode API Discovery
• 安全地列出、触发并监控仓库镜像：推送镜像操作
• 准备并提交可安全对外公开的试用反馈报告：结构化反馈

仓库结构

• cmd/gitcode-mcp/: CLI 入口。
• internal/: 缓存、服务、provider、CLI、MCP、同步、诊断与测试。
• docs/: 长期有效的产品、架构、运维和 API 文档。
• testdata/: 脱敏后可复用的测试夹具输入。

进行中的规划应放在 GitCode issue 和 Pull Request 中。仍有价值的历史调研或内部试用证据应放在 GitCode wiki，而不是 main。