feat(@mcp/hono): mcpHonoHandler mount helper (handleHttp-backed)

Author: felixweinberger

packages/middleware/hono/src/hono.ts

@@ -1,8 +1,44 @@
-import type { Context } from 'hono';
+import type { AuthInfo, Dispatchable, HandleHttpOptions } from '@modelcontextprotocol/server';
+import { handleHttp } from '@modelcontextprotocol/server';
+import type { Context, Handler } from 'hono';
 import { Hono } from 'hono';
 
 import { hostHeaderValidation, localhostHostValidation } from './middleware/hostHeaderValidation.js';
 
+/**
+ * Hono context variables {@linkcode mcpHonoHandler} reads. Upstream middleware
+ * may set `parsedBody` ({@linkcode createMcpHonoApp} does this for JSON requests)
+ * and `authInfo` (e.g. a bearer-token verifier) before this handler runs.
+ */
+export type McpHonoVariables = { parsedBody?: unknown; authInfo?: AuthInfo };
+
+/**
+ * Mounts an `McpServer` (or any `Protocol` subclass) as a Hono `Handler`.
+ * Each request flows through `mcp.dispatch()` directly via {@linkcode handleHttp};
+ * `mcp.connect()` and a transport instance are not used.
+ *
+ * Reads `c.get('parsedBody')` (set by {@linkcode createMcpHonoApp}'s JSON middleware)
+ * and `c.get('authInfo')` (set by an upstream auth middleware) when present.
+ *
+ * ```ts
+ * import { McpServer, SessionCompat } from '@modelcontextprotocol/server';
+ * import { createMcpHonoApp, mcpHonoHandler } from '@modelcontextprotocol/hono';
+ *
+ * const mcp = new McpServer({ name: 's', version: '1.0.0' });
+ * const app = createMcpHonoApp();
+ * app.all('/mcp', mcpHonoHandler(mcp, { session: new SessionCompat() }));
+ * ```
+ */
+export function mcpHonoHandler(mcp: Dispatchable, options?: HandleHttpOptions): Handler<{ Variables: McpHonoVariables }> {
+    const handler = handleHttp(mcp, options);
+    return c => {
+        const parsedBody = c.get('parsedBody');
+        const authInfo = c.get('authInfo');
+        const extra = authInfo !== undefined || parsedBody !== undefined ? { authInfo, parsedBody } : undefined;
+        return handler(c.req.raw, extra);
+    };
+}
+
 /**
  * Options for creating an MCP Hono application.
  */

packages/middleware/hono/test/hono.test.ts

@@ -2,9 +2,18 @@ import type { Context } from 'hono';
 import { Hono } from 'hono';
 import { vi } from 'vitest';
 
-import { createMcpHonoApp } from '../src/hono.js';
+import { McpServer, SessionCompat } from '@modelcontextprotocol/server';
+
+import { createMcpHonoApp, mcpHonoHandler } from '../src/hono.js';
 import { hostHeaderValidation } from '../src/middleware/hostHeaderValidation.js';
 
+const INIT_MESSAGE = {
+    jsonrpc: '2.0',
+    method: 'initialize',
+    params: { clientInfo: { name: 'test-client', version: '1.0' }, protocolVersion: '2025-11-25', capabilities: {} },
+    id: 'init-1'
+};
+
 describe('@modelcontextprotocol/hono', () => {
     test('hostHeaderValidation blocks invalid Host and allows valid Host', async () => {
         const app = new Hono();
@@ -106,4 +115,48 @@ describe('@modelcontextprotocol/hono', () => {
         expect(res.status).toBe(200);
         expect(await res.json()).toEqual({ preset: true });
     });
+
+    describe('mcpHonoHandler', () => {
+        function makeApp(options?: Parameters<typeof mcpHonoHandler>[1]) {
+            const mcp = new McpServer({ name: 'test-server', version: '1.0.0' });
+            const app = createMcpHonoApp({ host: '0.0.0.0', allowedHosts: ['localhost'] });
+            app.all('/mcp', mcpHonoHandler(mcp, { enableJsonResponse: true, ...options }));
+            return app;
+        }
+
+        async function postJson(app: Hono, body: unknown, headers: Record<string, string> = {}): Promise<Response> {
+            return app.request('http://localhost/mcp', {
+                method: 'POST',
+                headers: {
+                    Host: 'localhost',
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json, text/event-stream',
+                    ...headers
+                },
+                body: JSON.stringify(body)
+            });
+        }
+
+        test('serves initialize via mcp.dispatch() (stateless, no transport class)', async () => {
+            const res = await postJson(makeApp(), INIT_MESSAGE);
+            expect(res.status).toBe(200);
+            const body = (await res.json()) as { result: { serverInfo: { name: string } } };
+            expect(body.result).toMatchObject({ serverInfo: { name: 'test-server' } });
+            expect(res.headers.get('mcp-session-id')).toBeNull();
+        });
+
+        test('serves session lifecycle via SessionCompat', async () => {
+            const app = makeApp({ session: new SessionCompat() });
+            const initRes = await postJson(app, INIT_MESSAGE);
+            const sid = initRes.headers.get('mcp-session-id');
+            expect(sid).toBeTruthy();
+            const pingRes = await postJson(
+                app,
+                { jsonrpc: '2.0', method: 'ping', params: {}, id: 'p-1' },
+                { 'mcp-session-id': sid as string, 'mcp-protocol-version': '2025-11-25' }
+            );
+            expect(pingRes.status).toBe(200);
+            expect(await pingRes.json()).toMatchObject({ jsonrpc: '2.0', id: 'p-1', result: {} });
+        });
+    });
 });