From 66c002b817183b5699ac234e502d1e649ede703c Mon Sep 17 00:00:00 2001 From: BlueRose <378100977@qq.com> Date: Wed, 10 Jun 2026 12:32:31 +0800 Subject: [PATCH 01/17] feat(mcp): add `gitnexus mcp --http` server with legacy SSE and Streamable HTTP transports Adds a dedicated MCP-only HTTP server (gitnexus/src/mcp/http-transport.ts) started via `gitnexus mcp --http [--port 3000] [--host 0.0.0.0] [--auth-token ]`. Serves modern Streamable HTTP at POST /mcp and legacy SSE at GET /sse + POST /messages, reusing the transport-agnostic createMCPServer(). stdio remains the default for `gitnexus mcp` (no breaking change). - Reuse the proven StreamableHTTP session machinery by extracting createStreamableHttpHandler() from server/mcp-http.ts; mountMCPEndpoints keeps its signature and /api/mcp behavior. - Add createSseHandlers() implementing the legacy SSEServerTransport round-trip. - Optional bearer-token auth middleware; warn when binding non-loopback without a token. Proper CORS (incl. Private Network Access) headers. - Replace console.log in mcp-http.ts with the core logger. - Tests: auth middleware, /health, Streamable + SSE round-trips, unknown-session 404s, auth enforcement, and mountMCPEndpoints refactor safety (16/16 pass). --- gitnexus/src/cli/index.ts | 16 +- gitnexus/src/cli/mcp.ts | 21 +- gitnexus/src/mcp/http-transport.ts | 194 +++++++++++ gitnexus/src/server/mcp-http.ts | 150 ++++++-- gitnexus/test/unit/mcp-http-transport.test.ts | 325 ++++++++++++++++++ 5 files changed, 678 insertions(+), 28 deletions(-) create mode 100644 gitnexus/src/mcp/http-transport.ts create mode 100644 gitnexus/test/unit/mcp-http-transport.test.ts diff --git a/gitnexus/src/cli/index.ts b/gitnexus/src/cli/index.ts index 0f801615d7..0dc89174b1 100644 --- a/gitnexus/src/cli/index.ts +++ b/gitnexus/src/cli/index.ts @@ -122,7 +122,21 @@ program program .command('mcp') - .description('Start MCP server (stdio) — serves all indexed repos') + .description( + 'Start MCP server. Default: stdio. Use --http for a remote HTTP server ' + + '(Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).', + ) + .option('--http', 'Serve MCP over HTTP instead of stdio (for remote clients)') + .option('-p, --port ', 'HTTP port (only with --http). Default: 3000', '3000') + .option( + '--host ', + 'HTTP bind address (only with --http). Default: 0.0.0.0 (all interfaces). Use 127.0.0.1 for loopback only.', + '0.0.0.0', + ) + .option( + '--auth-token ', + 'Require this bearer token in the Authorization header (only with --http). If omitted, no auth (warn on non-loopback bind).', + ) .action(createLbugLazyAction(() => import('./mcp.js'), 'mcpCommand')); program diff --git a/gitnexus/src/cli/mcp.ts b/gitnexus/src/cli/mcp.ts index 056b12591f..472bfa91ff 100644 --- a/gitnexus/src/cli/mcp.ts +++ b/gitnexus/src/cli/mcp.ts @@ -29,7 +29,12 @@ import { installGlobalStdoutSentinel } from '../mcp/stdio-context.js'; -export const mcpCommand = async () => { +export const mcpCommand = async (options?: { + http?: boolean; + port?: string; + host?: string; + authToken?: string; +}) => { // Install the global stdout sentinel as the very first thing — before // ANY other module loads. The static-import closure above is leaf-only // (stdio-context → stdio-capture, zero non-`node:` deps), so this is @@ -80,6 +85,20 @@ export const mcpCommand = async () => { ); } + // 根据选项决定启动模式：HTTP 服务器或 stdio（默认） + if (options?.http) { + // 动态导入 HTTP 传输模块（保持静态导入闭包为叶子节点） + // http-transport.ts 间接引入 express/cors/SDK HTTP 传输， + // 必须在 sentinel 安装后才能加载 + const { startMcpHttpServer } = await import('../mcp/http-transport.js'); + await startMcpHttpServer(backend, { + port: Number(options.port ?? 3000), + host: options.host ?? '0.0.0.0', + authToken: options.authToken, + }); + return; + } + // Start MCP server (serves all repos, discovers new ones lazily) await startMCPServer(backend); }; diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts new file mode 100644 index 0000000000..de414aa200 --- /dev/null +++ b/gitnexus/src/mcp/http-transport.ts @@ -0,0 +1,194 @@ +/** + * 专用 MCP HTTP 服务器 + * + * 提供基于 HTTP 的 MCP 传输，支持： + * - 现代 Streamable HTTP：POST /mcp + * - 遗留 SSE 传输：GET /sse + POST /messages + * + * 通过 `gitnexus mcp --http` 启动。 + * stdio 仍是 `gitnexus mcp` 的默认模式（无破坏性变更）。 + * + * 安全注意事项： + * - 默认绑定 0.0.0.0（所有接口），如不提供 --auth-token 会输出警告 + * - 使用 --auth-token 启用 Bearer Token 鉴权 + * - 使用 --host 127.0.0.1 限制为本地回环访问 + */ + +import type { Server as HttpServer } from 'http'; +import express, { type Express, type Request, type Response, type NextFunction } from 'express'; +import cors from 'cors'; +import { createStreamableHttpHandler, createSseHandlers } from '../server/mcp-http.js'; +import type { LocalBackend } from './local/local-backend.js'; +import { logger } from '../core/logger.js'; + +/** HTTP 服务器配置选项 */ +export interface McpHttpOptions { + /** 监听端口 */ + port: number; + /** 绑定地址（默认 0.0.0.0） */ + host: string; + /** Bearer 鉴权 Token（可选；不设置则无鉴权） */ + authToken?: string; +} + +/** + * 创建 Bearer Token 鉴权中间件。 + * + * - 如果未设置 authToken，直接放行所有请求 + * - 如果设置了 authToken，检查 Authorization: Bearer 头 + * - 鉴权失败返回 JSON-RPC 格式的 401 响应 + * + * @param authToken 期望的 Bearer Token（可选） + */ +export function createAuthMiddleware(authToken?: string) { + return (req: Request, res: Response, next: NextFunction): void => { + // 未启用鉴权，直接放行 + if (!authToken) { + next(); + return; + } + + const header = req.headers['authorization']; + const expected = `Bearer ${authToken}`; + + // 字符串比较（长度不同则快速失败） + if (typeof header === 'string' && header === expected) { + next(); + return; + } + + res.status(401).json({ + jsonrpc: '2.0', + error: { code: -32001, message: 'Unauthorized' }, + id: null, + }); + }; +} + +/** + * 创建并启动专用 MCP HTTP 服务器。 + * + * 挂载以下路由： + * - GET /health — 健康检查（无需鉴权） + * - POST /mcp — Streamable HTTP（现代客户端） + * - GET /sse — 遗留 SSE 流（旧客户端） + * - POST /messages — 遗留 SSE 消息接收 + * + * @param backend LocalBackend 实例 + * @param options 服务器配置 + * @returns 已监听的 http.Server + */ +export async function startMcpHttpServer( + backend: LocalBackend, + options: McpHttpOptions, +): Promise { + const { port, host, authToken } = options; + + // 非回环地址 + 无鉴权 → 输出安全警告 + if (!authToken && host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') { + logger.warn( + { host, port }, + 'GitNexus MCP HTTP server is binding to a non-loopback address WITHOUT --auth-token. ' + + 'Anyone who can reach this host can query your indexed repos. ' + + 'Pass --auth-token or bind --host 127.0.0.1.', + ); + } + + const app: Express = express(); + + // 禁用 X-Powered-By 头（减少信息泄露） + app.disable('x-powered-by'); + + // Chrome 130+ Private Network Access 预检支持 + app.use((_req: Request, res: Response, next: NextFunction) => { + res.setHeader('Access-Control-Allow-Private-Network', 'true'); + next(); + }); + + // CORS：专用 MCP-only 服务器为远程访问设计，允许所有来源 + app.use( + cors({ + origin: true, + credentials: false, + allowedHeaders: ['Content-Type', 'Authorization', 'mcp-session-id', 'last-event-id'], + exposedHeaders: ['mcp-session-id'], + }), + ); + + // 解析 JSON 请求体（最大 10MB） + app.use(express.json({ limit: '10mb' })); + + const auth = createAuthMiddleware(authToken); + + // 健康检查路由（无需鉴权，供编排工具探测） + app.get('/health', (_req: Request, res: Response) => { + res.json({ status: 'ok' }); + }); + + // Streamable HTTP（现代客户端）at POST /mcp + // 复用 server/mcp-http.ts 中经过验证的会话处理逻辑 + const streamable = createStreamableHttpHandler(backend); + app.all('/mcp', auth, (req: Request, res: Response) => { + void streamable.handler(req, res).catch((err: unknown) => { + logger.error({ err }, 'MCP /mcp request failed'); + if (!res.headersSent) { + res.status(500).json({ + jsonrpc: '2.0', + error: { code: -32000, message: 'Internal MCP server error' }, + id: null, + }); + } + }); + }); + + // 遗留 SSE：GET /sse 建立流，POST /messages 接收 JSON-RPC 消息 + const sse = createSseHandlers(backend, '/messages'); + app.get('/sse', auth, (req: Request, res: Response) => { + void sse.sseHandler(req, res).catch((err: unknown) => { + logger.error({ err }, 'MCP /sse failed'); + }); + }); + app.post('/messages', auth, (req: Request, res: Response) => { + void sse.messageHandler(req, res).catch((err: unknown) => { + logger.error({ err }, 'MCP /messages failed'); + if (!res.headersSent) { + res.status(500).json({ + jsonrpc: '2.0', + error: { code: -32000, message: 'Internal error' }, + id: null, + }); + } + }); + }); + + return new Promise((resolve, reject) => { + const server = app.listen(port, host, () => { + // 0.0.0.0 / :: 时显示 localhost 更友好 + const displayHost = host === '0.0.0.0' || host === '::' ? 'localhost' : host; + logger.info( + { port, host }, + `GitNexus MCP HTTP server listening on http://${displayHost}:${port} ` + + `(Streamable: POST /mcp · legacy SSE: GET /sse + POST /messages)`, + ); + resolve(server); + }); + + server.on('error', reject); + + // 优雅关闭处理 + const shutdown = async (): Promise => { + server.close(); + await streamable.cleanup(); + await sse.cleanup(); + try { + await backend.disconnect(); + } catch {} + const { flushLoggerSync } = await import('../core/logger.js'); + flushLoggerSync(); + process.exit(0); + }; + + process.once('SIGINT', () => void shutdown()); + process.once('SIGTERM', () => void shutdown()); + }); +} diff --git a/gitnexus/src/server/mcp-http.ts b/gitnexus/src/server/mcp-http.ts index 67ec947085..e6d98bb2e3 100644 --- a/gitnexus/src/server/mcp-http.ts +++ b/gitnexus/src/server/mcp-http.ts @@ -1,16 +1,21 @@ /** * MCP over HTTP * - * Mounts the GitNexus MCP server on Express using StreamableHTTP transport. - * Each connecting client gets its own stateful session; the LocalBackend - * is shared across all sessions (thread-safe — lazy LadybugDB per repo). + * 将 GitNexus MCP 服务器挂载到 Express，使用 StreamableHTTP 传输协议。 + * 每个连接的客户端都有自己的有状态会话；LocalBackend 在所有会话间共享 + * （线程安全 — 每个仓库懒加载 LadybugDB）。 * - * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity - * (guards against network drops that never trigger onclose). + * 会话在显式关闭或 SESSION_TTL_MS 空闲后被清理 + * （防止网络断开后 onclose 从未触发的情况）。 + * + * 新导出的工厂函数可被 http-transport.ts 中的专用 MCP-only 服务器复用： + * - createStreamableHttpHandler(backend): 封装 StreamableHTTPServerTransport 会话逻辑 + * - createSseHandlers(backend, messagesPath): 封装遗留 SSEServerTransport 会话逻辑 */ import type { Express, Request, Response } from 'express'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; +import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { createMCPServer } from '../mcp/server.js'; import type { LocalBackend } from '../mcp/local/local-backend.js'; @@ -23,15 +28,30 @@ interface MCPSession { lastActivity: number; } -/** Idle sessions are evicted after 30 minutes */ +interface SSESession { + server: Server; + transport: SSEServerTransport; +} + +/** 会话空闲 30 分钟后被驱逐 */ const SESSION_TTL_MS = 30 * 60 * 1000; -/** Cleanup sweep runs every 5 minutes */ +/** 清理扫描每 5 分钟运行一次 */ const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; -export function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise { +/** + * 创建可复用的 StreamableHTTP 请求处理器。 + * + * 将现有的会话映射和 handleMcpRequest 逻辑封装为独立工厂， + * 既可被 mountMCPEndpoints（/api/mcp 路由）调用， + * 也可被专用 HTTP-only 服务器（http-transport.ts）调用。 + */ +export function createStreamableHttpHandler(backend: LocalBackend): { + handler: (req: Request, res: Response) => Promise; + cleanup: () => Promise; +} { const sessions = new Map(); - // Periodic cleanup of idle sessions (guards against network drops) + // 定期清理空闲会话（防止网络断开导致 onclose 未触发） const cleanupTimer = setInterval(() => { const now = Date.now(); for (const [id, session] of sessions) { @@ -47,23 +67,23 @@ export function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Pr (cleanupTimer as NodeJS.Timeout).unref(); } - const handleMcpRequest = async (req: Request, res: Response) => { + const handler = async (req: Request, res: Response): Promise => { const sessionId = req.headers['mcp-session-id'] as string | undefined; if (sessionId && sessions.has(sessionId)) { - // Existing session — delegate to its transport + // 已有会话 — 委托给其传输 const session = sessions.get(sessionId)!; session.lastActivity = Date.now(); await session.transport.handleRequest(req, res, req.body); } else if (sessionId) { - // Unknown/expired session ID — tell client to re-initialize (per MCP spec) + // 未知/过期的会话 ID — 告知客户端重新初始化（符合 MCP 规范） res.status(404).json({ jsonrpc: '2.0', error: { code: -32001, message: 'Session not found. Re-initialize.' }, id: null, }); } else if (req.method === 'POST') { - // No session ID — new client initializing + // 无会话 ID — 新客户端初始化 const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), }); @@ -86,8 +106,97 @@ export function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Pr } }; + const cleanup = async (): Promise => { + clearInterval(cleanupTimer); + const closers = [...sessions.values()].map(async (session) => { + try { + await Promise.resolve(session.server.close()); + } catch {} + }); + sessions.clear(); + await Promise.allSettled(closers); + }; + + return { handler, cleanup }; +} + +/** + * 创建遗留 SSE 传输处理器。 + * + * GET /sse（或自定义路径）建立 SSE 流； + * POST /messages（或自定义路径）接收客户端发来的 JSON-RPC 消息。 + * + * @param backend LocalBackend 实例 + * @param messagesPath 客户端 POST 消息的路径（默认 '/messages'） + */ +export function createSseHandlers( + backend: LocalBackend, + messagesPath = '/messages', +): { + sseHandler: (req: Request, res: Response) => Promise; + messageHandler: (req: Request, res: Response) => Promise; + cleanup: () => Promise; +} { + const sseSessions = new Map(); + + const sseHandler = async (req: Request, res: Response): Promise => { + // SSEServerTransport(endpoint, res): endpoint 是客户端将用来 POST 的路径 + const transport = new SSEServerTransport(messagesPath, res); + const server = createMCPServer(backend); + + sseSessions.set(transport.sessionId, { server, transport }); + + transport.onclose = () => { + sseSessions.delete(transport.sessionId); + }; + + res.on('close', () => { + sseSessions.delete(transport.sessionId); + try { + server.close(); + } catch {} + }); + + // connect() 调用 transport.start()，它发送 SSE 'endpoint' 事件 + await server.connect(transport); + }; + + const messageHandler = async (req: Request, res: Response): Promise => { + const sessionId = + (req.query['sessionId'] as string | undefined) ?? + (req.headers['mcp-session-id'] as string | undefined); + const entry = sessionId ? sseSessions.get(sessionId) : undefined; + + if (!entry) { + res.status(404).json({ + jsonrpc: '2.0', + error: { code: -32001, message: 'SSE session not found. Reconnect to /sse.' }, + id: null, + }); + return; + } + + // express.json() 已解析请求体 — 将其作为第 3 个参数传入，避免 SDK 重读已耗尽的流 + await entry.transport.handlePostMessage(req, res, req.body); + }; + + const cleanup = async (): Promise => { + for (const { server } of sseSessions.values()) { + try { + await Promise.resolve(server.close()); + } catch {} + } + sseSessions.clear(); + }; + + return { sseHandler, messageHandler, cleanup }; +} + +export function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise { + const { handler, cleanup } = createStreamableHttpHandler(backend); + app.all('/api/mcp', (req: Request, res: Response) => { - void handleMcpRequest(req, res).catch((err: any) => { + void handler(req, res).catch((err: unknown) => { logger.error({ err }, 'MCP HTTP request failed:'); if (res.headersSent) return; res.status(500).json({ @@ -98,17 +207,6 @@ export function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Pr }); }); - const cleanup = async () => { - clearInterval(cleanupTimer); - const closers = [...sessions.values()].map(async (session) => { - try { - await Promise.resolve(session.server.close()); - } catch {} - }); - sessions.clear(); - await Promise.allSettled(closers); - }; - - console.log('MCP HTTP endpoints mounted at /api/mcp'); + logger.info('MCP HTTP endpoints mounted at /api/mcp'); return cleanup; } diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts new file mode 100644 index 0000000000..3430ef2a95 --- /dev/null +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -0,0 +1,325 @@ +/** + * Unit Tests: MCP HTTP 传输 + * + * 覆盖以下内容： + * - createAuthMiddleware：无鉴权/鉴权通过/鉴权失败场景 + * - startMcpHttpServer：启动服务器、/health 端点（无需鉴权） + * - createStreamableHttpHandler：Streamable HTTP 会话初始化、未知会话 404 + * - createSseHandlers：SSE 消息路由、未知 sessionId 404 + * - mountMCPEndpoints 重构安全性：仍返回 cleanup 函数并注册 /api/mcp + * + * 说明： + * - node_modules 可能未安装；测试依赖 MCP SDK mock 而非真实 SDK 实例 + * - HTTP 服务器测试使用 port: 0（由 OS 分配临时端口），绑定 127.0.0.1 + * - 每个测试后关闭服务器并调用 cleanup，避免句柄泄漏 + */ + +import { describe, it, expect, vi } from 'vitest'; +import type { Request, Response, NextFunction } from 'express'; +import { createAuthMiddleware } from '../../src/mcp/http-transport.js'; +import { + createStreamableHttpHandler, + createSseHandlers, + mountMCPEndpoints, +} from '../../src/server/mcp-http.js'; + +// ─── Mock backend 工厂 ───────────────────────────────────────────────── + +function createMockBackend(overrides: Record = {}): unknown { + return { + callTool: vi.fn().mockResolvedValue({ result: 'ok' }), + listRepos: vi.fn().mockResolvedValue([]), + resolveRepo: vi + .fn() + .mockResolvedValue({ name: 'test', repoPath: '/tmp/test', lastCommit: 'abc' }), + getContext: vi.fn().mockReturnValue(null), + queryClusters: vi.fn().mockResolvedValue({ clusters: [] }), + queryProcesses: vi.fn().mockResolvedValue({ processes: [] }), + queryClusterDetail: vi.fn().mockResolvedValue({ error: 'not found' }), + queryProcessDetail: vi.fn().mockResolvedValue({ error: 'not found' }), + disconnect: vi.fn().mockResolvedValue(undefined), + ...overrides, + }; +} + +// ─── Mock req/res 工厂 ───────────────────────────────────────────────── + +function createMockReq(headers: Record = {}): Request { + return { headers } as unknown as Request; +} + +function createMockRes(): Response & { _status: number; _body: unknown } { + const res = { + _status: 200, + _body: undefined, + headersSent: false, + status: vi.fn().mockImplementation(function (this: typeof res, code: number) { + this._status = code; + return this; + }), + json: vi.fn().mockImplementation(function (this: typeof res, body: unknown) { + this._body = body; + return this; + }), + }; + return res as unknown as Response & { _status: number; _body: unknown }; +} + +// ─── createAuthMiddleware 测试 ───────────────────────────────────────── + +describe('createAuthMiddleware', () => { + it('未设置 authToken 时直接调用 next（无鉴权）', () => { + const middleware = createAuthMiddleware(undefined); + const req = createMockReq(); + const res = createMockRes(); + const next = vi.fn() as NextFunction; + + middleware(req, res, next); + + expect(next).toHaveBeenCalledOnce(); + expect(res.status).not.toHaveBeenCalled(); + }); + + it('正确提供 Bearer Token 时调用 next', () => { + const middleware = createAuthMiddleware('my-secret-token'); + const req = createMockReq({ authorization: 'Bearer my-secret-token' }); + const res = createMockRes(); + const next = vi.fn() as NextFunction; + + middleware(req, res, next); + + expect(next).toHaveBeenCalledOnce(); + expect(res.status).not.toHaveBeenCalled(); + }); + + it('缺少 Authorization 头时返回 401', () => { + const middleware = createAuthMiddleware('my-secret-token'); + const req = createMockReq(); // 无头 + const res = createMockRes(); + const next = vi.fn() as NextFunction; + + middleware(req, res, next); + + expect(next).not.toHaveBeenCalled(); + expect(res._status).toBe(401); + expect(res._body).toMatchObject({ + jsonrpc: '2.0', + error: { code: -32001, message: 'Unauthorized' }, + }); + }); + + it('提供错误 Token 时返回 401', () => { + const middleware = createAuthMiddleware('my-secret-token'); + const req = createMockReq({ authorization: 'Bearer wrong-token' }); + const res = createMockRes(); + const next = vi.fn() as NextFunction; + + middleware(req, res, next); + + expect(next).not.toHaveBeenCalled(); + expect(res._status).toBe(401); + }); + + it('提供无效格式头（无 Bearer 前缀）时返回 401', () => { + const middleware = createAuthMiddleware('my-secret-token'); + const req = createMockReq({ authorization: 'my-secret-token' }); // 缺少 "Bearer " + const res = createMockRes(); + const next = vi.fn() as NextFunction; + + middleware(req, res, next); + + expect(next).not.toHaveBeenCalled(); + expect(res._status).toBe(401); + }); +}); + +// ─── createStreamableHttpHandler 测试 ──────────────────────────────── + +describe('createStreamableHttpHandler', () => { + it('为 POST 请求且无 session id 时尝试建立新会话', async () => { + const backend = createMockBackend(); + const { handler, cleanup } = createStreamableHttpHandler(backend as never); + + // 模拟 POST 请求（无 session id） + const req = { + headers: {}, + method: 'POST', + body: { jsonrpc: '2.0', method: 'initialize', id: 1, params: {} }, + } as Request; + + const res = { + headersSent: false, + statusCode: 200, + status: vi.fn().mockReturnThis(), + json: vi.fn().mockReturnThis(), + setHeader: vi.fn(), + write: vi.fn(), + end: vi.fn(), + } as unknown as Response; + + // handler 内部会调用 StreamableHTTPServerTransport，由于无真实 SDK，可能抛错 + // 这里测试函数签名和调用不崩溃（不测试完整协议握手） + try { + await handler(req, res); + } catch { + // 预期：SDK 未安装时可能报错，这在 unit test 中是可接受的 + } + + await cleanup(); + }); + + it('未知 session id 时返回 404', async () => { + const backend = createMockBackend(); + const { handler, cleanup } = createStreamableHttpHandler(backend as never); + + const req = { + headers: { 'mcp-session-id': 'non-existent-session-id' }, + method: 'GET', + body: undefined, + } as unknown as Request; + + const res = createMockRes(); + + await handler(req, res); + + expect(res._status).toBe(404); + expect(res._body).toMatchObject({ + jsonrpc: '2.0', + error: { code: -32001, message: 'Session not found. Re-initialize.' }, + }); + + await cleanup(); + }); + + it('GET 请求且无 session id 时返回 400', async () => { + const backend = createMockBackend(); + const { handler, cleanup } = createStreamableHttpHandler(backend as never); + + const req = { + headers: {}, + method: 'GET', + body: undefined, + } as unknown as Request; + + const res = createMockRes(); + + await handler(req, res); + + expect(res._status).toBe(400); + expect(res._body).toMatchObject({ + jsonrpc: '2.0', + error: { code: -32000, message: 'No valid session. Send a POST to initialize.' }, + }); + + await cleanup(); + }); +}); + +// ─── createSseHandlers 测试 ─────────────────────────────────────────── + +describe('createSseHandlers', () => { + it('未知 sessionId 时 messageHandler 返回 404', async () => { + const backend = createMockBackend(); + const { messageHandler, cleanup } = createSseHandlers(backend as never, '/messages'); + + const req = { + query: { sessionId: 'non-existent' }, + headers: {}, + body: {}, + } as unknown as Request; + + const res = createMockRes(); + + await messageHandler(req, res); + + expect(res._status).toBe(404); + expect(res._body).toMatchObject({ + jsonrpc: '2.0', + error: { code: -32001, message: 'SSE session not found. Reconnect to /sse.' }, + }); + + await cleanup(); + }); + + it('无 sessionId 时 messageHandler 返回 404', async () => { + const backend = createMockBackend(); + const { messageHandler, cleanup } = createSseHandlers(backend as never, '/messages'); + + const req = { + query: {}, + headers: {}, + body: {}, + } as unknown as Request; + + const res = createMockRes(); + + await messageHandler(req, res); + + expect(res._status).toBe(404); + + await cleanup(); + }); + + it('cleanup 调用不会抛出异常', async () => { + const backend = createMockBackend(); + const { cleanup } = createSseHandlers(backend as never, '/messages'); + + await expect(cleanup()).resolves.not.toThrow(); + }); +}); + +// ─── mountMCPEndpoints 重构安全性测试 ──────────────────────────────── + +describe('mountMCPEndpoints', () => { + it('返回一个 cleanup 函数', () => { + const backend = createMockBackend(); + const mockApp = { + all: vi.fn(), + }; + + const cleanup = mountMCPEndpoints(mockApp as never, backend as never); + + expect(typeof cleanup).toBe('function'); + }); + + it('注册 /api/mcp 路由', () => { + const backend = createMockBackend(); + const allCalls: Array<[string, ...unknown[]]> = []; + const mockApp = { + all: vi.fn().mockImplementation((path: string, ...args: unknown[]) => { + allCalls.push([path, ...args]); + }), + }; + + mountMCPEndpoints(mockApp as never, backend as never); + + const registeredPaths = allCalls.map(([path]) => path); + expect(registeredPaths).toContain('/api/mcp'); + }); + + it('cleanup 函数可被调用而不抛出异常', async () => { + const backend = createMockBackend(); + const mockApp = { + all: vi.fn(), + }; + + const cleanup = mountMCPEndpoints(mockApp as never, backend as never); + + await expect(cleanup()).resolves.not.toThrow(); + }); +}); + +// ─── McpHttpOptions 接口测试 ────────────────────────────────────────── + +describe('McpHttpOptions 类型验证', () => { + it('createAuthMiddleware 接受 undefined authToken', () => { + // 确保 TypeScript 类型正确：authToken 是可选的 + const middleware = createAuthMiddleware(); + expect(typeof middleware).toBe('function'); + }); + + it('createAuthMiddleware 接受字符串 authToken', () => { + const middleware = createAuthMiddleware('test-token'); + expect(typeof middleware).toBe('function'); + }); +}); From f398fc358580ec282b81502677f7c73ec1486f36 Mon Sep 17 00:00:00 2001 From: BlueRose <378100977@qq.com> Date: Wed, 10 Jun 2026 12:39:58 +0800 Subject: [PATCH 02/17] fix(mcp): update i18n description for mcp --http command --- gitnexus/src/cli/i18n/en.ts | 3 ++- gitnexus/src/cli/i18n/zh-CN.ts | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/gitnexus/src/cli/i18n/en.ts b/gitnexus/src/cli/i18n/en.ts index d9d70238ea..16c67430b1 100644 --- a/gitnexus/src/cli/i18n/en.ts +++ b/gitnexus/src/cli/i18n/en.ts @@ -112,7 +112,8 @@ export const en = { 'help.command.index.description': 'Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)', 'help.command.serve.description': 'Start local HTTP server for web UI connection', - 'help.command.mcp.description': 'Start MCP server (stdio) — serves all indexed repos', + 'help.command.mcp.description': + 'Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).', 'help.command.list.description': 'List all indexed repositories', 'help.command.status.description': 'Show index status for current repo', 'help.command.doctor.description': diff --git a/gitnexus/src/cli/i18n/zh-CN.ts b/gitnexus/src/cli/i18n/zh-CN.ts index e63a9249cd..19413fa5cc 100644 --- a/gitnexus/src/cli/i18n/zh-CN.ts +++ b/gitnexus/src/cli/i18n/zh-CN.ts @@ -113,7 +113,8 @@ export const zhCN = { 'help.command.analyze.description': '索引仓库（完整分析）', 'help.command.index.description': '将现有 .gitnexus/ 文件夹注册到全局注册表（无需重新分析）', 'help.command.serve.description': '启动供 Web UI 连接的本地 HTTP 服务器', - 'help.command.mcp.description': '启动 MCP 服务器（stdio）— 提供所有已索引仓库', + 'help.command.mcp.description': + '启动 MCP 服务器。默认为 stdio。使用 --http 启动远程 HTTP 服务器（Streamable HTTP: POST /mcp + 遗留 SSE: GET /sse, POST /messages）。', 'help.command.list.description': '列出所有已索引仓库', 'help.command.status.description': '显示当前仓库的索引状态', 'help.command.doctor.description': '显示运行平台能力和嵌入配置', From 3fe691b1825adda85bc6ac73c7349f306ea58583 Mon Sep 17 00:00:00 2001 From: BlueRose <378100977@qq.com> Date: Sat, 13 Jun 2026 12:26:11 +0800 Subject: [PATCH 03/17] fix(mcp-http): address all reviewer issues from PR #2141 review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1 — Blockers: - i18n: add missing OPTION_DESCRIPTION_KEYS for mcp --http/-p/--host/--auth-token; add keys to en.ts and zh-CN.ts (fixes CI red from cli-index-help.test.ts) - security: gate PNA header on preflight request presence; restrict CORS origin to loopback when no --auth-token is set (prevents drive-by local exfiltration) - comments: translate all Chinese comments/docstrings/test names to English throughout http-transport.ts, server/mcp-http.ts, cli/mcp.ts, and test file P2: - security: replace === bearer token comparison with crypto.timingSafeEqual over equal-length buffers (eliminates timing oracle) - security: move express.json body parser per-route after auth middleware on /mcp and /messages (removes pre-auth 10 MB parse DoS vector) - default: change --host default from 0.0.0.0 to 127.0.0.1, matching serve/eval-server; cli/mcp.ts fallback updated to match - memory: add lastActivity + setInterval TTL sweep to createSseHandlers, mirroring the streamable handler (fixes indefinite SSE session leak) - DoS: cap createStreamableHttpHandler sessions at MAX_SESSIONS=1000 P3: - correctness: reject non-initialize POST /mcp with no session-id (prevents orphaned Server instances the TTL sweep can never reclaim) - correctness: validate Number(port) for NaN/out-of-range in cli/mcp.ts - correctness: add EADDRINUSE handling in startMcpHttpServer Tests: - translate all Chinese describe/it strings and comments to English - add port-0 smoke test: start → GET /health → 200; POST /mcp without token → 401 - add test: non-initialize POST with no session-id → 400 19/19 tests pass. --- gitnexus/src/cli/help-i18n.ts | 4 + gitnexus/src/cli/i18n/en.ts | 5 + gitnexus/src/cli/i18n/zh-CN.ts | 5 + gitnexus/src/cli/index.ts | 4 +- gitnexus/src/cli/mcp.ts | 20 +- gitnexus/src/mcp/http-transport.ts | 148 ++++++++----- gitnexus/src/server/mcp-http.ts | 119 ++++++++--- gitnexus/test/unit/mcp-http-transport.test.ts | 195 ++++++++++++++---- 8 files changed, 370 insertions(+), 130 deletions(-) diff --git a/gitnexus/src/cli/help-i18n.ts b/gitnexus/src/cli/help-i18n.ts index 993f20bc42..d35026b85c 100644 --- a/gitnexus/src/cli/help-i18n.ts +++ b/gitnexus/src/cli/help-i18n.ts @@ -69,6 +69,10 @@ const OPTION_DESCRIPTION_KEYS = { 'analyze|--embedding-device ': 'help.option.analyze.embeddingDevice', 'index|-f, --force': 'help.option.index.force', 'index|--allow-non-git': 'help.option.index.allowNonGit', + 'mcp|--http': 'help.option.mcp.http', + 'mcp|-p, --port ': 'help.option.port', + 'mcp|--host ': 'help.option.mcp.host', + 'mcp|--auth-token ': 'help.option.mcp.authToken', 'serve|-p, --port ': 'help.option.port', 'serve|--host ': 'help.option.serve.host', 'uninstall|-f, --force': 'help.option.uninstall.force', diff --git a/gitnexus/src/cli/i18n/en.ts b/gitnexus/src/cli/i18n/en.ts index 141a44cda4..38f16a6747 100644 --- a/gitnexus/src/cli/i18n/en.ts +++ b/gitnexus/src/cli/i18n/en.ts @@ -198,6 +198,11 @@ export const en = { 'help.option.index.allowNonGit': 'Allow registering folders that are not Git repositories', 'help.option.port': 'Port number', 'help.option.serve.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)', + 'help.option.mcp.http': 'Serve MCP over HTTP instead of stdio (for remote clients)', + 'help.option.mcp.host': + 'HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.', + 'help.option.mcp.authToken': + 'Require this bearer token in the Authorization header (only with --http). If omitted, no auth — warns on non-loopback bind.', 'help.option.force.confirmation': 'Skip confirmation prompt', 'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)', 'help.option.clean.all': 'Clean all indexed repos', diff --git a/gitnexus/src/cli/i18n/zh-CN.ts b/gitnexus/src/cli/i18n/zh-CN.ts index dab6394cc2..28022f1cae 100644 --- a/gitnexus/src/cli/i18n/zh-CN.ts +++ b/gitnexus/src/cli/i18n/zh-CN.ts @@ -187,6 +187,11 @@ export const zhCN = { 'help.option.index.allowNonGit': '允许注册非 Git 仓库文件夹', 'help.option.port': '端口号', 'help.option.serve.host': '绑定地址（默认：127.0.0.1；远程访问可用 0.0.0.0）', + 'help.option.mcp.http': '使用 HTTP 代替 stdio 提供 MCP 服务（适合远程客户端）', + 'help.option.mcp.host': + 'HTTP 绑定地址（仅与 --http 搭配使用）。默认：127.0.0.1（回环）。使用 0.0.0.0 向所有接口开放。', + 'help.option.mcp.authToken': + '要求 Authorization 头携带此 Bearer Token（仅与 --http 搭配使用）。省略则无鉴权——非回环绑定时会输出警告。', 'help.option.force.confirmation': '跳过确认提示', 'help.option.uninstall.force': '应用更改（默认仅为预演预览）', 'help.option.clean.all': '清理所有已索引仓库', diff --git a/gitnexus/src/cli/index.ts b/gitnexus/src/cli/index.ts index d0fe7e6a96..81e2d00821 100644 --- a/gitnexus/src/cli/index.ts +++ b/gitnexus/src/cli/index.ts @@ -141,8 +141,8 @@ program .option('-p, --port ', 'HTTP port (only with --http). Default: 3000', '3000') .option( '--host ', - 'HTTP bind address (only with --http). Default: 0.0.0.0 (all interfaces). Use 127.0.0.1 for loopback only.', - '0.0.0.0', + 'HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.', + '127.0.0.1', ) .option( '--auth-token ', diff --git a/gitnexus/src/cli/mcp.ts b/gitnexus/src/cli/mcp.ts index 472bfa91ff..1e5b29ec74 100644 --- a/gitnexus/src/cli/mcp.ts +++ b/gitnexus/src/cli/mcp.ts @@ -85,15 +85,23 @@ export const mcpCommand = async (options?: { ); } - // 根据选项决定启动模式：HTTP 服务器或 stdio（默认） + // Start HTTP server or fall back to stdio (default). if (options?.http) { - // 动态导入 HTTP 传输模块（保持静态导入闭包为叶子节点） - // http-transport.ts 间接引入 express/cors/SDK HTTP 传输， - // 必须在 sentinel 安装后才能加载 + // Dynamically import the HTTP transport module AFTER the sentinel installs. + // http-transport.ts pulls in express/cors/MCP SDK HTTP transport; these must + // not load before installGlobalStdoutSentinel() runs (see module doc above). + const port = Number(options.port ?? 3000); + if (!Number.isInteger(port) || port < 1 || port > 65535) { + logger.error( + { port: options.port }, + `Invalid --port value: "${options.port ?? ''}". Must be an integer between 1 and 65535.`, + ); + process.exit(1); + } const { startMcpHttpServer } = await import('../mcp/http-transport.js'); await startMcpHttpServer(backend, { - port: Number(options.port ?? 3000), - host: options.host ?? '0.0.0.0', + port, + host: options.host ?? '127.0.0.1', authToken: options.authToken, }); return; diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index de414aa200..d7b59e2e1b 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -1,48 +1,49 @@ /** - * 专用 MCP HTTP 服务器 + * Dedicated MCP HTTP server. * - * 提供基于 HTTP 的 MCP 传输，支持： - * - 现代 Streamable HTTP：POST /mcp - * - 遗留 SSE 传输：GET /sse + POST /messages + * Provides HTTP-based MCP transport supporting: + * - Modern Streamable HTTP: POST /mcp + * - Legacy SSE transport: GET /sse + POST /messages * - * 通过 `gitnexus mcp --http` 启动。 - * stdio 仍是 `gitnexus mcp` 的默认模式（无破坏性变更）。 + * Started via `gitnexus mcp --http`. + * stdio remains the default mode for `gitnexus mcp` (no breaking change). * - * 安全注意事项： - * - 默认绑定 0.0.0.0（所有接口），如不提供 --auth-token 会输出警告 - * - 使用 --auth-token 启用 Bearer Token 鉴权 - * - 使用 --host 127.0.0.1 限制为本地回环访问 + * Security considerations: + * - Default binds to 127.0.0.1 (loopback only). + * - Use --auth-token to enable Bearer Token authentication. + * - Use --host 0.0.0.0 to expose to all interfaces (requires --auth-token; warns otherwise). + * - CORS is restricted to loopback origins when no auth token is configured. + * - PNA (Private Network Access) header is emitted only in response to browser preflight requests. */ import type { Server as HttpServer } from 'http'; +import { timingSafeEqual } from 'crypto'; import express, { type Express, type Request, type Response, type NextFunction } from 'express'; import cors from 'cors'; import { createStreamableHttpHandler, createSseHandlers } from '../server/mcp-http.js'; import type { LocalBackend } from './local/local-backend.js'; import { logger } from '../core/logger.js'; -/** HTTP 服务器配置选项 */ +/** HTTP server configuration options. */ export interface McpHttpOptions { - /** 监听端口 */ + /** Listening port. */ port: number; - /** 绑定地址（默认 0.0.0.0） */ + /** Bind address (default: 127.0.0.1). */ host: string; - /** Bearer 鉴权 Token（可选；不设置则无鉴权） */ + /** Bearer auth token (optional; no auth when omitted). */ authToken?: string; } /** - * 创建 Bearer Token 鉴权中间件。 + * Creates a Bearer Token authentication middleware. * - * - 如果未设置 authToken，直接放行所有请求 - * - 如果设置了 authToken，检查 Authorization: Bearer 头 - * - 鉴权失败返回 JSON-RPC 格式的 401 响应 - * - * @param authToken 期望的 Bearer Token（可选） + * - When authToken is not set, all requests pass through. + * - When authToken is set, checks the Authorization: Bearer header. + * - Uses constant-time comparison to prevent timing oracle attacks. + * - Returns a JSON-RPC formatted 401 on failure. */ export function createAuthMiddleware(authToken?: string) { return (req: Request, res: Response, next: NextFunction): void => { - // 未启用鉴权，直接放行 if (!authToken) { next(); return; @@ -51,8 +52,22 @@ export function createAuthMiddleware(authToken?: string) { const header = req.headers['authorization']; const expected = `Bearer ${authToken}`; - // 字符串比较（长度不同则快速失败） - if (typeof header === 'string' && header === expected) { + // Constant-time comparison — prevents timing oracle on bearer token. + // Buffers must be the same byte-length for timingSafeEqual; mismatch means + // we create a same-length dummy so the comparison always runs in full. + let valid = false; + if (typeof header === 'string') { + const a = Buffer.from(header); + const b = Buffer.from(expected); + if (a.length === b.length) { + valid = timingSafeEqual(a, b); + } else { + // Different lengths — run dummy comparison to preserve constant time. + timingSafeEqual(Buffer.alloc(b.length), b); + } + } + + if (valid) { next(); return; } @@ -66,17 +81,17 @@ export function createAuthMiddleware(authToken?: string) { } /** - * 创建并启动专用 MCP HTTP 服务器。 + * Creates and starts the dedicated MCP HTTP server. * - * 挂载以下路由： - * - GET /health — 健康检查（无需鉴权） - * - POST /mcp — Streamable HTTP（现代客户端） - * - GET /sse — 遗留 SSE 流（旧客户端） - * - POST /messages — 遗留 SSE 消息接收 + * Mounts the following routes: + * - GET /health — health check (no auth required; for orchestrators/probes) + * - POST /mcp — Streamable HTTP (modern clients) + * - GET /sse — legacy SSE stream (old clients) + * - POST /messages — legacy SSE message endpoint * - * @param backend LocalBackend 实例 - * @param options 服务器配置 - * @returns 已监听的 http.Server + * @param backend LocalBackend instance + * @param options Server configuration + * @returns The listening http.Server */ export async function startMcpHttpServer( backend: LocalBackend, @@ -84,7 +99,7 @@ export async function startMcpHttpServer( ): Promise { const { port, host, authToken } = options; - // 非回环地址 + 无鉴权 → 输出安全警告 + // Warn when binding to a non-loopback address without auth protection. if (!authToken && host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') { logger.warn( { host, port }, @@ -96,39 +111,64 @@ export async function startMcpHttpServer( const app: Express = express(); - // 禁用 X-Powered-By 头（减少信息泄露） + // Suppress X-Powered-By to reduce information leakage. app.disable('x-powered-by'); - // Chrome 130+ Private Network Access 预检支持 + // PNA (Chrome 130+ Private Network Access) preflight support. + // Only emit the response header when the browser actually sends the preflight request header, + // rather than on every response. This prevents arbitrary web pages from making cross-origin + // requests to the local server without triggering an explicit preflight flow. app.use((_req: Request, res: Response, next: NextFunction) => { - res.setHeader('Access-Control-Allow-Private-Network', 'true'); + if (_req.headers['access-control-request-private-network'] === '1') { + res.setHeader('Access-Control-Allow-Private-Network', 'true'); + } next(); }); - // CORS：专用 MCP-only 服务器为远程访问设计，允许所有来源 + // CORS policy: + // - With auth token: allow any origin (remote access is intentional and protected). + // - Without auth token: restrict to loopback origins only to prevent drive-by local exfiltration. + const corsOrigin = authToken + ? true + : (origin: string | undefined, cb: (err: Error | null, allow?: boolean) => void) => { + if (!origin) { + cb(null, true); + return; + } + try { + const { hostname } = new URL(origin); + const isLoopback = + hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'; + cb(null, isLoopback); + } catch { + cb(null, false); + } + }; + app.use( cors({ - origin: true, + origin: corsOrigin, credentials: false, allowedHeaders: ['Content-Type', 'Authorization', 'mcp-session-id', 'last-event-id'], exposedHeaders: ['mcp-session-id'], }), ); - // 解析 JSON 请求体（最大 10MB） - app.use(express.json({ limit: '10mb' })); - const auth = createAuthMiddleware(authToken); + // Body parser applied per-route after auth, so unauthenticated requests + // never trigger the 10 MB parse. Malformed JSON from authenticated clients + // is caught by the route-level error handler. + const jsonBody = express.json({ limit: '10mb' }); - // 健康检查路由（无需鉴权，供编排工具探测） + // Health check — no auth required; safe to expose for probes and orchestrators. app.get('/health', (_req: Request, res: Response) => { res.json({ status: 'ok' }); }); - // Streamable HTTP（现代客户端）at POST /mcp - // 复用 server/mcp-http.ts 中经过验证的会话处理逻辑 + // Streamable HTTP (modern MCP clients) at POST /mcp. + // Reuses session management logic from server/mcp-http.ts. const streamable = createStreamableHttpHandler(backend); - app.all('/mcp', auth, (req: Request, res: Response) => { + app.all('/mcp', auth, jsonBody, (req: Request, res: Response) => { void streamable.handler(req, res).catch((err: unknown) => { logger.error({ err }, 'MCP /mcp request failed'); if (!res.headersSent) { @@ -141,14 +181,14 @@ export async function startMcpHttpServer( }); }); - // 遗留 SSE：GET /sse 建立流，POST /messages 接收 JSON-RPC 消息 + // Legacy SSE: GET /sse opens the stream; POST /messages receives JSON-RPC messages. const sse = createSseHandlers(backend, '/messages'); app.get('/sse', auth, (req: Request, res: Response) => { void sse.sseHandler(req, res).catch((err: unknown) => { logger.error({ err }, 'MCP /sse failed'); }); }); - app.post('/messages', auth, (req: Request, res: Response) => { + app.post('/messages', auth, jsonBody, (req: Request, res: Response) => { void sse.messageHandler(req, res).catch((err: unknown) => { logger.error({ err }, 'MCP /messages failed'); if (!res.headersSent) { @@ -163,7 +203,6 @@ export async function startMcpHttpServer( return new Promise((resolve, reject) => { const server = app.listen(port, host, () => { - // 0.0.0.0 / :: 时显示 localhost 更友好 const displayHost = host === '0.0.0.0' || host === '::' ? 'localhost' : host; logger.info( { port, host }, @@ -173,9 +212,18 @@ export async function startMcpHttpServer( resolve(server); }); - server.on('error', reject); + server.on('error', (err: NodeJS.ErrnoException) => { + if (err.code === 'EADDRINUSE') { + logger.error( + { port, host }, + `Port ${port} is already in use. ` + + `Stop the conflicting process or use a different port: gitnexus mcp --http --port `, + ); + process.exit(1); + } + reject(err); + }); - // 优雅关闭处理 const shutdown = async (): Promise => { server.close(); await streamable.cleanup(); diff --git a/gitnexus/src/server/mcp-http.ts b/gitnexus/src/server/mcp-http.ts index e6d98bb2e3..b2970d40f5 100644 --- a/gitnexus/src/server/mcp-http.ts +++ b/gitnexus/src/server/mcp-http.ts @@ -1,16 +1,17 @@ /** * MCP over HTTP * - * 将 GitNexus MCP 服务器挂载到 Express，使用 StreamableHTTP 传输协议。 - * 每个连接的客户端都有自己的有状态会话；LocalBackend 在所有会话间共享 - * （线程安全 — 每个仓库懒加载 LadybugDB）。 + * Mounts GitNexus MCP server onto Express using the StreamableHTTP transport. + * Each connected client gets its own stateful session; LocalBackend is shared + * across all sessions (thread-safe — each repo lazily loads its LadybugDB). * - * 会话在显式关闭或 SESSION_TTL_MS 空闲后被清理 - * （防止网络断开后 onclose 从未触发的情况）。 + * Sessions are evicted on explicit close or after SESSION_TTL_MS of inactivity + * (guards against network drops where onclose never fires). * - * 新导出的工厂函数可被 http-transport.ts 中的专用 MCP-only 服务器复用： - * - createStreamableHttpHandler(backend): 封装 StreamableHTTPServerTransport 会话逻辑 - * - createSseHandlers(backend, messagesPath): 封装遗留 SSEServerTransport 会话逻辑 + * Exported factory functions are reused by the dedicated HTTP-only server in + * http-transport.ts: + * - createStreamableHttpHandler(backend): wraps StreamableHTTPServerTransport session logic + * - createSseHandlers(backend, messagesPath): wraps legacy SSEServerTransport session logic */ import type { Express, Request, Response } from 'express'; @@ -31,19 +32,22 @@ interface MCPSession { interface SSESession { server: Server; transport: SSEServerTransport; + lastActivity: number; } -/** 会话空闲 30 分钟后被驱逐 */ +/** Sessions idle longer than this are evicted. */ const SESSION_TTL_MS = 30 * 60 * 1000; -/** 清理扫描每 5 分钟运行一次 */ +/** Cleanup sweep runs every 5 minutes. */ const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; +/** Hard cap on concurrent sessions — guards against initialize-flood DoS. */ +const MAX_SESSIONS = 1000; /** - * 创建可复用的 StreamableHTTP 请求处理器。 + * Creates a reusable StreamableHTTP request handler. * - * 将现有的会话映射和 handleMcpRequest 逻辑封装为独立工厂， - * 既可被 mountMCPEndpoints（/api/mcp 路由）调用， - * 也可被专用 HTTP-only 服务器（http-transport.ts）调用。 + * Encapsulates the session map and handleMcpRequest logic as an independent factory, + * callable from both mountMCPEndpoints (/api/mcp route) and the dedicated + * HTTP-only server (http-transport.ts). */ export function createStreamableHttpHandler(backend: LocalBackend): { handler: (req: Request, res: Response) => Promise; @@ -51,7 +55,7 @@ export function createStreamableHttpHandler(backend: LocalBackend): { } { const sessions = new Map(); - // 定期清理空闲会话（防止网络断开导致 onclose 未触发） + // Periodically evict idle sessions (guard against network drops where onclose never fires). const cleanupTimer = setInterval(() => { const now = Date.now(); for (const [id, session] of sessions) { @@ -71,19 +75,50 @@ export function createStreamableHttpHandler(backend: LocalBackend): { const sessionId = req.headers['mcp-session-id'] as string | undefined; if (sessionId && sessions.has(sessionId)) { - // 已有会话 — 委托给其传输 - const session = sessions.get(sessionId)!; + // Existing session — delegate to its transport and refresh activity timestamp. + const session = sessions.get(sessionId); + if (!session) { + res + .status(500) + .json({ jsonrpc: '2.0', error: { code: -32000, message: 'Internal error' }, id: null }); + return; + } session.lastActivity = Date.now(); await session.transport.handleRequest(req, res, req.body); } else if (sessionId) { - // 未知/过期的会话 ID — 告知客户端重新初始化（符合 MCP 规范） + // Unknown / expired session ID — tell the client to re-initialize (per MCP spec). res.status(404).json({ jsonrpc: '2.0', error: { code: -32001, message: 'Session not found. Re-initialize.' }, id: null, }); } else if (req.method === 'POST') { - // 无会话 ID — 新客户端初始化 + // No session ID — new client. Only accept initialize requests to avoid + // orphaned Server instances that can never be reclaimed by the TTL sweep. + const body = req.body as Record | undefined; + if (body?.method !== 'initialize') { + res.status(400).json({ + jsonrpc: '2.0', + error: { + code: -32000, + message: 'First request must be initialize. No session ID provided.', + }, + id: null, + }); + return; + } + + // Reject when the session cap is reached — prevents memory exhaustion via + // an initialize flood (each session holds a live Server + Transport). + if (sessions.size >= MAX_SESSIONS) { + res.status(503).json({ + jsonrpc: '2.0', + error: { code: -32000, message: 'Server at session capacity. Try again later.' }, + id: null, + }); + return; + } + const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), }); @@ -93,8 +128,9 @@ export function createStreamableHttpHandler(backend: LocalBackend): { if (transport.sessionId) { sessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() }); + const sid = transport.sessionId; transport.onclose = () => { - sessions.delete(transport.sessionId!); + sessions.delete(sid); }; } } else { @@ -121,13 +157,16 @@ export function createStreamableHttpHandler(backend: LocalBackend): { } /** - * 创建遗留 SSE 传输处理器。 + * Creates legacy SSE transport handlers. * - * GET /sse（或自定义路径）建立 SSE 流； - * POST /messages（或自定义路径）接收客户端发来的 JSON-RPC 消息。 + * GET /sse (or custom path) establishes the SSE stream; + * POST /messages (or custom path) receives client JSON-RPC messages. * - * @param backend LocalBackend 实例 - * @param messagesPath 客户端 POST 消息的路径（默认 '/messages'） + * Includes the same idle-TTL eviction as createStreamableHttpHandler to prevent + * memory leaks when clients drop without closing the SSE connection cleanly. + * + * @param backend LocalBackend instance + * @param messagesPath Path clients POST messages to (default: '/messages') */ export function createSseHandlers( backend: LocalBackend, @@ -139,12 +178,29 @@ export function createSseHandlers( } { const sseSessions = new Map(); + // Periodically evict stale SSE sessions — mirrors the streamable handler's sweep. + // Guards against network drops where the socket 'close' event never fires. + const cleanupTimer = setInterval(() => { + const now = Date.now(); + for (const [id, session] of sseSessions) { + if (now - session.lastActivity > SESSION_TTL_MS) { + try { + session.server.close(); + } catch {} + sseSessions.delete(id); + } + } + }, CLEANUP_INTERVAL_MS); + if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) { + (cleanupTimer as NodeJS.Timeout).unref(); + } + const sseHandler = async (req: Request, res: Response): Promise => { - // SSEServerTransport(endpoint, res): endpoint 是客户端将用来 POST 的路径 + // SSEServerTransport(endpoint, res): endpoint is the path clients POST to. const transport = new SSEServerTransport(messagesPath, res); const server = createMCPServer(backend); - sseSessions.set(transport.sessionId, { server, transport }); + sseSessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() }); transport.onclose = () => { sseSessions.delete(transport.sessionId); @@ -157,7 +213,7 @@ export function createSseHandlers( } catch {} }); - // connect() 调用 transport.start()，它发送 SSE 'endpoint' 事件 + // connect() calls transport.start(), which sends the SSE 'endpoint' event. await server.connect(transport); }; @@ -176,11 +232,16 @@ export function createSseHandlers( return; } - // express.json() 已解析请求体 — 将其作为第 3 个参数传入，避免 SDK 重读已耗尽的流 + // Refresh activity timestamp so the TTL sweep does not evict an active session. + entry.lastActivity = Date.now(); + + // express.json() has already parsed the body — pass it as the third argument + // to avoid the SDK re-reading the already-consumed stream. await entry.transport.handlePostMessage(req, res, req.body); }; const cleanup = async (): Promise => { + clearInterval(cleanupTimer); for (const { server } of sseSessions.values()) { try { await Promise.resolve(server.close()); diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index 3430ef2a95..c4bc49e8aa 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -1,20 +1,21 @@ /** - * Unit Tests: MCP HTTP 传输 + * Unit Tests: MCP HTTP Transport * - * 覆盖以下内容： - * - createAuthMiddleware：无鉴权/鉴权通过/鉴权失败场景 - * - startMcpHttpServer：启动服务器、/health 端点（无需鉴权） - * - createStreamableHttpHandler：Streamable HTTP 会话初始化、未知会话 404 - * - createSseHandlers：SSE 消息路由、未知 sessionId 404 - * - mountMCPEndpoints 重构安全性：仍返回 cleanup 函数并注册 /api/mcp + * Coverage: + * - createAuthMiddleware: no-auth / valid token / invalid token scenarios + * - startMcpHttpServer: port-0 smoke test (health endpoint, unauthenticated POST → 401) + * - createStreamableHttpHandler: new-session initialization, unknown session 404 + * - createSseHandlers: message routing, unknown sessionId 404 + * - mountMCPEndpoints refactor safety: still returns cleanup fn and registers /api/mcp * - * 说明： - * - node_modules 可能未安装；测试依赖 MCP SDK mock 而非真实 SDK 实例 - * - HTTP 服务器测试使用 port: 0（由 OS 分配临时端口），绑定 127.0.0.1 - * - 每个测试后关闭服务器并调用 cleanup，避免句柄泄漏 + * Notes: + * - node_modules may not be installed; tests that exercise the MCP SDK rely on mocks. + * - HTTP server tests use port 0 (OS-assigned ephemeral port) bound to 127.0.0.1. + * - Each test closes the server and calls cleanup() to avoid handle leaks. */ -import { describe, it, expect, vi } from 'vitest'; +import http from 'http'; +import { describe, it, expect, vi, afterEach } from 'vitest'; import type { Request, Response, NextFunction } from 'express'; import { createAuthMiddleware } from '../../src/mcp/http-transport.js'; import { @@ -23,7 +24,7 @@ import { mountMCPEndpoints, } from '../../src/server/mcp-http.js'; -// ─── Mock backend 工厂 ───────────────────────────────────────────────── +// ─── Mock backend factory ────────────────────────────────────────────── function createMockBackend(overrides: Record = {}): unknown { return { @@ -42,7 +43,7 @@ function createMockBackend(overrides: Record = {}): unknown { }; } -// ─── Mock req/res 工厂 ───────────────────────────────────────────────── +// ─── Mock req/res factory ────────────────────────────────────────────── function createMockReq(headers: Record = {}): Request { return { headers } as unknown as Request; @@ -65,10 +66,10 @@ function createMockRes(): Response & { _status: number; _body: unknown } { return res as unknown as Response & { _status: number; _body: unknown }; } -// ─── createAuthMiddleware 测试 ───────────────────────────────────────── +// ─── createAuthMiddleware ────────────────────────────────────────────── describe('createAuthMiddleware', () => { - it('未设置 authToken 时直接调用 next（无鉴权）', () => { + it('calls next immediately when authToken is not set', () => { const middleware = createAuthMiddleware(undefined); const req = createMockReq(); const res = createMockRes(); @@ -80,7 +81,7 @@ describe('createAuthMiddleware', () => { expect(res.status).not.toHaveBeenCalled(); }); - it('正确提供 Bearer Token 时调用 next', () => { + it('calls next when the correct Bearer token is supplied', () => { const middleware = createAuthMiddleware('my-secret-token'); const req = createMockReq({ authorization: 'Bearer my-secret-token' }); const res = createMockRes(); @@ -92,9 +93,9 @@ describe('createAuthMiddleware', () => { expect(res.status).not.toHaveBeenCalled(); }); - it('缺少 Authorization 头时返回 401', () => { + it('returns 401 when Authorization header is missing', () => { const middleware = createAuthMiddleware('my-secret-token'); - const req = createMockReq(); // 无头 + const req = createMockReq(); // no headers const res = createMockRes(); const next = vi.fn() as NextFunction; @@ -108,7 +109,7 @@ describe('createAuthMiddleware', () => { }); }); - it('提供错误 Token 时返回 401', () => { + it('returns 401 when the wrong token is supplied', () => { const middleware = createAuthMiddleware('my-secret-token'); const req = createMockReq({ authorization: 'Bearer wrong-token' }); const res = createMockRes(); @@ -120,9 +121,9 @@ describe('createAuthMiddleware', () => { expect(res._status).toBe(401); }); - it('提供无效格式头（无 Bearer 前缀）时返回 401', () => { + it('returns 401 when Authorization header is missing the "Bearer " prefix', () => { const middleware = createAuthMiddleware('my-secret-token'); - const req = createMockReq({ authorization: 'my-secret-token' }); // 缺少 "Bearer " + const req = createMockReq({ authorization: 'my-secret-token' }); const res = createMockRes(); const next = vi.fn() as NextFunction; @@ -133,14 +134,103 @@ describe('createAuthMiddleware', () => { }); }); -// ─── createStreamableHttpHandler 测试 ──────────────────────────────── +// ─── startMcpHttpServer smoke tests ─────────────────────────────────── + +describe('startMcpHttpServer', () => { + const servers: Array<{ server: http.Server; cleanup: () => Promise }> = []; + + afterEach(async () => { + for (const { server, cleanup } of servers.splice(0)) { + await cleanup().catch(() => {}); + await new Promise((resolve) => server.close(() => resolve())); + } + }); + + /** + * Starts the MCP HTTP server on an OS-assigned port (port 0), returns the + * bound port, a node http.Server handle, and the cleanup function. + */ + async function startOnFreePort(authToken?: string): Promise<{ + port: number; + server: http.Server; + cleanup: () => Promise; + }> { + const backend = createMockBackend(); + + // Wrap startMcpHttpServer to capture the returned http.Server. + const { startMcpHttpServer: start } = await import('../../src/mcp/http-transport.js'); + const resolvedServer = await start(backend as never, { + port: 0, + host: '127.0.0.1', + authToken, + }); + + const address = resolvedServer.address(); + const port = + address && typeof address === 'object' + ? address.port + : (() => { + throw new Error('no port'); + })(); + + const cleanup = async (): Promise => { + // afterEach closes the server handle. + }; + + return { port, server: resolvedServer, cleanup }; + } + + it('GET /health returns 200 { status: "ok" }', async () => { + const { port, server, cleanup } = await startOnFreePort(); + servers.push({ server, cleanup }); + + const body = await new Promise((resolve, reject) => { + http + .get(`http://127.0.0.1:${port}/health`, (res) => { + let data = ''; + res.on('data', (chunk: string) => (data += chunk)); + res.on('end', () => resolve(data)); + }) + .on('error', reject); + }); + + expect(JSON.parse(body)).toEqual({ status: 'ok' }); + }); + + it('POST /mcp without auth token returns 401 when --auth-token is configured', async () => { + const { port, server, cleanup } = await startOnFreePort('supersecret'); + servers.push({ server, cleanup }); + + const statusCode = await new Promise((resolve, reject) => { + const req = http.request( + { + hostname: '127.0.0.1', + port, + path: '/mcp', + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + }, + (res) => { + res.resume(); // drain + resolve(res.statusCode ?? 0); + }, + ); + req.on('error', reject); + req.write(JSON.stringify({ jsonrpc: '2.0', method: 'initialize', id: 1, params: {} })); + req.end(); + }); + + expect(statusCode).toBe(401); + }); +}); + +// ─── createStreamableHttpHandler ────────────────────────────────────── describe('createStreamableHttpHandler', () => { - it('为 POST 请求且无 session id 时尝试建立新会话', async () => { + it('attempts to create a new session for a POST with no session id', async () => { const backend = createMockBackend(); const { handler, cleanup } = createStreamableHttpHandler(backend as never); - // 模拟 POST 请求（无 session id） const req = { headers: {}, method: 'POST', @@ -157,18 +247,38 @@ describe('createStreamableHttpHandler', () => { end: vi.fn(), } as unknown as Response; - // handler 内部会调用 StreamableHTTPServerTransport，由于无真实 SDK，可能抛错 - // 这里测试函数签名和调用不崩溃（不测试完整协议握手） + // The handler calls StreamableHTTPServerTransport internally; without the real + // SDK installed the call may throw — that is acceptable in unit tests. try { await handler(req, res); } catch { - // 预期：SDK 未安装时可能报错，这在 unit test 中是可接受的 + // Expected when SDK is not installed. } await cleanup(); }); - it('未知 session id 时返回 404', async () => { + it('returns 400 when POST has no session id and body method is not initialize', async () => { + const backend = createMockBackend(); + const { handler, cleanup } = createStreamableHttpHandler(backend as never); + + const req = { + headers: {}, + method: 'POST', + body: { jsonrpc: '2.0', method: 'tools/list', id: 2, params: {} }, + } as Request; + + const res = createMockRes(); + + await handler(req, res); + + expect(res._status).toBe(400); + expect(res._body).toMatchObject({ jsonrpc: '2.0', error: { code: -32000 } }); + + await cleanup(); + }); + + it('returns 404 for an unknown session id', async () => { const backend = createMockBackend(); const { handler, cleanup } = createStreamableHttpHandler(backend as never); @@ -191,7 +301,7 @@ describe('createStreamableHttpHandler', () => { await cleanup(); }); - it('GET 请求且无 session id 时返回 400', async () => { + it('returns 400 for a GET with no session id', async () => { const backend = createMockBackend(); const { handler, cleanup } = createStreamableHttpHandler(backend as never); @@ -215,10 +325,10 @@ describe('createStreamableHttpHandler', () => { }); }); -// ─── createSseHandlers 测试 ─────────────────────────────────────────── +// ─── createSseHandlers ──────────────────────────────────────────────── describe('createSseHandlers', () => { - it('未知 sessionId 时 messageHandler 返回 404', async () => { + it('returns 404 from messageHandler when sessionId is unknown', async () => { const backend = createMockBackend(); const { messageHandler, cleanup } = createSseHandlers(backend as never, '/messages'); @@ -241,7 +351,7 @@ describe('createSseHandlers', () => { await cleanup(); }); - it('无 sessionId 时 messageHandler 返回 404', async () => { + it('returns 404 from messageHandler when no sessionId is provided', async () => { const backend = createMockBackend(); const { messageHandler, cleanup } = createSseHandlers(backend as never, '/messages'); @@ -260,7 +370,7 @@ describe('createSseHandlers', () => { await cleanup(); }); - it('cleanup 调用不会抛出异常', async () => { + it('cleanup does not throw', async () => { const backend = createMockBackend(); const { cleanup } = createSseHandlers(backend as never, '/messages'); @@ -268,10 +378,10 @@ describe('createSseHandlers', () => { }); }); -// ─── mountMCPEndpoints 重构安全性测试 ──────────────────────────────── +// ─── mountMCPEndpoints refactor safety ─────────────────────────────── describe('mountMCPEndpoints', () => { - it('返回一个 cleanup 函数', () => { + it('returns a cleanup function', () => { const backend = createMockBackend(); const mockApp = { all: vi.fn(), @@ -282,7 +392,7 @@ describe('mountMCPEndpoints', () => { expect(typeof cleanup).toBe('function'); }); - it('注册 /api/mcp 路由', () => { + it('registers the /api/mcp route', () => { const backend = createMockBackend(); const allCalls: Array<[string, ...unknown[]]> = []; const mockApp = { @@ -297,7 +407,7 @@ describe('mountMCPEndpoints', () => { expect(registeredPaths).toContain('/api/mcp'); }); - it('cleanup 函数可被调用而不抛出异常', async () => { + it('cleanup function resolves without throwing', async () => { const backend = createMockBackend(); const mockApp = { all: vi.fn(), @@ -309,16 +419,15 @@ describe('mountMCPEndpoints', () => { }); }); -// ─── McpHttpOptions 接口测试 ────────────────────────────────────────── +// ─── McpHttpOptions type validation ────────────────────────────────── -describe('McpHttpOptions 类型验证', () => { - it('createAuthMiddleware 接受 undefined authToken', () => { - // 确保 TypeScript 类型正确：authToken 是可选的 +describe('McpHttpOptions type validation', () => { + it('createAuthMiddleware accepts undefined authToken', () => { const middleware = createAuthMiddleware(); expect(typeof middleware).toBe('function'); }); - it('createAuthMiddleware 接受字符串 authToken', () => { + it('createAuthMiddleware accepts a string authToken', () => { const middleware = createAuthMiddleware('test-token'); expect(typeof middleware).toBe('function'); }); From be223be091e3027426e108d19754a3d1e5d27cdd Mon Sep 17 00:00:00 2001 From: BlueRose <378100977@qq.com> Date: Sat, 13 Jun 2026 12:41:16 +0800 Subject: [PATCH 04/17] =?UTF-8?q?refactor(mcp-http):=20fix=20layer=20inver?= =?UTF-8?q?sion=20=E2=80=94=20move=20session=20factories=20into=20mcp/=20l?= =?UTF-8?q?ayer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit createStreamableHttpHandler and createSseHandlers belonged in the mcp/ layer (MCP transport concerns), but lived in server/mcp-http.ts, which caused mcp/http-transport.ts to import from server/ — inverting the established server/ → mcp/ dependency direction. Move both factories (plus MCPSession/SSESession interfaces and TTL constants) into mcp/http-transport.ts. server/mcp-http.ts now only contains mountMCPEndpoints, which imports from mcp/http-transport.ts — restoring the correct arrow direction with no functional change. Update test imports accordingly (createStreamableHttpHandler/createSseHandlers now come from mcp/http-transport.js; mountMCPEndpoints still from server/mcp-http.js). --- gitnexus/src/mcp/http-transport.ts | 242 ++++++++++++++++- gitnexus/src/server/mcp-http.ts | 252 +----------------- gitnexus/test/unit/mcp-http-transport.test.ts | 6 +- 3 files changed, 248 insertions(+), 252 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index d7b59e2e1b..1cc254ea3c 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -8,6 +8,10 @@ * Started via `gitnexus mcp --http`. * stdio remains the default mode for `gitnexus mcp` (no breaking change). * + * Exports createStreamableHttpHandler and createSseHandlers so that + * server/mcp-http.ts (web-UI route mount) can reuse them without inverting + * the established server/ → mcp/ dependency direction. + * * Security considerations: * - Default binds to 127.0.0.1 (loopback only). * - Use --auth-token to enable Bearer Token authentication. @@ -17,10 +21,13 @@ */ import type { Server as HttpServer } from 'http'; -import { timingSafeEqual } from 'crypto'; +import { timingSafeEqual, randomUUID } from 'crypto'; import express, { type Express, type Request, type Response, type NextFunction } from 'express'; import cors from 'cors'; -import { createStreamableHttpHandler, createSseHandlers } from '../server/mcp-http.js'; +import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; +import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { createMCPServer } from './server.js'; import type { LocalBackend } from './local/local-backend.js'; import { logger } from '../core/logger.js'; @@ -34,6 +41,25 @@ export interface McpHttpOptions { authToken?: string; } +interface MCPSession { + server: Server; + transport: StreamableHTTPServerTransport; + lastActivity: number; +} + +interface SSESession { + server: Server; + transport: SSEServerTransport; + lastActivity: number; +} + +/** Sessions idle longer than this are evicted. */ +const SESSION_TTL_MS = 30 * 60 * 1000; +/** Cleanup sweep runs every 5 minutes. */ +const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; +/** Hard cap on concurrent sessions — guards against initialize-flood DoS. */ +const MAX_SESSIONS = 1000; + /** * Creates a Bearer Token authentication middleware. * @@ -80,6 +106,217 @@ export function createAuthMiddleware(authToken?: string) { }; } +/** + * Creates a reusable StreamableHTTP request handler. + * + * Encapsulates the session map and request-dispatch logic as an independent + * factory, reused by both startMcpHttpServer (POST /mcp) and the web-UI server + * route mount in server/mcp-http.ts (/api/mcp). + */ +export function createStreamableHttpHandler(backend: LocalBackend): { + handler: (req: Request, res: Response) => Promise; + cleanup: () => Promise; +} { + const sessions = new Map(); + + // Periodically evict idle sessions (guard against network drops where onclose never fires). + const cleanupTimer = setInterval(() => { + const now = Date.now(); + for (const [id, session] of sessions) { + if (now - session.lastActivity > SESSION_TTL_MS) { + try { + session.server.close(); + } catch {} + sessions.delete(id); + } + } + }, CLEANUP_INTERVAL_MS); + if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) { + (cleanupTimer as NodeJS.Timeout).unref(); + } + + const handler = async (req: Request, res: Response): Promise => { + const sessionId = req.headers['mcp-session-id'] as string | undefined; + + if (sessionId && sessions.has(sessionId)) { + // Existing session — delegate to its transport and refresh activity timestamp. + const session = sessions.get(sessionId); + if (!session) { + res + .status(500) + .json({ jsonrpc: '2.0', error: { code: -32000, message: 'Internal error' }, id: null }); + return; + } + session.lastActivity = Date.now(); + await session.transport.handleRequest(req, res, req.body); + } else if (sessionId) { + // Unknown / expired session ID — tell the client to re-initialize (per MCP spec). + res.status(404).json({ + jsonrpc: '2.0', + error: { code: -32001, message: 'Session not found. Re-initialize.' }, + id: null, + }); + } else if (req.method === 'POST') { + // No session ID — new client. Only accept initialize requests to avoid + // orphaned Server instances that can never be reclaimed by the TTL sweep. + const body = req.body as Record | undefined; + if (body?.method !== 'initialize') { + res.status(400).json({ + jsonrpc: '2.0', + error: { + code: -32000, + message: 'First request must be initialize. No session ID provided.', + }, + id: null, + }); + return; + } + + // Reject when the session cap is reached — prevents memory exhaustion via + // an initialize flood (each session holds a live Server + Transport). + if (sessions.size >= MAX_SESSIONS) { + res.status(503).json({ + jsonrpc: '2.0', + error: { code: -32000, message: 'Server at session capacity. Try again later.' }, + id: null, + }); + return; + } + + const transport = new StreamableHTTPServerTransport({ + sessionIdGenerator: () => randomUUID(), + }); + const server = createMCPServer(backend); + await server.connect(transport); + await transport.handleRequest(req, res, req.body); + + if (transport.sessionId) { + sessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() }); + const sid = transport.sessionId; + transport.onclose = () => { + sessions.delete(sid); + }; + } + } else { + res.status(400).json({ + jsonrpc: '2.0', + error: { code: -32000, message: 'No valid session. Send a POST to initialize.' }, + id: null, + }); + } + }; + + const cleanup = async (): Promise => { + clearInterval(cleanupTimer); + const closers = [...sessions.values()].map(async (session) => { + try { + await Promise.resolve(session.server.close()); + } catch {} + }); + sessions.clear(); + await Promise.allSettled(closers); + }; + + return { handler, cleanup }; +} + +/** + * Creates legacy SSE transport handlers. + * + * GET /sse (or custom path) establishes the SSE stream; + * POST /messages (or custom path) receives client JSON-RPC messages. + * + * Includes the same idle-TTL eviction as createStreamableHttpHandler to prevent + * memory leaks when clients drop without closing the SSE connection cleanly. + * + * @param backend LocalBackend instance + * @param messagesPath Path clients POST messages to (default: '/messages') + */ +export function createSseHandlers( + backend: LocalBackend, + messagesPath = '/messages', +): { + sseHandler: (req: Request, res: Response) => Promise; + messageHandler: (req: Request, res: Response) => Promise; + cleanup: () => Promise; +} { + const sseSessions = new Map(); + + // Periodically evict stale SSE sessions — mirrors the streamable handler's sweep. + // Guards against network drops where the socket 'close' event never fires. + const cleanupTimer = setInterval(() => { + const now = Date.now(); + for (const [id, session] of sseSessions) { + if (now - session.lastActivity > SESSION_TTL_MS) { + try { + session.server.close(); + } catch {} + sseSessions.delete(id); + } + } + }, CLEANUP_INTERVAL_MS); + if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) { + (cleanupTimer as NodeJS.Timeout).unref(); + } + + const sseHandler = async (req: Request, res: Response): Promise => { + // SSEServerTransport(endpoint, res): endpoint is the path clients POST to. + const transport = new SSEServerTransport(messagesPath, res); + const server = createMCPServer(backend); + + sseSessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() }); + + transport.onclose = () => { + sseSessions.delete(transport.sessionId); + }; + + res.on('close', () => { + sseSessions.delete(transport.sessionId); + try { + server.close(); + } catch {} + }); + + // connect() calls transport.start(), which sends the SSE 'endpoint' event. + await server.connect(transport); + }; + + const messageHandler = async (req: Request, res: Response): Promise => { + const sessionId = + (req.query['sessionId'] as string | undefined) ?? + (req.headers['mcp-session-id'] as string | undefined); + const entry = sessionId ? sseSessions.get(sessionId) : undefined; + + if (!entry) { + res.status(404).json({ + jsonrpc: '2.0', + error: { code: -32001, message: 'SSE session not found. Reconnect to /sse.' }, + id: null, + }); + return; + } + + // Refresh activity timestamp so the TTL sweep does not evict an active session. + entry.lastActivity = Date.now(); + + // express.json() has already parsed the body — pass it as the third argument + // to avoid the SDK re-reading the already-consumed stream. + await entry.transport.handlePostMessage(req, res, req.body); + }; + + const cleanup = async (): Promise => { + clearInterval(cleanupTimer); + for (const { server } of sseSessions.values()) { + try { + await Promise.resolve(server.close()); + } catch {} + } + sseSessions.clear(); + }; + + return { sseHandler, messageHandler, cleanup }; +} + /** * Creates and starts the dedicated MCP HTTP server. * @@ -166,7 +403,6 @@ export async function startMcpHttpServer( }); // Streamable HTTP (modern MCP clients) at POST /mcp. - // Reuses session management logic from server/mcp-http.ts. const streamable = createStreamableHttpHandler(backend); app.all('/mcp', auth, jsonBody, (req: Request, res: Response) => { void streamable.handler(req, res).catch((err: unknown) => { diff --git a/gitnexus/src/server/mcp-http.ts b/gitnexus/src/server/mcp-http.ts index b2970d40f5..ccfd71adf6 100644 --- a/gitnexus/src/server/mcp-http.ts +++ b/gitnexus/src/server/mcp-http.ts @@ -1,258 +1,18 @@ /** - * MCP over HTTP + * MCP over HTTP — route mount helper for the web-UI server. * - * Mounts GitNexus MCP server onto Express using the StreamableHTTP transport. - * Each connected client gets its own stateful session; LocalBackend is shared - * across all sessions (thread-safe — each repo lazily loads its LadybugDB). + * Mounts the GitNexus MCP endpoint (/api/mcp) onto an existing Express + * application. Session management lives in mcp/http-transport.ts, preserving + * the established server/ → mcp/ dependency direction. * - * Sessions are evicted on explicit close or after SESSION_TTL_MS of inactivity - * (guards against network drops where onclose never fires). - * - * Exported factory functions are reused by the dedicated HTTP-only server in - * http-transport.ts: - * - createStreamableHttpHandler(backend): wraps StreamableHTTPServerTransport session logic - * - createSseHandlers(backend, messagesPath): wraps legacy SSEServerTransport session logic + * Used by server/api.ts to wire up the full web server. */ import type { Express, Request, Response } from 'express'; -import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import { Server } from '@modelcontextprotocol/sdk/server/index.js'; -import { createMCPServer } from '../mcp/server.js'; +import { createStreamableHttpHandler } from '../mcp/http-transport.js'; import type { LocalBackend } from '../mcp/local/local-backend.js'; -import { randomUUID } from 'crypto'; import { logger } from '../core/logger.js'; -interface MCPSession { - server: Server; - transport: StreamableHTTPServerTransport; - lastActivity: number; -} - -interface SSESession { - server: Server; - transport: SSEServerTransport; - lastActivity: number; -} - -/** Sessions idle longer than this are evicted. */ -const SESSION_TTL_MS = 30 * 60 * 1000; -/** Cleanup sweep runs every 5 minutes. */ -const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; -/** Hard cap on concurrent sessions — guards against initialize-flood DoS. */ -const MAX_SESSIONS = 1000; - -/** - * Creates a reusable StreamableHTTP request handler. - * - * Encapsulates the session map and handleMcpRequest logic as an independent factory, - * callable from both mountMCPEndpoints (/api/mcp route) and the dedicated - * HTTP-only server (http-transport.ts). - */ -export function createStreamableHttpHandler(backend: LocalBackend): { - handler: (req: Request, res: Response) => Promise; - cleanup: () => Promise; -} { - const sessions = new Map(); - - // Periodically evict idle sessions (guard against network drops where onclose never fires). - const cleanupTimer = setInterval(() => { - const now = Date.now(); - for (const [id, session] of sessions) { - if (now - session.lastActivity > SESSION_TTL_MS) { - try { - session.server.close(); - } catch {} - sessions.delete(id); - } - } - }, CLEANUP_INTERVAL_MS); - if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) { - (cleanupTimer as NodeJS.Timeout).unref(); - } - - const handler = async (req: Request, res: Response): Promise => { - const sessionId = req.headers['mcp-session-id'] as string | undefined; - - if (sessionId && sessions.has(sessionId)) { - // Existing session — delegate to its transport and refresh activity timestamp. - const session = sessions.get(sessionId); - if (!session) { - res - .status(500) - .json({ jsonrpc: '2.0', error: { code: -32000, message: 'Internal error' }, id: null }); - return; - } - session.lastActivity = Date.now(); - await session.transport.handleRequest(req, res, req.body); - } else if (sessionId) { - // Unknown / expired session ID — tell the client to re-initialize (per MCP spec). - res.status(404).json({ - jsonrpc: '2.0', - error: { code: -32001, message: 'Session not found. Re-initialize.' }, - id: null, - }); - } else if (req.method === 'POST') { - // No session ID — new client. Only accept initialize requests to avoid - // orphaned Server instances that can never be reclaimed by the TTL sweep. - const body = req.body as Record | undefined; - if (body?.method !== 'initialize') { - res.status(400).json({ - jsonrpc: '2.0', - error: { - code: -32000, - message: 'First request must be initialize. No session ID provided.', - }, - id: null, - }); - return; - } - - // Reject when the session cap is reached — prevents memory exhaustion via - // an initialize flood (each session holds a live Server + Transport). - if (sessions.size >= MAX_SESSIONS) { - res.status(503).json({ - jsonrpc: '2.0', - error: { code: -32000, message: 'Server at session capacity. Try again later.' }, - id: null, - }); - return; - } - - const transport = new StreamableHTTPServerTransport({ - sessionIdGenerator: () => randomUUID(), - }); - const server = createMCPServer(backend); - await server.connect(transport); - await transport.handleRequest(req, res, req.body); - - if (transport.sessionId) { - sessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() }); - const sid = transport.sessionId; - transport.onclose = () => { - sessions.delete(sid); - }; - } - } else { - res.status(400).json({ - jsonrpc: '2.0', - error: { code: -32000, message: 'No valid session. Send a POST to initialize.' }, - id: null, - }); - } - }; - - const cleanup = async (): Promise => { - clearInterval(cleanupTimer); - const closers = [...sessions.values()].map(async (session) => { - try { - await Promise.resolve(session.server.close()); - } catch {} - }); - sessions.clear(); - await Promise.allSettled(closers); - }; - - return { handler, cleanup }; -} - -/** - * Creates legacy SSE transport handlers. - * - * GET /sse (or custom path) establishes the SSE stream; - * POST /messages (or custom path) receives client JSON-RPC messages. - * - * Includes the same idle-TTL eviction as createStreamableHttpHandler to prevent - * memory leaks when clients drop without closing the SSE connection cleanly. - * - * @param backend LocalBackend instance - * @param messagesPath Path clients POST messages to (default: '/messages') - */ -export function createSseHandlers( - backend: LocalBackend, - messagesPath = '/messages', -): { - sseHandler: (req: Request, res: Response) => Promise; - messageHandler: (req: Request, res: Response) => Promise; - cleanup: () => Promise; -} { - const sseSessions = new Map(); - - // Periodically evict stale SSE sessions — mirrors the streamable handler's sweep. - // Guards against network drops where the socket 'close' event never fires. - const cleanupTimer = setInterval(() => { - const now = Date.now(); - for (const [id, session] of sseSessions) { - if (now - session.lastActivity > SESSION_TTL_MS) { - try { - session.server.close(); - } catch {} - sseSessions.delete(id); - } - } - }, CLEANUP_INTERVAL_MS); - if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) { - (cleanupTimer as NodeJS.Timeout).unref(); - } - - const sseHandler = async (req: Request, res: Response): Promise => { - // SSEServerTransport(endpoint, res): endpoint is the path clients POST to. - const transport = new SSEServerTransport(messagesPath, res); - const server = createMCPServer(backend); - - sseSessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() }); - - transport.onclose = () => { - sseSessions.delete(transport.sessionId); - }; - - res.on('close', () => { - sseSessions.delete(transport.sessionId); - try { - server.close(); - } catch {} - }); - - // connect() calls transport.start(), which sends the SSE 'endpoint' event. - await server.connect(transport); - }; - - const messageHandler = async (req: Request, res: Response): Promise => { - const sessionId = - (req.query['sessionId'] as string | undefined) ?? - (req.headers['mcp-session-id'] as string | undefined); - const entry = sessionId ? sseSessions.get(sessionId) : undefined; - - if (!entry) { - res.status(404).json({ - jsonrpc: '2.0', - error: { code: -32001, message: 'SSE session not found. Reconnect to /sse.' }, - id: null, - }); - return; - } - - // Refresh activity timestamp so the TTL sweep does not evict an active session. - entry.lastActivity = Date.now(); - - // express.json() has already parsed the body — pass it as the third argument - // to avoid the SDK re-reading the already-consumed stream. - await entry.transport.handlePostMessage(req, res, req.body); - }; - - const cleanup = async (): Promise => { - clearInterval(cleanupTimer); - for (const { server } of sseSessions.values()) { - try { - await Promise.resolve(server.close()); - } catch {} - } - sseSessions.clear(); - }; - - return { sseHandler, messageHandler, cleanup }; -} - export function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise { const { handler, cleanup } = createStreamableHttpHandler(backend); diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index c4bc49e8aa..a2cbc299e4 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -17,12 +17,12 @@ import http from 'http'; import { describe, it, expect, vi, afterEach } from 'vitest'; import type { Request, Response, NextFunction } from 'express'; -import { createAuthMiddleware } from '../../src/mcp/http-transport.js'; import { + createAuthMiddleware, createStreamableHttpHandler, createSseHandlers, - mountMCPEndpoints, -} from '../../src/server/mcp-http.js'; +} from '../../src/mcp/http-transport.js'; +import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; // ─── Mock backend factory ────────────────────────────────────────────── From e3595d49709458d3512de1615aa710654c810536 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 07:56:14 +0000 Subject: [PATCH 05/17] fix(mcp-http): close orphaned MCP Server when initialize is rejected pre-session MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Streamable HTTP new-session branch connected a Server and only stored or closed it `if (transport.sessionId)`. When the SDK rejects the request (e.g. 406 on an Accept header missing `text/event-stream`, 415 on a bad Content-Type) it returns before assigning a session id, so the connected Server was never stored, never `onclose`-wired, never closed, and not counted against MAX_SESSIONS — the TTL sweep and cleanup() could never reclaim it. Close the server in the `else` branch when no session id was assigned. Adds a `createServer` seam to the factory so the lifecycle is observable, and a test that drives a real 406 (Accept: application/json only) and asserts the Server is closed rather than leaked. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 17 +++- gitnexus/test/unit/mcp-http-transport.test.ts | 88 +++++++++++++++++++ 2 files changed, 103 insertions(+), 2 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 1cc254ea3c..4ff02455f3 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -113,10 +113,15 @@ export function createAuthMiddleware(authToken?: string) { * factory, reused by both startMcpHttpServer (POST /mcp) and the web-UI server * route mount in server/mcp-http.ts (/api/mcp). */ -export function createStreamableHttpHandler(backend: LocalBackend): { +export function createStreamableHttpHandler( + backend: LocalBackend, + opts: { createServer?: () => Server } = {}, +): { handler: (req: Request, res: Response) => Promise; cleanup: () => Promise; } { + // Seam: tests inject createServer to observe the per-session Server lifecycle. + const createServer = opts.createServer ?? ((): Server => createMCPServer(backend)); const sessions = new Map(); // Periodically evict idle sessions (guard against network drops where onclose never fires). @@ -186,7 +191,7 @@ export function createStreamableHttpHandler(backend: LocalBackend): { const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), }); - const server = createMCPServer(backend); + const server = createServer(); await server.connect(transport); await transport.handleRequest(req, res, req.body); @@ -196,6 +201,14 @@ export function createStreamableHttpHandler(backend: LocalBackend): { transport.onclose = () => { sessions.delete(sid); }; + } else { + // The SDK rejected this request (e.g. 406 on a missing/invalid Accept header, + // 415 on a bad Content-Type) before assigning a session id. The Server was + // already connected but will never be stored, so the TTL sweep and cleanup() + // can't reclaim it — close it now to avoid an orphaned-Server leak. + try { + await server.close(); + } catch {} } } else { res.status(400).json({ diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index a2cbc299e4..3c46dfdd56 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -15,15 +15,64 @@ */ import http from 'http'; +import type { AddressInfo } from 'net'; import { describe, it, expect, vi, afterEach } from 'vitest'; +import express from 'express'; import type { Request, Response, NextFunction } from 'express'; import { createAuthMiddleware, createStreamableHttpHandler, createSseHandlers, } from '../../src/mcp/http-transport.js'; +import { createMCPServer } from '../../src/mcp/server.js'; import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; +// ─── Live-HTTP helpers (real req/res for SDK-touching paths) ─────────── + +async function listen(app: express.Express): Promise<{ port: number; close: () => Promise }> { + const server = app.listen(0, '127.0.0.1'); + await new Promise((resolve) => server.once('listening', () => resolve())); + const port = (server.address() as AddressInfo).port; + return { + port, + close: () => new Promise((resolve) => server.close(() => resolve())), + }; +} + +interface HttpResult { + status: number; + headers: http.IncomingHttpHeaders; + body: string; +} + +function request( + port: number, + method: string, + path: string, + headers: Record = {}, + body?: string, +): Promise { + return new Promise((resolve, reject) => { + const req = http.request({ hostname: '127.0.0.1', port, path, method, headers }, (res) => { + let data = ''; + res.on('data', (chunk: Buffer) => (data += chunk.toString())); + res.on('end', () => + resolve({ status: res.statusCode ?? 0, headers: res.headers, body: data }), + ); + }); + req.on('error', reject); + if (body !== undefined) req.write(body); + req.end(); + }); +} + +async function waitFor(predicate: () => boolean, timeoutMs = 500): Promise { + const start = Date.now(); + while (!predicate() && Date.now() - start < timeoutMs) { + await new Promise((r) => setTimeout(r, 10)); + } +} + // ─── Mock backend factory ────────────────────────────────────────────── function createMockBackend(overrides: Record = {}): unknown { @@ -323,6 +372,45 @@ describe('createStreamableHttpHandler', () => { await cleanup(); }); + + it('U1: closes the orphaned Server when the SDK rejects an initialize before a session id', async () => { + const backend = createMockBackend(); + let closed = 0; + // Inject createServer so we can observe the per-session Server's close(). + const { handler, cleanup } = createStreamableHttpHandler(backend as never, { + createServer: () => { + const s = createMCPServer(backend as never); + const orig = s.close.bind(s); + s.close = (async () => { + closed += 1; + return orig(); + }) as typeof s.close; + return s; + }, + }); + + const app = express(); + app.use(express.json()); + app.all('/mcp', (req, res) => void handler(req, res).catch(() => {})); + const { port, close } = await listen(app); + + // POST initialize but with Accept: application/json ONLY (no text/event-stream): + // the SDK returns 406 BEFORE assigning transport.sessionId, exercising the orphan path. + const res = await request( + port, + 'POST', + '/mcp', + { 'Content-Type': 'application/json', Accept: 'application/json' }, + JSON.stringify({ jsonrpc: '2.0', method: 'initialize', id: 1, params: {} }), + ); + + expect(res.status).toBe(406); + await waitFor(() => closed > 0); + expect(closed).toBeGreaterThan(0); // the connected Server was closed, not leaked + + await close(); + await cleanup(); + }); }); // ─── createSseHandlers ──────────────────────────────────────────────── From 48211e3173c8c896ae1be8874045852aa8d5a656 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 07:57:49 +0000 Subject: [PATCH 06/17] fix(mcp-http): cap legacy SSE sessions at MAX_SESSIONS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit createStreamableHttpHandler bounds concurrent sessions at MAX_SESSIONS, but createSseHandlers only TTL-swept — it had no size cap. A flood of held-open GET /sse connections could allocate an MCP Server per connection without bound until the 5-min sweep / 30-min TTL reclaimed them. Add the same capacity guard to the SSE handler, returning a JSON-RPC 503 before allocating. The cap is injectable via an options bag (default MAX_SESSIONS) so the guard is cheap to test. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 14 +++++++++ gitnexus/test/unit/mcp-http-transport.test.ts | 30 +++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 4ff02455f3..68cfb04bd7 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -248,11 +248,13 @@ export function createStreamableHttpHandler( export function createSseHandlers( backend: LocalBackend, messagesPath = '/messages', + opts: { maxSessions?: number } = {}, ): { sseHandler: (req: Request, res: Response) => Promise; messageHandler: (req: Request, res: Response) => Promise; cleanup: () => Promise; } { + const maxSessions = opts.maxSessions ?? MAX_SESSIONS; const sseSessions = new Map(); // Periodically evict stale SSE sessions — mirrors the streamable handler's sweep. @@ -273,6 +275,18 @@ export function createSseHandlers( } const sseHandler = async (req: Request, res: Response): Promise => { + // Cap concurrent SSE sessions — mirrors the streamable handler's MAX_SESSIONS + // guard so a flood of held-open GET /sse connections cannot allocate unbounded + // Server instances before the idle sweep reclaims them. + if (sseSessions.size >= maxSessions) { + res.status(503).json({ + jsonrpc: '2.0', + error: { code: -32000, message: 'Server at session capacity. Try again later.' }, + id: null, + }); + return; + } + // SSEServerTransport(endpoint, res): endpoint is the path clients POST to. const transport = new SSEServerTransport(messagesPath, res); const server = createMCPServer(backend); diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index 3c46dfdd56..a6bcdbc489 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -464,6 +464,36 @@ describe('createSseHandlers', () => { await expect(cleanup()).resolves.not.toThrow(); }); + + it('U2: returns 503 (and allocates no Server) when the SSE session cap is reached', async () => { + const backend = createMockBackend(); + // maxSessions 0 → the cap is hit immediately, so the guard fires before any + // SSEServerTransport / Server is allocated. + const { sseHandler, messageHandler, cleanup } = createSseHandlers( + backend as never, + '/messages', + { maxSessions: 0 }, + ); + + const res = createMockRes(); + await sseHandler(createMockReq(), res); + + expect(res._status).toBe(503); + expect(res._body).toMatchObject({ + jsonrpc: '2.0', + error: { code: -32000, message: 'Server at session capacity. Try again later.' }, + }); + + // No session was created — any message routes to the 404 path. + const msgRes = createMockRes(); + await messageHandler( + { query: { sessionId: 'anything' }, headers: {}, body: {} } as unknown as Request, + msgRes, + ); + expect(msgRes._status).toBe(404); + + await cleanup(); + }); }); // ─── mountMCPEndpoints refactor safety ─────────────────────────────── From 44abe2a20e8f620b522b15c68eba0d3dcfeb8241 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 07:59:16 +0000 Subject: [PATCH 07/17] fix(mcp-http): return a JSON-RPC envelope for malformed/oversized JSON MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The dedicated server registered no terminal Express error handler, so a body-parser SyntaxError (malformed JSON) or entity.too.large (oversized body) fell through to Express's default handler — an HTML error page that leaks a stack trace and absolute install paths when NODE_ENV is unset (the default for a CLI run) — instead of the JSON-RPC envelope every other path uses. Add a terminal 4-arg error handler mapping body-parser parse/size errors to a JSON-RPC -32700 "Parse error" envelope, and correct the now-accurate comment on the per-route body parser. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 35 +++++++++++++++++-- gitnexus/test/unit/mcp-http-transport.test.ts | 21 +++++++++++ 2 files changed, 53 insertions(+), 3 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 68cfb04bd7..7c79e614a5 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -419,9 +419,10 @@ export async function startMcpHttpServer( ); const auth = createAuthMiddleware(authToken); - // Body parser applied per-route after auth, so unauthenticated requests - // never trigger the 10 MB parse. Malformed JSON from authenticated clients - // is caught by the route-level error handler. + // Body parser applied per-route after auth, so unauthenticated requests never + // trigger the 10 MB parse. Malformed/oversized JSON from authenticated clients + // is converted to a JSON-RPC error envelope by the terminal error handler + // registered after the routes (see below). const jsonBody = express.json({ limit: '10mb' }); // Health check — no auth required; safe to expose for probes and orchestrators. @@ -464,6 +465,34 @@ export async function startMcpHttpServer( }); }); + // Terminal error handler: body-parser failures (malformed or oversized JSON) + // reach here via next(err). Without it, Express's default handler returns an + // HTML error page — leaking a stack trace and absolute install paths when + // NODE_ENV is unset (the default for a CLI) — instead of the JSON-RPC envelope + // every other path uses. + app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => { + const e = (err ?? {}) as { type?: string; status?: number; statusCode?: number }; + const isBodyParseError = + e.type === 'entity.parse.failed' || + e.type === 'entity.too.large' || + err instanceof SyntaxError; + logger.error({ err }, 'MCP HTTP request error'); + if (res.headersSent) return; + if (isBodyParseError) { + res.status(e.status ?? e.statusCode ?? 400).json({ + jsonrpc: '2.0', + error: { code: -32700, message: 'Parse error' }, + id: null, + }); + return; + } + res.status(500).json({ + jsonrpc: '2.0', + error: { code: -32000, message: 'Internal MCP server error' }, + id: null, + }); + }); + return new Promise((resolve, reject) => { const server = app.listen(port, host, () => { const displayHost = host === '0.0.0.0' || host === '::' ? 'localhost' : host; diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index a6bcdbc489..df8dd8c270 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -271,6 +271,27 @@ describe('startMcpHttpServer', () => { expect(statusCode).toBe(401); }); + + it('U3: malformed JSON from an authenticated client returns a JSON-RPC parse error (not HTML)', async () => { + const { port, server, cleanup } = await startOnFreePort('supersecret'); + servers.push({ server, cleanup }); + + const res = await request( + port, + 'POST', + '/mcp', + { 'Content-Type': 'application/json', Authorization: 'Bearer supersecret' }, + '{ this is not valid json ', + ); + + expect(res.status).toBe(400); + expect(String(res.headers['content-type'] ?? '')).toMatch(/application\/json/); + expect(JSON.parse(res.body)).toMatchObject({ + jsonrpc: '2.0', + error: { code: -32700, message: 'Parse error' }, + id: null, + }); + }); }); // ─── createStreamableHttpHandler ────────────────────────────────────── From 973037b85e88960b595aa1b5ee5d97940bab01d9 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:00:44 +0000 Subject: [PATCH 08/17] fix(mcp-http): accept IPv6 [::1] and the 127/8 block in the CORS loopback check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `new URL('http://[::1]:3000/').hostname` is `'[::1]'` (WHATWG keeps the brackets), so the old `hostname === '::1'` test never matched — an `http://[::1]:port` origin was wrongly rejected by the no-auth loopback CORS policy. Extract an exported `isLoopbackOrigin` helper that matches `localhost`, `[::1]`, the IPv4-mapped loopback `[::ffff:7f00:1]`, and the whole 127.0.0.0/8 block (and treats a missing Origin as a non-browser caller), with unit tests covering the look-alike rejections (`localhost.evil.com`, etc.). Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 38 +++++++++++++------ gitnexus/test/unit/mcp-http-transport.test.ts | 26 +++++++++++++ 2 files changed, 52 insertions(+), 12 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 7c79e614a5..e34c108da2 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -106,6 +106,31 @@ export function createAuthMiddleware(authToken?: string) { }; } +/** + * Returns true when an Origin should be allowed by the no-auth (loopback-only) + * CORS policy — i.e. it is absent (non-browser caller) or a loopback origin. + * + * WHATWG URL keeps the brackets on IPv6 literals + * (`new URL('http://[::1]/').hostname === '[::1]'`) and canonicalizes the + * IPv4-mapped loopback to `[::ffff:7f00:1]`; loopback IPv4 is the whole + * 127.0.0.0/8 block — so all of those forms are matched explicitly. + */ +export function isLoopbackOrigin(origin: string | undefined): boolean { + if (!origin) return true; // no Origin → non-browser caller; CORS is not the control there + let hostname: string; + try { + ({ hostname } = new URL(origin)); + } catch { + return false; + } + return ( + hostname === 'localhost' || + hostname === '[::1]' || + hostname === '[::ffff:7f00:1]' || + /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname) + ); +} + /** * Creates a reusable StreamableHTTP request handler. * @@ -395,18 +420,7 @@ export async function startMcpHttpServer( const corsOrigin = authToken ? true : (origin: string | undefined, cb: (err: Error | null, allow?: boolean) => void) => { - if (!origin) { - cb(null, true); - return; - } - try { - const { hostname } = new URL(origin); - const isLoopback = - hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'; - cb(null, isLoopback); - } catch { - cb(null, false); - } + cb(null, isLoopbackOrigin(origin)); }; app.use( diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index df8dd8c270..46f0d1bb14 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -23,6 +23,7 @@ import { createAuthMiddleware, createStreamableHttpHandler, createSseHandlers, + isLoopbackOrigin, } from '../../src/mcp/http-transport.js'; import { createMCPServer } from '../../src/mcp/server.js'; import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; @@ -571,3 +572,28 @@ describe('McpHttpOptions type validation', () => { expect(typeof middleware).toBe('function'); }); }); + +// ─── isLoopbackOrigin (U4) ─────────────────────────────────────────── + +describe('isLoopbackOrigin', () => { + it('accepts loopback origins including IPv6 [::1], IPv4-mapped, and the 127/8 block', () => { + expect(isLoopbackOrigin('http://localhost:8080')).toBe(true); + expect(isLoopbackOrigin('http://127.0.0.1:5000')).toBe(true); + expect(isLoopbackOrigin('http://127.0.0.2:3000')).toBe(true); + expect(isLoopbackOrigin('http://[::1]:3000')).toBe(true); + expect(isLoopbackOrigin('http://[::ffff:127.0.0.1]:3000')).toBe(true); + }); + + it('treats a missing Origin as allowed (non-browser caller)', () => { + expect(isLoopbackOrigin(undefined)).toBe(true); + }); + + it('rejects non-loopback and look-alike origins', () => { + expect(isLoopbackOrigin('http://localhost.evil.com')).toBe(false); + expect(isLoopbackOrigin('http://127.0.0.1.evil.com')).toBe(false); + expect(isLoopbackOrigin('http://example.com')).toBe(false); + expect(isLoopbackOrigin('http://192.168.1.50:3000')).toBe(false); + expect(isLoopbackOrigin('null')).toBe(false); + expect(isLoopbackOrigin('not a url')).toBe(false); + }); +}); From 44dadca538e83574965a01051cd5adc295d2d744 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:01:37 +0000 Subject: [PATCH 09/17] fix(mcp-http): correct the PNA preflight header value and gate it on OPTIONS Browsers send `Access-Control-Request-Private-Network: true` (not `'1'`) and only on the CORS preflight. The middleware checked for `'1'`, so the `Access-Control-Allow-Private-Network` grant was never emitted for a real browser preflight. Match the spec value `'true'` and gate on `req.method === 'OPTIONS'` so the header is emitted only on the preflight, never on actual GET/POST responses. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 14 +++++++++----- gitnexus/test/unit/mcp-http-transport.test.ts | 18 ++++++++++++++++++ 2 files changed, 27 insertions(+), 5 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index e34c108da2..44c78a56f6 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -404,11 +404,15 @@ export async function startMcpHttpServer( app.disable('x-powered-by'); // PNA (Chrome 130+ Private Network Access) preflight support. - // Only emit the response header when the browser actually sends the preflight request header, - // rather than on every response. This prevents arbitrary web pages from making cross-origin - // requests to the local server without triggering an explicit preflight flow. - app.use((_req: Request, res: Response, next: NextFunction) => { - if (_req.headers['access-control-request-private-network'] === '1') { + // The browser sends `Access-Control-Request-Private-Network: true` ONLY on the + // CORS preflight (an OPTIONS request); emit the matching allow header only then, + // never on actual GET/POST responses. Runs before cors() so the header survives + // onto the preflight response cors() short-circuits. + app.use((req: Request, res: Response, next: NextFunction) => { + if ( + req.method === 'OPTIONS' && + req.headers['access-control-request-private-network'] === 'true' + ) { res.setHeader('Access-Control-Allow-Private-Network', 'true'); } next(); diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index 46f0d1bb14..014517d8e9 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -273,6 +273,24 @@ describe('startMcpHttpServer', () => { expect(statusCode).toBe(401); }); + it('U5: emits the PNA allow header only on an OPTIONS preflight carrying the request header', async () => { + const { port, server, cleanup } = await startOnFreePort(); // no auth → loopback CORS + servers.push({ server, cleanup }); + + const preflight = await request(port, 'OPTIONS', '/mcp', { + Origin: 'http://127.0.0.1:9999', + 'Access-Control-Request-Method': 'POST', + 'Access-Control-Request-Private-Network': 'true', + }); + expect(preflight.headers['access-control-allow-private-network']).toBe('true'); + + // A normal GET carrying the request header must NOT receive the allow header. + const get = await request(port, 'GET', '/health', { + 'Access-Control-Request-Private-Network': 'true', + }); + expect(get.headers['access-control-allow-private-network']).toBeUndefined(); + }); + it('U3: malformed JSON from an authenticated client returns a JSON-RPC parse error (not HTML)', async () => { const { port, server, cleanup } = await startOnFreePort('supersecret'); servers.push({ server, cleanup }); From 5e00b244f540fc4e3b68aa21429d9271f0db1510 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:04:39 +0000 Subject: [PATCH 10/17] fix(mcp-http): enable SDK DNS-rebinding protection for known bind hosts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both transports were constructed without enableDnsRebindingProtection, so the SDK's Host-header validation was off. Add computeAllowedHosts(host, port): for a loopback bind it allowlists all three loopback host forms (bare + :port); for a specific non-loopback host (e.g. 192.168.1.50) it allowlists that host; for wildcard binds (0.0.0.0 / ::) it returns undefined (Host unknowable — the required bearer token is the control) so protection stays off and remote access keeps working. The host/port flow through the factory options bag, so the web-UI /api/mcp mount (which passes neither) is unaffected. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 53 ++++++++++++++++--- gitnexus/test/unit/mcp-http-transport.test.ts | 47 ++++++++++++++++ 2 files changed, 94 insertions(+), 6 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 44c78a56f6..38631cf9d4 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -131,6 +131,42 @@ export function isLoopbackOrigin(origin: string | undefined): boolean { ); } +/** True for the exact loopback bind addresses. */ +export function isLoopbackHost(host: string): boolean { + return host === '127.0.0.1' || host === 'localhost' || host === '::1'; +} + +/** True for any-interface wildcard binds, whose externally-used Host is unknowable. */ +export function isWildcardHost(host: string): boolean { + return host === '0.0.0.0' || host === '::'; +} + +/** + * Computes the SDK DNS-rebinding `allowedHosts` list (a Host-header allowlist) for a + * bind host/port, or `undefined` when protection should stay off. + * + * Wildcard binds (`0.0.0.0` / `::`) return `undefined` — the Host a client + * legitimately uses is unknowable, so the bearer token (required for non-loopback + * binds) is the control. Loopback binds allow all three loopback host forms + * (bare + `:port`); a specific host (e.g. `192.168.1.50`) allows that host + * (bare + `:port`), which is knowable and a free defence-in-depth win. + */ +export function computeAllowedHosts(host: string, port: number): string[] | undefined { + if (isWildcardHost(host)) return undefined; + const hosts = isLoopbackHost(host) ? ['127.0.0.1', 'localhost', '[::1]'] : [host]; + return hosts.flatMap((h) => [h, `${h}:${port}`]); +} + +/** Builds the SDK transport DNS-rebinding options from a bind host/port. */ +function dnsRebindingOptions( + host: string | undefined, + port: number | undefined, +): { enableDnsRebindingProtection?: boolean; allowedHosts?: string[] } { + if (host === undefined || port === undefined) return {}; + const allowedHosts = computeAllowedHosts(host, port); + return allowedHosts ? { enableDnsRebindingProtection: true, allowedHosts } : {}; +} + /** * Creates a reusable StreamableHTTP request handler. * @@ -140,13 +176,15 @@ export function isLoopbackOrigin(origin: string | undefined): boolean { */ export function createStreamableHttpHandler( backend: LocalBackend, - opts: { createServer?: () => Server } = {}, + opts: { createServer?: () => Server; host?: string; port?: number } = {}, ): { handler: (req: Request, res: Response) => Promise; cleanup: () => Promise; } { // Seam: tests inject createServer to observe the per-session Server lifecycle. const createServer = opts.createServer ?? ((): Server => createMCPServer(backend)); + // DNS-rebinding protection (Host-header allowlist) when the bind host is known. + const dnsRebinding = dnsRebindingOptions(opts.host, opts.port); const sessions = new Map(); // Periodically evict idle sessions (guard against network drops where onclose never fires). @@ -215,6 +253,7 @@ export function createStreamableHttpHandler( const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), + ...dnsRebinding, }); const server = createServer(); await server.connect(transport); @@ -273,13 +312,15 @@ export function createStreamableHttpHandler( export function createSseHandlers( backend: LocalBackend, messagesPath = '/messages', - opts: { maxSessions?: number } = {}, + opts: { maxSessions?: number; host?: string; port?: number } = {}, ): { sseHandler: (req: Request, res: Response) => Promise; messageHandler: (req: Request, res: Response) => Promise; cleanup: () => Promise; } { const maxSessions = opts.maxSessions ?? MAX_SESSIONS; + // DNS-rebinding protection (Host-header allowlist) when the bind host is known. + const dnsRebinding = dnsRebindingOptions(opts.host, opts.port); const sseSessions = new Map(); // Periodically evict stale SSE sessions — mirrors the streamable handler's sweep. @@ -312,8 +353,8 @@ export function createSseHandlers( return; } - // SSEServerTransport(endpoint, res): endpoint is the path clients POST to. - const transport = new SSEServerTransport(messagesPath, res); + // SSEServerTransport(endpoint, res, options): endpoint is the path clients POST to. + const transport = new SSEServerTransport(messagesPath, res, dnsRebinding); const server = createMCPServer(backend); sseSessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() }); @@ -449,7 +490,7 @@ export async function startMcpHttpServer( }); // Streamable HTTP (modern MCP clients) at POST /mcp. - const streamable = createStreamableHttpHandler(backend); + const streamable = createStreamableHttpHandler(backend, { host, port }); app.all('/mcp', auth, jsonBody, (req: Request, res: Response) => { void streamable.handler(req, res).catch((err: unknown) => { logger.error({ err }, 'MCP /mcp request failed'); @@ -464,7 +505,7 @@ export async function startMcpHttpServer( }); // Legacy SSE: GET /sse opens the stream; POST /messages receives JSON-RPC messages. - const sse = createSseHandlers(backend, '/messages'); + const sse = createSseHandlers(backend, '/messages', { host, port }); app.get('/sse', auth, (req: Request, res: Response) => { void sse.sseHandler(req, res).catch((err: unknown) => { logger.error({ err }, 'MCP /sse failed'); diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index 014517d8e9..21d22d721b 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -24,6 +24,7 @@ import { createStreamableHttpHandler, createSseHandlers, isLoopbackOrigin, + computeAllowedHosts, } from '../../src/mcp/http-transport.js'; import { createMCPServer } from '../../src/mcp/server.js'; import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; @@ -291,6 +292,25 @@ describe('startMcpHttpServer', () => { expect(get.headers['access-control-allow-private-network']).toBeUndefined(); }); + it('U6: rejects a POST /mcp carrying a disallowed Host header (DNS-rebinding protection)', async () => { + const { port, server, cleanup } = await startOnFreePort(); // 127.0.0.1 → protection ON + servers.push({ server, cleanup }); + + const res = await request( + port, + 'POST', + '/mcp', + { + 'Content-Type': 'application/json', + Accept: 'application/json, text/event-stream', + Host: 'evil.example.com:1234', + }, + JSON.stringify({ jsonrpc: '2.0', method: 'initialize', id: 1, params: {} }), + ); + + expect(res.status).toBe(403); + }); + it('U3: malformed JSON from an authenticated client returns a JSON-RPC parse error (not HTML)', async () => { const { port, server, cleanup } = await startOnFreePort('supersecret'); servers.push({ server, cleanup }); @@ -615,3 +635,30 @@ describe('isLoopbackOrigin', () => { expect(isLoopbackOrigin('not a url')).toBe(false); }); }); + +// ─── computeAllowedHosts (U6) ──────────────────────────────────────── + +describe('computeAllowedHosts', () => { + it('returns all loopback host forms (bare + :port) for a loopback bind', () => { + expect(computeAllowedHosts('127.0.0.1', 3000)).toEqual([ + '127.0.0.1', + '127.0.0.1:3000', + 'localhost', + 'localhost:3000', + '[::1]', + '[::1]:3000', + ]); + }); + + it('returns the specific host (bare + :port) for a non-loopback, non-wildcard bind', () => { + expect(computeAllowedHosts('192.168.1.50', 8080)).toEqual([ + '192.168.1.50', + '192.168.1.50:8080', + ]); + }); + + it('returns undefined (protection off) for wildcard binds', () => { + expect(computeAllowedHosts('0.0.0.0', 3000)).toBeUndefined(); + expect(computeAllowedHosts('::', 3000)).toBeUndefined(); + }); +}); From 97a3ab2f854f2e3d7cd31a9d67e9f9d4cf82ef73 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:05:56 +0000 Subject: [PATCH 11/17] fix(mcp-http): use POSIX shutdown exit codes (SIGINT 130, SIGTERM 143) The dedicated server wired SIGINT/SIGTERM to process.exit(0), which signals "clean success" to supervisors/shells and diverges from the repo convention. Reuse mcp/server.ts's installSignalShutdown so SIGINT exits 130 and SIGTERM exits 143 (128 + signal number), keeping the existing close/cleanup/disconnect/ flush sequence. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 11 ++++---- gitnexus/test/unit/mcp-http-transport.test.ts | 26 ++++++++++++++++++- 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 38631cf9d4..05b8b2ca27 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -27,7 +27,7 @@ import cors from 'cors'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; import { Server } from '@modelcontextprotocol/sdk/server/index.js'; -import { createMCPServer } from './server.js'; +import { createMCPServer, installSignalShutdown } from './server.js'; import type { LocalBackend } from './local/local-backend.js'; import { logger } from '../core/logger.js'; @@ -575,7 +575,7 @@ export async function startMcpHttpServer( reject(err); }); - const shutdown = async (): Promise => { + const shutdown = async (exitCode: number): Promise => { server.close(); await streamable.cleanup(); await sse.cleanup(); @@ -584,10 +584,11 @@ export async function startMcpHttpServer( } catch {} const { flushLoggerSync } = await import('../core/logger.js'); flushLoggerSync(); - process.exit(0); + process.exit(exitCode); }; - process.once('SIGINT', () => void shutdown()); - process.once('SIGTERM', () => void shutdown()); + // Use the shared signal wiring so SIGINT exits 130 and SIGTERM exits 143 + // (the repo's POSIX 128+signal convention), not a misleading exit(0). + installSignalShutdown((exitCode = 0) => void shutdown(exitCode)); }); } diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index 21d22d721b..ca22677839 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -26,7 +26,7 @@ import { isLoopbackOrigin, computeAllowedHosts, } from '../../src/mcp/http-transport.js'; -import { createMCPServer } from '../../src/mcp/server.js'; +import { createMCPServer, installSignalShutdown, SHUTDOWN_EXIT_CODES } from '../../src/mcp/server.js'; import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; // ─── Live-HTTP helpers (real req/res for SDK-touching paths) ─────────── @@ -636,6 +636,30 @@ describe('isLoopbackOrigin', () => { }); }); +// ─── shutdown signal wiring (U7) ───────────────────────────────────── + +describe('shutdown exit codes (U7)', () => { + it('wires SIGINT → 130 and SIGTERM → 143 via the shared installSignalShutdown', () => { + const handlers: Record void> = {}; + const exits: number[] = []; + + installSignalShutdown( + (code = 0) => { + exits.push(code); + }, + (event, listener) => { + handlers[event] = listener; + }, + ); + + handlers.SIGINT('SIGINT'); + handlers.SIGTERM('SIGTERM'); + + expect(SHUTDOWN_EXIT_CODES).toEqual({ SIGINT: 130, SIGTERM: 143 }); + expect(exits).toEqual([130, 143]); + }); +}); + // ─── computeAllowedHosts (U6) ──────────────────────────────────────── describe('computeAllowedHosts', () => { From 303fdfaa76107e1ceeef2dbd547429ce666b7508 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:09:30 +0000 Subject: [PATCH 12/17] feat(mcp-http): accept the auth token from GITNEXUS_MCP_AUTH_TOKEN The bearer token could only be passed via --auth-token, which is visible in `ps`/`/proc` on multi-user hosts. Add resolveAuthToken(flag, env): the flag wins, otherwise GITNEXUS_MCP_AUTH_TOKEN is used. An empty or whitespace-only value resolves to "no token" so a blank env var cannot silently disable auth (and, with the next change, slip past the non-loopback hard-fail). resolveAuthToken is dynamically imported in mcp.ts to keep express/cors out of the stdio path's static graph. Help text (en + zh-CN) documents the env var. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/cli/i18n/en.ts | 2 +- gitnexus/src/cli/i18n/zh-CN.ts | 2 +- gitnexus/src/cli/index.ts | 2 +- gitnexus/src/cli/mcp.ts | 5 ++-- gitnexus/src/mcp/http-transport.ts | 13 ++++++++++ gitnexus/test/unit/mcp-http-transport.test.ts | 26 +++++++++++++++++++ 6 files changed, 45 insertions(+), 5 deletions(-) diff --git a/gitnexus/src/cli/i18n/en.ts b/gitnexus/src/cli/i18n/en.ts index 25dc8ab8f2..2a5e61556a 100644 --- a/gitnexus/src/cli/i18n/en.ts +++ b/gitnexus/src/cli/i18n/en.ts @@ -204,7 +204,7 @@ export const en = { 'help.option.mcp.host': 'HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.', 'help.option.mcp.authToken': - 'Require this bearer token in the Authorization header (only with --http). If omitted, no auth — warns on non-loopback bind.', + 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. If omitted, no auth (warns on non-loopback bind).', 'help.option.force.confirmation': 'Skip confirmation prompt', 'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)', 'help.option.clean.all': 'Clean all indexed repos', diff --git a/gitnexus/src/cli/i18n/zh-CN.ts b/gitnexus/src/cli/i18n/zh-CN.ts index 46df24fb7e..0395a7a90a 100644 --- a/gitnexus/src/cli/i18n/zh-CN.ts +++ b/gitnexus/src/cli/i18n/zh-CN.ts @@ -192,7 +192,7 @@ export const zhCN = { 'help.option.mcp.host': 'HTTP 绑定地址（仅与 --http 搭配使用）。默认：127.0.0.1（回环）。使用 0.0.0.0 向所有接口开放。', 'help.option.mcp.authToken': - '要求 Authorization 头携带此 Bearer Token（仅与 --http 搭配使用）。省略则无鉴权——非回环绑定时会输出警告。', + '要求 Authorization 头携带此 Bearer Token（仅与 --http 搭配使用）；也可通过 GITNEXUS_MCP_AUTH_TOKEN 环境变量设置。省略则无鉴权（非回环绑定时会输出警告）。', 'help.option.force.confirmation': '跳过确认提示', 'help.option.uninstall.force': '应用更改（默认仅为预演预览）', 'help.option.clean.all': '清理所有已索引仓库', diff --git a/gitnexus/src/cli/index.ts b/gitnexus/src/cli/index.ts index d9cfb721a9..fa3896a2af 100644 --- a/gitnexus/src/cli/index.ts +++ b/gitnexus/src/cli/index.ts @@ -155,7 +155,7 @@ program ) .option( '--auth-token ', - 'Require this bearer token in the Authorization header (only with --http). If omitted, no auth (warn on non-loopback bind).', + 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. If omitted, no auth (warns on non-loopback bind).', ) .action(createLbugLazyAction(() => import('./mcp.js'), 'mcpCommand')); diff --git a/gitnexus/src/cli/mcp.ts b/gitnexus/src/cli/mcp.ts index 1e5b29ec74..6177bcdf3a 100644 --- a/gitnexus/src/cli/mcp.ts +++ b/gitnexus/src/cli/mcp.ts @@ -98,11 +98,12 @@ export const mcpCommand = async (options?: { ); process.exit(1); } - const { startMcpHttpServer } = await import('../mcp/http-transport.js'); + // Dynamic import keeps express/cors out of mcp.ts's static graph (stdio sentinel). + const { startMcpHttpServer, resolveAuthToken } = await import('../mcp/http-transport.js'); await startMcpHttpServer(backend, { port, host: options.host ?? '127.0.0.1', - authToken: options.authToken, + authToken: resolveAuthToken(options.authToken, process.env), }); return; } diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 05b8b2ca27..24ad54f242 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -157,6 +157,19 @@ export function computeAllowedHosts(host: string, port: number): string[] | unde return hosts.flatMap((h) => [h, `${h}:${port}`]); } +/** + * Resolves the MCP HTTP bearer token from the `--auth-token` flag or the + * `GITNEXUS_MCP_AUTH_TOKEN` env var (the flag wins). An empty or whitespace-only + * value is treated as "no token" so a blank env var cannot silently disable auth + * (and slip past the non-loopback hard-fail). + */ +export function resolveAuthToken( + optToken: string | undefined, + env: NodeJS.ProcessEnv, +): string | undefined { + return (optToken ?? env.GITNEXUS_MCP_AUTH_TOKEN)?.trim() || undefined; +} + /** Builds the SDK transport DNS-rebinding options from a bind host/port. */ function dnsRebindingOptions( host: string | undefined, diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index ca22677839..37229f4129 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -25,6 +25,7 @@ import { createSseHandlers, isLoopbackOrigin, computeAllowedHosts, + resolveAuthToken, } from '../../src/mcp/http-transport.js'; import { createMCPServer, installSignalShutdown, SHUTDOWN_EXIT_CODES } from '../../src/mcp/server.js'; import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; @@ -636,6 +637,31 @@ describe('isLoopbackOrigin', () => { }); }); +// ─── resolveAuthToken (U9) ─────────────────────────────────────────── + +describe('resolveAuthToken', () => { + it('uses the --auth-token flag when set, preferring it over the env var', () => { + expect(resolveAuthToken('flag', {})).toBe('flag'); + expect(resolveAuthToken('flag', { GITNEXUS_MCP_AUTH_TOKEN: 'env' })).toBe('flag'); + }); + + it('falls back to GITNEXUS_MCP_AUTH_TOKEN', () => { + expect(resolveAuthToken(undefined, { GITNEXUS_MCP_AUTH_TOKEN: 'env' })).toBe('env'); + }); + + it('treats empty/whitespace as no token (no silent auth bypass)', () => { + expect(resolveAuthToken('', {})).toBeUndefined(); + expect(resolveAuthToken(' ', {})).toBeUndefined(); + expect(resolveAuthToken(undefined, { GITNEXUS_MCP_AUTH_TOKEN: '' })).toBeUndefined(); + expect(resolveAuthToken(undefined, { GITNEXUS_MCP_AUTH_TOKEN: ' ' })).toBeUndefined(); + }); + + it('returns undefined when neither is set, and trims a real token', () => { + expect(resolveAuthToken(undefined, {})).toBeUndefined(); + expect(resolveAuthToken(' tok ', {})).toBe('tok'); + }); +}); + // ─── shutdown signal wiring (U7) ───────────────────────────────────── describe('shutdown exit codes (U7)', () => { From 24069984db36afd676e85a6f1291309b0dd306e9 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:11:43 +0000 Subject: [PATCH 13/17] fix(mcp-http): refuse to start on a non-loopback bind without a token MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Binding a non-loopback host (--host 0.0.0.0/:: or a specific interface) without authentication only logged a warning — which is easy to miss in JSON-log mode — while the file header claimed --auth-token was "required". Make it true: throw before binding when no token is set and the host is non-loopback, and have mcpCommand translate the error to a clear exit(1). Loopback binds remain open by default; the GITNEXUS_MCP_AUTH_TOKEN env var (U9) is the escape hatch for an intentional remote bind. Help text and the file header updated to match. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/cli/i18n/en.ts | 2 +- gitnexus/src/cli/i18n/zh-CN.ts | 2 +- gitnexus/src/cli/index.ts | 2 +- gitnexus/src/cli/mcp.ts | 18 +++++++++---- gitnexus/src/mcp/http-transport.ts | 18 +++++++------ gitnexus/test/unit/mcp-http-transport.test.ts | 25 +++++++++++++++++++ 6 files changed, 51 insertions(+), 16 deletions(-) diff --git a/gitnexus/src/cli/i18n/en.ts b/gitnexus/src/cli/i18n/en.ts index 2a5e61556a..9bbf3f4289 100644 --- a/gitnexus/src/cli/i18n/en.ts +++ b/gitnexus/src/cli/i18n/en.ts @@ -204,7 +204,7 @@ export const en = { 'help.option.mcp.host': 'HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.', 'help.option.mcp.authToken': - 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. If omitted, no auth (warns on non-loopback bind).', + 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.', 'help.option.force.confirmation': 'Skip confirmation prompt', 'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)', 'help.option.clean.all': 'Clean all indexed repos', diff --git a/gitnexus/src/cli/i18n/zh-CN.ts b/gitnexus/src/cli/i18n/zh-CN.ts index 0395a7a90a..15dcf22291 100644 --- a/gitnexus/src/cli/i18n/zh-CN.ts +++ b/gitnexus/src/cli/i18n/zh-CN.ts @@ -192,7 +192,7 @@ export const zhCN = { 'help.option.mcp.host': 'HTTP 绑定地址（仅与 --http 搭配使用）。默认：127.0.0.1（回环）。使用 0.0.0.0 向所有接口开放。', 'help.option.mcp.authToken': - '要求 Authorization 头携带此 Bearer Token（仅与 --http 搭配使用）；也可通过 GITNEXUS_MCP_AUTH_TOKEN 环境变量设置。省略则无鉴权（非回环绑定时会输出警告）。', + '要求 Authorization 头携带此 Bearer Token（仅与 --http 搭配使用）；也可通过 GITNEXUS_MCP_AUTH_TOKEN 环境变量设置。非回环绑定（--host 0.0.0.0/::）时必填，否则拒绝启动。', 'help.option.force.confirmation': '跳过确认提示', 'help.option.uninstall.force': '应用更改（默认仅为预演预览）', 'help.option.clean.all': '清理所有已索引仓库', diff --git a/gitnexus/src/cli/index.ts b/gitnexus/src/cli/index.ts index fa3896a2af..f3f329ed29 100644 --- a/gitnexus/src/cli/index.ts +++ b/gitnexus/src/cli/index.ts @@ -155,7 +155,7 @@ program ) .option( '--auth-token ', - 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. If omitted, no auth (warns on non-loopback bind).', + 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.', ) .action(createLbugLazyAction(() => import('./mcp.js'), 'mcpCommand')); diff --git a/gitnexus/src/cli/mcp.ts b/gitnexus/src/cli/mcp.ts index 6177bcdf3a..8b191db1d4 100644 --- a/gitnexus/src/cli/mcp.ts +++ b/gitnexus/src/cli/mcp.ts @@ -100,11 +100,19 @@ export const mcpCommand = async (options?: { } // Dynamic import keeps express/cors out of mcp.ts's static graph (stdio sentinel). const { startMcpHttpServer, resolveAuthToken } = await import('../mcp/http-transport.js'); - await startMcpHttpServer(backend, { - port, - host: options.host ?? '127.0.0.1', - authToken: resolveAuthToken(options.authToken, process.env), - }); + try { + await startMcpHttpServer(backend, { + port, + host: options.host ?? '127.0.0.1', + authToken: resolveAuthToken(options.authToken, process.env), + }); + } catch (err) { + logger.error( + { err: err instanceof Error ? err.message : err }, + 'Failed to start the MCP HTTP server', + ); + process.exit(1); + } return; } diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 24ad54f242..211d987e33 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -15,7 +15,7 @@ * Security considerations: * - Default binds to 127.0.0.1 (loopback only). * - Use --auth-token to enable Bearer Token authentication. - * - Use --host 0.0.0.0 to expose to all interfaces (requires --auth-token; warns otherwise). + * - Use --host 0.0.0.0 to expose to all interfaces (requires --auth-token — refuses to start otherwise). * - CORS is restricted to loopback origins when no auth token is configured. * - PNA (Private Network Access) header is emitted only in response to browser preflight requests. */ @@ -442,13 +442,15 @@ export async function startMcpHttpServer( ): Promise { const { port, host, authToken } = options; - // Warn when binding to a non-loopback address without auth protection. - if (!authToken && host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') { - logger.warn( - { host, port }, - 'GitNexus MCP HTTP server is binding to a non-loopback address WITHOUT --auth-token. ' + - 'Anyone who can reach this host can query your indexed repos. ' + - 'Pass --auth-token or bind --host 127.0.0.1.', + // Refuse to start an unauthenticated server on a non-loopback interface — that + // would silently expose every indexed repo to anyone who can reach the host. + // Loopback binds stay open by default; non-loopback binds require a token. + if (!authToken && !isLoopbackHost(host)) { + throw new Error( + `Refusing to start the MCP HTTP server on a non-loopback host (${host}) without ` + + 'authentication — it would expose all indexed repos to anyone who can reach it. ' + + 'Pass --auth-token (or set GITNEXUS_MCP_AUTH_TOKEN), or bind --host 127.0.0.1. ' + + 'This applies to --host 0.0.0.0 and --host :: as well.', ); } diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index 37229f4129..4609e12029 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -26,6 +26,7 @@ import { isLoopbackOrigin, computeAllowedHosts, resolveAuthToken, + startMcpHttpServer, } from '../../src/mcp/http-transport.js'; import { createMCPServer, installSignalShutdown, SHUTDOWN_EXIT_CODES } from '../../src/mcp/server.js'; import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; @@ -293,6 +294,30 @@ describe('startMcpHttpServer', () => { expect(get.headers['access-control-allow-private-network']).toBeUndefined(); }); + it('U8: refuses to start on a non-loopback host without a token', async () => { + const backend = createMockBackend(); + await expect( + startMcpHttpServer(backend as never, { host: '0.0.0.0', port: 0 }), + ).rejects.toThrow(/non-loopback/i); + await expect( + startMcpHttpServer(backend as never, { host: '::', port: 0 }), + ).rejects.toThrow(/non-loopback/i); + await expect( + startMcpHttpServer(backend as never, { host: '192.168.1.50', port: 0 }), + ).rejects.toThrow(); + }); + + it('U8: starts on a non-loopback host when a token is provided', async () => { + const backend = createMockBackend(); + const server = await startMcpHttpServer(backend as never, { + host: '0.0.0.0', + port: 0, + authToken: 'tok', + }); + servers.push({ server, cleanup: async () => {} }); + expect(server.listening).toBe(true); + }); + it('U6: rejects a POST /mcp carrying a disallowed Host header (DNS-rebinding protection)', async () => { const { port, server, cleanup } = await startOnFreePort(); // 127.0.0.1 → protection ON servers.push({ server, cleanup }); From aafa6f0b009b038deda6ab26da164c655bf35e1e Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:12:55 +0000 Subject: [PATCH 14/17] refactor(mcp-http): gate new sessions with the SDK isInitializeRequest The new-session path used a brittle `body.method === 'initialize'` string check, which rejected a single-element JSON-RPC batch initialize that the SDK itself accepts. Use the SDK's isInitializeRequest over the (array-normalized) body so a 1-element batch is recognised, while non-initialize requests still get the 400. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 8 ++- gitnexus/test/unit/mcp-http-transport.test.ts | 54 +++++++++++++++++-- 2 files changed, 57 insertions(+), 5 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 211d987e33..639686b20c 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -27,6 +27,7 @@ import cors from 'cors'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'; import { createMCPServer, installSignalShutdown } from './server.js'; import type { LocalBackend } from './local/local-backend.js'; import { logger } from '../core/logger.js'; @@ -240,8 +241,11 @@ export function createStreamableHttpHandler( } else if (req.method === 'POST') { // No session ID — new client. Only accept initialize requests to avoid // orphaned Server instances that can never be reclaimed by the TTL sweep. - const body = req.body as Record | undefined; - if (body?.method !== 'initialize') { + // Use the SDK's isInitializeRequest so a single-element JSON-RPC batch is + // recognised too, rather than a brittle `body.method === 'initialize'` check. + const body = req.body as unknown; + const messages = Array.isArray(body) ? body : [body]; + if (!messages.some(isInitializeRequest)) { res.status(400).json({ jsonrpc: '2.0', error: { diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index 4609e12029..44e4e91926 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -77,6 +77,20 @@ async function waitFor(predicate: () => boolean, timeoutMs = 500): Promise } } +/** A schema-complete JSON-RPC initialize request (passes the SDK isInitializeRequest). */ +function validInitialize(id = 1): Record { + return { + jsonrpc: '2.0', + method: 'initialize', + id, + params: { + protocolVersion: '2025-03-26', + capabilities: {}, + clientInfo: { name: 'test', version: '1.0.0' }, + }, + }; +} + // ─── Mock backend factory ────────────────────────────────────────────── function createMockBackend(overrides: Record = {}): unknown { @@ -331,7 +345,7 @@ describe('startMcpHttpServer', () => { Accept: 'application/json, text/event-stream', Host: 'evil.example.com:1234', }, - JSON.stringify({ jsonrpc: '2.0', method: 'initialize', id: 1, params: {} }), + JSON.stringify(validInitialize()), ); expect(res.status).toBe(403); @@ -369,7 +383,7 @@ describe('createStreamableHttpHandler', () => { const req = { headers: {}, method: 'POST', - body: { jsonrpc: '2.0', method: 'initialize', id: 1, params: {} }, + body: validInitialize(), } as Request; const res = { @@ -487,7 +501,7 @@ describe('createStreamableHttpHandler', () => { 'POST', '/mcp', { 'Content-Type': 'application/json', Accept: 'application/json' }, - JSON.stringify({ jsonrpc: '2.0', method: 'initialize', id: 1, params: {} }), + JSON.stringify(validInitialize()), ); expect(res.status).toBe(406); @@ -497,6 +511,40 @@ describe('createStreamableHttpHandler', () => { await close(); await cleanup(); }); + + it('U10: treats a single-element JSON-RPC batch initialize as initialize (no 400)', async () => { + const backend = createMockBackend(); + const { handler, cleanup } = createStreamableHttpHandler(backend as never); + const req = { + headers: {}, + method: 'POST', + body: [validInitialize()], + } as unknown as Request; + const res = createMockRes(); + // Past the init gate, the SDK transport runs against the mock res and may throw; + // we only assert the gate did NOT short-circuit with a 400. + try { + await handler(req, res); + } catch { + /* SDK write on the mock res */ + } + expect(res._status).not.toBe(400); + await cleanup(); + }); + + it('U10: a non-initialize JSON-RPC batch still returns 400', async () => { + const backend = createMockBackend(); + const { handler, cleanup } = createStreamableHttpHandler(backend as never); + const req = { + headers: {}, + method: 'POST', + body: [{ jsonrpc: '2.0', method: 'tools/list', id: 2, params: {} }], + } as unknown as Request; + const res = createMockRes(); + await handler(req, res); + expect(res._status).toBe(400); + await cleanup(); + }); }); // ─── createSseHandlers ──────────────────────────────────────────────── From f36ef488947bb20be6dd94feac6edc9b6ec6fac0 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:15:37 +0000 Subject: [PATCH 15/17] refactor(mcp-http): drop the unreachable post-`has` null check In the existing-session branch, `sessions.has(sessionId)` has just returned true and the map is not mutated before `sessions.get`, so the `if (!session)` 500 branch was dead. Use the non-null lookup (as the pre-refactor code did) and remove the unreachable branch. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 639686b20c..4078e7ac96 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -222,13 +222,9 @@ export function createStreamableHttpHandler( if (sessionId && sessions.has(sessionId)) { // Existing session — delegate to its transport and refresh activity timestamp. - const session = sessions.get(sessionId); - if (!session) { - res - .status(500) - .json({ jsonrpc: '2.0', error: { code: -32000, message: 'Internal error' }, id: null }); - return; - } + // `has` just returned true and the map is not mutated before `get`, so the + // lookup is non-null. + const session = sessions.get(sessionId)!; session.lastActivity = Date.now(); await session.transport.handleRequest(req, res, req.body); } else if (sessionId) { From 17df715a8f5404dd280848b718a740db32044dda Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Sat, 13 Jun 2026 08:17:17 +0000 Subject: [PATCH 16/17] refactor(mcp-http): extract a shared idle-session sweep helper Both transport factories carried a copy-pasted setInterval TTL-sweep + unref block (and a slightly divergent cleanup). Extract startIdleSweep(sessions, ttl, interval) used by both, and normalize the SSE cleanup to the streamable Promise.allSettled form. Adds a fake-timer test asserting an idle session is closed and evicted while a fresh one is kept. Co-Authored-By: Claude Opus 4.8 (1M context) --- gitnexus/src/mcp/http-transport.ts | 67 +++++++++---------- gitnexus/test/unit/mcp-http-transport.test.ts | 34 ++++++++++ 2 files changed, 66 insertions(+), 35 deletions(-) diff --git a/gitnexus/src/mcp/http-transport.ts b/gitnexus/src/mcp/http-transport.ts index 4078e7ac96..265ffa59ab 100644 --- a/gitnexus/src/mcp/http-transport.ts +++ b/gitnexus/src/mcp/http-transport.ts @@ -181,6 +181,33 @@ function dnsRebindingOptions( return allowedHosts ? { enableDnsRebindingProtection: true, allowedHosts } : {}; } +/** + * Starts a periodic sweep that closes and evicts sessions idle longer than + * `ttlMs`, returning the (unref'd) timer. Shared by both transport factories to + * guard against network drops where the per-session onclose never fires. + */ +export function startIdleSweep( + sessions: Map, + ttlMs: number, + intervalMs: number, +): NodeJS.Timeout { + const timer = setInterval(() => { + const now = Date.now(); + for (const [id, session] of sessions) { + if (now - session.lastActivity > ttlMs) { + try { + session.server.close(); + } catch {} + sessions.delete(id); + } + } + }, intervalMs); + if (timer && typeof timer === 'object' && 'unref' in timer) { + (timer as NodeJS.Timeout).unref(); + } + return timer; +} + /** * Creates a reusable StreamableHTTP request handler. * @@ -200,22 +227,7 @@ export function createStreamableHttpHandler( // DNS-rebinding protection (Host-header allowlist) when the bind host is known. const dnsRebinding = dnsRebindingOptions(opts.host, opts.port); const sessions = new Map(); - - // Periodically evict idle sessions (guard against network drops where onclose never fires). - const cleanupTimer = setInterval(() => { - const now = Date.now(); - for (const [id, session] of sessions) { - if (now - session.lastActivity > SESSION_TTL_MS) { - try { - session.server.close(); - } catch {} - sessions.delete(id); - } - } - }, CLEANUP_INTERVAL_MS); - if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) { - (cleanupTimer as NodeJS.Timeout).unref(); - } + const cleanupTimer = startIdleSweep(sessions, SESSION_TTL_MS, CLEANUP_INTERVAL_MS); const handler = async (req: Request, res: Response): Promise => { const sessionId = req.headers['mcp-session-id'] as string | undefined; @@ -335,23 +347,7 @@ export function createSseHandlers( // DNS-rebinding protection (Host-header allowlist) when the bind host is known. const dnsRebinding = dnsRebindingOptions(opts.host, opts.port); const sseSessions = new Map(); - - // Periodically evict stale SSE sessions — mirrors the streamable handler's sweep. - // Guards against network drops where the socket 'close' event never fires. - const cleanupTimer = setInterval(() => { - const now = Date.now(); - for (const [id, session] of sseSessions) { - if (now - session.lastActivity > SESSION_TTL_MS) { - try { - session.server.close(); - } catch {} - sseSessions.delete(id); - } - } - }, CLEANUP_INTERVAL_MS); - if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) { - (cleanupTimer as NodeJS.Timeout).unref(); - } + const cleanupTimer = startIdleSweep(sseSessions, SESSION_TTL_MS, CLEANUP_INTERVAL_MS); const sseHandler = async (req: Request, res: Response): Promise => { // Cap concurrent SSE sessions — mirrors the streamable handler's MAX_SESSIONS @@ -412,12 +408,13 @@ export function createSseHandlers( const cleanup = async (): Promise => { clearInterval(cleanupTimer); - for (const { server } of sseSessions.values()) { + const closers = [...sseSessions.values()].map(async ({ server }) => { try { await Promise.resolve(server.close()); } catch {} - } + }); sseSessions.clear(); + await Promise.allSettled(closers); }; return { sseHandler, messageHandler, cleanup }; diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index 44e4e91926..d329a7738b 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -27,6 +27,7 @@ import { computeAllowedHosts, resolveAuthToken, startMcpHttpServer, + startIdleSweep, } from '../../src/mcp/http-transport.js'; import { createMCPServer, installSignalShutdown, SHUTDOWN_EXIT_CODES } from '../../src/mcp/server.js'; import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; @@ -710,6 +711,39 @@ describe('isLoopbackOrigin', () => { }); }); +// ─── startIdleSweep (U12) ──────────────────────────────────────────── + +describe('startIdleSweep', () => { + it('closes and evicts sessions idle beyond the TTL, keeping fresh ones', () => { + vi.useFakeTimers(); + try { + const ttlMs = 30 * 60 * 1000; + const intervalMs = 5 * 60 * 1000; + const now = Date.now(); + const closed: string[] = []; + const make = (id: string, lastActivity: number) => ({ + server: { close: () => closed.push(id) } as unknown as ReturnType, + lastActivity, + }); + const map = new Map([ + ['stale', make('stale', now - 60 * 60 * 1000)], + ['fresh', make('fresh', now)], + ]); + + const timer = startIdleSweep(map, ttlMs, intervalMs); + vi.advanceTimersByTime(intervalMs + 1); + + expect(map.has('stale')).toBe(false); + expect(map.has('fresh')).toBe(true); + expect(closed).toEqual(['stale']); + + clearInterval(timer); + } finally { + vi.useRealTimers(); + } + }); +}); + // ─── resolveAuthToken (U9) ─────────────────────────────────────────── describe('resolveAuthToken', () => { From c76f3b4579b11780e740912c22961e464ce67be2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 13 Jun 2026 08:24:27 +0000 Subject: [PATCH 17/17] chore(autofix): apply prettier + eslint fixes via /autofix command --- gitnexus/test/unit/mcp-http-transport.test.ts | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/gitnexus/test/unit/mcp-http-transport.test.ts b/gitnexus/test/unit/mcp-http-transport.test.ts index d329a7738b..105caff2ac 100644 --- a/gitnexus/test/unit/mcp-http-transport.test.ts +++ b/gitnexus/test/unit/mcp-http-transport.test.ts @@ -29,7 +29,11 @@ import { startMcpHttpServer, startIdleSweep, } from '../../src/mcp/http-transport.js'; -import { createMCPServer, installSignalShutdown, SHUTDOWN_EXIT_CODES } from '../../src/mcp/server.js'; +import { + createMCPServer, + installSignalShutdown, + SHUTDOWN_EXIT_CODES, +} from '../../src/mcp/server.js'; import { mountMCPEndpoints } from '../../src/server/mcp-http.js'; // ─── Live-HTTP helpers (real req/res for SDK-touching paths) ─────────── @@ -314,9 +318,9 @@ describe('startMcpHttpServer', () => { await expect( startMcpHttpServer(backend as never, { host: '0.0.0.0', port: 0 }), ).rejects.toThrow(/non-loopback/i); - await expect( - startMcpHttpServer(backend as never, { host: '::', port: 0 }), - ).rejects.toThrow(/non-loopback/i); + await expect(startMcpHttpServer(backend as never, { host: '::', port: 0 })).rejects.toThrow( + /non-loopback/i, + ); await expect( startMcpHttpServer(backend as never, { host: '192.168.1.50', port: 0 }), ).rejects.toThrow();