gitnexus 1.6.8-rc.25 → 1.6.8-rc.26

package/dist/cli/help-i18n.js

@@ -66,6 +66,10 @@ const OPTION_DESCRIPTION_KEYS = {
     'analyze|--embedding-device <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 <port>': 'help.option.port',
+    'mcp|--host <host>': 'help.option.mcp.host',
+    'mcp|--auth-token <token>': 'help.option.mcp.authToken',
     'serve|-p, --port <port>': 'help.option.port',
     'serve|--host <host>': 'help.option.serve.host',
     'uninstall|-f, --force': 'help.option.uninstall.force',

package/dist/cli/i18n/en.d.ts

@@ -112,7 +112,7 @@ export declare const en: {
     readonly 'help.command.analyze.description': "Index a repository (full analysis)";
     readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
     readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
-    readonly 'help.command.mcp.description': "Start MCP server (stdio) — serves all indexed repos";
+    readonly '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).";
     readonly 'help.command.list.description': "List all indexed repositories";
     readonly 'help.command.status.description': "Show index status for current repo";
     readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
@@ -164,6 +164,9 @@ export declare const en: {
     readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
     readonly 'help.option.port': "Port number";
     readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
+    readonly 'help.option.mcp.http': "Serve MCP over HTTP instead of stdio (for remote clients)";
+    readonly '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.";
+    readonly '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. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.";
     readonly 'help.option.force.confirmation': "Skip confirmation prompt";
     readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
     readonly 'help.option.clean.all': "Clean all indexed repos";

package/dist/cli/i18n/en.js

@@ -112,7 +112,7 @@ export const en = {
     'help.command.analyze.description': 'Index a repository (full analysis)',
     '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': 'Show runtime platform capabilities and embedding configuration',
@@ -164,6 +164,9 @@ 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); 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',

package/dist/cli/i18n/resources.d.ts

@@ -113,7 +113,7 @@ export declare const cliResources: {
         readonly 'help.command.analyze.description': "Index a repository (full analysis)";
         readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
         readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
-        readonly 'help.command.mcp.description': "Start MCP server (stdio) — serves all indexed repos";
+        readonly '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).";
         readonly 'help.command.list.description': "List all indexed repositories";
         readonly 'help.command.status.description': "Show index status for current repo";
         readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
@@ -165,6 +165,9 @@ export declare const cliResources: {
         readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
         readonly 'help.option.port': "Port number";
         readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
+        readonly 'help.option.mcp.http': "Serve MCP over HTTP instead of stdio (for remote clients)";
+        readonly '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.";
+        readonly '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. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.";
         readonly 'help.option.force.confirmation': "Skip confirmation prompt";
         readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
         readonly 'help.option.clean.all': "Clean all indexed repos";
@@ -392,6 +395,9 @@ export declare const cliResources: {
         'help.option.index.allowNonGit': string;
         'help.option.port': string;
         'help.option.serve.host': string;
+        'help.option.mcp.http': string;
+        'help.option.mcp.host': string;
+        'help.option.mcp.authToken': string;
         'help.option.force.confirmation': string;
         'help.option.uninstall.force': string;
         'help.option.clean.all': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -164,6 +164,9 @@ export declare const zhCN: {
     'help.option.index.allowNonGit': string;
     'help.option.port': string;
     'help.option.serve.host': string;
+    'help.option.mcp.http': string;
+    'help.option.mcp.host': string;
+    'help.option.mcp.authToken': string;
     'help.option.force.confirmation': string;
     'help.option.uninstall.force': string;
     'help.option.clean.all': string;

package/dist/cli/i18n/zh-CN.js

@@ -112,7 +112,7 @@ 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': '显示运行平台能力和嵌入配置',
@@ -164,6 +164,9 @@ 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 搭配使用）；也可通过 GITNEXUS_MCP_AUTH_TOKEN 环境变量设置。非回环绑定（--host 0.0.0.0/::）时必填，否则拒绝启动。',
     'help.option.force.confirmation': '跳过确认提示',
     'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',

package/dist/cli/index.js

@@ -79,7 +79,12 @@ program
     .action(createLbugLazyAction(() => import('./serve.js'), 'serveCommand'));
 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 <port>', 'HTTP port (only with --http). Default: 3000', '3000')
+    .option('--host <host>', '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 <token>', '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'));
 program
     .command('list')

package/dist/cli/mcp.d.ts

@@ -26,4 +26,9 @@
  * `mcpCommand` after the sentinel install. The regression test at
  * `gitnexus/test/integration/mcp/import-closure.test.ts` enforces this.
  */
-export declare const mcpCommand: () => Promise<void>;
+export declare const mcpCommand: (options?: {
+    http?: boolean;
+    port?: string;
+    host?: string;
+    authToken?: string;
+}) => Promise<void>;

package/dist/cli/mcp.js

@@ -27,7 +27,7 @@
  * `gitnexus/test/integration/mcp/import-closure.test.ts` enforces this.
  */
 import { installGlobalStdoutSentinel } from '../mcp/stdio-context.js';
-export const mcpCommand = async () => {
+export const mcpCommand = async (options) => {
     // 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
@@ -68,6 +68,31 @@ export const mcpCommand = async () => {
     else {
         logger.info({ repoCount: repos.length, repos: repos.map((r) => r.name) }, 'GitNexus: MCP server starting');
     }
+    // Start HTTP server or fall back to stdio (default).
+    if (options?.http) {
+        // 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);
+        }
+        // Dynamic import keeps express/cors out of mcp.ts's static graph (stdio sentinel).
+        const { startMcpHttpServer, resolveAuthToken } = await import('../mcp/http-transport.js');
+        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;
+    }
     // Start MCP server (serves all repos, discovers new ones lazily)
     await startMCPServer(backend);
 };

package/dist/mcp/http-transport.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Dedicated MCP HTTP server.
+ *
+ * Provides HTTP-based MCP transport supporting:
+ * - Modern Streamable HTTP: POST /mcp
+ * - Legacy SSE transport: GET /sse + POST /messages
+ *
+ * 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.
+ * - 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.
+ */
+import type { Server as HttpServer } from 'http';
+import { type Request, type Response, type NextFunction } from 'express';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { LocalBackend } from './local/local-backend.js';
+/** HTTP server configuration options. */
+export interface McpHttpOptions {
+    /** Listening port. */
+    port: number;
+    /** Bind address (default: 127.0.0.1). */
+    host: string;
+    /** Bearer auth token (optional; no auth when omitted). */
+    authToken?: string;
+}
+/**
+ * Creates a Bearer Token authentication middleware.
+ *
+ * - When authToken is not set, all requests pass through.
+ * - When authToken is set, checks the Authorization: Bearer <token> header.
+ * - Uses constant-time comparison to prevent timing oracle attacks.
+ * - Returns a JSON-RPC formatted 401 on failure.
+ */
+export declare function createAuthMiddleware(authToken?: string): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * 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 declare function isLoopbackOrigin(origin: string | undefined): boolean;
+/** True for the exact loopback bind addresses. */
+export declare function isLoopbackHost(host: string): boolean;
+/** True for any-interface wildcard binds, whose externally-used Host is unknowable. */
+export declare function isWildcardHost(host: string): boolean;
+/**
+ * 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 declare function computeAllowedHosts(host: string, port: number): string[] | undefined;
+/**
+ * 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 declare function resolveAuthToken(optToken: string | undefined, env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * 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 declare function startIdleSweep<T extends {
+    server: Server;
+    lastActivity: number;
+}>(sessions: Map<string, T>, ttlMs: number, intervalMs: number): NodeJS.Timeout;
+/**
+ * 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 declare function createStreamableHttpHandler(backend: LocalBackend, opts?: {
+    createServer?: () => Server;
+    host?: string;
+    port?: number;
+}): {
+    handler: (req: Request, res: Response) => Promise<void>;
+    cleanup: () => Promise<void>;
+};
+/**
+ * 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 declare function createSseHandlers(backend: LocalBackend, messagesPath?: string, opts?: {
+    maxSessions?: number;
+    host?: string;
+    port?: number;
+}): {
+    sseHandler: (req: Request, res: Response) => Promise<void>;
+    messageHandler: (req: Request, res: Response) => Promise<void>;
+    cleanup: () => Promise<void>;
+};
+/**
+ * Creates and starts the dedicated MCP HTTP server.
+ *
+ * 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 instance
+ * @param options   Server configuration
+ * @returns         The listening http.Server
+ */
+export declare function startMcpHttpServer(backend: LocalBackend, options: McpHttpOptions): Promise<HttpServer>;