mcp-ts模板
构建具有强大、类型安全和可扩展基础的生产级模型上下文协议(MCP)服务器。
此模板为构建丰富的模型上下文协议服务器提供了全面的基础,遵守 MCP 2025-06-18规范 以及现代最佳实践。它包括一个功能齐全的服务器、生产就绪的实用程序和清晰的文档,可以让您快速启动和运行。
🤔 为什么使用此模板?
为AI代理构建一个强大的服务器不仅仅是编写代码。它需要一个坚实的架构、一致的错误处理以及从头开始的安全、类型安全的实践。该模板通过提供以下功能解决了这些挑战:
- 加速发展:跳过样板,专注于工具的核心逻辑。
- 生产就绪基础:内置日志记录、错误处理、安全性和测试。
- 默认最佳实践:强制实施易于维护和扩展的干净、模块化架构。
- AI就绪:设计时考虑了LLM代理,包括详细的模式和丰富的LLM开发人员友好资源(例如.clinerules)。
> 关于src/mcp客户端和src/agent的说明: MCP客户端和代理组件已得到增强,并已移动到 atlas-mcp试剂 存储库。此模板现在专注于提供一流的服务器实现和框架。
✨ 主要特点
| 功能区 | 描述 | 关键组件/位置 |
|---|---|---|
| 🔌 MCP服务器 | 具有示例工具和资源的功能服务器。支持 stdio 以及a 流式HTTP 运输用 你好. |
src/mcp-server/, src/mcp-server/transports/ |
| 🔭 可观测性 | 内置 开放遥测 用于分布式跟踪和度量。核心模块的自动检测和所有工具执行的自定义跟踪。 | src/utils/telemetry/ |
| 🚀 生产公用设施 | 日志记录、错误处理、ID生成、速率限制、请求上下文跟踪、输入净化。 | src/utils/ |
| 🔒 类型安全/安保 | 通过TypeScript和Zod验证进行强类型检查。内置安全实用程序(净化、HTTP身份验证中间件)。 | 自始至终, src/utils/security/, src/mcp-server/transports/auth/ |
| ⚙️ 错误处理 | 一致的错误分类(BaseErrorCode),详细记录,集中处理(ErrorHandler). |
src/utils/internal/errorHandler.ts, src/types-global/ |
| 📚 文档 | 综合 README.md,结构化JSDoc注释,API参考。 |
README.md,代码库, tsdoc.json, docs/api-references/ |
| 🕵️ 交互日志记录 | 捕获所有外部LLM提供商与专用LLM提供商交互的原始请求和响应 interactions.log 文件以实现完全可追溯性。 |
src/utils/internal/logger.ts |
| 🤖 代理就绪 | 包括a .微规则 为LLM编码代理量身定制的开发人员备忘单。 | .clinerules/ |
| 🛠️ 实用程序脚本 | 用于清理构建、设置可执行权限、生成目录树和获取OpenAPI规范的脚本。 | scripts/ |
| 🧩 服务 | 用于LLM(OpenRouter)和数据存储(DuckDB)集成的可重用模块,并附有示例。 | src/services/, src/storage/duckdbExample.ts |
| 🧪 集成测试 | 与Vitest集成,实现快速可靠的集成测试。包括核心逻辑和覆盖率报告器的示例测试。 | vitest.config.ts, tests/ |
| ⏱️ 性能指标 | 内置实用程序,可自动测量和记录每次工具调用的执行时间和有效载荷大小。 | src/utils/internal/performance.ts |
架构概述
此模板基于一组架构原则构建,以确保模块化、可测试性和操作清晰度。
- 核心服务器(
src/mcp-server/server.ts):登记工具和资源的中心点。它使用aManagedMcpServer包装器提供增强的自检功能。它的行为方式与本机McpServer相同,但具有自检和增强的错误处理等附加功能。 - 运输(
src/mcp-server/transports/):传输层将核心服务器连接到外部世界。它支持两者stdio用于直接过程通信和流式传输 你好表示“总部设在…的”、“以…为基地的”http服务器。 - “逻辑抛出,处理器捕获”:这是我们错误处理策略不可改变的基石。
- 核心逻辑(
logic.ts):此层负责纯的、自包含的业务逻辑。它 投掷 结构化的McpError任何失败。 - 处理人员(
registration.ts):该层与服务器接口,调用核心逻辑,以及 捕获 任何错误。它是处理错误并将其格式化为最终响应的唯一位置。 - 结构化、可追溯的操作:每个操作都通过
RequestContext它通过整个调用栈传递,确保全面和结构化的日志记录。
快速开始
1.安装
克隆存储库并安装依赖项:```bash
git clone https://github.com/cyanheads/mcp-ts-template.git
cd mcp-ts-template
npm install
### 2.建设项目```bash
npm run build
# Or use 'npm run rebuild' for a clean install
3.运行服务器
- 通过Stdio(默认):```bash
npm run start:server
- **通过可流式HTTP:**```bash
npm run start:server:http
4.运行测试
此模板使用 速度 用于测试,特别强调 集成测试 以确保所有组件正确协同工作。
- 运行所有测试一次:```bash
npm test
- **在监视模式下运行测试:**```bash
npm run test:watch
- 运行测试并生成覆盖率报告:```bash
npm run test:coverage
## ⚙️ 配置
使用这些环境变量(或 `.env` 文件):
|变量|描述|默认值|
| :-------------------- | :---------------------------------------------------------------------------------------- | :------------------------------------- |
| `MCP_TRANSPORT_TYPE` |服务器传输: `stdio` 或 `http`. | `stdio` |
| `MCP_SESSION_MODE` |HTTP的会话模式: `stateless`, `stateful`,或 `auto`. | `auto` |
| `MCP_HTTP_PORT` |HTTP服务器的端口。 | `3010` |
| `MCP_HTTP_HOST` |HTTP服务器的主机地址。 | `127.0.0.1` |
| `MCP_ALLOWED_ORIGINS` |逗号分隔允许CORS的起源。|(无)|
| `MCP_AUTH_MODE` |HTTP的身份验证模式: `jwt`, `oauth`,或 `none`. | `none` |
| `MCP_AUTH_SECRET_KEY` | **要求…… `jwt` 模式。** 用于签名/验证身份验证令牌的密钥(最少32个字符)。|(无- **必须在生产中设置**) |
| `OAUTH_ISSUER_URL` | **要求…… `oauth` 模式。** 您的授权服务器的发行者URL。|(无)|
| `OAUTH_AUDIENCE` | **要求…… `oauth` 模式。** 此MCP服务器的受众标识符。|(无)|
| `OPENROUTER_API_KEY` |OpenRouter.ai服务的API密钥。|(无)|
| `OTEL_ENABLED` |设置为 `true` 以启用OpenTetry仪器。 | `false` |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` |用于导出轨迹的OTLP端点(例如。, `http://localhost:4318/v1/traces`).|(无;记录到文件中)|
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` |用于导出度量的OTLP端点(例如。, `http://localhost:4318/v1/metrics`).|(无)|
## 🏗️ 项目结构
- **`src/mcp-server/`**:包含核心MCP服务器、工具、资源和传输处理程序。
- **`src/config/`**:处理环境变量的加载和验证。
- **`src/services/`**:用于与外部服务集成的可重用模块(DuckDB、OpenRouter)。
- **`src/types-global/`**:定义共享的TypeScript接口和类型定义。
- **`src/utils/`**:核心实用程序(日志记录、错误处理、安全性等)。
- **`src/index.ts`**:初始化和启动服务器的主要入口点。
**亲自探索整个结构:**
请参阅中的当前文件树 docs/tree.md 或者动态生成它:```bash
npm run tree
🧩 扩展系统
该模板强制执行严格的模块化模式,以添加新的工具和资源,如 建筑标准The echoTool (src/mcp-server/tools/echoTool/)作为典型示例。
“逻辑抛出,处理器捕获”模式
这是架构的基石:
logic.ts:此文件包含纯业务逻辑。
- 它定义了输入和输出的Zod模式,这些模式是工具数据契约的唯一真实来源。
- 核心逻辑函数是纯的:它接受经过验证的参数和请求上下文,并返回结果或 投掷 结构化的
McpError. - 它 从不 包含
try...catch用于格式化最终响应的块。
registration.ts:此文件是将逻辑连接到MCP服务器的“处理程序”。
- 它从以下位置导入模式和逻辑函数
logic.ts. - 它召唤
server.registerTool(),提供工具的元数据和运行时处理程序。 - 运行时处理程序 总是 将对逻辑函数的调用封装在
try...catch块。这就是 仅 错误被捕获、处理的地方ErrorHandler,并格式化为标准化的错误响应。
这种模式确保核心逻辑保持解耦、纯粹和易于测试,而注册层处理所有传输级问题、副作用和响应格式。
🌍 探索更多MCP资源
您在寻找更多示例、指南和预构建的MCP服务器吗?查看配套存储库:
➡️ cyanheads/模型上下文协议资源
📜 许可证
此项目根据Apache许可证2.0获得许可。请参阅 许可证 文件以获取详细信息。
