MCP Server com SSE e Autenticação Bearer

带 SSE 和 Bearer 身份验证的 MCP 服务

本项目是使用 TypeScript 构建的 MCP Server（Model Context Protocol）实现。它使用 **Server-Sent Events（SSE）**传输远程消息，并采用基于 Bearer Token 的身份验证，从而能够与 LLM 主机（例如 Claude Desktop）等客户端进行安全的实时通信。

---

目录

• 概述
• 架构
• 资源与功能
• 要求
• 安装与配置
• 运行
• 时序图
• 贡献
• 许可证

---

概述

本项目实现了一个 MCP 服务，提供可通过 MCP 协议调用的工具，并使用 SSE 进行实时通信，同时通过 Bearer Token 验证请求。 在官方网站了解更多 MCP 协议信息

---

架构

项目架构由以下模块组成：

• **MCP Module：**负责创建和配置 MCP 服务，包括注册工具。
• **Middlewares：**包含身份验证中间件（Bearer Token）和用于处理 JSON 的条件中间件，确保 /messages 端点的数据流不会被意外读取。
• **Routes：**定义 Express 端点，用于建立 SSE 连接（/sse）和接收消息（/messages）。
• **Config：**存储身份验证令牌和服务端口等配置。
• **App：**集中配置 Express、集成中间件和路由，并启动服务。

---

资源与功能

• **SSE 传输：**使用 Server-Sent Events 建立实时远程连接。
• **Bearer 身份验证：**通过 Authorization 标头中提供的令牌进行安全验证。
• **示例工具：**四个简单工具，分别执行数学中的四则运算，展示 MCP Server 中工具的注册和执行结构。
• **模块化结构：**根据 SOLID 和 Clean Code 原则划分职责。
• **使用 ts-node 开发：**无需预编译即可直接运行 TypeScript 文件（适用于开发和调试）。

---

要求

• Node.js（20 或更高版本）
• npm
• TypeScript
• ts-node（用于开发）
• 兼容 WSL 的环境（如适用）

---

安装与配置

1. 克隆仓库：

   git clone <URL_DO_REPOSITORIO>
   cd mcp-sse
   

2. 安装依赖：

   npm install
   

3. 配置：

   • 身份验证令牌： 在项目根目录创建 .env 文件并设置 Bearer Token：

     BEARER_TOKEN=meu-token-secreto
     PORT=3001
     

   • 项目使用环境变量在运行时加载这些配置。

---

运行

使用 ts-node

开发期间，可以在不预先编译的情况下运行服务：

npm run dev

ℹ️ 注意：package.json 中的 "start" 脚本配置为使用 node，并且需要先通过 tsc 构建。

---

使用 @modelcontextprotocol/inspector

若要通过 Web 界面实时查看和测试 MCP 工具，请运行：

npm run dev:inspect

💡 此命令使用 ts-node 运行项目，无需预先构建。 🔐 界面将在以下地址提供：http://127.0.0.1:6274

---

构建并在生产环境中运行

若要编译 TypeScript 文件：

npm run build

然后，运行编译后的版本：

node dist/index.js

序列图

MCP 服务的通信和使用流程如以下图表所示：

@startuml

title "Fluxo de Comunicação do MCP Server com SSE e Autenticação Bearer"

actor "MCP Client" as Client

participant "Express Server" as Express
participant "Auth Middleware" as Auth
participant "Route /sse" as SSERoute
participant "SSE Server Transport" as SSE
participant "MCP Server" as MCP
participant "Route /messages" as MsgRoute

== Estabelecimento da Conexão ==
Client -> Express: GET /sse\n(Authorization: Bearer <token>)
Express -> Auth: Verifica header Authorization
Auth --> Express: Token válido\n(continua)
Express -> SSERoute: Rota /sse invocada
SSERoute -> SSE: Cria nova instância SSEServerTransport
note right of SSE: Armazena sessionId
SSE -> SSERoute: Retorna transport
SSERoute -> Express: Retorna resposta SSE
Express -> MCP: mcpServer.connect(transport SSE)
MCP -> SSE: Inicia comunicação\n(enviar mensagens iniciais)
SSE -> Client: Envia eventos SSE\n(ex.: lista de tools)

== Envio de Mensagem (POST /messages) ==
Client -> Express: POST /messages?sessionId=XYZ\n(Corpo da mensagem)
Express -> MsgRoute: Rota /messages invocada
MsgRoute -> SSE: Procura transporte pelo sessionId
SSE -> MsgRoute: Transport encontrado
MsgRoute -> SSE: transport.handlePostMessage(request)
SSE -> MCP: Encaminha mensagem recebida
MCP -> SSE: Processa mensagem e retorna resposta
SSE -> Client: Envia resposta via SSE

== Encerramento da Conexão ==
Client -> Express: Fecha conexão SSE
Express -> SSE: Detecta fechamento da conexão
SSE -> Express: Notifica desconexão
Express -> SSERoute: Remove transporte (sessionId)
@enduml

推荐名称：“序列图 - MCP 服务使用 SSE 和 Bearer 身份验证的通信流程”。

---

贡献

欢迎贡献！如果您希望改进此项目：

1. Fork 并克隆此仓库。
2. 为您的功能或修复创建一个分支。
3. 遵循代码指南并秉持 SOLID 和 Clean Code 原则，提交包含您所做更改的拉取请求。

---

许可证

此项目采用 MIT 许可证 授权。

---

文档更新于 2025 年 4 月 15 日。