MCP Server Demo: OAuth, TypeScript & Firestore Patterns

MCP 服务演示：OAuth、TypeScript 与 Firestore 模式

此代码仓库提供了一个精简的示例实现，用于演示模型上下文协议（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 令牌。

[Client / LLM with MCP Client SDK]
       |
       | (HTTPS Request with Bearer Token)
       v
[This MCP Resource Server (Node.js / TypeScript)]
       |  1. MCP SDK Middleware (parses request, extracts token)
       |  2. `withWorkspaceAccess` HOC
       |     a. Using the userId associated with the token
       |     b. Validates the user can access the workspace_id in the request
       |  3. Tool Handler Execution (interacts with Firestore based on validated context)
       |
       v
[Google Firestore (Database)]

OAuth 授权服务（由你提供或使用已有服务）负责：

• 对用户进行身份验证。
• 颁发 OAuth 令牌（访问令牌、刷新令牌）。
• 管理 OAuth 客户端（动态发现）。

然后，此资源服务会验证从客户端收到的令牌。

前置条件

• Node.js（建议使用 v18.x 或更高版本）
• npm 或 yarn
• 可访问已启用 Firestore 的 Google Cloud 项目，或已配置用于 Firestore 模拟器的 Google Cloud SDK。
• 已有 OAuth 2.0 授权服务。

快速入门

1. 克隆仓库：

   git clone https://github.com/portal-labs-infrastructure/mcp-server-blog
   cd mcp-server-blog
   

2. 安装依赖：

   npm install
   # or
   yarn install
   

3. 设置环境变量： 将 .env.example 文件复制为名为 .env 的新文件：

   cp .env.example .env
   

   然后，编辑 .env 并填写所需的配置值：

   # Firestore Configuration
   # If using Firestore Emulator, these might not all be strictly needed,
   # but ensure your gcloud CLI is configured or provide necessary emulator host.
   PROJECT_ID="your-gcp-project-id"
   # FIRESTORE_EMULATOR_HOST="localhost:8081" # Uncomment if using emulator and not relying on gcloud config
   
   # OAuth 2.0 Configuration (for this Resource Server to validate tokens)
   # This depends on your OAuth Authorization Server's setup.
   OAUTH_ISSUER_URL="https_your_auth_server_com"
   
   # MCP Server Configuration
   BASE_URL="http://localhost:8080" # URL this server is accessible at
   

   重要： OAuth 配置至关重要。此服务需要知道如何验证由授权服务颁发的令牌。请查阅授权服务的文档。

4. （可选）填充 Firestore 数据： 如果你有数据填充脚本，或者想要手动向 Firestore 实例／模拟器添加一些示例用户、OAuth 令牌（需与授权服务颁发的令牌相符）和工作区数据，请现在进行。这会让工具测试更有意义。

运行服务

• 开发模式（使用 Nodemon 自动重启）：

  npm run dev
  

• 生产模式： bash npm run build npm start 服务通常会在 http://localhost:8080 启动（或在 .env 中指定的端口启动）。

使用 Firestore 模拟器运行

1. 确保已安装并配置 Google Cloud SDK。
2. 在单独的终端中启动 Firestore 模拟器：

   gcloud emulators firestore start --host-port=localhost:8081
   

   （如有需要，请调整端口并更新 .env 中的 FIRESTORE_EMULATOR_HOST，或者确保应用能够通过 gcloud 环境变量自动检测到它。）
3. 按照上述说明运行 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/                # Tool definitions
│   │   ├── getAgentTool.ts
│   │   └── ...
│   ├── utils/                # Shared utilities, HOCs, types
│   │   ├── withWorkspaceAccess.ts
│   │   ├── types.ts
│   │   └── ...
│   ├── services/             # Interaction logic
│   │   ├── firestoreService.ts    # Firestore interaction logic
│   │   └── ...
│   ├── config/               # Configuration loading
│   └── index.ts              # Main server setup
├── .env.example              # Example environment variables
├── .env                      # Your local environment variables (ignored by git)
├── package.json
├── tsconfig.json
└── ...

此演示的内容与非内容

• 是： 展示用于构建安全、多租户 MCP 资源服务的服务端模式。
• 是： 展示如何在 MCP 环境中应用 TypeScript、Zod、Firestore 和 OAuth 概念。
• 不是： 完整的生产级 OAuth 授权服务（你需要自行提供）。
• 不是： 可直接使用的库或 SDK（这是一个示例应用）。
• 不是： 包含复杂的业务逻辑（工具仅用于示例说明）。

贡献

这主要是一个演示仓库。不过，如果你发现错误，或对如何让所展示的模式更加清晰有建议，欢迎提交 issue 或拉取请求。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

本演示深受文章中分享的经验和模式启发：“使用 OAuth、TypeScript 和我们的实战经验构建生产就绪的 MCP 服务”。