{"id":17680,"library":"hono-mcp-server-sse-transport","title":"Hono MCP Server-Sent Events Transport","description":"This package provides a Server-Sent Events (SSE) transport layer specifically designed for Hono applications to interface with a Model Context Protocol (MCP) server. As of version `0.0.7`, it offers a working solution to a known incompatibility: the official `@modelcontextprotocol/sdk` is primarily built for Express.js, leading to issues with Hono's response handling for SSE. This library acts as an interim solution, enabling developers to integrate MCP servers with Hono by correctly managing SSE connections and message routing. Releases are currently rapid patch/minor versions, indicating active development in its early stages. Its primary differentiator is bridging this specific framework gap, ensuring proper header and stream management for Hono-based MCP server implementations, including robust handling of multiple simultaneous connections via session IDs.","status":"active","version":"0.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/NikaBuligini/hono-mcp-server-sse-transport","tags":["javascript","modelcontextprotocol","mcp","hono"],"install":[{"cmd":"npm install hono-mcp-server-sse-transport","lang":"bash","label":"npm"},{"cmd":"yarn add hono-mcp-server-sse-transport","lang":"bash","label":"yarn"},{"cmd":"pnpm add hono-mcp-server-sse-transport","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for MCP Server functionality and protocol interaction.","package":"@modelcontextprotocol/sdk","optional":false},{"reason":"The web framework for which this transport is designed.","package":"hono","optional":false}],"imports":[{"note":"This package is ESM-first. Use `import` syntax.","wrong":"const { SSETransport } = require('hono-mcp-server-sse-transport');","symbol":"SSETransport","correct":"import { SSETransport } from 'hono-mcp-server-sse-transport';"},{"note":"The MCP Server class requires a deep import from the SDK's server module path, including the `.js` extension for explicit ESM resolution.","wrong":"import { McpServer } from '@modelcontextprotocol/sdk';","symbol":"McpServer","correct":"import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';"},{"note":"Hono's SSE utility is a named export from the `hono/streaming` submodule, not directly from the main `hono` package.","wrong":"import { streamSSE } from 'hono';","symbol":"streamSSE","correct":"import { streamSSE } from 'hono/streaming';"},{"note":"Standard named import for the Hono application class.","wrong":"const Hono = require('hono').Hono;","symbol":"Hono","correct":"import { Hono } from 'hono';"}],"quickstart":{"code":"import { Hono } from 'hono';\nimport { serve } from '@hono/node-server';\nimport { streamSSE } from 'hono/streaming';\nimport { SSETransport } from 'hono-mcp-server-sse-transport';\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\nconst mcpServer = new McpServer(\n  {\n    name: 'your-mcp-server-name',\n    version: '1.0.0'\n  },\n  {\n    capabilities: {\n      tools: {}\n    }\n  }\n);\n\n// here you add your tools\n// ...\n\nconst app = new Hono();\n\n// to support multiple simultaneous connections we have a lookup object from\n// sessionId to transport\nconst transports: { [sessionId: string]: SSETransport } = {};\n\napp.get('/sse', (c) => {\n  return streamSSE(c, async (stream) => {\n    const transport = new SSETransport('/messages', stream);\n\n    transports[transport.sessionId] = transport;\n\n    stream.onAbort(() => {\n      delete transports[transport.sessionId];\n    });\n\n    await mcpServer.connect(transport);\n\n    while (true) {\n      // This will keep the connection alive\n      // You can also await for a promise that never resolves\n      await stream.sleep(60_000);\n    }\n  });\n});\n\napp.post('/messages', async (c) => {\n  const sessionId = c.req.query('sessionId');\n  const transport = transports[sessionId];\n\n  if (transport == null) {\n    return c.text('No transport found for sessionId', 400);\n  }\n\n  return await transport.handlePostMessage(c);\n});\n\nserve(\n  {\n    fetch: app.fetch,\n    port: 3000\n  }\n);\n","lang":"typescript","description":"Demonstrates setting up a Hono server that acts as an MCP server, using SSE for client communication. It includes session management for multiple concurrent connections."},"warnings":[{"fix":"Monitor the `@modelcontextprotocol/sdk` repository for official Hono integration. Be prepared to migrate if official support is released.","message":"This package is an interim solution designed to bridge an incompatibility between Hono and the official `@modelcontextprotocol/sdk`. It may become deprecated or obsolete once official Hono support is integrated into the SDK.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure all imports for `hono-mcp-server-sse-transport` use the direct, top-level named exports as shown in the documentation and examples (e.g., `import { SSETransport } from 'hono-mcp-server-sse-transport';`).","message":"Version `0.0.5` introduced a fix for 'export destinations'. If you were relying on previously incorrect or internal module paths, this change might break your imports or module resolution.","severity":"breaking","affected_versions":">=0.0.5"},{"fix":"Implement robust session management, including proper `onAbort` handlers to remove disconnected clients from the `transports` lookup, and consider strategies for handling stale or unclosed connections.","message":"The management of `sessionId` and the `transports` object is manual in the quickstart example. Incorrect handling of session IDs or failure to clean up abandoned transports can lead to memory leaks or messages being routed to the wrong client.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure your SSE client-side logic is resilient to the order of initial events or specifically handles a 'ping' event before other setup events.","message":"As of v0.0.7, a 'ping event' is sent before the 'endpoint event'. This changes the event order in the SSE stream, which could potentially affect clients expecting a different sequence of initial events.","severity":"gotcha","affected_versions":">=0.0.7"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Verify that the client is sending the correct `sessionId` that corresponds to an established SSE connection. Ensure the server-side `transports` object correctly tracks and cleans up connections.","cause":"The `sessionId` provided in a POST request did not match any active `SSETransport` in the server's `transports` lookup object.","error":"No transport found for sessionId"},{"fix":"Use the correct deep import path: `import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';`","cause":"The `@modelcontextprotocol/sdk` package is being imported incorrectly, likely missing the deep import path or the `.js` extension for ESM.","error":"TypeError: Cannot find module '@modelcontextprotocol/sdk'"},{"fix":"Import `streamSSE` from the correct Hono submodule: `import { streamSSE } from 'hono/streaming';`","cause":"The `streamSSE` utility from Hono is imported from the main `hono` package instead of its specific submodule.","error":"TypeError: streamSSE is not a function"},{"fix":"Ensure you are using `import { SSETransport } from 'hono-mcp-server-sse-transport';` at the top of your TypeScript/ESM file.","cause":"The `SSETransport` class was not imported correctly, likely due to using CommonJS `require` syntax in an ESM environment or a typo in the import.","error":"ReferenceError: SSETransport is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}