博客服务器

Name: 博客服务器
Author: portal-labs-infrastructure

作者：portal-labs-infrastructure9 星标更新：2025-06-02

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

项目介绍

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 start
```
服务器通常会在http://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服务器及其经验教训".