MCP Server Template (

MCP 服务模板（create-mcp-server）

此模板可帮助你根据推荐实践，快速搭建新的 Model Context Protocol（MCP）服务项目。

用法（创建新服务）

要创建一个名为 my-new-mcp-server 的新 MCP 服务项目，请使用 npx 运行以下命令：

npx create-mcp-server my-new-mcp-server

（注意：如果你尚未将此软件包发布到 npm，可能需要先在此模板目录中运行 npm link，然后使用 create-mcp-server my-new-mcp-server）

此命令将：

1. 创建名为 my-new-mcp-server 的新目录。
2. 提示你填写项目详情（名称、描述）。
3. 将模板文件（src、docs、配置文件等）复制到新目录中。
4. 使用你的项目详情更新 package.json。

初始化后，请按照终端中提供的说明操作：

cd my-new-mcp-server
npm install
# Review configuration in src/config/ConfigurationManager.ts
# Add your tools in src/tools/
# Add your services in src/services/
npm run dev  # Start the development server

---

开发此模板（进阶）

本节介绍 mcp-server-template 模板本身的结构和开发流程。如果你只是使用此模板创建自己的服务，通常无需阅读本节。

项目结构

• /src：包含所有源代码。
  • /config：配置管理（ConfigurationManager）。
  • /services：核心业务逻辑类。
  • /tools：MCP 工具定义和适配器（*Tool.ts,*Params.ts）。
  • /types：TypeScript 接口和 Zod 模式。
  • /utils：共享实用函数（日志记录、错误处理等）。
  • initialize.ts：创建服务实例并注册工具。
  • server.ts：应用程序主入口。
• /dist：编译后的 JavaScript 输出（由 pm run build 生成）。
• package.json：项目元数据和依赖项。
• sconfig.json：TypeScript 编译器选项。
• .eslintrc.json：ESLint 配置。
• .prettierrc.json：Prettier 配置。
• .gitignore：Git 忽略规则。

开始使用

1. 安装依赖： ash npm install
2. 配置 Husky（如有需要，首次配置时）： ash npx husky install
3. 在开发模式下运行：（使用 s-node 和 odemon 自动重新加载） ash npm run dev
4. 构建生产版本： ash npm run build
5. 运行生产构建： ash npm start

添加新工具（yourTool）

1. **定义类型：**创建 src/types/yourServiceTypes.ts，定义接口（例如 YourServiceConfig、YourServiceData）。从 src/types/index.ts 导出。
2. **实现服务：**创建 src/services/YourService.ts，实现包含核心逻辑的类。从 src/services/index.ts 导出。
3. **定义工具参数：**创建 src/tools/yourToolParams.ts，其中包含 TOOL_NAME、TOOL_DESCRIPTION 和 TOOL_PARAMS（使用 Zod 并通过详细的 .describe() 调用提供说明）。
4. **实现工具注册：**创建 src/tools/yourTool.ts。导入服务和参数。创建一个函数，用于实例化服务并调用 server.tool()，传入一个异步处理程序，用于验证输入、调用服务、格式化输出并处理错误（映射到 McpError）。
5. **注册工具：**在 egisterTools 函数中，从 src/tools/index.ts 导入并调用注册函数。
6. **添加配置：**如有需要，更新 src/config/ConfigurationManager.ts，为新服务添加配置类型、默认值、获取器和更新器。
7. **添加实用函数：**如有需要，在 src/utils/ 中添加辅助函数并导出。
8. **编写测试：**在 src/services/ 中为服务逻辑添加单元测试，并可在 src/tools/ 中为工具适配器添加集成测试。

代码检查与格式化

• 代码检查： pm run lint
• 格式化： pm run format

提交时，Husky 和 lint-staged 会自动检查并格式化代码。