🚀 MCP 开发模板集合

这是一套完整的 MCP (Model Context Protocol) 服务器开发模板，基于 crawl-mcp 项目的实践经验打造，帮助开发者快速构建高质量的 MCP 服务器。

✨ 特性

• 🏗️ 完整的项目架构 - 标准化的目录结构和文件组织
• 🔧 即用型配置 - TypeScript、Jest、ESLint 等配置文件
• 🛠️ 核心实现模板 - MCP 服务器核心逻辑和工具实现
• 🧪 全面的测试框架 - 单元测试、集成测试、参数处理测试
• 📦 自动化构建 - 构建脚本和发布流程
• 🚀 GitHub Actions - 完整的 CI/CD 自动化工作流
• 📚 详细的文档 - 开发指南、使用示例、故障排除
• 🔍 最佳实践 - 基于实际项目经验的解决方案

📁 模板结构

docs/templates/
├── 🏗️ architecture/           # 架构设计
│   └── project-structure.md   # 项目结构指南
├── ⚙️ config/                 # 配置文件模板
│   ├── package.template.json  # package.json 配置
│   ├── tsconfig.template.json # TypeScript 配置
│   └── jest.template.js       # Jest 测试配置
├── 🎯 core/                   # 核心实现模板
│   ├── MCPServer.template.ts  # MCP 服务器核心
│   └── index.template.ts      # 主入口文件
├── 🚀 deployment/             # 部署相关
│   └── publish-script.template.sh # 发布脚本
├── 📚 docs/                   # 文档模板
│   └── README.template.md     # 项目 README
├── 📝 examples/               # 使用示例
│   └── usage-examples.template.ts # 完整示例集合
├── 🤖 github/                 # GitHub Actions (新增)
│   ├── workflows/
│   │   ├── release.template.yml # 自动发布工作流
│   │   └── ci.template.yml     # 持续集成工作流
│   └── setup-guide.md         # GitHub Actions 设置指南
├── 🔄 processors/             # 数据处理器
│   └── DataProcessor.template.ts # 数据处理模板
├── 📜 scripts/                # 脚本模板
│   ├── start-server.template.js # 启动脚本
│   └── pre-commit-check.template.sh # 预提交检查
├── 🧪 testing/                # 测试模板
│   └── test.template.ts       # 测试用例模板
├── 🛠️ tools/                  # 工具模板
│   └── tool.template.ts       # 标准工具实现
├── 📋 types/                  # 类型定义
│   └── index.template.ts      # TypeScript 类型
├── 🔧 utils/                  # 工具类模板
│   ├── Logger.template.ts     # 日志系统
│   └── ImageDownloader.template.ts # 图片下载器
└── 📖 TUTORIAL.md             # 完整开发教程

🚀 快速开始

1. 使用教程快速创建项目

# 跟随完整教程创建项目
cat docs/templates/TUTORIAL.md

2. 使用 GitHub Actions 自动化部署 (推荐)

# 复制 GitHub Actions 配置
mkdir -p .github/workflows
cp docs/templates/github/workflows/release.template.yml .github/workflows/release.yml
cp docs/templates/github/workflows/ci.template.yml .github/workflows/ci.yml

# 查看详细设置指南
cat docs/templates/github/setup-guide.md

3. 传统手动创建

# 设置模板目录变量
export TEMPLATE_DIR="./docs/templates"

# 1. 创建项目结构
mkdir -p my-mcp-project/{src/{core,tools,types,utils},tests/{unit,integration},scripts}
cd my-mcp-project

# 2. 复制配置文件
cp $TEMPLATE_DIR/config/package.template.json package.json
cp $TEMPLATE_DIR/config/tsconfig.template.json tsconfig.json
cp $TEMPLATE_DIR/config/jest.template.js jest.config.js

# 3. 复制核心文件
cp $TEMPLATE_DIR/core/MCPServer.template.ts src/core/MCPServer.ts
cp $TEMPLATE_DIR/core/index.template.ts src/index.ts
cp $TEMPLATE_DIR/tools/tool.template.ts src/tools/myTool.ts

# 4. 复制测试文件
cp $TEMPLATE_DIR/testing/test.template.ts tests/unit/myTool.test.ts

# 5. 复制脚本文件
cp $TEMPLATE_DIR/scripts/start-server.template.js start-server.js
cp $TEMPLATE_DIR/scripts/pre-commit-check.template.sh scripts/pre-commit-check.sh
chmod +x scripts/pre-commit-check.sh

# 6. 复制文档
cp $TEMPLATE_DIR/docs/README.template.md README.md

🎯 核心特性详解

🔧 MCP 参数处理兼容性

模板内置了 MCP 参数传递机制的兼容性处理，解决了参数为空的常见问题：

// 兼容性参数提取 (模板已内置)
const params = request.params.arguments || request.params;
const { url, strategy = 'basic' } = params;

🧪 完整的测试覆盖

包含针对 MCP 特性的专门测试：

// 参数处理测试
it('应该正确处理 MCP 参数格式', async () => {
    const request = {
        params: {
            arguments: { text: 'test' }  // MCP 格式
        }
    };
    // 测试逻辑...
});

🚀 GitHub Actions 自动化

提供完整的 CI/CD 工作流：

• 🔄 持续集成 (CI)：多平台测试、安全扫描、依赖检查
• 📦 自动发布 (Release)：版本管理、NPM 发布、GitHub Release
• ⚡ 性能监控：包大小检查、启动时间测试
• 🔐 安全审计：依赖漏洞扫描、CodeQL 分析

📊 智能版本管理

支持基于提交信息的自动版本管理：

git commit -m "feat: 新功能"      # minor 版本升级
git commit -m "fix: 修复bug"     # patch 版本升级
git commit -m "breaking: 重大更改" # major 版本升级
git push origin main             # 自动发布！

📚 使用指南

🎓 完整教程

查看 TUTORIAL.md 获取详细的分步教程，包含：

• 项目初始化和配置
• 核心功能实现
• 测试编写和调试
• 自动化部署设置
• 高级功能扩展

🚀 Cursor + Claude 快速开发

查看 CURSOR_CLAUDE_GUIDE.md 获取专门的开发指南：

• 即用型启动提示词
• Cursor IDE 开发技巧
• Claude Sonnet 4 最佳实践
• 调试和问题解决
• 高效开发流程

🤖 GitHub Actions 设置

查看 github/setup-guide.md 了解：

• NPM Token 配置
• 工作流触发条件
• 自动版本管理
• 故障排除指南

📖 架构设计

查看 architecture/project-structure.md 了解：

• 项目结构设计原则
• 模块化架构
• 扩展性考虑

🔧 模板定制

修改项目信息

1. 更新 package.json：修改项目名称、描述、作者信息
2. 更新 README：替换项目特定内容
3. 修改工具逻辑：在 src/tools/ 中实现你的业务逻辑

添加新功能

1. 新工具：复制 tool.template.ts 并修改
2. 新处理器：使用 DataProcessor.template.ts
3. 新工具类：参考 utils/ 下的模板

🐛 常见问题

Q: MCP 调用时参数为空？

A: 使用模板内置的兼容性参数提取：

const params = request.params.arguments || request.params;

Q: GitHub Actions 发布失败？

A: 检查 NPM_TOKEN 配置，参考 setup-guide.md

Q: 测试无法运行？

A: 确保使用了模板提供的 Jest 配置文件

Q: TypeScript 编译错误？

A: 检查 tsconfig.json 是否使用了模板配置

🎉 成功案例

基于这套模板开发的项目：

• crawl-mcp-server: 微信文章抓取 MCP 服务器
• 更多项目持续添加中...

🤝 贡献指南

欢迎贡献新的模板和改进：

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 发起 Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件

🔗 相关资源

• MCP 官方文档
• crawl-mcp 项目
• GitHub Actions 文档
• NPM 发布指南

---

让 MCP 开发变得简单高效！ 🚀

基于 crawl-mcp 项目实践经验，持续更新中...