mcp-server-template

企业级 MCP 服务模板 🚀

一个可用于生产环境的企业级模板，用于使用 TypeScript 和 Node.js 构建 Model Context Protocol (MCP) 服务。专为可扩展性、类型安全，以及与 Claude Desktop、Cursor 等 AI Agent 无缝集成而设计。

📖 关于

Model Context Protocol (MCP) 标准化了 AI 模型与本地和远程资源的交互方式。此模板为构建自定义 MCP 服务提供了可靠的基础，可省去样板代码并落实最佳实践。

主要功能

• 严格的 TypeScript：使用现代 ECMAScript 目标版本，并提供严格的类型安全保障。
• Zod 验证：对工具输入和环境变量执行运行时架构验证，确保服务不会因格式错误的 AI 负载而崩溃。
• 快速打包（esbuild）：将整个服务编译为单个优化后的可执行文件（dist/index.js），无需部署 node_modules。
• 安全的结构化日志记录：预先配置的 pino 日志记录器安全地将日志写入 stderr，确保 MCP 所需的 stdout JSON-RPC 传输完整无损。
• 模块化架构：清晰分离工具、资源、提示词和服务。
• Vitest 集成：开箱即用的极速单元测试。

🚀 开始使用

1. 安装

克隆仓库并安装依赖：

git clone https://github.com/qmmughal/mcp-server-template.git
cd mcp-server-template
npm install

2. 配置

复制环境变量示例文件并配置变量：

cp .env.example .env

3. 开发工作流

在监视模式下启动服务，以便进行本地开发：

npm run dev

运行测试套件：

npm test

验证类型：

npm run typecheck

4. 生产构建

将服务打包为单个优化后的可执行文件：

npm run build

输出文件将生成在 dist/index.js。

🔌 连接到 MCP 客户端

Claude Desktop

要将此服务连接到 Claude Desktop 桌面应用，请编辑 Claude 配置文件（在 Windows 上通常位于 %APPDATA%\Claude\claude_desktop_config.json，在 Mac 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "enterprise-template-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-template/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "EXAMPLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

在 Cursor 中，前往 Settings -> Features -> MCP 并添加新的 MCP 服务：

• 类型：command
• 命令：node /absolute/path/to/mcp-server-template/dist/index.js

🏗️ 架构概览

• src/index.ts：应用入口、能力注册和 stdio 连接设置。
• src/tools/：MCP 工具的定义和 JSON 架构（AI 可执行的操作）。
• src/resources/：通过 URI 模板提供动态资源（AI 可读取的数据）。
• src/prompts/：可复用的 Agent 提示词模板。
• src/services/：核心业务逻辑，使协议处理程序保持精简且易于测试。
• src/utils/errors.ts：与 MCP 错误代码一致的标准化错误处理。

📦 发布与注册表

package.json 已做好发布准备（作用域名称 @qmmughal/mcp-server-template、许可证、仓库、关键词），并配置了 server.json 和 .github/workflows/publish-mcp.yml，每当推送 v* 标签时，便会自动发布到 npm 和 MCP Registry：

git tag v1.0.0
git push origin v1.0.0

工作流运行前需要设置一个仓库密钥：NPM_TOKEN（具有 @qmmughal 作用域发布权限的 npm 自动化令牌）。MCP Registry 使用 GitHub OIDC 进行身份验证，因此无需额外设置密钥。

🤝 参与贡献

欢迎贡献代码、提交问题和功能请求！欢迎查看 issues 页面。

📝 许可证

本项目基于 MIT 许可协议授权。