gitnexus 1.6.8-rc.24 → 1.6.8-rc.26

package/README.md

@@ -34,7 +34,7 @@ That's it. This indexes the codebase, installs agent skills, registers Claude Co
 
 To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
-`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once. To configure only selected integrations, pass `--coding-agent`/`-c` with a comma-separated list or repeat the option, for example `gitnexus setup -c cursor,codex`.
 
 ### Editor Support
 
@@ -158,7 +158,7 @@ Your AI agent gets these tools automatically:
 ## CLI Commands
 
 ```bash
-gitnexus setup                   # Configure MCP for your editors (one-time)
+gitnexus setup                   # Configure MCP for detected editors (one-time; use -c to select)
 gitnexus uninstall               # Preview removal of GitNexus MCP/skills/hooks (add --force to apply)
 gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data

package/dist/cli/help-i18n.js

@@ -42,6 +42,7 @@ const COMMAND_DESCRIPTION_KEYS = {
 };
 const OPTION_DESCRIPTION_KEYS = {
     '|-V, --version': 'help.option.version',
+    'setup|-c, --coding-agent <agents>': 'help.option.setup.codingAgent',
     'analyze|-f, --force': 'help.option.analyze.force',
     'analyze|--repair-fts': 'help.option.analyze.repairFts',
     'analyze|--embeddings [limit]': 'help.option.analyze.embeddings',
@@ -65,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";
@@ -138,6 +138,7 @@ export declare const en: {
     readonly 'help.command.group.impact.description': "Cross-repo impact for a symbol in one member repo of a group";
     readonly 'help.command.group.query.description': "Search execution flows across all repos in a group";
     readonly 'help.command.group.contracts.description': "Inspect Contract Registry";
+    readonly 'help.option.setup.codingAgent': "Configure only these coding agents (comma-separated or repeatable)";
     readonly 'help.option.analyze.force': "Force full re-index even if up to date";
     readonly 'help.option.analyze.repairFts': "Repair/rebuild search FTS indexes without full re-analysis";
     readonly 'help.option.analyze.embeddings': "Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.";
@@ -163,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',
@@ -138,6 +138,7 @@ export const en = {
     'help.command.group.impact.description': 'Cross-repo impact for a symbol in one member repo of a group',
     'help.command.group.query.description': 'Search execution flows across all repos in a group',
     'help.command.group.contracts.description': 'Inspect Contract Registry',
+    'help.option.setup.codingAgent': 'Configure only these coding agents (comma-separated or repeatable)',
     'help.option.analyze.force': 'Force full re-index even if up to date',
     'help.option.analyze.repairFts': 'Repair/rebuild search FTS indexes without full re-analysis',
     'help.option.analyze.embeddings': 'Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.',
@@ -163,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";
@@ -139,6 +139,7 @@ export declare const cliResources: {
         readonly 'help.command.group.impact.description': "Cross-repo impact for a symbol in one member repo of a group";
         readonly 'help.command.group.query.description': "Search execution flows across all repos in a group";
         readonly 'help.command.group.contracts.description': "Inspect Contract Registry";
+        readonly 'help.option.setup.codingAgent': "Configure only these coding agents (comma-separated or repeatable)";
         readonly 'help.option.analyze.force': "Force full re-index even if up to date";
         readonly 'help.option.analyze.repairFts': "Repair/rebuild search FTS indexes without full re-analysis";
         readonly 'help.option.analyze.embeddings': "Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.";
@@ -164,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";
@@ -365,6 +369,7 @@ export declare const cliResources: {
         'help.command.group.impact.description': string;
         'help.command.group.query.description': string;
         'help.command.group.contracts.description': string;
+        'help.option.setup.codingAgent': string;
         'help.option.analyze.force': string;
         'help.option.analyze.repairFts': string;
         'help.option.analyze.embeddings': string;
@@ -390,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

@@ -138,6 +138,7 @@ export declare const zhCN: {
     'help.command.group.impact.description': string;
     'help.command.group.query.description': string;
     'help.command.group.contracts.description': string;
+    'help.option.setup.codingAgent': string;
     'help.option.analyze.force': string;
     'help.option.analyze.repairFts': string;
     'help.option.analyze.embeddings': string;
@@ -163,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': '显示运行平台能力和嵌入配置',
@@ -138,6 +138,7 @@ export const zhCN = {
     'help.command.group.impact.description': '分析仓库组中某个成员仓库符号的跨仓库影响',
     'help.command.group.query.description': '跨仓库组所有仓库搜索执行流程',
     'help.command.group.contracts.description': '查看 Contract Registry',
+    'help.option.setup.codingAgent': '仅配置这些编码代理（逗号分隔或重复传入）',
     'help.option.analyze.force': '即使已是最新也强制完整重建索引',
     'help.option.analyze.repairFts': '修复/重建搜索 FTS 索引，不执行完整重新分析',
     'help.option.analyze.embeddings': '启用语义搜索的嵌入生成（默认关闭）。可选 [limit] 覆盖 50,000 节点安全上限；传 0 可完全禁用上限。',
@@ -163,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

@@ -10,10 +10,14 @@ import { t } from './i18n/index.js';
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
 const program = new Command();
+function collectCodingAgents(value, previous) {
+    return [...(previous ?? []), ...value.split(',')];
+}
 program.name('gitnexus').description('GitNexus local CLI and MCP server').version(pkg.version);
 program
     .command('setup')
     .description('One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, Codex')
+    .option('-c, --coding-agent <agents>', 'Configure only these coding agents (comma-separated or repeatable)', collectCodingAgents)
     .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
 program
     .command('uninstall')
@@ -75,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/cli/setup.d.ts

@@ -37,5 +37,7 @@ interface SetupResult {
  * install paths copy this same list from hooks/claude/ (the canonical source).
  */
 export declare function copyHookHelpers(srcDir: string, destDir: string, label: string, result: SetupResult): Promise<string[]>;
-export declare const setupCommand: () => Promise<void>;
+export declare const setupCommand: (options?: {
+    codingAgent?: string[] | string;
+}) => Promise<void>;
 export {};

package/dist/cli/setup.js

@@ -61,6 +61,33 @@ export function formatHookCommand(hookPath, isWindows = process.platform === 'wi
 // changes this literal, the guard records an actionable error instead of
 // silently shipping a hook with an unresolved relative cliPath.
 const CLI_PATH_SOURCE_LITERAL = "let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');";
+const CODING_AGENT_IDS = {
+    cursor: 'cursor',
+    claude: 'claude',
+    antigravity: 'antigravity',
+    opencode: 'opencode',
+    codex: 'codex',
+};
+const SUPPORTED_CODING_AGENTS = Object.values(CODING_AGENT_IDS);
+function selectedCodingAgents(values) {
+    if (values == null)
+        return new Set(SUPPORTED_CODING_AGENTS);
+    const rawValues = Array.isArray(values) ? values : [values];
+    const requested = rawValues
+        .flatMap((value) => value.split(','))
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean);
+    const invalid = requested.filter((value) => !SUPPORTED_CODING_AGENTS.includes(value));
+    if (requested.length === 0 || invalid.length > 0) {
+        const detail = requested.length === 0
+            ? 'No coding agents were provided.'
+            : `Unknown: ${invalid.join(', ')}.`;
+        process.stderr.write(`${detail} Valid values: ${SUPPORTED_CODING_AGENTS.join(', ')}.\n`);
+        process.exitCode = 1;
+        return null;
+    }
+    return new Set(requested);
+}
 /**
  * Resolve the absolute path to the `gitnexus` binary if it's installed
  * globally (or via npm -g / yarn global). Returns null when not found.
@@ -832,7 +859,11 @@ async function installCodexSkills(result) {
     }
 }
 // ─── Main command ──────────────────────────────────────────────────
-export const setupCommand = async () => {
+export const setupCommand = async (options) => {
+    const explicitSelection = options?.codingAgent != null;
+    const selected = selectedCodingAgents(options?.codingAgent);
+    if (!selected)
+        return;
     console.log('');
     console.log('  GitNexus Setup');
     console.log('  ==============');
@@ -846,19 +877,31 @@ export const setupCommand = async () => {
         errors: [],
     };
     // Detect and configure each editor's MCP
-    await setupCursor(result);
-    await setupClaudeCode(result);
-    await setupAntigravity(result);
-    await setupOpenCode(result);
-    await setupCodex(result);
+    if (selected.has('cursor'))
+        await setupCursor(result);
+    if (selected.has('claude'))
+        await setupClaudeCode(result);
+    if (selected.has('antigravity'))
+        await setupAntigravity(result);
+    if (selected.has('opencode'))
+        await setupOpenCode(result);
+    if (selected.has('codex'))
+        await setupCodex(result);
     // Install global skills for platforms that support them
-    await installClaudeCodeSkills(result);
-    await installClaudeCodeHooks(result);
-    await installAntigravitySkills(result);
-    await installAntigravityHooks(result);
-    await installCursorSkills(result);
-    await installOpenCodeSkills(result);
-    await installCodexSkills(result);
+    if (selected.has('claude')) {
+        await installClaudeCodeSkills(result);
+        await installClaudeCodeHooks(result);
+    }
+    if (selected.has('antigravity')) {
+        await installAntigravitySkills(result);
+        await installAntigravityHooks(result);
+    }
+    if (selected.has('cursor'))
+        await installCursorSkills(result);
+    if (selected.has('opencode'))
+        await installOpenCodeSkills(result);
+    if (selected.has('codex'))
+        await installCodexSkills(result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');
@@ -884,10 +927,17 @@ export const setupCommand = async () => {
     console.log('  Summary:');
     console.log(`    MCP configured for: ${result.configured.filter((c) => !c.includes('skills')).join(', ') || 'none'}`);
     console.log(`    Skills installed to: ${result.configured.filter((c) => c.includes('skills')).length > 0 ? result.configured.filter((c) => c.includes('skills')).join(', ') : 'none'}`);
+    const configurationSucceeded = result.configured.length > 0;
+    if (explicitSelection && !configurationSucceeded) {
+        process.stderr.write('None of the explicitly selected coding agents were configured.\n');
+        process.exitCode = 1;
+    }
     console.log('');
-    console.log('  Next steps:');
-    console.log('    1. cd into any git repo');
-    console.log('    2. Run: gitnexus analyze');
-    console.log('    3. Open the repo in your editor — MCP is ready!');
+    if (configurationSucceeded) {
+        console.log('  Next steps:');
+        console.log('    1. cd into any git repo');
+        console.log('    2. Run: gitnexus analyze');
+        console.log('    3. Open the repo in your editor — MCP is ready!');
+    }
     console.log('');
 };

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>;