sentinel-ir-mcp 0.4.4 → 0.4.6

package/README.md

@@ -6,8 +6,10 @@ it lets AI agents in Claude Desktop, Cursor, Windsurf or any other
 compact **structural IR** of JavaScript, TypeScript and Python files instead of the raw source.
 
 - npm: <https://www.npmjs.com/package/sentinel-ir-mcp>
-- GitLab: <https://gitlab.com/jakubrojicek11/sentinel-ir-mcp>
-- Library behind it: <https://gitlab.com/jakubrojicek11/sentinel-ir>
+- GitLab (main repository): <https://gitlab.com/jakubrojicek11/sentinel-ir-mcp>
+- GitHub (mirror): <https://github.com/jakcmencz/sentinel-ir-mcp>
+- Library behind it: [`sentinel-ir`](https://github.com/jakcmencz/sentinel-ir)
+- See what the agent sees, in your browser: <https://sentinel-ir-playground-dc30c8.gitlab.io/>
 
 The IR tells the agent what a file *does* (risk level, dangerous
 capabilities such as `eval` or `child_process`, routes, exports, imports,
@@ -25,6 +27,15 @@ 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.6** is listed in the official
+[MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.jakcmencz/sentinel-ir-mcp`, so clients that browse the registry
+can find and install it. Nothing else changes.
+
+**0.4.5** adds to that log the SHA-256 of every file the server read, so you
+can check later which version of a file the agent was shown (see
+[Audit log](#audit-log)).
+
 **0.4.4** can keep a log of what the agent asked for (off unless you turn it on):
 
 - **One question in `setup`:** *"Keep a log of what the agent asks for (file
@@ -358,6 +369,16 @@ server through `cmd`). Then read it with `log --dir <folder>`.
   result (risk, `analysisStatus`, file counts, up to 20 `critical`/`high` file
   paths of a folder) or why it was refused (`excluded`, `outside`,
   `not-found`, `too-large`), and the duration. A line when the server starts.
+- **Which version of a file (0.4.5):** for every file the server read, the
+  SHA-256 of the exact bytes it analyzed: `sha256` for `analyze_file`; for
+  `analyze_directory` the folder line gets a `call` id and `hashed` count,
+  and the hashes follow in `"event": "hashes"` lines (40 files each, same
+  `call` id), so no line gets long. `log` shows the first 12 digits for
+  files and the risky files of a folder; `log --json` has all of them. To check whether a file is still the
+  one the agent saw, compare with `certutil -hashfile <file> SHA256`
+  (Windows), `shasum -a 256 <file>` (macOS) or `sha256sum <file>` (Linux).
+  Pasted code (`analyze_code`) gets no hash: a very short snippet could be
+  guessed from it. The tool answers to the agent are unchanged.
 - **What is not written:** source code. For `analyze_code` only the size in
   bytes, the language and the risk. Names of excluded files are not written
   either, only their count. Long values are cut to 300 characters.
@@ -489,8 +510,20 @@ starting the published package through `npx`, and the printed VS Code/Claude
 Code commands pasted into PowerShell 5.1, PowerShell 7 and cmd.exe. See
 [COMPATIBILITY.md](COMPATIBILITY.md).
 
-Release: bump `version` in `package.json`, push a protected tag `vX.Y.Z`;
-GitLab CI tests and publishes to npm with provenance.
+Release: bump `version` in `package.json` and both `version` fields in
+`server.json` (a test checks they match), push a protected tag `vX.Y.Z`;
+GitLab CI tests and publishes to npm with provenance. Then publish the same
+`server.json` to the MCP Registry: `mcp-publisher login github` and
+`mcp-publisher publish`.
+
+## Contributing
+
+Development, CI and npm releases run on
+[GitLab](https://gitlab.com/jakubrojicek11/sentinel-ir-mcp). The
+[GitHub repository](https://github.com/jakcmencz/sentinel-ir-mcp) is a mirror
+that GitLab updates on every push to `main` and every tag. Issues are welcome
+on either; a pull request opened on GitHub is applied on GitLab, and the mirror
+then brings it back.
 
 ## License
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "sentinel-ir-mcp",
-  "version": "0.4.4",
+  "version": "0.4.6",
+  "mcpName": "io.github.jakcmencz/sentinel-ir-mcp",
   "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": {

package/src/analyze.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const fs = require("fs/promises");
+const { createHash } = require("crypto");
 const { constants, realpathSync } = require("fs");
 const path = require("path");
 const { analyzeAsync, compress } = require("sentinel-ir");
@@ -35,7 +36,7 @@ function resolveAllowed(requested, roots, excluder) {
 // 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, excluder = NONE) {
+async function readInside(full, roots, maxFileBytes, label, excluder = NONE, onRead = null) {
     let handle;
     try {
         handle = await fs.open(full, OPEN_FLAGS);
@@ -73,6 +74,8 @@ async function readInside(full, roots, maxFileBytes, label, excluder = NONE) {
         }
         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`);
+        // The audit log records which bytes were read, never the bytes.
+        if (onRead) onRead(createHash("sha256").update(buffer.subarray(0, length)).digest("hex"));
         return buffer.toString("utf8", 0, length);
     } finally {
         await handle.close();
@@ -94,7 +97,7 @@ async function analyzeCode(code, target, language) {
     return compress(ir);
 }
 
-async function analyzeFile(requested, roots, { maxFileBytes, excluder = NONE }) {
+async function analyzeFile(requested, roots, { maxFileBytes, excluder = NONE, hashes = null }) {
     const { real, display } = resolveAllowed(requested, roots, excluder);
     const stat = await fs.stat(real);
     if (!stat.isFile()) throw new AccessError(`Not a file: ${requested}`);
@@ -104,7 +107,7 @@ async function analyzeFile(requested, roots, { maxFileBytes, excluder = NONE })
     if (stat.size > maxFileBytes) {
         throw new AccessError(`File too large: ${requested} is ${stat.size} bytes, limit is ${maxFileBytes}`);
     }
-    const code = await readInside(real, roots, maxFileBytes, requested, excluder);
+    const code = await readInside(real, roots, maxFileBytes, requested, excluder, hashes && ((h) => hashes.set(display, h)));
     return analyzeCode(code, display);
 }
 
@@ -221,7 +224,7 @@ function fullEntry(rel, ir) {
 async function analyzeDirectory(
     requested,
     roots,
-    { maxFiles, maxFileBytes, recursive = true, timeBudgetMs = Infinity, detail = "summary", excluder = NONE }
+    { maxFiles, maxFileBytes, recursive = true, timeBudgetMs = Infinity, detail = "summary", excluder = NONE, hashes = null }
 ) {
     const started = Date.now();
     const { real, root, display } = resolveAllowed(requested, roots, excluder);
@@ -241,7 +244,9 @@ async function analyzeDirectory(
         // One file that cannot be read or analyzed must not hide the others.
         let ir;
         try {
-            ir = await analyzeCode(await readInside(full, [root], maxFileBytes, rel, excluder), rel);
+            let hash = null;
+            ir = await analyzeCode(await readInside(full, [root], maxFileBytes, rel, excluder, hashes && ((h) => { hash = h; })), rel);
+            if (hash) hashes.set(rel, hash);
         } catch (err) {
             if (err instanceof ExcludedError) {
                 skipped.excluded++;

package/src/auditLog.js

@@ -1,5 +1,6 @@
 "use strict";
 
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 const { homeOf } = require("./clients");
@@ -17,6 +18,7 @@ const MAX_DAY_BYTES = 50 * 1024 * 1024;
 const DAY_RESERVE = 1024 * 1024;
 const MAX_TEXT = 300;
 const MAX_LISTED = 20;
+const HASHES_PER_LINE = 40;
 // Characters cmd.exe acts on: an MCP entry on Windows runs through "cmd /c".
 const UNSAFE_DIR = /["&|<>^%!\u0000-\u001f]/;
 const OPEN_FLAGS = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW || 0);
@@ -134,17 +136,41 @@ function describeCall(tool, args, outcome) {
         if (notRead) entry.notRead = notRead;
         if (r.truncated) entry.truncated = true;
         if (r.timedOut) entry.timedOut = true;
+        // sha256 of every analyzed file, so the user can check later which
+        // version of each file the agent was shown. splitHashes moves the
+        // full list to lines of its own.
+        const hashes = args.hashes instanceof Map ? args.hashes : new Map();
+        const withHash = (f) => (hashes.has(f.path) ? { sha256: hashes.get(f.path) } : {});
         const top = r.files.filter((f) => f.risk === "critical" || f.risk === "high").slice(0, MAX_LISTED);
-        if (top.length) entry.top = top.map((f) => ({ path: cut(f.path), risk: f.risk }));
+        if (top.length) entry.top = top.map((f) => ({ path: cut(f.path), risk: f.risk, ...withHash(f) }));
+        const files = r.files.filter((f) => hashes.has(f.path)).map((f) => ({ path: cut(f.path), risk: f.risk, ...withHash(f) }));
+        if (files.length) entry.files = files;
     } else {
         entry.risk = r.world && r.world.risk;
         entry.analysisStatus = r.analysisStatus;
         entry.language = r.language;
         if (tool === "analyze_file" && r.mission && typeof r.mission.target === "string") entry.file = cut(r.mission.target);
+        if (tool === "analyze_file" && args.hashes instanceof Map && args.hashes.size) entry.sha256 = [...args.hashes.values()][0];
     }
     return entry;
 }
 
+// A folder can have 500 files: their hashes go in follow-up lines of at most
+// HASHES_PER_LINE files (usually under 20 kB each, so DAY_RESERVE still holds and
+// one write stays one line), linked to the call by a random "call" id.
+function splitHashes(entry) {
+    if (!Array.isArray(entry.files)) return [entry];
+    const { files, ...main } = entry;
+    main.call = crypto.randomBytes(6).toString("hex");
+    main.hashed = files.length;
+    const parts = Math.ceil(files.length / HASHES_PER_LINE);
+    const more = [];
+    for (let i = 0; i < parts; i++) {
+        more.push({ event: "hashes", call: main.call, part: i + 1, parts, files: files.slice(i * HASHES_PER_LINE, (i + 1) * HASHES_PER_LINE) });
+    }
+    return [main, ...more];
+}
+
 function createAuditLog({ dir, now = () => Date.now(), onError = (m) => process.stderr.write(`sentinel-ir-mcp: ${m}\n`) } = {}) {
     if (!dir) return { active: false, record() {}, flush: async () => {} };
     let queue = Promise.resolve();
@@ -200,5 +226,5 @@ function createAuditLog({ dir, now = () => Date.now(), onError = (m) => process.
 
 module.exports = {
     AuditLogError, KEEP_DAYS, MAX_DAY_BYTES, FILE_RE,
-    defaultAuditDir, normalizeAuditDir, assertOutsideProjects, createAuditLog, describeCall, logFiles, dayName, cut
+    defaultAuditDir, normalizeAuditDir, assertOutsideProjects, createAuditLog, describeCall, splitHashes, HASHES_PER_LINE, logFiles, dayName, cut
 };

package/src/logView.js

@@ -38,6 +38,10 @@ function riskCounts(counts) {
     return parts.length ? ` (${parts.join(", ")})` : "";
 }
 
+const SHA256 = /^[0-9a-f]{64}$/;
+// The first 12 hex digits are enough to compare by eye; --json has all 64.
+function shortHash(h) { return typeof h === "string" && SHA256.test(h) ? ` sha256 ${h.slice(0, 12)}` : ""; }
+
 function describe(e) {
     if (e.event === "start") {
         const folders = Array.isArray(e.folders) && e.folders.length ? ` for ${e.folders.map(safe).join(", ")}` : "";
@@ -45,6 +49,7 @@ function describe(e) {
     }
     if (e.event === "check") return [`doctor checked that the log can be written`];
     if (e.event === "full") return [`the log for this day reached its size limit; nothing more is written today`];
+    if (typeof e.event === "string") return [`${safe(e.event).slice(0, 40)} (see log --json)`];
     const what = TOOL_WORDS[e.tool] ? TOOL_WORDS[e.tool] : safe(e.tool);
     const target = e.tool === "analyze_code" ? `${what} (${Number(e.bytes) || 0} bytes${e.language ? `, ${safe(e.language)}` : ""})` : `${what} ${safe(e.path)}`;
     if (e.ok === false) {
@@ -57,15 +62,17 @@ function describe(e) {
         if (Number(e.notRead) > 0) extra.push(`${Number(e.notRead)} not read (too large or unreadable)`);
         if (e.truncated) extra.push("stopped at the file limit");
         if (e.timedOut) extra.push("stopped at the time limit");
+        if (Number(e.hashed) > 0) extra.push(`sha256 of ${Number(e.hashed)} file(s) in log --json`);
         const lines = [`${target}: ${Number(e.analyzed) || 0} file(s)${riskCounts(e.riskCounts)}${extra.length ? `, ${extra.join(", ")}` : ""}`];
-        if (Array.isArray(e.top)) for (const f of e.top) lines.push(`    ${safe(f.risk).padEnd(8)} ${safe(f.path)}`);
+        if (Array.isArray(e.top)) for (const f of e.top) if (f) lines.push(`    ${safe(f.risk).padEnd(8)} ${safe(f.path)}${shortHash(f.sha256)}`);
         return lines;
     }
     const incomplete = e.analysisStatus && e.analysisStatus !== "complete" ? " (incomplete: broken code)" : "";
-    return [`${target}: ${safe(e.risk)}${incomplete}`];
+    return [`${target}: ${safe(e.risk)}${incomplete}${shortHash(e.sha256)}`];
 }
 
-function parseFile(file) {
+// Hash lines of a folder call are data for --json, not entries to read.
+function parseFile(file, { hashLines = true } = {}) {
     const entries = [];
     let damaged = 0;
     let text;
@@ -77,7 +84,9 @@ function parseFile(file) {
         if (line === "") continue;
         try {
             const e = JSON.parse(line);
-            if (e && typeof e === "object" && !Array.isArray(e) && (typeof e.tool === "string" || typeof e.event === "string")) entries.push(e);
+            if (e && typeof e === "object" && !Array.isArray(e) && (typeof e.tool === "string" || typeof e.event === "string")) {
+                if (hashLines || e.event !== "hashes") entries.push(e);
+            }
             else damaged++;
         } catch { damaged++; }
     }
@@ -113,7 +122,7 @@ function runLog(opts, io) {
     if (opts.json) io.stdout.write(`{\n  "folder": ${JSON.stringify(dir)},\n  "entries": [`);
     if (opts.all) {
         for (const file of files) {
-            const r = parseFile(file);
+            const r = parseFile(file, { hashLines: Boolean(opts.json) });
             damaged += r.damaged;
             for (const e of r.entries) emit(e);
             count += r.entries.length;
@@ -121,7 +130,7 @@ function runLog(opts, io) {
     } else {
         let recent = [];
         for (let i = files.length - 1; i >= 0 && recent.length < RECENT; i--) {
-            const r = parseFile(files[i]);
+            const r = parseFile(files[i], { hashLines: Boolean(opts.json) });
             damaged += r.damaged;
             recent = r.entries.concat(recent);
             if (recent.length >= RECENT && i > 0) more = true;

package/src/server.js

@@ -6,7 +6,7 @@ const { version } = require("../package.json");
 const { AccessError, canonicalRoots, rootsFromUris } = require("./paths");
 const { analyzeCode, analyzeFile, analyzeDirectory } = require("./analyze");
 const { createExcluder } = require("./exclude");
-const { createAuditLog, describeCall } = require("./auditLog");
+const { createAuditLog, describeCall, splitHashes } = require("./auditLog");
 
 const DEFAULT_LIMITS = Object.freeze({
     maxFileBytes: 1024 * 1024,
@@ -110,7 +110,9 @@ function createServer(options = {}) {
             try {
                 const info = server.server.getClientVersion();
                 const client = info && typeof info.name === "string" ? info.name.slice(0, 100) : undefined;
-                auditLog.record({ client, ...describeCall(tool, args, outcome), ms });
+                const [main, ...hashLines] = splitHashes({ client, ...describeCall(tool, args, outcome), ms });
+                auditLog.record(main);
+                for (const line of hashLines) auditLog.record(line);
             } catch { /* logging must never break a tool call */ }
         };
     }
@@ -153,7 +155,10 @@ function createServer(options = {}) {
             path: z.string().min(1).describe("File path, absolute or relative to the first allowed folder")
         },
         annotations: { title: "Analyze a JavaScript, TypeScript or Python file", ...READ_ONLY }
-    }, async ({ path }) => guarded(async () => analyzeFile(path, await allowedRoots(), { ...limits, excluder }), auditor("analyze_file", { path })));
+    }, async ({ path }) => {
+        const hashes = auditLog.active ? new Map() : null;
+        return guarded(async () => analyzeFile(path, await allowedRoots(), { ...limits, excluder, hashes }), auditor("analyze_file", { path, hashes }));
+    });
 
     server.registerTool("analyze_directory", {
         title: "Analyze a folder of JavaScript, TypeScript and Python files",
@@ -182,15 +187,18 @@ function createServer(options = {}) {
                 .describe("\"summary\" (default): short entries; \"full\": all facts per file, much larger")
         },
         annotations: { title: "Analyze a folder of JavaScript, TypeScript and Python files", ...READ_ONLY }
-    }, async ({ path, max_files, recursive, detail }) => guarded(async () =>
-        analyzeDirectory(path ?? ".", await allowedRoots(), {
+    }, async ({ path, max_files, recursive, detail }) => {
+        const hashes = auditLog.active ? new Map() : null;
+        return guarded(async () => analyzeDirectory(path ?? ".", await allowedRoots(), {
             maxFiles: max_files ?? limits.maxFiles,
             maxFileBytes: limits.maxFileBytes,
             timeBudgetMs: limits.timeBudgetMs,
             recursive: recursive ?? true,
             detail: detail ?? "summary",
-            excluder
-        }), auditor("analyze_directory", { path, max_files, recursive, detail })));
+            excluder,
+            hashes
+        }), auditor("analyze_directory", { path, max_files, recursive, detail, hashes }));
+    });
 
     server.auditLog = auditLog;
     return server;