如何成为 MCPCAN 贡献者:代码结构与开发工作流完全指南
如何成为 MCPCAN 贡献者:代码结构与开发工作流完全指南
想为开源项目贡献代码,却不知道从何下手?这份 MCPCAN 贡献指南带你快速摸清代码结构与开发工作流。MCPCAN 是一个开源的 MCP 服务集中管理(统一治理)平台:用容器化方式部署每一类 MCP 服务,支持 SSE、STDIO、STREAMABLEHTTP 三种接入协议,并内置 Token 鉴权、容器监控、RBAC 权限管理与一键部署能力。读完本文,你就能从"看懂仓库"到"提交第一个 PR",完整走通 MCPCAN 贡献者的开发流程。
上图是 MCPCAN 管理端的"MCP 实例资源"页面:所有 MCP 服务实例、接入协议、鉴权开关与容器状态都集中呈现,这正是贡献者需要持续打磨的核心功能区域。
一、先认识项目:MCPCAN 是什么
MCPCAN 解决的核心痛点是 MCP 服务生态的"碎片化":协议标准不一、部署方式混乱、安全风险敞口大。它用统一平台把这些 MCP 服务纳入管理——统一目录、统一鉴权、统一监控、统一发布。
| 能力 | 说明 |
|---|---|
| 统一纳管 | 所有 MCP 实例、模板、代码包集中管理 |
| 协议兼容 | SSE / STDIO / STREAMABLEHTTP 多协议接入与转换 |
| 安全鉴权 | 内置 Token 校验与 RBAC 角色权限 |
| 容器化部署 | 每个 MCP 服务以容器隔离运行,避免环境冲突 |
| 实时监控 | 容器状态、资源占用、访问日志可视化 |
理解这一点很重要:你贡献的每一行代码,最终都会影响一个"平台级"产品,而不仅仅是一个脚本。
二、MCPCAN 代码结构:一个 Monorepo 的分工
MCPCAN 采用单仓库(Monorepo)组织,顶层目录各司其职:
mcpcan/
├── backend/ # Go 后端(核心业务)
├── frontend/ # Vue 3 前端(管理 UI)
├── docs/ # 中英文文档
├── deploy/ # Docker Compose / Helm 部署配置
├── dockerfiles/ # 各服务镜像 Dockerfile
├── images/ # 宣传与示例图片
├── Makefile # 顶层构建 / 发布 / 文档同步目标
├── VERSION # 版本号
└── CONTRIBUTING.md
1. 后端 backend/:Go 服务的标准布局
后端用 Go 编写,遵循清晰的"入口 / 内部 / 通用包 / 接口契约"分层:
| 目录 | 职责 |
|---|---|
| backend/cmd/ | 各服务入口:market(核心业务)、authz(权限)、gateway(网关)、init(初始化)、mcp-sidecar |
| backend/internal/ | 业务实现,按模块划分:market、authz、gateway、init,各自含 app / biz / service / task |
| backend/pkg/ | 可复用通用包:container(容器)、k8s、redis、jwt、middleware、i18n 等 |
| backend/api/ | proto 接口契约定义,是 gRPC / OpenAPI 生成的源头 |
以核心业务 market 模块为例,它内部分为三层,改动前建议先看清职责边界:
- 应用装配层:backend/internal/market/app/app.go(
App结构体与依赖装配) - 业务逻辑层:backend/internal/market/biz/
- 服务编排层:backend/internal/market/service/
2. 前端 frontend/:Vue 3 + Vite 管理台
前端同样结构清晰,按"页面 / API / 状态 / 国际化"组织:
- 页面:frontend/src/pages/(
mcp、market、environment、agent、home等) - API 封装:frontend/src/api/
- 状态管理:frontend/src/stores/modules/(Pinia)
- 多语言:frontend/src/lang/(
zh-cn.json/en.json成对维护)
3. 文档与部署
- 用户文档:docs/zh/guide/ 与 docs/en/guide/,中英文一一对应
- 部署配置:deploy/docker-compose/(含开发用的
docker-compose.dev.yml)与 deploy/helm/(Kubernetes)
💡 小提示:企业版特性集中在
.ee目录,受独立的 LICENSE_EE.md 约束;公开贡献请避开这些目录。
三、环境准备:成为贡献者的第一步
在提交代码前,请确认本地已具备这些工具(依据 CONTRIBUTING.md 的前置要求):
- Go 1.21+(后端)
- Node.js 20.19+ / 22.12+ 与 pnpm(前端)
- Docker 与 Docker Compose(容器化与本地联调)
- Git
克隆仓库并进入项目:
git clone https://gitcode.com/gh_mirrors/mc/mcpcan.git
cd mcpcan
四、开发工作流:热重载 + 一键启动
这是新手最容易卡住的环节。MCPCAN 提供了一键式本地开发环境,你不需要在本地装齐整套运行环境。
1. 一键拉起开发环境
在 deploy/docker-compose/docker-compose.dev.yml 中,mcp-market-svc 服务把整个 backend/ 目录挂载进容器,并注入 air.market.toml 热重载配置,再配合 Go 调试器 dlv 运行:
cd deploy/docker-compose
docker compose -f docker-compose.dev.yml up
它会一次性拉起 MySQL、Redis、mcp-market、mcp-authz、mcp-web(Vite 前端)与 Traefik 网关。关键点:
- air 热重载:修改任意
.go文件约 1 秒内自动重编译并重启,无需手动go run - 断点调试:调试器监听
2345端口,IDE 可直接远程 attach,断点精准 - 前端
pnpm dev也在容器内热更新,改完即生效
容器化的运行方式,正是 MCPCAN 部署每个 MCP 服务的核心理念——你在本地调试的,和线上运行的环境一致。
2. API 契约先行:buf 代码生成
后端接口不是手写的,而是由 proto 契约统一生成。改动 API 的正确顺序是:
- 先修改 backend/api/ 下的
.proto文件(如 backend/api/market/market/) - 运行
make proto-buf,由 backend/api/buf.gen.yaml 驱动,一次性生成 Go 代码、gRPC 桩与 OpenAPI 文档
顶层 Makefile 中的 proto-buf 目标会自动清理旧文件、执行 buf generate、合并 Swagger,因此不要手改生成产物。
3. 后端构建与测试:Makefile 目标
backend/Makefile 把常用操作封装成目标,贡献者日常最常用这几个:
| 命令 | 作用 |
|---|---|
make build |
构建 market 服务 |
make test-all |
跑单元 + AI 集成测试 |
make coverage |
生成覆盖率 HTML 报告 |
make gen-api |
重新生成 proto API 代码(见 backend/Makefile) |
make docs |
生成 OpenAPI 3 文档 |
make clean |
清理构建产物 |
提交前务必 make test-all 通过,并在 README/文档同步更新。
4. 前端脚本:package.json 约定
前端脚本定义在 frontend/package.json:
pnpm dev:本地开发(Vite 热更新)pnpm type-check:vue-tsc类型检查(提交前必过)pnpm lint/pnpm format:ESLint 修复与 Prettier 格式化pnpm test:Vitest 单测pnpm build:生产构建
✍️ 国际化提醒:任何用户可见文案都要同时改
zh-cn与en两份语言文件,后端同理,位于 backend/pkg/i18n/locales/。
五、PR 流程:从 Commit 到合并
1. Commit 规范:Conventional Commits
遵循 CONTRIBUTING.md 的约定式提交,格式为 type(scope): description。结合 MCPCAN 场景,例如:
feat(instance): 支持 SSE 协议接入fix(gateway): 修复代理模式 Token 校验失败docs(contribution): 补充开发工作流说明test(user): 新增用户服务单元测试
2. 提交前自查清单
- [ ] 代码符合项目编码规范(后端
gofmt,前端eslint+prettier) - [ ]
make test-all/pnpm test本地全部通过 - [ ] 相关文档已同步更新
- [ ] Commit 信息清晰、描述性
- [ ] 分支已与
main对齐,无合并冲突 - [ ] UI 改动附截图
3. 审核环节
每个 PR 至少需要一名维护者审核。请快速、专业地响应反馈,保持 PR 聚焦且体量适中——小而清晰的改动更容易被合并。
4. 贡献什么、优先级如何
官方文档 docs/zh/guide/contribution.md 给出了清晰指引:
| 贡献类型 | 建议动作 |
|---|---|
| 文档 / 翻译 / 拼写 | 直接开始,低门槛友好入门 |
| Bug 修复 / 性能优化 | 建 Issue 说明复现步骤,随后开 PR |
| 新功能 / 功能请求 | 先评论或新建 Issue 讨论方案,再编码 |
| 核心漏洞 / 安全问题 | 最高优先级,尽快处理 |
对于安全漏洞,不要公开建 Issue,而应遵循 SECURITY.md 的负责任披露流程。所有贡献都将在 LICENSE 条款下授权,请在提交前确认知悉。
六、关键资源速查
| 资源 | 路径 |
|---|---|
| 贡献指南 | CONTRIBUTING.md |
| 中文贡献文档 | docs/zh/guide/contribution.md |
| 代码行为准则 | CODE_OF_CONDUCT.md |
| 安全策略 | SECURITY.md |
| 开发环境编排 | deploy/docker-compose/docker-compose.dev.yml |
| 后端 proto 契约 | backend/api/ |
| 部署文档 | deploy/helm/README.md |
写在最后
成为 MCPCAN 贡献者的路径其实很清晰:读懂结构 → 跑起热重载环境 → 契约先行改 API → 测试通过 → 规范提交 → 等待审核。建议新手从文档、翻译或小 Bug 切入,熟悉 Conventional Commits 与 CI 约定后,再挑战核心业务模块。
每一份帮助,都会让 MCP 管理这件事变得更简单。祝你提交顺利,期待看到你的第一个 PR!🚀

