Skip to Content
贡献指南贡献指南

贡献指南

欢迎来到 BestMCP 项目！我们非常感谢您考虑为这个开源项目做出贡献。这份指南将帮助您了解如何参与项目开发。

🎯 贡献方式

报告问题

  • 发现 bug 或有问题需要修复？请创建一个 Issue 
  • 在提交 Issue 前，请先搜索现有问题，避免重复
  • 提供详细的问题描述、重现步骤和环境信息

提交代码

  • 修复 bug 或实现新功能？请提交 Pull Request
  • 查看 Issues 页面  寻找可以解决的问题
  • 大的功能改动建议先创建 Issue 讨论

改进文档

  • 文档和代码同样重要！
  • 修复错别字、改进说明、添加示例等都是很有价值的贡献
  • 可以直接提交 PR 或提出改进建议

示例项目

  • 贡献新的示例项目展示 BestMCP 的用法
  • 改进现有示例的代码质量和文档

🛠️ 开发环境设置

环境要求

  • Node.js: 20.19.2 或更高版本
  • pnpm: 10.13.1 或更高版本（推荐使用 pnpm  作为包管理器）

快速开始

  1. Fork 项目

    # 在 GitHub 上 Fork 项目到你的账户
# 然后克隆你的 Fork
git clone https://github.com/YOUR_USERNAME/bestmcp.git
cd bestmcp

  2. 安装依赖

    # 启用 corepack（pnpm 管理工具）
corepack enable
 
# 安装所有依赖
pnpm install

  3. 验证环境

    # 运行测试确保环境正常
pnpm test
 
# 检查代码质量工具是否正常
pnpm check:fix

📝 贡献流程

1. 创建分支

# 同步上游代码
git remote add upstream https://github.com/shenjingnan/bestmcp.git
git fetch upstream
git merge upstream/main
 
# 创建新分支（使用有意义的前缀）
git checkout -b feature/your-feature-name
# 或
git checkout -b fix/your-bug-fix

分支命名规范

  • feature/功能描述 - 新功能开发
  • fix/问题描述 - Bug 修复
  • docs/文档说明 - 文档更新
  • test/测试相关 - 测试相关改动
  • refactor/重构说明 - 代码重构

2. 开发和测试

# 启动开发模式（自动监听文件变化）
pnpm dev
 
# 在另一个终端运行测试
pnpm test:watch
 
# 构建验证
pnpm build

3. 提交代码

我们使用语义化的提交信息格式：

# 格式：<type>(<scope>): <subject>
# 类型：feat, fix, docs, style, refactor, test, chore
 
git commit -m "feat(server): 添加新的工具验证功能"
git commit -m "fix(http): 修复 HTTP 传输层的内存泄漏"
git commit -m "docs: 更新 API 文档"

4. 提交 Pull Request

  1. 推送到你的 Fork：

    git push origin feature/your-feature-name

  2. 在 GitHub 上创建 Pull Request：

    • 提供清晰的 PR 标题和描述
    • 关联相关的 Issue
    • 填写 PR 模板中的所有必要信息

🔍 代码质量标准

测试要求

所有代码提交都必须包含适当的测试：

# 运行所有测试
pnpm test
 
# 生成覆盖率报告
pnpm test:coverage
 
# 目标：保持高测试覆盖率

代码规范

我们使用 Biome  进行代码格式化和检查：

# 自动修复格式和 lint 问题
pnpm check:fix
 
# 检查但不自动修复
pnpm check

类型检查

TypeScript 严格模式，确保类型安全：

# 类型检查（不生成文件）
pnpm type:check

拼写检查

# 检查代码和文档中的拼写
pnpm spell:check

📁 项目结构

BestMCP 是一个 monorepo  项目：

bestmcp/
├── packages/                 # 核心包
│   └── server/              # BestMCP 服务器框架
├── examples/                # 示例项目
│   ├── stdio-mcp/          # STDIO 模式示例
│   ├── http-mcp/           # HTTP 模式示例
│   └── calculator-mcp/     # 计算器服务示例
├── docs/                   # 项目文档
├── .github/                # GitHub 配置
│   └── workflows/          # CI/CD 工作流
└── tests/                  # 集成测试

核心开发

  • 框架开发: 主要在 packages/server/ 目录
  • 示例开发: 在 examples/ 目录添加新的使用示例
  • 文档开发: 在 docs/ 目录改进项目文档

🏗️ 构建系统

项目使用优化的并行构建系统：

# 核心包构建（推荐日常使用）
pnpm build
 
# 构建所有包
pnpm build:packages
 
# 构建示例项目
pnpm build:examples
 
# 完整构建
pnpm build:all

开发模式

# 核心包开发模式
pnpm dev
 
# 所有包开发模式
pnpm dev:packages
 
# 示例项目开发模式
pnpm dev:examples
 
# 全部开发模式
pnpm dev:all

🤝 社区指南

行为准则

我们致力于为每个人提供友好、安全和欢迎的环境。请：

  • 尊重不同的观点和经验
  • 使用友好和包容的语言
  • 专注于对社区最有利的事情
  • 对其他社区成员表示同理心

沟通渠道

  • GitHub Issues: 报告 bug 和请求功能
  • GitHub Discussions: 一般讨论和问答
  • Pull Requests: 代码审查和技术讨论

获得帮助

如果您需要帮助：

  1. 查看 现有 Issues 
  2. 阅读 项目文档
  3. 在 GitHub Discussions 中提问
  4. 查看示例项目了解用法

📋 提交前检查清单

在提交 PR 前，请确保：

  • 代码通过所有测试：pnpm test
  • 代码格式正确：pnpm check:fix
  • 拼写检查通过：pnpm spell:check
  • 类型检查通过：pnpm type:check
  • 构建验证通过：pnpm build
  • 添加了适当的测试用例
  • 更新了相关文档
  • 提交信息符合规范
  • PR 描述清晰详细

🎉 致谢

感谢所有为 BestMCP 项目做出贡献的开发者！您的贡献让这个项目变得更好。

📚 更多资源

如果您有任何问题或建议，请随时联系我们！

Last updated on
快速上手开发框架