claude-ex 1.4.1 → 1.5.1

package/README.md

@@ -15,6 +15,14 @@ claude-ex init
 
 That's it. Open Claude Code — the MCP server starts automatically and gives Claude structural awareness of your entire codebase.
 
+For Codex, register it during init:
+
+```bash
+claude-ex init --codex
+```
+
+That also writes a marker-safe `AGENTS.md` snippet and runs `codex mcp add claude-ex -- claude-ex mcp --no-watch /path/to/project`.
+
 ## How It Works
 
 1. **Indexes** your codebase using tree-sitter (functions, classes, methods, imports, call graphs)
@@ -195,6 +203,8 @@ In Claude Code, type:
 | `get_dependencies` | What a symbol depends on | <3ms |
 | `get_file_map` | Every file and its exports | <5ms |
 | `get_file_symbols` | All symbols in a file | <3ms |
+| `get_file_context` | Best context around files: symbols, imports, importers, callers, related files | <30ms |
+| `get_task_context` | One-shot AI context pack from task/query to symbols, files, and related context | <50ms |
 | `find_files` | Find files by glob pattern | <3ms |
 | `find_by_kind` | All classes, interfaces, enums, etc. | <5ms |
 | `get_type_hierarchy` | Subclasses/implementors | <3ms |
@@ -209,6 +219,7 @@ In Claude Code, type:
 
 ```
 claude-ex init [path]                  Index + install config + generate docs
+claude-ex init [path] --codex          Also register the MCP server with Codex + write AGENTS.md
 claude-ex transparent-review [target]  Zero-black-box review (before/after code, English, blast radius)
 claude-ex review [target]              Graph-aware diff review (structured JSON)
 claude-ex search <query>               Search symbols
@@ -223,7 +234,7 @@ claude-ex brief                        Project summary (SessionStart hook)
 claude-ex pre-edit <file>              Pre-edit context (PreToolUse hook)
 claude-ex post-edit <file>             Post-edit reindex (PostToolUse hook)
 claude-ex generate-docs                Regenerate CLAUDE.md
-claude-ex mcp                          Run as MCP server
+claude-ex mcp [path] [--no-watch]      Run as MCP server
 claude-ex uninstall                    Remove all config
 ```
 

package/dist/claude/installer.d.ts

@@ -1,3 +1,11 @@
+import { type SpawnSyncReturns } from 'child_process';
+type CommandRunner = (command: string, args: string[], options: {
+    cwd: string;
+    encoding: BufferEncoding;
+}) => SpawnSyncReturns<string>;
 export declare function install(rootDir: string, options?: {
     work?: boolean;
+    codex?: boolean;
+    commandRunner?: CommandRunner;
 }): void;
+export {};

package/dist/claude/installer.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.install = install;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
 const SKILL_CONTENT = `---
 name: claude-ex
 description: >
@@ -192,8 +193,44 @@ For each changed file with symbols:
 - Overall assessment: approve, request changes, or needs discussion
 - Prioritized list of action items if any
 `;
+const AGENTS_MARKER_START = '<!-- claude-ex:agents:start -->';
+const AGENTS_MARKER_END = '<!-- claude-ex:agents:end -->';
+const AGENTS_CONTENT = `${AGENTS_MARKER_START}
+# claude-ex
+
+Use the \`claude-ex\` MCP server for structural codebase tasks before falling back to broad text search.
+
+Prefer MCP for:
+- symbol search and code discovery
+- callers, dependents, dependencies, and type hierarchy
+- architecture, file maps, and package usage
+- graph-aware diff review
+
+Use the following tools when they match the task:
+- \`search_code\`
+- \`get_symbol\`
+- \`get_callers\`
+- \`get_dependents\`
+- \`get_dependencies\`
+- \`get_architecture\`
+- \`get_file_map\`
+- \`find_files\`
+- \`get_file_symbols\`
+- \`get_file_context\`
+- \`get_task_context\`
+- \`find_by_kind\`
+- \`get_type_hierarchy\`
+- \`find_dead_exports\`
+- \`get_pkg_usages\`
+- \`review_diff\`
+- \`transparent_review\`
+
+Use grep/ripgrep for plain text and regex-only searches like TODOs, exact literals, or log lines.
+${AGENTS_MARKER_END}
+`;
 function install(rootDir, options) {
     const work = options?.work ?? false;
+    const codex = options?.codex ?? false;
     if (work) {
         // Work mode: data goes in .local/.codex/, config stays at root but is gitignored
         const codexDir = path.join(rootDir, '.local', '.codex');
@@ -203,6 +240,8 @@ function install(rootDir, options) {
         addToGitignore(rootDir, '.local/');
         addToGitignore(rootDir, '.claude/');
         addToGitignore(rootDir, '.mcp.json');
+        if (codex)
+            addToGitignore(rootDir, 'AGENTS.md');
     }
     else {
         // Normal mode: .codex/ at root
@@ -219,6 +258,10 @@ function install(rootDir, options) {
     // 4. Create skill files
     installSkill(rootDir);
     installReviewSkill(rootDir);
+    if (codex) {
+        installAgentsMd(rootDir);
+        installCodexMcp(rootDir, options?.commandRunner ?? child_process_1.spawnSync);
+    }
 }
 function addToGitignore(rootDir, entry) {
     const gitignorePath = path.join(rootDir, '.gitignore');
@@ -247,7 +290,7 @@ function installMcpConfig(rootDir) {
     config.mcpServers.codex = {
         type: 'stdio',
         command: 'claude-ex',
-        args: ['mcp'],
+        args: ['mcp', rootDir],
     };
     fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n');
 }
@@ -334,4 +377,53 @@ function installReviewSkill(rootDir) {
     fs.mkdirSync(skillDir, { recursive: true });
     fs.writeFileSync(path.join(skillDir, 'SKILL.md'), REVIEW_SKILL_CONTENT);
 }
+function installAgentsMd(rootDir) {
+    const agentsPath = path.join(rootDir, 'AGENTS.md');
+    let updated = AGENTS_CONTENT;
+    if (fs.existsSync(agentsPath)) {
+        const existing = fs.readFileSync(agentsPath, 'utf-8');
+        const start = existing.indexOf(AGENTS_MARKER_START);
+        const end = existing.indexOf(AGENTS_MARKER_END);
+        if (start !== -1 && end !== -1 && end > start) {
+            updated = existing.slice(0, start) + AGENTS_CONTENT + existing.slice(end + AGENTS_MARKER_END.length);
+        }
+        else if (!existing.includes(AGENTS_MARKER_START)) {
+            updated = existing.trimEnd() + '\n\n' + AGENTS_CONTENT + '\n';
+        }
+        else {
+            updated = existing;
+        }
+    }
+    if (!fs.existsSync(agentsPath) || fs.readFileSync(agentsPath, 'utf-8') !== updated) {
+        fs.writeFileSync(agentsPath, updated);
+    }
+}
+function installCodexMcp(rootDir, commandRunner) {
+    const addArgs = ['mcp', 'add', 'claude-ex', '--', 'claude-ex', 'mcp', '--no-watch', rootDir];
+    const existing = commandRunner('codex', ['mcp', 'get', 'claude-ex'], {
+        cwd: rootDir,
+        encoding: 'utf-8',
+    });
+    if (existing.status === 0) {
+        const current = `${existing.stdout || ''}\n${existing.stderr || ''}`;
+        if (current.includes(rootDir))
+            return;
+        const remove = commandRunner('codex', ['mcp', 'remove', 'claude-ex'], {
+            cwd: rootDir,
+            encoding: 'utf-8',
+        });
+        if (remove.status !== 0) {
+            const detail = (remove.stderr || remove.stdout || remove.error?.message || 'unknown error').trim();
+            throw new Error(`Failed to update existing Codex MCP server: ${detail}`);
+        }
+    }
+    const result = commandRunner('codex', addArgs, {
+        cwd: rootDir,
+        encoding: 'utf-8',
+    });
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || result.error?.message || 'unknown error').trim();
+        throw new Error(`Failed to register Codex MCP server: ${detail}`);
+    }
+}
 //# sourceMappingURL=installer.js.map

package/dist/claude/installer.js.map

@@ -1 +1 @@
-{"version":3,"file":"installer.js","sourceRoot":"","sources":["../../src/claude/installer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"installer.js","sourceRoot":"","sources":["../../src/claude/installer.ts"],"names":[],"mappings":"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"}

package/dist/claude/mcp.d.ts

@@ -1 +1,3 @@
-export declare function runMcpServer(): Promise<void>;
+export declare function runMcpServer(pathArg?: string, options?: {
+    watch?: boolean;
+}): Promise<void>;

package/dist/claude/mcp.js

@@ -1,16 +1,155 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runMcpServer = runMcpServer;
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const schema_1 = require("../db/schema");
 const utils_1 = require("../utils");
 const daemon_1 = require("../watcher/daemon");
 const engine_1 = require("../query/engine");
 const indexer_1 = require("../indexer");
-async function runMcpServer() {
-    const rootDir = (0, utils_1.findProjectRoot)() || process.env.CODEX_ROOT || process.cwd();
+const collector_1 = require("../indexer/collector");
+const parser_1 = require("../indexer/parser");
+function resolveMcpRoot(pathArg) {
+    const explicitRoot = pathArg || process.env.CLAUDE_EX_ROOT || process.env.CODEX_ROOT;
+    if (explicitRoot) {
+        const resolved = path.resolve(explicitRoot);
+        return (0, utils_1.findProjectRoot)(resolved) || resolved;
+    }
+    return (0, utils_1.findProjectRoot)() || process.cwd();
+}
+function normalizeFileArg(rootDir, fileArg) {
+    if (typeof fileArg !== 'string')
+        return '';
+    let filePath = fileArg.trim();
+    if (filePath.startsWith('file://')) {
+        try {
+            filePath = new URL(filePath).pathname;
+        }
+        catch {
+            // Keep the original value and let normal path handling deal with it.
+        }
+    }
+    filePath = filePath.replace(/\\/g, '/');
+    const relPath = path.isAbsolute(filePath)
+        ? path.relative(rootDir, filePath)
+        : filePath;
+    return path.normalize(relPath).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function normalizeFileList(rootDir, fileArgs) {
+    const values = Array.isArray(fileArgs) ? fileArgs : [fileArgs];
+    return [...new Set(values
+            .map(file => normalizeFileArg(rootDir, file))
+            .filter(Boolean))];
+}
+function resolveInsideRoot(rootDir, relPath) {
+    if (!relPath || relPath === '.')
+        return null;
+    const fullPath = path.resolve(rootDir, relPath);
+    const relative = path.relative(rootDir, fullPath);
+    if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative))
+        return null;
+    return fullPath;
+}
+function fileExists(rootDir, relPath) {
+    const fullPath = resolveInsideRoot(rootDir, relPath);
+    return !!fullPath && fs.existsSync(fullPath);
+}
+function readLiveFileSymbols(rootDir, relPath) {
+    const fullPath = resolveInsideRoot(rootDir, relPath);
+    if (!fullPath)
+        return [];
+    try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        return (0, parser_1.parseFile)(relPath, content).symbols.map(sym => ({
+            name: sym.name,
+            qualifiedName: sym.qualifiedName ?? null,
+            kind: sym.kind,
+            lineStart: sym.lineStart,
+            lineEnd: sym.lineEnd,
+            signature: sym.signature ?? null,
+            exported: !!sym.exported,
+            parameters: sym.parameters ? JSON.stringify(sym.parameters) : null,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function hasIndexableCode(rootDir) {
+    return (0, collector_1.collectFiles)(rootDir).some(file => {
+        const language = (0, parser_1.getLanguage)(file);
+        return !!language && !['json', 'css', 'html'].includes(language);
+    });
+}
+function needsIndexRecovery(rootDir, stats) {
+    if (stats.files === 0)
+        return (0, collector_1.collectFiles)(rootDir).length > 0;
+    if (stats.symbols === 0)
+        return hasIndexableCode(rootDir);
+    return false;
+}
+function latestSourceMtime(rootDir, files) {
+    let latest = 0;
+    for (const file of files) {
+        try {
+            const mtime = fs.statSync(path.join(rootDir, file)).mtimeMs;
+            if (mtime > latest)
+                latest = mtime;
+        }
+        catch {
+            // Ignore files that disappeared between collection and stat.
+        }
+    }
+    return latest;
+}
+function indexLooksStale(rootDir, db, stats) {
+    const files = (0, collector_1.collectFiles)(rootDir);
+    if (files.length !== stats.files)
+        return true;
+    if (files.length === 0)
+        return false;
+    const indexed = db.prepare('SELECT COALESCE(MAX(last_modified), 0) as latest FROM files').get();
+    return latestSourceMtime(rootDir, files) > indexed.latest + 1;
+}
+async function runMcpServer(pathArg, options) {
+    const rootDir = resolveMcpRoot(pathArg);
     const startTime = performance.now();
     // Open database (stays open for lifetime)
     let db;
@@ -22,22 +161,62 @@ async function runMcpServer() {
         process.stderr.write(`[codex-mcp] Run 'claude-ex init' first.\n`);
         process.exit(1);
     }
-    // Start file watcher inside MCP server process
     let watcher;
-    try {
-        watcher = await (0, daemon_1.startWatcher)(rootDir, db, (file) => {
-            process.stderr.write(`[codex-mcp] reindexed: ${file}\n`);
-        });
-    }
-    catch (err) {
-        process.stderr.write(`[codex-mcp] Watcher failed to start: ${err}\n`);
-    }
+    let shuttingDown = false;
+    let recoveryPromise = null;
+    let lastFreshnessCheck = 0;
     // Pre-warm statement cache + SQLite page cache
     try {
         (0, engine_1.getStats)(db);
         (0, engine_1.search)(db, 'a', 1);
     }
     catch { /* warm-up, ignore errors */ }
+    function scheduleIndexRecovery(reason) {
+        if (!recoveryPromise) {
+            recoveryPromise = Promise.resolve().then(() => {
+                const start = performance.now();
+                process.stderr.write(`[codex-mcp] rebuilding index (${reason})...\n`);
+                const stats = (0, indexer_1.indexProject)(rootDir);
+                const elapsed = (performance.now() - start).toFixed(0);
+                process.stderr.write(`[codex-mcp] rebuilt index in ${elapsed}ms (${stats.totalFiles} files, ${stats.symbols} symbols)\n`);
+            }).finally(() => {
+                recoveryPromise = null;
+            });
+        }
+        return recoveryPromise;
+    }
+    async function ensureIndexReady() {
+        if (recoveryPromise) {
+            await recoveryPromise;
+            return;
+        }
+        try {
+            const stats = (0, engine_1.getStats)(db);
+            if (needsIndexRecovery(rootDir, stats)) {
+                await scheduleIndexRecovery('empty index');
+                return;
+            }
+            const now = performance.now();
+            if (now - lastFreshnessCheck > 5000) {
+                lastFreshnessCheck = now;
+                if (indexLooksStale(rootDir, db, stats)) {
+                    await scheduleIndexRecovery('stale index');
+                }
+            }
+        }
+        catch (err) {
+            await scheduleIndexRecovery(`stats failed: ${err.message}`);
+        }
+    }
+    try {
+        const stats = (0, engine_1.getStats)(db);
+        if (needsIndexRecovery(rootDir, stats)) {
+            void scheduleIndexRecovery('startup empty index');
+        }
+    }
+    catch {
+        void scheduleIndexRecovery('startup stats failed');
+    }
     const server = new index_js_1.Server({ name: 'claude-ex', version: '1.0.0' }, { capabilities: { tools: {} } });
     // Memoized tool list (allocated once, not per request)
     const TOOL_LIST = [
@@ -139,6 +318,44 @@ async function runMcpServer() {
                 required: ['file'],
             },
         },
+        {
+            name: 'get_file_context',
+            description: 'Build the best structural context around one or more files: key symbols, exports, imports, importers, packages, callers, transitive dependents, and ranked related files. Use before editing or reviewing files.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    files: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'File paths relative to project root, or absolute paths',
+                    },
+                    maxSymbols: { type: 'number', description: 'Max symbols per file (default 30)' },
+                    maxRelated: { type: 'number', description: 'Max related files to return (default 20)' },
+                    includeCode: { type: 'boolean', description: 'Include stored symbol code snippets for top symbols (default false)' },
+                },
+                required: ['files'],
+            },
+        },
+        {
+            name: 'get_task_context',
+            description: 'One-shot AI context builder. Given a task or symbol query plus optional files, returns ranked symbols, matched files, selected file context, dependency/importer/caller context, and related files in one MCP call.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Natural-language task, symbol name, or file-ish query' },
+                    files: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Optional files to pin into the context first',
+                    },
+                    maxSymbols: { type: 'number', description: 'Max symbol matches and per-file symbols (default 12)' },
+                    maxFiles: { type: 'number', description: 'Max selected files (default 8)' },
+                    maxRelated: { type: 'number', description: 'Max related files (default 12)' },
+                    includeCode: { type: 'boolean', description: 'Include stored symbol code snippets (default false)' },
+                },
+                required: ['query'],
+            },
+        },
         {
             name: 'find_by_kind',
             description: 'Find all symbols of a specific kind (class, function, interface, type, enum, method, variable). Ranked by structural importance.',
@@ -222,6 +439,7 @@ async function runMcpServer() {
         const callStart = performance.now();
         try {
             let result;
+            await ensureIndexReady();
             switch (name) {
                 case 'search_code':
                     result = (0, engine_1.search)(db, args.query, args.limit);
@@ -236,7 +454,7 @@ async function runMcpServer() {
                     result = (0, engine_1.getCallers)(db, args.name);
                     break;
                 case 'get_dependents':
-                    result = (0, engine_1.getImpact)(db, args.file, args.maxDepth);
+                    result = (0, engine_1.getImpact)(db, normalizeFileArg(rootDir, args.file), args.maxDepth);
                     break;
                 case 'get_dependencies':
                     result = (0, engine_1.getDeps)(db, args.name);
@@ -255,7 +473,48 @@ async function runMcpServer() {
                     result = (0, engine_1.findFiles)(db, args.pattern, args.limit);
                     break;
                 case 'get_file_symbols':
-                    result = (0, engine_1.getFileSymbols)(db, args.file);
+                    {
+                        const file = normalizeFileArg(rootDir, args.file);
+                        if (fileExists(rootDir, file)) {
+                            (0, indexer_1.reindexFile)(rootDir, file, db);
+                        }
+                        result = (0, engine_1.getFileSymbols)(db, file);
+                        if (result.length === 0 && fileExists(rootDir, file)) {
+                            result = readLiveFileSymbols(rootDir, file);
+                        }
+                    }
+                    break;
+                case 'get_file_context':
+                    {
+                        const files = normalizeFileList(rootDir, args.files);
+                        for (const file of files) {
+                            if (fileExists(rootDir, file)) {
+                                (0, indexer_1.reindexFile)(rootDir, file, db);
+                            }
+                        }
+                        result = (0, engine_1.getFileContext)(db, files, {
+                            maxSymbols: args.maxSymbols,
+                            maxRelated: args.maxRelated,
+                            includeCode: !!args.includeCode,
+                        });
+                    }
+                    break;
+                case 'get_task_context':
+                    {
+                        const files = normalizeFileList(rootDir, args.files ?? []);
+                        for (const file of files) {
+                            if (fileExists(rootDir, file)) {
+                                (0, indexer_1.reindexFile)(rootDir, file, db);
+                            }
+                        }
+                        result = (0, engine_1.getTaskContext)(db, args.query, {
+                            files,
+                            maxSymbols: args.maxSymbols,
+                            maxFiles: args.maxFiles,
+                            maxRelated: args.maxRelated,
+                            includeCode: !!args.includeCode,
+                        });
+                    }
                     break;
                 case 'find_by_kind':
                     result = (0, engine_1.findByKind)(db, args.kind, args.limit);
@@ -271,7 +530,7 @@ async function runMcpServer() {
                     break;
                 case 'reindex_file': {
                     const fileStart = performance.now();
-                    (0, indexer_1.reindexFile)(rootDir, args.file, db);
+                    (0, indexer_1.reindexFile)(rootDir, normalizeFileArg(rootDir, args.file), db, { force: true });
                     result = { success: true, timeMs: +(performance.now() - fileStart).toFixed(1) };
                     break;
                 }
@@ -313,8 +572,25 @@ async function runMcpServer() {
     // Connect stdio transport
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
+    const watchEnabled = options?.watch ?? process.env.CLAUDE_EX_WATCH !== '0';
+    if (watchEnabled) {
+        (0, daemon_1.startWatcher)(rootDir, db, (file) => {
+            process.stderr.write(`[codex-mcp] reindexed: ${file}\n`);
+        }).then((startedWatcher) => {
+            if (shuttingDown) {
+                startedWatcher.close();
+                return;
+            }
+            watcher = startedWatcher;
+        }).catch((err) => {
+            process.stderr.write(`[codex-mcp] Watcher failed to start: ${err}\n`);
+        });
+    }
     // Graceful shutdown
     const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
         process.stderr.write('[codex-mcp] Shutting down...\n');
         if (watcher)
             watcher.close();
@@ -323,5 +599,13 @@ async function runMcpServer() {
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    // A stdio MCP server is owned by its client (e.g. Claude Code). If the
+    // client goes away without sending a signal, the OS reparents us to launchd
+    // and we keep running forever — each orphan holding a chokidar watcher that
+    // slowly leaks file descriptors until the system file table is exhausted.
+    // Exit as soon as the transport or stdin closes so orphans can't accumulate.
+    transport.onclose = shutdown;
+    process.stdin.on('end', shutdown);
+    process.stdin.on('close', shutdown);
 }
 //# sourceMappingURL=mcp.js.map