内容
# 企业MCP服务器模板 🚀
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
一个为构建 **模型上下文协议（MCP）** 服务器而准备的生产就绪型、企业级模板，使用TypeScript和Node.js。设计用于可扩展性、类型安全性和与Claude Desktop和Cursor等AI代理的无缝集成。
## 📖 关于
**模型上下文协议（MCP）** 标准化了AI模型与本地和远程资源之间的交互方式。该模板为构建您自己的自定义MCP服务器提供了坚实的基础，消除了样板代码并强制执行最佳实践。
### 主要功能
- **严格的TypeScript**：现代ECMAScript目标，具有严格的类型安全性。
- **Zod验证**：工具输入和环境变量的运行时模式验证，确保您的服务器不会因格式错误的AI有效载荷而崩溃。
- **快速捆绑（esbuild）**：将整个服务器编译为单个优化的可执行文件（`dist/index.js`），无需部署`node_modules`。
- **安全结构化日志记录**：预配置的`pino`日志记录器安全地写入`stderr`，保留`stdout` JSON-RPC传输的完整性，MCP需要该传输。
- **模块化架构**：工具、资源、提示和服务的清晰分离。
- **Vitest集成**：开箱即用的超快速单元测试。
## 🚀 快速开始
### 1. 安装
克隆仓库并安装依赖项：
```bash
git clone https://github.com/qmmughal/mcp-server-template.git
cd mcp-server-template
npm install
```
### 2. 配置
复制示例环境文件并配置您的变量：
```bash
cp .env.example .env
```
### 3. 开发工作流
在监视模式下启动服务器进行本地开发：
```bash
npm run dev
```
运行测试套件：
```bash
npm test
```
验证类型：
```bash
npm run typecheck
```
### 4. 生产构建
将服务器捆绑为单个优化的可执行文件：
```bash
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`）：
```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中，导航到 **设置 -> 功能 -> MCP** 并添加新的MCP服务器：
- **类型**：`command`
- **命令**：`node /absolute/path/to/mcp-server-template/dist/index.js`
## 🏗️ 架构概述
- `src/index.ts`：应用程序入口点、功能注册和stdio连接设置。
- `src/tools/`：MCP工具（AI可以采取的行动）的定义和JSON模式。
- `src/resources/`：通过URI模板化的动态资源（AI可以读取的数据）。
- `src/prompts/`：可重用的代理提示模板。
- `src/services/`：核心业务逻辑，保持协议处理程序精简和可测试。
- `src/utils/errors.ts`：与MCP错误代码对齐的标准错误处理。
## 📦 发布和注册
`package.json` 已准备好发布（作用域名称 `@qmmughal/mcp-server-template`、许可证、仓库、关键词），`server.json` 和 `.github/workflows/publish-mcp.yml` 已配置好，以便在推送 `v*` 标签时自动发布到 **npm** 和 **MCP注册表**：
```bash
git tag v1.0.0
git push origin v1.0.0
```
工作流需要一个仓库秘密才能运行：`NPM_TOKEN`（具有发布权限到 `@qmmughal` 作用域的npm自动化令牌）。MCP注册表身份验证使用GitHub OIDC，因此不需要额外的秘密。
## 🤝 贡献
欢迎贡献、问题和功能请求！请随意查看问题页面。
## 📝 许可证
该项目是 [MIT](LICENSE) 许可的。
