sentinel-ir-mcp 0.4.0 → 0.4.1

package/README.md

@@ -25,6 +25,32 @@ of safety. Other languages are not supported yet. What is detected in Python
 (and what is not) is listed in the
 [sentinel-ir README](https://gitlab.com/jakubrojicek11/sentinel-ir#python).
 
+**0.4.1** uses `sentinel-ir` 0.4.3:
+
+- **Faster on large JavaScript:** a valid 1 MiB file takes about 5 s instead
+  of about 170 s, so `analyze_directory` no longer runs past the 60 s request
+  timeout of MCP SDK clients on one big file.
+- **Read-time check:** files are opened first and then checked, so a file
+  swapped for a symlink between listing and reading is refused instead of read
+  from outside the allowed folders. A file removed during a scan no longer
+  fails the whole scan; it is listed in `skipped.unreadable`. Files with more
+  than one hard link are refused (`skipped.hardlinks`).
+- **Finite limits:** `--max-file-bytes` is capped at 2 MiB. Valid JavaScript
+  with `sentinel-ir` 0.4.3:
+
+  | size | Linux | Windows CI (Node 20/22/24) |
+  |---|---|---|
+  | 1 MiB | 4–5 s, 0.9 GB | 13–23 s, 0.8 GB |
+  | 2 MiB | 10–14 s, 1.6 GB | 29–40 s, 1.5 GB |
+  | 4 MiB | 25–29 s, 3 GB | process aborts |
+
+  A file above 2 MiB can take longer than the 60 s request timeout on its own.
+- **Time budget:** `analyze_directory` starts no new file after 30 s
+  (`--time-budget-ms`). Then `timedOut` is `true` and the remaining files are
+  listed in `notAnalyzed`. A file already being analyzed is not interrupted.
+- **Parser errors:** incomplete files carry `facts.parseError` with the line,
+  column and kind of the first parser error (from `sentinel-ir` 0.4.3).
+
 **0.4.0** uses `sentinel-ir` 0.4.2:
 
 - **Native code:** `ctypes` / `cffi`, `process.dlopen`, `*.node` addons and
@@ -231,9 +257,10 @@ if the client offers them; if it offers none, only `analyze_code` works.
 ### Options
 
 ```text
-sentinel-ir-mcp [--max-file-bytes <n>] [--max-files <n>] [folder ...]
+sentinel-ir-mcp [--max-file-bytes <n>] [--max-files <n>] [--time-budget-ms <n>] [folder ...]
 
-  --max-file-bytes <n>   largest file to analyze (default 1048576 = 1 MiB)
+  --max-file-bytes <n>   largest file to analyze (default 1048576 = 1 MiB, max 2097152 = 2 MiB)
+  --time-budget-ms <n>   analyze_directory starts no new file after this (default 30000, max 600000)
   --max-files <n>        default file limit for analyze_directory (default 50, max 500)
 ```
 
@@ -248,7 +275,15 @@ sentinel-ir-mcp [--max-file-bytes <n>] [--max-files <n>] [folder ...]
   or, without folder arguments, inside one of the client's MCP roots. `../`,
   absolute paths elsewhere and symlinks pointing outside are refused.
 - **`analyze_directory`** skips `node_modules`, `.git`, hidden folders and
-  every symlink, and stops after `max_files` files (`truncated: true`).
+  every symlink, and stops after `max_files` files (`truncated: true`) or
+  when the time budget is spent (`timedOut: true`, rest in `notAnalyzed`).
+  Each file is checked again when it is opened: it must still be a regular
+  file inside the allowed folders.
+- **Hard links are refused.** A hard link inside the folder can point to a
+  file outside it, and the other names of a file cannot be found. So files
+  with more than one hard link are refused (`analyze_file` error,
+  `skipped.hardlinks` in `analyze_directory`). This also refuses harmless hard
+  links, e.g. pnpm's in `node_modules`.
 - **The IR is still untrusted text.** Comments, string bodies and function
   bodies are not copied into it, so instructions hidden there do not reach the
   agent through the IR. It does contain identifiers and some literals from the

package/bin/sentinel-ir-mcp.js

@@ -23,7 +23,8 @@ Usage: sentinel-ir-mcp [options] [folder ...]
                          command must be written as ./setup, ./doctor or ./guide. Without folders the
                          server uses the MCP roots offered by the client; if the
                          client offers none, only analyze_code works.
-  --max-file-bytes <n>   Largest file to analyze (default ${DEFAULT_LIMITS.maxFileBytes})
+  --max-file-bytes <n>   Largest file to analyze (default ${DEFAULT_LIMITS.maxFileBytes}, max ${DEFAULT_LIMITS.hardMaxFileBytes})
+  --time-budget-ms <n>   analyze_directory starts no new file after this time (default ${DEFAULT_LIMITS.timeBudgetMs}, max ${DEFAULT_LIMITS.hardMaxTimeBudgetMs})
   --max-files <n>        Default file limit for analyze_directory (default ${DEFAULT_LIMITS.maxFiles}, max ${DEFAULT_LIMITS.hardMaxFiles})
   -h, --help             Show this help
   -v, --version          Show the version
@@ -36,6 +37,12 @@ function die(message) {
     process.exit(2);
 }
 
+const NUMBER_OPTIONS = {
+    "--max-file-bytes": ["maxFileBytes", DEFAULT_LIMITS.hardMaxFileBytes],
+    "--max-files": ["maxFiles", DEFAULT_LIMITS.hardMaxFiles],
+    "--time-budget-ms": ["timeBudgetMs", DEFAULT_LIMITS.hardMaxTimeBudgetMs]
+};
+
 function parseArgs(argv) {
     const opts = { roots: [] };
     for (let i = 0; i < argv.length; i++) {
@@ -44,12 +51,12 @@ function parseArgs(argv) {
         if (arg.startsWith("--") && arg.includes("=")) [arg, value] = [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)];
         if (arg === "-h" || arg === "--help") { process.stdout.write(USAGE + "\n"); process.exit(0); }
         if (arg === "-v" || arg === "--version") { process.stdout.write(version + "\n"); process.exit(0); }
-        if (arg === "--max-file-bytes" || arg === "--max-files") {
+        if (Object.hasOwn(NUMBER_OPTIONS, arg)) {
+            const [key, max] = NUMBER_OPTIONS[arg];
             if (value === undefined) value = argv[++i];
             const n = Number(value);
-            const max = arg === "--max-files" ? DEFAULT_LIMITS.hardMaxFiles : Number.MAX_SAFE_INTEGER;
             if (!Number.isInteger(n) || n < 1 || n > max) die(`${arg} must be an integer between 1 and ${max}`);
-            opts[arg === "--max-files" ? "maxFiles" : "maxFileBytes"] = n;
+            opts[key] = n;
         } else if (arg.startsWith("-")) {
             die(`unknown option ${arg}`);
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinel-ir-mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "MCP server for sentinel-ir: lets AI agents (Claude Desktop, Cursor, Windsurf, ...) read a compact structural IR of JavaScript, TypeScript and Python files instead of the raw source. Read-only, sandboxed to allowed folders.",
   "main": "src/server.js",
   "bin": {
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "sentinel-ir": "^0.4.2",
+    "sentinel-ir": "^0.4.3",
     "zod": "^4.1.0"
   },
   "keywords": [

package/src/analyze.js

@@ -1,9 +1,64 @@
 "use strict";
 
 const fs = require("fs/promises");
+const { constants, realpathSync } = require("fs");
 const path = require("path");
 const { analyzeAsync, compress } = require("sentinel-ir");
-const { AccessError, resolveInside, isSourceFile } = require("./paths");
+const { AccessError, resolveInside, isInside, isSourceFile } = require("./paths");
+
+// O_NONBLOCK: opening a FIFO swapped in after listing must not block the
+// server forever. Neither flag exists on Windows; the inode check covers that.
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0);
+
+class TooLargeError extends AccessError {}
+class HardlinkError extends AccessError {}
+
+// Reads the file that is actually opened, not the one checked earlier: the
+// path may be swapped for a symlink between the check and the read. The open
+// handle must be a regular file whose inode is the one now found at a real
+// path inside the allowed folders, and at most maxFileBytes are read.
+async function readInside(full, roots, maxFileBytes, label) {
+    let handle;
+    try {
+        handle = await fs.open(full, OPEN_FLAGS);
+    } catch (err) {
+        if (err && err.code === "ELOOP") throw new AccessError(`Access denied: ${label} is a symlink`);
+        throw err;
+    }
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile()) throw new AccessError(`Not a file: ${label}`);
+        if (opened.size > BigInt(maxFileBytes)) {
+            throw new TooLargeError(`File too large: ${label} is ${opened.size} bytes, limit is ${maxFileBytes}`);
+        }
+        // Same realpath as resolveInside: on Windows fs.promises.realpath
+        // expands 8.3 short names (GITLAB~1) and would never match the roots.
+        const real = realpathSync(full);
+        const current = await fs.stat(real, { bigint: true });
+        if (!roots.some((r) => isInside(real, r)) || current.dev !== opened.dev || current.ino !== opened.ino) {
+            throw new AccessError(`Access denied: ${label} changed while it was being read`);
+        }
+        // Another name of the same file may lie outside the allowed folders,
+        // and where it lies cannot be found out, so such files are refused.
+        // Both counts: the handle's alone can read 1 while the path is swapped.
+        const links = opened.nlink > current.nlink ? opened.nlink : current.nlink;
+        if (links > 1n) {
+            throw new HardlinkError(`Access denied: ${label} has ${links} hard links; files with more than one are refused`);
+        }
+        const buffer = Buffer.alloc(Number(opened.size) + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+            if (!bytesRead) break;
+            length += bytesRead;
+        }
+        if (length > maxFileBytes) throw new TooLargeError(`File too large: ${label} grew past the limit of ${maxFileBytes} bytes`);
+        if (length === buffer.length) throw new AccessError(`Access denied: ${label} changed while it was being read`);
+        return buffer.toString("utf8", 0, length);
+    } finally {
+        await handle.close();
+    }
+}
 
 const SKIP_DIRS = new Set(["node_modules", ".git", "__pycache__", "venv", "site-packages"]);
 const RISK_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
@@ -26,7 +81,7 @@ async function analyzeFile(requested, roots, { maxFileBytes }) {
     if (stat.size > maxFileBytes) {
         throw new AccessError(`File too large: ${requested} is ${stat.size} bytes, limit is ${maxFileBytes}`);
     }
-    const code = await fs.readFile(real, "utf8");
+    const code = await readInside(real, roots, maxFileBytes, requested);
     return analyzeCode(code, display);
 }
 
@@ -34,12 +89,20 @@ async function analyzeFile(requested, roots, { maxFileBytes }) {
 // __pycache__, venv, site-packages and hidden folders are skipped.
 async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive }) {
     const files = [];
-    const skipped = { tooLarge: [], symlinks: 0, unreadable: [] };
+    const skipped = { tooLarge: [], symlinks: 0, unreadable: [], hardlinks: [] };
     let truncated = false;
     const queue = [dir];
     while (queue.length && !truncated) {
         const current = queue.shift();
-        const entries = (await fs.readdir(current, { withFileTypes: true }))
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        } catch {
+            // Removed or made unreadable while the scan runs.
+            skipped.unreadable.push(path.relative(root, current).split(path.sep).join("/") || ".");
+            continue;
+        }
+        entries = entries
             .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
         for (const entry of entries) {
             const full = path.join(current, entry.name);
@@ -49,7 +112,13 @@ async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive }) {
             } else if (entry.isDirectory()) {
                 if (recursive && !SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) queue.push(full);
             } else if (entry.isFile() && isSourceFile(entry.name)) {
-                const { size } = await fs.stat(full);
+                let size;
+                try {
+                    ({ size } = await fs.lstat(full));
+                } catch {
+                    skipped.unreadable.push(rel);
+                    continue;
+                }
                 if (size > maxFileBytes) {
                     skipped.tooLarge.push(rel);
                 } else if (files.length >= maxFiles) {
@@ -64,20 +133,30 @@ async function collectFiles(dir, root, { maxFiles, maxFileBytes, recursive }) {
     return { files, skipped, truncated };
 }
 
-async function analyzeDirectory(requested, roots, { maxFiles, maxFileBytes, recursive = true }) {
+async function analyzeDirectory(requested, roots, { maxFiles, maxFileBytes, recursive = true, timeBudgetMs = Infinity }) {
+    const started = Date.now();
     const { real, root, display } = resolveInside(requested, roots);
     const stat = await fs.stat(real);
     if (!stat.isDirectory()) throw new AccessError(`Not a folder: ${requested}`);
 
     const { files, skipped, truncated } = await collectFiles(real, root, { maxFiles, maxFileBytes, recursive });
     const results = [];
+    const notAnalyzed = [];
     for (const { full, rel } of files) {
+        // A running analysis cannot be interrupted, so the budget only stops
+        // new files from starting; the rest are listed in notAnalyzed.
+        if (notAnalyzed.length || Date.now() - started >= timeBudgetMs) {
+            notAnalyzed.push(rel);
+            continue;
+        }
         // One file that cannot be read or analyzed must not hide the others.
         let ir;
         try {
-            ir = await analyzeCode(await fs.readFile(full, "utf8"), rel);
-        } catch {
-            skipped.unreadable.push(rel);
+            ir = await analyzeCode(await readInside(full, [root], maxFileBytes, rel), rel);
+        } catch (err) {
+            const list = err instanceof TooLargeError ? skipped.tooLarge
+                : err instanceof HardlinkError ? skipped.hardlinks : skipped.unreadable;
+            list.push(rel);
             continue;
         }
         results.push({
@@ -107,6 +186,8 @@ async function analyzeDirectory(requested, roots, { maxFiles, maxFileBytes, recu
         analyzed: results.length,
         truncated,
         maxFiles,
+        timedOut: notAnalyzed.length > 0,
+        notAnalyzed,
         skipped,
         riskCounts,
         statusCounts,
@@ -115,4 +196,4 @@ async function analyzeDirectory(requested, roots, { maxFiles, maxFileBytes, recu
     };
 }
 
-module.exports = { analyzeCode, analyzeFile, analyzeDirectory, SKIP_DIRS };
+module.exports = { analyzeCode, analyzeFile, analyzeDirectory, readInside, SKIP_DIRS };

package/src/doctor.js

@@ -10,7 +10,7 @@ const { readConfig } = require("./setup");
 
 const BIN = path.join(__dirname, "..", "bin", "sentinel-ir-mcp.js");
 const EXPECTED_TOOLS = ["analyze_code", "analyze_directory", "analyze_file"];
-const VALUE_OPTIONS = new Set(["--max-file-bytes", "--max-files"]);
+const VALUE_OPTIONS = new Set(["--max-file-bytes", "--max-files", "--time-budget-ms"]);
 
 function irVersion() {
     try {

package/src/guide.js

@@ -8,9 +8,12 @@ env reads and network/filesystem/process/crypto calls. It reads files only.
 
 Recommended order:
 1. Call analyze_directory on the project (or a sub-folder) first.
-2. Look at "incomplete" and "skipped.unreadable" before anything else. Those
+2. Look at "incomplete", "skipped.unreadable" and "skipped.hardlinks" before
+   anything else. Those
    files were not fully analyzed: a low risk there is NOT evidence of safety.
-   Read their raw source if they matter.
+   Read their raw source if they matter. If "timedOut" is true, the files in
+   "notAnalyzed" were not analyzed at all: call analyze_directory on a
+   sub-folder or analyze_file for them.
 3. Pick the relevant files from "files" (sorted from highest to lowest risk).
 4. Call analyze_file for the full IR of a single file.
 5. Read raw source only for the files you actually need to change or verify.

package/src/server.js

@@ -8,6 +8,12 @@ const { analyzeCode, analyzeFile, analyzeDirectory } = require("./analyze");
 
 const DEFAULT_LIMITS = Object.freeze({
     maxFileBytes: 1024 * 1024,
+    // 4 MiB of JavaScript aborts the process on Windows CI (3 GB on Linux).
+    hardMaxFileBytes: 2 * 1024 * 1024,
+    // Plus one 1 MiB file (up to 23 s on Windows CI) stays below the 60 s
+    // request timeout of MCP SDK clients.
+    timeBudgetMs: 30000,
+    hardMaxTimeBudgetMs: 600000,
     maxFiles: 50,
     hardMaxFiles: 500
 });
@@ -30,7 +36,7 @@ const INSTRUCTIONS =
     "or risk, then read the raw source of the files that matter. Supported: JavaScript (.js, .mjs, .cjs), TypeScript (.ts, .mts, .cts, .tsx) and Python (.py, .pyi); the language is picked from the file extension. " +
     "Rely on analysisStatus, world.risk, forbidden and facts; analysisStatus \"incomplete\" means the file did not parse cleanly. " +
     "analyze_directory lists such files separately in 'incomplete'; their low risk is not evidence of safety. " +
-    "Suggested order: analyze_directory first, check 'incomplete' and 'skipped.unreadable', pick the relevant files, " +
+    "Suggested order: analyze_directory first, check 'incomplete', 'skipped.unreadable' and 'notAnalyzed' (set when the time budget ran out), pick the relevant files, " +
     "then analyze_file, and read raw source only where needed. " +
     "Read-only: nothing is written, executed or sent over the network. " + UNTRUSTED_NOTE;
 
@@ -56,8 +62,9 @@ async function guarded(fn) {
 
 function createServer(options = {}) {
     const limits = {
-        maxFileBytes: options.maxFileBytes ?? DEFAULT_LIMITS.maxFileBytes,
-        maxFiles: options.maxFiles ?? DEFAULT_LIMITS.maxFiles
+        maxFileBytes: Math.min(options.maxFileBytes ?? DEFAULT_LIMITS.maxFileBytes, DEFAULT_LIMITS.hardMaxFileBytes),
+        maxFiles: options.maxFiles ?? DEFAULT_LIMITS.maxFiles,
+        timeBudgetMs: Math.min(options.timeBudgetMs ?? DEFAULT_LIMITS.timeBudgetMs, DEFAULT_LIMITS.hardMaxTimeBudgetMs)
     };
     const fixedRoots = canonicalRoots(options.roots || []);
 
@@ -112,6 +119,9 @@ function createServer(options = {}) {
             "you when there were more. 'incomplete' lists files whose analysis did not finish (e.g. parse errors); " +
             "their risk is not reliable, check them separately. statusCounts counts complete vs incomplete. " +
             "Files that could not be read are listed in skipped.unreadable and are not counted as analyzed. " +
+            "Files with more than one hard link are refused and listed in skipped.hardlinks. " +
+            `No new file is started after ${limits.timeBudgetMs / 1000} s: then timedOut is true and the remaining files are in notAnalyzed; ` +
+            "call again on a subfolder or use analyze_file for them. " +
             "Use analyze_file for the full IR of a single file. " + UNTRUSTED_NOTE,
         inputSchema: {
             path: z.string().min(1).optional().describe("Folder path, absolute or relative to the first allowed folder (default: the first allowed folder)"),
@@ -124,6 +134,7 @@ function createServer(options = {}) {
         analyzeDirectory(path ?? ".", await allowedRoots(), {
             maxFiles: max_files ?? limits.maxFiles,
             maxFileBytes: limits.maxFileBytes,
+            timeBudgetMs: limits.timeBudgetMs,
             recursive: recursive ?? true
         })));