MCP Server com SSE e Autenticação Bearer

SSE と Bearer 認証を使用する MCP サーバー

このプロジェクトは、TypeScript で構築された MCP サーバー（Model Context Protocol）の実装です。リモートメッセージの転送に Server-Sent Events（SSE） を使用し、Bearer Token ベースの認証を採用することで、LLM ホスト（例：Claude Desktop）などのクライアントと安全かつリアルタイムに通信できます。

---

目次

• 概要
• アーキテクチャ
• リソースと機能
• 要件
• インストールと設定
• 実行
• シーケンス図
• 貢献
• ライセンス

---

概要

このプロジェクトは、SSE によるリアルタイム通信を利用し、Bearer トークンを通じてリクエストを認証する MCP サーバーを実装しています。このサーバーは、MCP プロトコル経由で呼び出せるツールを公開します。 MCP プロトコルの詳細は公式サイトをご覧ください

---

アーキテクチャ

このプロジェクトのアーキテクチャは、次のモジュールで構成されています。

• MCP Module： ツールの登録を含む、MCP サーバーの作成と設定を担当します。
• Middlewares： Bearer Token 認証ミドルウェアと、JSON 処理用の条件付きミドルウェアを含み、/messages エンドポイントのデータフローが誤って消費されないようにします。
• ルート： SSE 接続を確立するためのエンドポイント（/sse）と、メッセージを受信するためのエンドポイント（/messages）を Express で定義します。
• Config： 認証トークンやサーバーポートなどの設定を保存します。
• App： Express の設定、ミドルウェアとルートの統合、サーバーの起動を一元管理します。

---

リソースと機能

• SSE トランスポート： Server-Sent Events を使用したリアルタイムのリモート接続。
• Bearer 認証： Authorization ヘッダーで提供されるトークンによるセキュリティ検証。
• サンプルツール： 基本的な4つの数学演算を行う4つのシンプルなツールです。MCP サーバーにおけるツールの登録と実行の構成を示します。
• モジュール構造： 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 トークンを設定します。

     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

推奨名：「シーケンス図 - SSE と Bearer 認証を使用した MCP サーバーの通信フロー」

---

コントリビューション

コントリビューションを歓迎します！このプロジェクトの改善に協力する場合は、以下の手順に従ってください。

1. リポジトリをフォークして、クローンします。
2. 機能追加または修正用のブランチを作成します。
3. コーディングガイドラインに従い、SOLID とクリーンコードの原則を守って変更を加え、プルリクエストを送信します。

---

ライセンス

このプロジェクトは MIT License の下でライセンスされています。

---

ドキュメント更新日：2025年4月15日。