MCP Server com SSE e Autenticação Bearer

Este projeto é uma implementação de um MCP Server (Model Context Protocol) construído em TypeScript. Ele utiliza Server-Sent Events (SSE) para o transporte remoto de mensagens e autenticação baseada em Bearer Token, permitindo a comunicação segura e em tempo real com clientes, como hosts de LLM (ex.: Claude Desktop).

Índice

• Visão Geral
• Arquitetura
• Recursos e Funcionalidades
• Requisitos
• Instalação e Configuração
• Execução
• Diagrama de Sequência
• Contribuição
• Licença

Visão Geral

Este projeto implementa um servidor MCP que expõe ferramentas (tools) para serem chamadas via protocolo MCP, utilizando SSE para comunicação em tempo real e autenticando requisições através de um token Bearer. Saiba mais sobre o protocolo MCP no site oficial

Arquitetura

A arquitetura do projeto é composta pelos seguintes módulos:

• MCP Module: Responsável pela criação e configuração do servidor MCP, incluindo o registro de ferramentas.
• Middlewares: Inclui o middleware de autenticação (Bearer Token) e o middleware condicional para o processamento de JSON, garantindo que o fluxo de dados no endpoint /messages não seja consumido indevidamente.
• Rotas: Define os endpoints do Express para estabelecer a conexão SSE (/sse) e para a recepção de mensagens (/messages).
• Config: Armazena configurações como token de autenticação e porta do servidor.
• App: Centraliza a configuração do Express, integração dos middlewares e rotas, e o início do servidor.

Recursos e Funcionalidades

• Transporte SSE: Conexão remota em tempo real usando Server-Sent Events.
• Autenticação Bearer: Verificação de segurança via token fornecido no header Authorization.
• Ferramentas de Exemplo: Quatro ferramentas simples que realizam as quatro operações básicas de matemática, demonstrando a estrutura de registro e execução de ferramentas no MCP Server.
• Estrutura Modular: Separação de responsabilidades conforme os princípios SOLID e Clean Code.
• Desenvolvimento com ts-node: Execução direta dos arquivos TypeScript sem necessidade de pré-compilação (ideal para desenvolvimento e debugging).

Requisitos

• Node.js (versão 20 ou superior)
• npm
• TypeScript
• ts-node (para desenvolvimento)
• Ambiente compatível com WSL (se aplicável)

Instalação e Configuração

1. Clone o repositório:

   git clone <URL_DO_REPOSITORIO>
   cd mcp-sse
   

2. Instale as dependências:

   npm install
   

3. Configuração:

   • Token de Autenticação: Crie um arquivo .env na raiz do projeto e defina o token Bearer:

     BEARER_TOKEN=meu-token-secreto
     PORT=3001
     

   • O projeto utiliza variáveis de ambiente para carregar essas configurações em runtime.

Execução

Usando ts-node

Durante o desenvolvimento, é possível executar o servidor sem pré-compilá-lo:

npm run dev

ℹ️ Nota: o script "start" no package.json está configurado para uso com node e exige build prévio via tsc.

Usando @modelcontextprotocol/inspector

Para visualizar e testar as ferramentas MCP em tempo real via interface web, execute:

npm run dev:inspect

💡 Esse comando utiliza ts-node para rodar o projeto sem build prévio. 🔐 A interface ficará disponível em: http://127.0.0.1:6274

Build e Execução em Produção

Para compilar os arquivos TypeScript:

npm run build

Depois, execute a versão compilada:

node dist/index.js

Diagrama de Sequência

O fluxo de comunicação e uso do MCP Server está ilustrado no diagrama abaixo:

@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

Nome Recomendado: "Diagrama de Sequência - Fluxo de Comunicação do MCP Server com SSE e Autenticação Bearer".

Contribuição

Contribuições são bem-vindas! Se você deseja melhorar este projeto:

1. Faça um fork e clone o repositório.
2. Crie uma branch para a sua feature ou correção.
3. Submeta um Pull Request com suas alterações, seguindo as diretrizes de código e mantendo os princípios SOLID e Clean Code.

Licença

Este projeto está licenciado sob a MIT License.

Documentação atualizada em 15/04/2025.