AI导哈

MCP服务器模板

一个用于构建生产级Model Context Protocol（MCP）服务器的强大、类型安全且可扩展的模板，适用于AI代理开发和集成。

  • by IsKaros
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 iskaros/yunxiao-mcp-server

使用说明

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)：登记工具和资源的中心点。它使用a ManagedMcpServer 包装器提供增强的自检功能。它的行为方式与本机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 install

2.建设项目

npm run build
# Or use 'npm run rebuild' for a clean install

3.运行服务器

  • 通过Stdio（默认）：
    npm run start:server
  • 通过可流式HTTP:
    npm run start:server:http

4.运行测试

此模板使用 速度 用于测试，特别强调 集成测试 以确保所有组件正确协同工作。

  • 运行所有测试一次：
    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/)作为典型示例。

“逻辑抛出，处理器捕获”模式

这是架构的基石：

  1. logic.ts：此文件包含纯业务逻辑。

    • 它定义了输入和输出的Zod模式，这些模式是工具数据契约的唯一真实来源。
    • 核心逻辑函数是纯的：它接受经过验证的参数和请求上下文，并返回结果或 投掷 结构化的 McpError.
    • 它 从不 包含 try...catch 用于格式化最终响应的块。

  2. registration.ts：此文件是将逻辑连接到MCP服务器的“处理程序”。

    • 它从以下位置导入模式和逻辑函数 logic.ts.
    • 它召唤 server.registerTool()，提供工具的元数据和运行时处理程序。
    • 运行时处理程序 总是 将对逻辑函数的调用封装在 try...catch 块。这就是 仅 错误被捕获、处理的地方 ErrorHandler，并格式化为标准化的错误响应。

这种模式确保核心逻辑保持解耦、纯粹和易于测试，而注册层处理所有传输级问题、副作用和响应格式。

🌍 探索更多MCP资源

您在寻找更多示例、指南和预构建的MCP服务器吗？查看配套存储库：

➡️ cyanheads/模型上下文协议资源

📜 许可证

此项目根据Apache许可证2.0获得许可。请参阅 许可证 文件以获取详细信息。

相关 MCP