MCP Server Blog

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


该存储库提供了一个简化的、说明性的模型上下文协议（MCP）服务器实现。它展示了我们随附文章中详细介绍的架构模式、安全考虑因素（OAuth 2.0）和开发实践（TypeScript、Firestore、Zod）：

➡️ 阅读完整故事：“使用OAuth、TypeScript和我们的战斗伤痕构建生产就绪的MCP服务器"

此演示侧重于 MCP资源服务器 组件，并假设您有一个单独的OAuth 2.0授权服务器。

更新：MCP SDK 1.12.0版本引入了对授权服务器元数据（/.wearned/oauth授权服务器）的支持，并消除了通过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 2.0承载令牌由单独的 OAuth授权服务器.

[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或纱线
• 访问启用了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

1. 安装依赖项：

   npm install
   # or
   yarn install

1. 设置环境变量：

复制 .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配置至关重要。此服务器需要知道如何验证授权服务器颁发的令牌。请查阅您的认证服务器文档。

1. （可选）种子仓库数据：

如果你有种子脚本，或者想手动添加一些示例用户、OAuth令牌（与你的Auth服务器会发出的令牌匹配）和工作区数据到你的Firestore实例/模拟器中，现在就这样做。这将使测试工具更有意义。

运行服务器

• 开发模式（带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

（必要时调整端口并更新 FIRESTORE_EMULATOR_HOST 在……里面 .env 或确保您的应用程序通过以下方式自动检测到它 gcloud 环境变量）。

1. 如上所述运行MCP服务器。它应该连接到模拟器。

代码中展示的关键模式和概念

在 src 目录：

• src/index.ts: 主MCP服务器设置。
• src/controllers/mcpController.ts: 工具注册和MCP控制器处理传入请求。
• src/services/: 用于处理Firestore交互的服务层。
• src/tools/: 工具定义示例。

- 每个工具都有一个 inputSchema （Zod）和a 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（这是一个示例应用程序）。
• 不是： 充满了复杂的业务逻辑（工具是说明性的）。

贡献

这主要是一个演示存储库。但是，如果您发现错误或对提高演示模式的清晰度有建议，请随时打开问题或提交拉取请求。

许可证

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

致谢

这个演示深受文章中讨论的经验和模式的启发：“使用OAuth、TypeScript和我们的战斗伤痕构建生产就绪的MCP服务器".