MCP Tool Starter Kit

# MCP 工具入门套件 (MCP Tool Starter Kit) 这是一个功能完备、开箱即用的 TypeScript 项目模板，旨在帮助开发者快速、规范地启动任何新的 MCP (Model Context Protocol) 工具项目。 它集成了业界最佳的工程化实践，涵盖了从代码规范、测试、调试到自动化发布的全流程。 ## 🚀 如何使用此模板 1. **创建新仓库**: 在 GitHub 或 GitLab 上，使用此模板创建一个新的代码仓库。 2. **克隆新仓库到本地**: ```bash git clone [你的新仓库地址] cd [你的新项目目录] ``` 3. **修改 `package.json`**: - 将 `name` 字段修改为你自己的包名 (例如: `"@your-scope/my-new-tool"`)。 - 将 `bin` 字段中的命令名修改为你的工具名 (例如: `"my-new-tool": "./dist/index.js"`)。 - 按需修改 `author`, `description` 等字段。 4. **安装依赖**: ```bash pnpm install ``` 5. **开始开发**: 你现在可以开始在 `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](https://www.conventionalcommits.org/) 规范。 - 通过 `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 1. 在 `src/tools/` 目录下创建一个新的 `*.tool.ts` 文件。 2. 参考 `src/tools/example.tool.ts` 的结构，定义一个新的 `Tool` 对象和对应的 `Handler` 函数。 3. 在 `src/server.ts` 中导入新的 Tool 和 Handler，并在请求处理逻辑中注册它。 ### 2. 编写测试 1. 在 `tests/` 目录下创建一个新的 `*.test.ts` 文件。 2. 参考 `tests/example.test.ts`，使用 `Vitest` 编写测试用例。 3. 如果你的 Tool 涉及到外部 API 请求，可以在 `tests/mocks/handlers.ts` 中使用 `msw` 添加对应的 mock 处理器。 ### 3. 本地调试 如果你想在本地像全局命令一样运行和调试你的工具，而不是每次都通过 `pnpm start`，你可以遵循以下步骤： 1. **构建项目**: 首先，你需要编译你的 TypeScript 源码，生成 `dist` 目录。 ```bash pnpm run build ``` 2. **链接包**: 使用 `npm link` 命令在你的系统中创建一个全局符号链接，指向你当前的项目。这会让你能直接运行在 `package.json` 的 `bin` 字段中定义的命令。 ```bash npm link ``` 3. **运行命令**: 现在你可以在任何终端窗口中直接运行你的命令了。 ```bash # 假设你的命令是 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](https://www.conventionalcommits.org/) 规范，例如： - `feat: add new feature` - `fix: resolve a bug` - `docs: update documentation` 这是自动化版本管理和 Changelog 生成的基础。 ## 📦 发布流程 当你准备好发布一个新版本时，只需简单地运行： ```bash pnpm release ``` `bumpp` 会启动一个交互式流程，引导你选择新的版本号。确认后，它会自动完成以下所有工作： 1. 更新 `package.json` 中的版本号。 2. 提交版本变更。 3. 创建一个以新版本号命名的 Git 标签 (e.g., `v1.2.3`)。 4. 将所有变更和标签推送到远程仓库。 5. 运行 `pnpm publish` 将包发布到 npm。 之后，GitLab CI (或 GitHub Actions) 会检测到新的标签，并根据 `.gitlab-ci.yml` 中的配置执行自动化发布流程。