项目介绍
MCP服务器示例：OAuth、TypeScript及Firestore模式
此仓库提供了一个精简且具有说明性的Model Context Protocol（MCP）服务器实现。它展示了架构模式、安全考虑（OAuth 2.0）以及开发实践（TypeScript、Firestore、Zod），这些内容在我们的配套文章中有详细描述：
➡️ 阅读全文："使用OAuth、TypeScript构建生产就绪的MCP服务器及其经验教训"
本示例专注于MCP资源服务器组件，并假设您有一个独立的OAuth 2.0授权服务器。
更新：MCP SDK版本1.12.0引入了授权服务器元数据（/.well-known/oauth-authorization-server）支持，并移除了通过MCP资源服务器代理OAuth调用的需求。
目的
此仓库旨在作为学习资源，用于：
- 展示如何使用TypeScript MCP SDK实现一个实际的MCP服务器。
- 说明如何集成OAuth 2.0以保护工具调用的安全性。
- 展示管理工作区上下文和多租户模式的方法。
- 提供使用Zod定义和验证模式的例子。
- 提供关于结构化工具、使用高阶组件（HOC）进行常见逻辑处理以及与Firestore交互的见解。
这不是适用于所有情况的生产就绪、即插即用服务器。 它省略了特定的业务逻辑，并假定存在一个预先存在的OAuth授权服务器。
主要功能及展示模式
- MCP TypeScript SDK集成： 核心服务器设置和工具注册。
- OAuth 2.0令牌验证： 安全地处理Bearer令牌（通过SDK中间件）。
- 工作区上下文管理：
- 工具参数中的显式
workspace_id。 - 使用
withWorkspaceAccess高阶组件（HOC）进行身份验证和工作区授权。
- 工具参数中的显式
- Firestore集成：
- 获取用户数据、OAuth令牌信息（概念性）和工具特定的数据。
- 使用Firestore模拟器进行本地开发和测试。
- Zod用于模式定义和验证： 定义工具的输入模式并利用Zod进行运行时验证。
- 类型安全开发： 利用TypeScript进行健壮的代码编写。
- 实用函数： 如
fetchResourceList用于DRY数据获取的示例。 - 标准化错误处理： 使用
throw new Error()进行清晰的错误传播。 - 示例工具结构： 基本工具定义展示模式。
- 环境变量配置： 数据库和OAuth设置。
架构概述
此示例代表的是MCP资源服务器。它期望由一个单独的OAuth授权服务器颁发的OAuth 2.0 Bearer令牌。
[客户端 / 具有MCP客户端SDK的LLM]
|
| (带有Bearer令牌的HTTPS请求)
v
[这个MCP资源服务器（Node.js / TypeScript）]
| 1. MCP SDK中间件（解析请求，提取令牌）
| 2. `withWorkspaceAccess` HOC
| a. 使用与令牌关联的userId
| b. 验证用户可以访问请求中的workspace_id
| 3. 工具处理器执行（根据验证的上下文与Firestore交互）
|
v
[Google Firestore（数据库）]
OAuth授权服务器（您需要提供或已有）负责：
- 用户认证。
- 发行OAuth令牌（访问令牌、刷新令牌）。
- 管理OAuth客户端（动态发现）。
然后，此资源服务器会验证从客户端接收到的令牌。
前提条件
- Node.js（推荐v18.x或更高版本）
- npm或yarn
- 访问已启用Firestore的Google Cloud项目或配置了Firestore模拟器的Google Cloud SDK。
- 已有的OAuth 2.0授权服务器。
开始使用
-
克隆仓库：
git clone https://github.com/portal-labs-infrastructure/mcp-server-blog cd mcp-server-blog -
安装依赖项：
npm install # 或 yarn install -
设置环境变量： 将
.env.example文件复制到名为.env的新文件中：cp .env.example .env现在编辑
.env并填写所需的配置值：# Firestore配置 # 如果使用Firestore模拟器，可能不需要全部配置， # 但确保您的gcloud CLI已配置或提供必要的模拟器主机。 PROJECT_ID="your-gcp-project-id" # FIRESTORE_EMULATOR_HOST="localhost:8081" # 如果使用模拟器且不依赖于gcloud配置，请取消注释 # OAuth 2.0配置（此资源服务器用于验证令牌） # 这取决于您的OAuth授权服务器设置。 OAUTH_ISSUER_URL="https_your_auth_server_com" # MCP服务器配置 BASE_URL="http://localhost:8080" # 此服务器可访问的URL重要： OAuth配置至关重要。此服务器需要知道如何验证授权服务器发出的令牌。请参阅您的授权服务器文档。
-
（可选）填充Firestore数据： 如果您有填充脚本或希望手动添加一些示例用户、OAuth令牌（匹配您的授权服务器发出的令牌）和工作区数据到您的Firestore实例/模拟器中，请现在进行。这将使测试工具更有意义。
运行服务器
- 开发模式（使用Nodemon自动重启）：
npm run dev - 生产模式：
服务器通常会在npm run build npm starthttp://localhost:8080（或.env中指定的端口）启动。
使用Firestore模拟器运行
- 确保已安装并配置了Google Cloud SDK。
- 在另一个终端中启动Firestore模拟器：
（如有必要调整端口，并更新gcloud emulators firestore start --host-port=localhost:8081.env中的FIRESTORE_EMULATOR_HOST或确保应用程序通过gcloud环境变量自动检测它）。 - 按照上述步骤运行MCP服务器。它应该连接到模拟器。
代码中展示的关键模式及概念
在src目录中查找这些模式：
src/index.ts： 主MCP服务器设置。src/controllers/mcpController.ts： 工具注册和MCP控制器处理传入请求。src/services/： 处理Firestore交互的服务层。src/tools/： 示例工具定义。- 每个工具都有一个
inputSchema（Zod）和一个handler。 - 处理程序可能会被
withWorkspaceAccess包装。
- 每个工具都有一个
src/utils/withWorkspaceAccess.ts： 工作区检查的高阶组件。src/utils/fetchResourceList.ts： 可重用数据获取实用程序的示例。src/utils/types.ts： 共享的TypeScript类型和Zod模式（例如EntityType、ResourceType）。
目录结构
.
├── src/
│ ├── tools/ # 工具定义
│ │ ├── getAgentTool.ts
│ │ └── ...
│ ├── utils/ # 共享实用程序、HOC、类型
│ │ ├── withWorkspaceAccess.ts
│ │ ├── types.ts
│ │ └── ...
│ ├── services/ # 交互逻辑
│ │ ├── firestoreService.ts # Firestore交互逻辑
│ │ └── ...
│ ├── config/ # 配置加载
│ └── index.ts # 主服务器设置
├── .env.example # 示例环境变量
├── .env # 您的本地环境变量（git忽略）
├── package.json
├── tsconfig.json
└── ...
这个示例是什么（不是什么）
- 是： 构建安全、多租户MCP资源服务器的服务器端模式演示。
- 是： 在MCP上下文中应用TypeScript、Zod、Firestore和OAuth概念的方式。
- 不是： 完整的、生产就绪的OAuth授权服务器（您需要提供）。
- 不是： 可直接消费的库或SDK（这是一个示例应用程序）。
- 不是： 包含复杂业务逻辑（工具是示范性的）。
贡献
这是一个主要的演示仓库。然而，如果您发现错误或有关于改进所展示模式清晰度的建议，请随时打开问题或提交拉取请求。
许可
此项目基于MIT许可——详情见LICENSE文件。
致谢
此演示深受以下文章中讨论的经验和模式的影响："使用OAuth、TypeScript构建生产就绪的MCP服务器及其经验教训".