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授权服务器。
入门指南
- 克隆存储库：
git clone https://github.com/portal-labs-infrastructure/mcp-server-blog
cd mcp-server-blog- 安装依赖项：
npm install
# or
yarn install- 设置环境变量：
复制 .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配置至关重要。此服务器需要知道如何验证授权服务器颁发的令牌。请查阅您的认证服务器文档。
- （可选）种子仓库数据：
如果你有种子脚本，或者想手动添加一些示例用户、OAuth令牌（与你的Auth服务器会发出的令牌匹配）和工作区数据到你的Firestore实例/模拟器中，现在就这样做。这将使测试工具更有意义。
运行服务器
- 开发模式（带Nodemon自动重启）：
npm run dev- 生产模式：
bash npm run build npm start 服务器通常会启动 http://localhost:8080 （或中指定的端口 .env).
使用Firestore模拟器运行
- 确保已安装并配置Google Cloud SDK。
- 在单独的终端中启动Firestore模拟器：
gcloud emulators firestore start --host-port=localhost:8081（必要时调整端口并更新 FIRESTORE_EMULATOR_HOST 在……里面 .env 或确保您的应用程序通过以下方式自动检测到它 gcloud 环境变量）。
- 如上所述运行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服务器".