MCP 工具入门套件 (MCP Tool Starter Kit)

这是一个功能完备、开箱即用的 TypeScript 项目模板，旨在帮助开发者快速、规范地启动任何新的 MCP (Model Context Protocol) 工具项目。

它集成了业界最佳的工程化实践，涵盖了从代码规范、测试、调试到自动化发布的全流程。

🚀 如何使用此模板

创建新仓库: 在 GitHub 或 GitLab 上，使用此模板创建一个新的代码仓库。

克隆新仓库到本地:

git clone [你的新仓库地址]
cd [你的新项目目录]

修改 package.json:
- 将 name 字段修改为你自己的包名 (例如: "@your-scope/my-new-tool")。
- 将 bin 字段中的命令名修改为你的工具名 (例如: "my-new-tool": "./dist/index.js")。
- 按需修改 author, description 等字段。
安装依赖:
```
pnpm install
```
开始开发: 你现在可以开始在 src/tools/ 目录下创建你自己的工具了！

✨ 特性

Node.js 版本: 要求 Node.js 20 或更高版本。
现代化的模块系统: 使用 TypeScript，并配置为标准的 ES Module ("type": "module") 项目。
强大的构建工具: 使用 tsup 进行快速、高效的构建，并已通过 tsup.config.ts 进行配置。
严格的代码规范:
- 使用 ESLint 进行静态代码分析。
- 使用 Prettier 进行代码格式化。
- 通过 eslint-config-prettier 完美解决两者冲突。
- 使用 husky, lint-staged, 和 commitlint 在代码提交前自动检查、格式化并校验提交信息，保证代码库的整洁统一和 Git 历史的规范性。
完备的测试框架:
- 使用 Vitest 作为现代化、极速的单元测试框架。
- 集成 msw (Mock Service Worker) 用于模拟 API 请求，编写高保真度的单元测试。
专业的命令行接口 (CLI):
- 使用 yargs 构建强大且可扩展的 CLI。
- 内置 --verbose (调试模式), --help, --version 等标准参数。
自动化的版本与发布流程:
- 使用 bumpp 进行交互式的版本管理。
- 遵循 Conventional Commits 规范。
- 通过 pnpm release 命令一键完成版本提升、生成 Git 标签等操作。
持续集成与部署 (CI/CD):
- 提供 GitHub Actions (ci.yml) 和 GitLab CI (.gitlab-ci.yml) 的标准配置文件。
- CI 流程包括自动安装依赖、运行代码检查、测试和构建。
- CD 流程配置为在创建新的 Git 标签时自动发布包。
清晰的项目结构: 采用关注点分离原则，将 CLI、服务器逻辑、工具等模块清晰地划分到不同文件中。

📂 项目结构

.
├── .github/workflows/   # GitHub Actions CI/CD 配置
├── .husky/              # Git 钩子
├── dist/                # 构建产物
├── src/                 # 源码
│   ├── tools/           # MCP Tools 目录
│   │   └── example.tool.ts # 示例 Tool
│   ├── cli.ts           # 命令行接口定义
│   ├── server.ts        # MCP 服务器逻辑
│   └── index.ts         # 主入口
├── tests/               # 测试文件
│   ├── mocks/           # MSW mock 配置
│   └── example.test.ts  # 示例测试
├── .eslintrc.cjs        # ESLint 配置
├── .gitignore
├── .gitlab-ci.yml       # GitLab CI/CD 配置
├── commitlint.config.cjs  # Commitlint 配置
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
├── tsup.config.ts       # tsup 构建配置
└── vitest.config.ts     # Vitest 测试配置

🚀 可用脚本

pnpm start: 使用 tsx 启动服务。
pnpm start:debug: 以调试模式启动服务，会打印详细的请求日志。
pnpm build: 使用 tsup 构建项目。
pnpm test: 使用 Vitest 运行所有测试。
pnpm lint: 使用 ESLint 检查整个项目的代码规范。
pnpm release: 使用 bumpp 交互式地提升版本号，创建 Git 标签，并自动发布到 npm。
pnpm inspect: 使用官方的 @modelcontextprotocol/inspector 工具进行调试。

🛠️ 开发流程

1. 创建一个新的 Tool

在 src/tools/ 目录下创建一个新的 *.tool.ts 文件。
参考 src/tools/example.tool.ts 的结构，定义一个新的 Tool 对象和对应的 Handler 函数。
在 src/server.ts 中导入新的 Tool 和 Handler，并在请求处理逻辑中注册它。

2. 编写测试

在 tests/ 目录下创建一个新的 *.test.ts 文件。
参考 tests/example.test.ts，使用 Vitest 编写测试用例。
如果你的 Tool 涉及到外部 API 请求，可以在 tests/mocks/handlers.ts 中使用 msw 添加对应的 mock 处理器。

3. 本地调试

如果你想在本地像全局命令一样运行和调试你的工具，而不是每次都通过 pnpm start，你可以遵循以下步骤：

构建项目: 首先，你需要编译你的 TypeScript 源码，生成 dist 目录。
```
pnpm run build
```
链接包: 使用 npm link 命令在你的系统中创建一个全局符号链接，指向你当前的项目。这会让你能直接运行在 package.json 的 bin 字段中定义的命令。
```
npm link
```
运行命令: 现在你可以在任何终端窗口中直接运行你的命令了。
```
# 假设你的命令是 auto-complete-document
auto-complete-document --help
```

注意: 每次你修改了 src 目录下的代码，都需要重新运行 pnpm run build 来确保你的全局命令执行的是最新的代码。

4. 提交代码

当你提交代码时 (git commit)，husky 会自动触发两个钩子：

commit-msg: 使用 commitlint 校验你的提交信息是否符合 Conventional Commits 规范。不规范的提交将被拒绝。
pre-commit: 使用 lint-staged 对你本次修改的文件运行 ESLint 和 Prettier，以确保代码质量。

请确保你的 Commit Message 遵循 Conventional Commits 规范，例如：

feat: add new feature
fix: resolve a bug
docs: update documentation

这是自动化版本管理和 Changelog 生成的基础。

📦 发布流程

当你准备好发布一个新版本时，只需简单地运行：

pnpm release

bumpp 会启动一个交互式流程，引导你选择新的版本号。确认后，它会自动完成以下所有工作：

更新 package.json 中的版本号。
提交版本变更。
创建一个以新版本号命名的 Git 标签 (e.g., v1.2.3)。
将所有变更和标签推送到远程仓库。
运行 pnpm publish 将包发布到 npm。

之后，GitLab CI (或 GitHub Actions) 会检测到新的标签，并根据 .gitlab-ci.yml 中的配置执行自动化发布流程。

MCP Tool Starter Kit

README Documentation