mcp-sse
If you are the rightful owner of mcp-sse and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
This project is an implementation of an MCP Server using TypeScript, Server-Sent Events (SSE), and Bearer Token authentication for secure real-time communication with clients.
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
/messagesnã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
-
Clone o repositório:
git clone <URL_DO_REPOSITORIO> cd mcp-sse -
Instale as dependências:
npm install -
Configuração:
-
Token de Autenticação: Crie um arquivo
.envna 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"nopackage.jsonestá configurado para uso comnodee exige build prévio viatsc.
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-nodepara 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:
- Faça um fork e clone o repositório.
- Crie uma branch para a sua feature ou correção.
- 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 .
Documentação atualizada em 15/04/2025.
