H402 MCP Template

mcp-ts-template

Production-grade TypeScript template for building Model Context Protocol (MCP) servers. Ships with declarative tools/resources, robust error handling, DI, easy auth, optional OpenTelemetry, and first-class support for both local and edge (Cloudflare Workers) runtimes.

5 Tools • 1 Resource • 1 Prompt

______________________________________________________________________

✨ 特点

• 声明式工具与资源在单个、自包含的文件中定义功能。框架负责注册和执行。
• 启发支持（或引出支持，根据上下文可灵活翻译）工具可以在执行过程中交互式地提示用户输入缺失的参数，从而简化用户的工作流程。
• 强大的错误处理一个统一的 McpError 该系统确保服务器上错误响应的一致性和结构化。
• 可插拔认证为您的服务器提供无忧支持，确保安全 none， jwt，或者 oauth 模式。
• 抽象存储交换存储后端（in-memory， filesystem， Supabase， SurrealDB， Cloudflare D1/KV/R2) 在不改变业务逻辑的情况下，具备安全的不透明游标分页、并行批量操作以及全面的验证功能。
• 图数据库操作可选的图服务，用于关系管理、图遍历和路径查找算法（SurrealDB 提供商）。
• 全栈可观测性通过结构化日志记录（Pino）和可选的自动插桩OpenTelemetry，获取深入见解，用于追踪和指标收集。
• 依赖注入用……建造/构建 tsyringe 为了实现一个干净、解耦且可测试的架构。
• 服务集成针对外部API的可插拔服务，包括大型语言模型（LLM）提供商（OpenRouter）、文本转语音（ElevenLabs）以及图数据库操作（SurrealDB）。
• 丰富的内置实用工具套件解析（PDF、YAML、CSV、前置信息）、格式化（差异、表格、树形结构、Markdown）、调度、安全等辅助工具。
• “Edge-Ready”可以翻译为“已就绪，可边缘部署”或“准备就绪，适用于边缘环境”。这个短语通常用于描述技术或产品已经准备好在边缘计算环境中使用或部署编写一次代码，即可在本地机器或 Cloudflare Workers 边缘节点上无缝运行。

🏗️ 建筑学

此模板遵循模块化、领域驱动的设计架构，具有明确的职责分离：

┌─────────────────────────────────────────────────────────┐
│              MCP Client (Claude Code, ChatGPT, etc.)    │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC 2.0
                     ▼
┌─────────────────────────────────────────────────────────┐
│           MCP Server (Tools, Resources)                 │
│           📖 [MCP Server Guide](src/mcp-server/)        │
└────────────────────┬────────────────────────────────────┘
                     │ Dependency Injection
                     ▼
┌─────────────────────────────────────────────────────────┐
│          Dependency Injection Container                 │
│              📦 [Container Guide](src/container/)       │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
 ┌──────────┐   ┌──────────┐   ┌──────────┐
 │ Services │   │ Storage  │   │ Utilities│
 │ 🔌 [→]   │   │ 💾 [→]   │   │ 🛠️ [→]   │
 └──────────┘   └──────────┘   └──────────┘

[→]: src/services/    [→]: src/storage/    [→]: src/utils/

关键模块：

• MCP 服务器 - 工具、资源、提示和传输层实现
• 集装箱 - 使用tsyringe进行依赖注入设置，以实现整洁架构
• 服务 - 与可插拔提供者集成的外部服务（大型语言模型、语音、图形）
• 存储 - 支持多种后端的抽象持久层
• 公用事业 - 横切关注点（日志记录、安全性、解析、遥测）

💡 灯泡（或表示“想法”、“灵感”的表情符号） 提示每个模块都附有详尽的README文件，其中包含架构图、使用示例和最佳实践。点击上方的链接深入了解！

🛠️ 包含的功能

这个模板包含了一些实用示例，帮助您快速上手。

工具

资源

提示

🚀 开始入门

MCP 客户端设置/配置

在您的MCP客户端配置文件中添加以下内容（例如。， cline_mcp_settings.json）。

{
  "mcpServers": {
    "mcp-ts-template": {
      "type": "stdio",
      "command": "bunx",
      "args": ["mcp-ts-template@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "/path/to/your/storage"
      }
    }
  }
}

先决条件

• Bun 版本 1.2.21 或更高。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/mcp-ts-template.git

1. 导航进入该目录：

cd mcp-ts-template

1. 安装依赖项：

bun install

⚙️ 配置

所有配置在启动时集中进行并验证 src/config/index.ts您系统中的关键环境变量 .env 文件包含：

认证与授权

• 模式: none （默认）， jwt （需要 MCP_AUTH_SECRET_KEY)，或者 oauth （需要 OAUTH_ISSUER_URL 并且 OAUTH_AUDIENCE）。
• 执行包装你的工具/资源 logic 带有函数的功能/特性 withToolAuth([...]) 或者 withResourceAuth([...]) 以执行范围检查。当认证模式为（某种模式时，为开发者的便利起见，会跳过范围检查） none。

存储

• 服务一个由DI（依赖注入）管理的 StorageService 提供了一致的API用于持久化。 永远不要访问 fs 或直接从工具逻辑中使用其他存储SDK。
• 服务提供者默认设置是 in-memory仅节点提供者包括 filesystem与Edge兼容的提供商包括 supabase， surrealdb， cloudflare-kv，以及 cloudflare-r2。
• SurrealDB 安装配置当使用时 surrealdb 提供者，使用（工具/方法）初始化数据库架构 docs/surrealdb-schema.surql 首次使用前。
• 多租户（性）这个（或：该） StorageService 需要 context.tenantId这个会自动从……传播过来 tid 当启用身份验证时，在JWT（JSON Web Token）中声明。
• 高级功能：

- 安全分页带有租户ID绑定的不透明光标可防止跨租户攻击 - 批处理操作并行执行用于 getMany()， setMany()， deleteMany() - TTL 支持在所有提供商中实现带适当过期处理的生存时间（Time-to-live） - 全面验证租户ID、密钥和选项的集中输入验证

可观测性

• 结构化日志记录Pino开箱即用。所有日志均为JSON格式，并包含 RequestContext。
• OpenTelemetry默认禁用。如需启用，请使用 OTEL_ENABLED=true 并配置OTLP（Open Telemetry Protocol）端点。每次工具调用时，都会自动捕获追踪信息、指标（持续时间、有效载荷大小）和错误。

▶️ 运行服务器

本地开发

• 构建并运行生产版本:

  # One-time build
  bun rebuild

  # Run the built server
  bun start:http
  # or
  bun start:stdio

• 运行检查和测试：

  bun devcheck # Lints, formats, type-checks, and more
  bun run test # Runs the test suite (Do not use 'bun test' directly as it may not work correctly)

Cloudflare Workers（云网工）

1. 构建Worker包：

bun build:worker

1. 使用 Wrangler 在本地运行：

bun deploy:dev

1. 部署到Cloudflare：

bun deploy:prod

注这个 wrangler.toml 文件已预先配置以启用 nodejs_compat 以获得最佳效果。

📂 项目结构

📚 文档

每个主要模块都包含全面的文档，其中包括架构图、使用示例和最佳实践：

核心模块

• MCP服务器指南 - 构建MCP工具和资源的完整指南

- 使用声明式定义创建工具 - 使用URI模板进行资源开发 - 认证和授权 - 传输层（HTTP/stdio）配置 - SDK上下文和客户端交互 - 响应格式化和错误处理

• 集装箱指南 - 使用tsyringe进行依赖注入

- 理解DI令牌和注册 - 服务生命周期（单例、瞬态、实例） - 构造函数注入模式 - 使用模拟依赖进行测试 - 向容器中添加新服务

• 服务指南 - 外部服务集成模式

- 大型语言模型（LLM）提供商集成（OpenRouter） - 语音服务（使用ElevenLabs、Whisper的TTS/STT） - 图数据库操作（SurrealDB） - 创建自定义服务提供者 - 健康检查和错误处理

• 存储指南 - 抽象化的持久层

- 存储提供商的实现 - 多租户和租户隔离 - 基于光标的分页（安全实现） - 批处理操作和TTL支持 - 特定提供商的设置指南

额外资源

• AGENTS.md 翻译为中文是：“代理文件.md” - 为AI代理制定严格的发展规则
• CHANGELOG.md 翻译为中文是：“变更日志文件（Markdown 格式）” - 版本历史和重大变更
• docs/tree.md 翻译为中文是：“文档/树状结构.md” 或者更自然的表达可能是“文档/目录结构.md”，这里“tree.md”通常指的是描述文件或目录树状结构的Markdown文件 - 完整的视觉目录结构
• docs/publishing-mcp-server-registry.md 翻译为中文是：docs/发布MCP服务器注册表.md - MCP注册中心发布指南

🧑‍💻 代理开发指南

如需了解在使用此模板与AI代理时应遵循的严格规则，请参阅 AGENTS.md关键原则包括：

• 逻辑抛出，处理程序捕获永远不要使用 try/catch 在你的工具/资源中 logic. 扔一个 McpError 相反。
• 使用引出法处理缺失的输入如果某个工具需要用户输入而用户未提供，使用 elicitInput 来自（或：来自...的功能） SdkContext 向用户请求它。
• 传递上下文总是要传递 RequestContext 通过你的调用栈来获取对象。
• 使用桶装出口仅在（指定的）地方注册新的工具和资源 index.ts 桶装文件。

❓ 常见问题解答 (FAQ)

• 这个功能同时支持STDIO和Streamable HTTP吗？

- 是的。这两种传输方式都是第一等的。使用 bun run dev:stdio 或者 bun run dev:http。

• 我可以将这个部署到边缘吗？

- 是的。这个模板是为Cloudflare Workers设计的。运行 bun run build:worker 并使用 Wrangler 进行部署。

• 我必须使用 OpenTelemetry 吗？

- 不，默认情况下它是禁用的。通过设置来启用它 OTEL_ENABLED=true 在你的 .env 文件。

• 如何将我的服务器发布到MCP注册表中？

- 按照以下分步指南操作 docs/publishing-mcp-server-registry.md.

🤝 贡献（或：参与贡献）

欢迎提出问题和拉取请求！如果您计划做出贡献，请在提交拉取请求前先进行本地检查和测试。

bun run devcheck
bun test

📜 许可证

此项目遵循Apache 2.0许可证。详见 许可证 文件中详述。

______________________________________________________________________

Sponsor this project • Buy me a coffee