mcp-ts模板
构建具有强大、类型安全和可扩展基础的生产级模型上下文协议（MCP）服务器。
  ](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) ](./CHANGELOG.md)    ](https://github.com/cyanheads/mcp-ts-template)
此模板为构建丰富的模型上下文协议服务器提供了全面的基础，遵守 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.安装
克隆存储库并安装依赖项：
git clone https://github.com/cyanheads/mcp-ts-template.git
cd mcp-ts-template
npm install2.建设项目
npm run build
# Or use 'npm run rebuild' for a clean install3.运行服务器
- 通过Stdio（默认）：
npm run start:server- 通过可流式HTTP:
npm run start:server:http4.运行测试
此模板使用 速度 用于测试，特别强调 集成测试 以确保所有组件正确协同工作。
- 运行所有测试一次：
npm test- 在监视模式下运行测试：
npm run test:watch- 运行测试并生成覆盖率报告：
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 或者动态生成它：
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服务器吗？查看配套存储库：
📜 许可证
此项目根据Apache许可证2.0获得许可。请参阅 许可证 文件以获取详细信息。