# 如何贡献 MCP 服务
欢迎贡献你的 MCP 服务！本指南将帮助你完成整个流程。
## 快速开始（5 分钟）
1. Fork 本仓库
2. 在 `packages/` 下创建你的服务目录
3. 开发你的 MCP 服务
4. 更新版本号
5. 提交 PR
就这么简单！合并后会自动发布到 npm。
---
## 详细步骤
### 步骤 1：Fork 并克隆仓库
```bash
# 1. 在 GitHub 网页点击 "Fork" 按钮
# 2. 克隆你的 fork
git clone https://github.com/你的用户名/mcp-list.git
cd mcp-list
# 3. 添加上游仓库（用于同步）
git remote add upstream https://github.com/原作者/mcp-list.git
```
### 步骤 2：创建新服务
```bash
# 进入 packages 目录
cd packages
# 创建你的服务目录
mkdir my-awesome-service
cd my-awesome-service
```
### 步骤 3：初始化项目
**方式 1：使用 AI 生成（推荐）** ⭐
```bash
# 在服务目录打开 Cursor 或 Claude Code
code .
# 告诉 AI：
# "创建一个 MCP 项目，用于 [你的需求描述]"
```
AI 会自动生成完整的项目结构和代码！
**方式 2：手动创建**
参考 [node-mcp-template](../node-mcp-template) 创建项目。
### 步骤 4：配置 package.json
**重要**：必须正确配置以下字段
```json
{
"name": "@你的npm用户名/包名",
"version": "1.0.0",
"description": "简短描述你的服务功能",
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"bin": {
"你的命令名": "./dist/index.js"
},
"files": ["dist"],
"scripts": {
"dev": "tsx src/index.ts",
"build": "tsc",
"start": "node dist/index.js"
},
"keywords": ["mcp", "fastmcp", "其他相关关键词"],
"author": "你的名字 <你的邮箱>",
"license": "MIT",
"dependencies": {
"fastmcp": "^3.25.3",
"zod": "^4.1.13",
"dotenv": "^17.2.3"
},
"devDependencies": {
"@types/node": "^20.10.0",
"tsx": "^4.7.0",
"typescript": "^5.3.3"
},
"engines": {
"node": ">=18.0.0"
}
}
```
**包名规范**：
- ✅ 推荐：`@your-username/package-name`（scoped package）
- ✅ 可选：`your-username-package-name`
- ❌ 避免：过于通用的名称（容易冲突）
### 步骤 5：开发和测试
```bash
# 安装依赖
npm install
# 开发模式（热重载）
npm run dev
# 构建
npm run build
# 测试构建产物
npm start
```
确保：
- ✅ `npm run build` 成功无错误
- ✅ `dist/` 目录生成正确
- ✅ 代码可以正常运行
### 步骤 6：编写文档
在你的服务目录创建 `README.md`：
```markdown
# 你的 MCP 服务名
简短描述服务功能。
## 功能
- 功能 1
- 功能 2
- ...
## 安装
\`\`\`bash
npx -y @your-username/your-package
\`\`\`
## 配置
在 Cursor/Claude Code 中添加：
\`\`\`json
{
"mcpServers": {
"your-service": {
"command": "npx",
"args": ["-y", "@your-username/your-package"]
}
}
}
\`\`\`
## 使用示例
（提供使用示例）
## 配置说明
（如果需要配置文件或环境变量，说明如何配置）
```
### 步骤 7：提交代码
```bash
# 回到仓库根目录
cd ../..
# 创建功能分支
git checkout -b feat/add-my-service
# 添加文件
git add packages/my-awesome-service
# 提交
git commit -m "feat: add my awesome MCP service"
# 推送到你的 fork
git push origin feat/add-my-service
```
### 步骤 8：创建 Pull Request
1. 访问你的 GitHub fork 页面
2. 点击 "Compare & pull request"
3. 填写 PR 描述：
```markdown
## 新增服务：你的服务名
### 功能描述
简短描述你的服务功能
### 包信息
- 包名：@your-username/your-package
- 版本：1.0.0
### 检查清单
- [x] 代码可以正常构建
- [x] 有完整的 README
- [x] package.json 配置正确
- [x] 版本号为 1.0.0
```
4. 提交 PR
### 步骤 9：等待审核和合并
维护者会审核你的 PR，可能会提出修改建议。
审核通过并合并后：
- ✅ GitHub Actions 自动运行
- ✅ 自动构建你的包
- ✅ 自动发布到 npm
- ✅ 你会在 Actions 日志中看到发布结果
大约 2-3 分钟后，你的包就可以通过 `npx` 安装了！
---
## 更新已有服务
### 修复 Bug 或添加功能
```bash
# 1. 同步上游仓库
git fetch upstream
git checkout main
git merge upstream/main
# 2. 创建功能分支
git checkout -b fix/my-service-bugfix
# 3. 修改代码
cd packages/my-service
# 进行修改...
# 4. 更新版本号
npm version patch # 1.0.0 → 1.0.1 (修复)
# 或
npm version minor # 1.0.0 → 1.1.0 (新功能)
# 或
npm version major # 1.0.0 → 2.0.0 (重大更新)
# 5. 测试
npm run build
# 6. 提交 PR
cd ../..
git add packages/my-service
git commit -m "fix: fix bug in my-service"
git push origin fix/my-service-bugfix
```
### 版本号规范（Semantic Versioning）
- **patch** (1.0.0 → 1.0.1)：Bug 修复，向后兼容
- **minor** (1.0.0 → 1.1.0)：新功能，向后兼容
- **major** (1.0.0 → 2.0.0)：重大更新，可能不向后兼容
---
## PR 审核标准
你的 PR 需要满足以下条件才能被合并：
### 必需项 ✅
- [ ] **代码质量**：代码清晰，有适当的注释
- [ ] **可以构建**：`npm run build` 成功
- [ ] **package.json 正确**：
- name 字段唯一
- version 字段正确
- 必要的依赖都已添加
- [ ] **有 README**：说明如何使用
- [ ] **版本号正确**：
- 新包从 1.0.0 开始
- 更新包版本号大于当前 npm 版本
- [ ] **代码规范**：
- 使用 TypeScript
- 使用 ES Modules
- 入口文件有 `#!/usr/bin/env node`
### 推荐项 ⭐
- [ ] 有使用示例
- [ ] 有配置说明（如果需要配置）
- [ ] 错误处理完善
- [ ] 工具有清晰的 description
---
## 常见问题
### Q1: 我不懂 TypeScript，能贡献吗？
**A**: 能！使用 Cursor 或 Claude Code，告诉 AI 你的需求，它会生成所有代码。
### Q2: 包名已被占用怎么办？
**A**: 使用 scoped package：`@your-username/package-name`
### Q3: 如何测试我的包？
**A**:
```bash
# 本地测试
npm run dev
# 测试构建
npm run build
npm start
# 在 Cursor 中测试（本地）
# 配置文件指向本地路径：
{
"mcpServers": {
"test": {
"command": "node",
"args": ["/path/to/your/package/dist/index.js"]
}
}
}
```
### Q4: PR 合并后多久能用？
**A**: 通常 2-5 分钟。GitHub Actions 运行 + npm 索引更新。
### Q5: 发布失败了怎么办？
**A**: 查看 GitHub Actions 日志，常见原因：
- 构建失败 → 修复代码错误
- 版本冲突 → 更新版本号
- 包名冲突 → 修改包名
### Q6: 可以删除已发布的包吗？
**A**: 可以，但有限制：
- 24 小时内：可以使用 `npm unpublish` 删除
- 超过 24 小时：需要联系 npm 支持
---
## 开发技巧
### 使用 node-mcp-template
在 `packages/` 下直接使用 [node-mcp-template](../node-mcp-template)：
```bash
cd packages
cp -r ../node-mcp-template my-service
cd my-service
# 用 Cursor 打开
code .
# 告诉 AI 你的需求，AI 会修改模板
```
### 参考现有服务
查看 `packages/` 下的其他服务作为参考。
### 本地测试发布流程
```bash
# 在仓库根目录
npm run check
# 查看哪些包会被发布（不会真正发布）
```
---
## 需要帮助？
- 📖 查看 [完整文档](../MCP开发入门与实战.md)
- 💬 [提交 Issue](https://github.com/你的用户名/mcp-list/issues)
- 🔍 查看 [示例服务](../node-mcp-template/docs/examples/)
---
**感谢你的贡献！** 🎉
你的 MCP 服务将帮助更多人使用 AI 工具！
