麦克普模板服务

Name: 麦克普模板服务
Author: cyanheads

作者：cyanheads102 星标更新：2025-10-28

安装使用来源：spider==github.com

项目介绍

技术文档摘要

<div align="center"> <h1>mcp-ts-template</h1> <p><b>用于构建模型上下文协议（MCP）服务器的生产级TypeScript模板。包含声明式工具/资源、强大的错误处理、依赖注入、简单的认证、可选的OpenTelemetry以及本地和边缘（Cloudflare Workers）运行时的一流支持。</b> <div>5 工具 • 1 资源 • 1 提示</div> </p> </div> <div align="center">

</div>

✨ 特性

声明式工具与资源：在单个自包含文件中定义功能。框架负责注册和执行。
交互式支持：工具可以在执行过程中交互式地提示用户缺失的参数，简化用户工作流程。
强大的错误处理：统一的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、frontmatter）、格式化器（差异、表格、树形结构、markdown）、调度、安全等。
边缘就绪：编写一次代码，无缝运行在本地机器或Cloudflare Workers边缘。

🏗️ 架构

此模板遵循模块化、领域驱动的架构，明确分离关注点：

┌─────────────────────────────────────────────────────────┐
│              MCP 客户端（Claude Code，ChatGPT 等）    │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC 2.0
                     ▼
┌─────────────────────────────────────────────────────────┐
│           MCP 服务器（工具，资源）                      │
│           📖 [MCP 服务器指南](src/mcp-server/)         │
└────────────────────┬────────────────────────────────────┘
                     │ 依赖注入
                     ▼
┌─────────────────────────────────────────────────────────┐
│          依赖注入容器                                  │
│              📦 [容器指南](src/container/)             │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
 ┌──────────┐   ┌──────────┐   ┌──────────┐
 │ 服务     │   │ 存储      │   │ 实用程序 │
 │ 🔌 [→]   │   │ 💾 [→]   │   │ 🛠️ [→]   │
 └──────────┘   └──────────┘   └──────────┘

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

关键模块：

MCP 服务器 - 工具、资源、提示和传输层实现
容器 - 使用tsyringe的干净架构依赖注入设置
服务 - 外部服务集成（LLM、语音、图）及其插件式提供者
存储 - 支持多个后端的抽象持久层
实用程序 - 横切关注点（日志记录、安全性、解析、遥测）

💡 提示：每个模块都有自己的详细README，包含架构图、使用示例和最佳实践。点击上面的链接深入了解！

🛠️ 包含的功能

此模板包含一些示例以帮助您开始。

工具

工具	描述
`template_echo_message`	回显一条消息，可选格式化和重复。
`template_cat_fact`	从外部API获取随机猫事实。
`template_madlibs_elicitation`	通过询问单词来完成故事，演示交互式输入。
`template_code_review_sampling`	使用LLM服务模拟代码审查。
`template_image_test`	返回一个作为base64编码数据URI的测试图像。

资源

资源	URI	描述
`echo`	`echo://{message}`	一个简单的资源，回显一条消息。

提示

提示	描述
`code-review`	结构化的提示，引导LLM进行代码审查。

🚀 开始使用

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 v1.2.21 或更高版本。

安装

克隆仓库：

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

cd mcp-ts-template

安装依赖项：

bun install

⚙️ 配置

所有配置都在启动时集中并验证于src/config/index.ts。您的.env文件中的关键环境变量包括：

变量	描述	默认值
`MCP_TRANSPORT_TYPE`	使用的传输类型：`stdio`或`http`。	`http`
`MCP_HTTP_PORT`	HTTP服务器的端口。	`3010`
`MCP_HTTP_HOST`	HTTP服务器的主机名。	`127.0.0.1`
`MCP_AUTH_MODE`	认证模式：`none`，`jwt`或`oauth`。	`none`
`MCP_AUTH_SECRET_KEY`	对于`jwt`认证模式必需。 32个字符以上的密钥。	`(none)`
`OAUTH_ISSUER_URL`	对于`oauth`认证模式必需。 OIDC提供者的URL。	`(none)`
`STORAGE_PROVIDER_TYPE`	存储后端：`in-memory`，`filesystem`，`supabase`，`surrealdb`，`cloudflare-d1`，`cloudflare-kv`，`cloudflare-r2`。	`in-memory`
`STORAGE_FILESYSTEM_PATH`	对于`filesystem`存储必需。存储目录的路径。	`(none)`
`SUPABASE_URL`	对于`supabase`存储必需。您的Supabase项目URL。	`(none)`
`SUPABASE_SERVICE_ROLE_KEY`	对于`supabase`存储必需。您的Supabase服务角色密钥。	`(none)`
`SURREALDB_URL`	对于`surrealdb`存储必需。 SurrealDB端点（例如`wss://cloud.surrealdb.com/rpc`）。	`(none)`
`SURREALDB_NAMESPACE`	对于`surrealdb`存储必需。 SurrealDB命名空间。	`(none)`
`SURREALDB_DATABASE`	对于`surrealdb`存储必需。 SurrealDB数据库名称。	`(none)`
`SURREALDB_USERNAME`	对于`surrealdb`存储可选。数据库用户名用于身份验证。	`(none)`
`SURREALDB_PASSWORD`	对于`surrealdb`存储可选。数据库密码用于身份验证。	`(none)`
`OTEL_ENABLED`	设置为`true`启用OpenTelemetry。	`false`
`LOG_LEVEL`	日志记录的最小级别（`debug`，`info`，`warn`，`error`）。	`info`
`OPENROUTER_API_KEY`	OpenRouter LLM服务的API密钥。	`(none)`

认证与授权

模式：none（默认），jwt（需要MCP_AUTH_SECRET_KEY），或oauth（需要OAUTH_ISSUER_URL和OAUTH_AUDIENCE）。
强制执行：使用withToolAuth([...])或withResourceAuth([...])包装您的工具/资源logic函数以执行范围检查。当认证模式为none时，为开发人员便利，范围检查被绕过。

存储

服务：DI管理的StorageService提供了持久化的统一API。永远不要直接从工具逻辑访问fs或其他存储SDK。
提供者：默认是in-memory。仅限Node的提供者包括filesystem。边缘兼容的提供者包括supabase，surrealdb，cloudflare-kv和cloudflare-r2。
SurrealDB设置：使用surrealdb提供者时，在首次使用前使用docs/surrealdb-schema.surql初始化数据库模式。
多租户：StorageService需要context.tenantId。当启用认证时，这会自动从JWT的tid声明传播。
高级功能：
- 安全分页：绑定租户ID的不透明游标防止跨租户攻击
- 批处理操作：getMany()，setMany()，deleteMany()的并行执行
- TTL支持：所有提供者中的正确过期处理
- 全面验证：租户ID、键和选项的集中输入验证

可观测性

结构化日志记录：Pino开箱即用。所有日志都是JSON，并包含RequestContext。
OpenTelemetry：默认禁用。通过OTEL_ENABLED=true启用并配置OTLP端点。每个工具调用的跟踪、指标（持续时间、负载大小）和错误都会自动捕获。

▶️ 运行服务器

本地开发

构建并运行生产版本：

# 一次性构建
bun rebuild

# 运行已构建的服务器
bun start:http
# 或
bun start:stdio

运行检查和测试：

bun devcheck # 代码检查、格式化、类型检查等
bun run test # 运行测试套件（不要直接使用'bun test'，因为它可能无法正常工作）

Cloudflare Workers

构建Worker捆绑包：

bun build:worker

使用Wrangler本地运行：

bun deploy:dev

部署到Cloudflare：

bun deploy:prod

注意：wrangler.toml文件预配置了nodejs_compat以获得最佳结果。

📂 项目结构

目录	目的及内容	指南
`src/mcp-server/tools/definitions`	您的工具定义（`*.tool.ts`）。这是您添加新功能的地方。	📖 MCP指南
`src/mcp-server/resources/definitions`	您的资源定义（`*.resource.ts`）。这是您添加新数据源的地方。	📖 MCP指南
`src/mcp-server/transports`	HTTP和STDIO传输的实现，包括认证中间件。	📖 MCP指南
`src/storage`	`StorageService`抽象和所有存储提供者实现。	💾 存储指南
`src/services`	与外部服务的集成（例如，默认的OpenRouter LLM提供者）。	🔌 服务指南
`src/container`	依赖注入容器注册和服务令牌。	📦 容器指南
`src/utils`	核心实用程序，包括日志记录、错误处理、性能、安全性和遥测。
`src/config`	使用Zod解析和验证环境变量。
`tests/`	单元和集成测试，镜像`src/`目录结构。

📚 文档

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

核心模块

MCP服务器指南 - 构建MCP工具和资源的完整指南
- 使用声明式定义创建工具
- 使用URI模板开发资源
- 认证和授权
- 传输层（HTTP/stdio）配置
- SDK上下文和客户端交互
- 响应格式化和错误处理
容器指南 - 使用tsyringe的依赖注入
- 理解DI令牌和注册
- 服务生命周期（单例、瞬态、实例）
- 构造函数注入模式
- 使用模拟依赖项进行测试
- 向容器添加新服务
服务指南 - 外部服务集成模式
- LLM提供商集成（OpenRouter）
- 语音服务（TTS/STT与ElevenLabs，Whisper）
- 图数据库操作（SurrealDB）
- 创建自定义服务提供商
- 健康检查和错误处理
存储指南 - 抽象持久层
- 存储提供者实现
- 多租户和租户隔离
- 安全基于游标的分页
- 批处理操作和TTL支持
- 提供商特定的设置指南

额外资源

AGENTS.md - 使用AI代理时的严格开发规则
CHANGELOG.md - 版本历史和重大变更
docs/tree.md - 完整的可视化目录结构
docs/publishing-mcp-server-registry.md - MCP注册表发布指南

🧑‍💻 代理开发指南

使用此模板与AI代理时，请参阅**AGENTS.md**中的严格规则集。关键原则包括：

逻辑抛出，处理器捕获：在您的工具/资源logic中永远不要使用try/catch。相反，抛出一个McpError。
使用交互式输入获取缺失输入：如果工具需要未提供的