@levnikolaevich/hex-line-mcp 1.13.0 → 1.14.0

package/README.md

@@ -9,6 +9,8 @@ Hash-verified file editing MCP + token efficiency hook for AI coding agents.
 
 Every line carries an FNV-1a content hash. Every edit must present those hashes back -- proving the agent is editing what it thinks it's editing. No stale context, no silent corruption. Hashing works on normalized logical text; writes preserve the file's existing line endings and trailing-newline shape.
 
+By default, mutating tools stay inside the current project root. If you intentionally need to edit a temp or external path, pass `allow_external: true` on `edit_file`, `write_file`, or `bulk_replace`.
+
 ## Features
 
 ### 9 MCP Tools
@@ -182,6 +184,7 @@ Edit using revision-aware hash-verified anchors. Prefer one batched call per fil
 | `restore_indent` | boolean | no | Auto-fix indentation to match anchor context (default: false) |
 | `base_revision` | string | no | Prior revision from `read_file` / `edit_file` for same-file follow-up edits |
 | `conflict_policy` | enum | no | `conservative` or `strict` (default: `conservative`) |
+| `allow_external` | boolean | no | Allow editing a path outside the current project root |
 
 Edit operations (JSON array):
 
@@ -227,6 +230,7 @@ Create a new file or overwrite an existing one. Creates parent directories autom
 |-----------|------|----------|-------------|
 | `path` | string | yes | File path |
 | `content` | string | yes | File content |
+| `allow_external` | boolean | no | Allow writing a path outside the current project root |
 
 ### grep_search
 
@@ -247,7 +251,7 @@ Search file contents using ripgrep. Three output modes: `content` (canonical `se
 | `context_before` | number | no | Context lines BEFORE match (`-B`) |
 | `context_after` | number | no | Context lines AFTER match (`-A`) |
 | `limit` | number | no | Max matches per file (default: 100) |
-| `total_limit` | number | no | Total match events across all files; multiline matches count as 1 (0 = unlimited) |
+| `total_limit` | number | no | Total match events across all files; multiline matches count as 1 (default: 200 for `content`, 1000 for `files`/`count`, 0 = unlimited) |
 | `plain` | boolean | no | Omit hash tags inside block entries, return `lineNum\|content` |
 
 `content` mode returns canonical `search_hunk` blocks with per-hunk checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.

package/dist/hook.mjs

@@ -439,7 +439,7 @@ function handleSessionStart() {
     } catch {
     }
   }
-  const msg = styleActive ? "Hex-line MCP available. Output style active.\n<hex-line_instructions>\n  <deferred_loading>If hex-line schemas not loaded, run: ToolSearch('+hex-line read edit')</deferred_loading>\n  <note>Follow the active hex-line output style for primary tool choices.</note>\n  <exceptions>Built-in tools stay OK for images, PDFs, notebooks, Glob, .claude/settings.json, and .claude/settings.local.json.</exceptions>\n</hex-line_instructions>" : "Hex-line MCP available.\n<hex-line_instructions>\n  <deferred_loading>If hex-line schemas not loaded, run: ToolSearch('+hex-line read edit')</deferred_loading>\n  <exploration>\n    <rule>Use outline for structure (code + markdown), not Read. ~10-20 lines vs hundreds.</rule>\n    <rule>Use read_file with offset/limit or ranges for targeted reads.</rule>\n    <rule>Use grep_search before editing to get hash anchors.</rule>\n  </exploration>\n  <editing>\n    <path name='surgical'>grep_search \u2192 edit_file (fastest: hash-verified, no full read needed)</path>\n    <path name='exploratory'>outline \u2192 read_file (ranges) \u2192 edit_file with base_revision</path>\n    <path name='multi-file'>bulk_replace(path=&quot;&lt;project root&gt;&quot;) for text rename/refactor across files</path>\n  </editing>\n  <tips>\n    <tip>Auto-fill path from the active file or project root. Do not leave repo scope implicit.</tip>\n    <tip>Never invent range_checksum. Copy it from fresh read_file or grep_search blocks.</tip>\n    <tip>Prefer set_line or insert_after for small local changes and replace_between for larger bounded rewrites.</tip>\n    <tip>Carry revision from read_file into base_revision on edit_file.</tip>\n    <tip>If edit returns CONFLICT, call verify \u2014 only reread when STALE.</tip>\n    <tip>Avoid large first-pass edit batches. Start with 1-2 hunks, then continue from the returned revision.</tip>\n    <tip>Use write_file for new files (no prior Read needed).</tip>\n  </tips>\n  <exceptions>Built-in tools stay OK for images, PDFs, notebooks, Glob, .claude/settings.json, and .claude/settings.local.json.</exceptions>\n</hex-line_instructions>";
+  const msg = styleActive ? "Hex-line MCP available. Output style active.\n<hex-line_instructions>\n  <deferred_loading>If hex-line schemas not loaded, run: ToolSearch('+hex-line read edit')</deferred_loading>\n  <note>Follow the active hex-line output style for primary tool choices.</note>\n  <exceptions>Built-in tools stay OK for images, PDFs, notebooks, Glob, .claude/settings.json, and .claude/settings.local.json.</exceptions>\n</hex-line_instructions>" : "Hex-line MCP available.\n<hex-line_instructions>\n  <deferred_loading>If hex-line schemas not loaded, run: ToolSearch('+hex-line read edit')</deferred_loading>\n  <exploration>\n    <rule>Use outline for structure (code + markdown), not Read. ~10-20 lines vs hundreds.</rule>\n    <rule>Use read_file with offset/limit or ranges for targeted reads.</rule>\n    <rule>Use grep_search before editing to get hash anchors.</rule>\n  </exploration>\n  <editing>\n    <path name='surgical'>grep_search \u2192 edit_file (fastest: hash-verified, no full read needed)</path>\n    <path name='exploratory'>outline \u2192 read_file (ranges) \u2192 edit_file with base_revision</path>\n    <path name='multi-file'>bulk_replace(path=&quot;&lt;project root&gt;&quot;) for text rename/refactor across files</path>\n  </editing>\n  <tips>\n    <tip>Auto-fill path from the active file or project root. Read-only tools may inspect explicit temp-file paths outside the repo. Mutating tools stay project-scoped unless you intentionally pass allow_external=true.</tip>\n    <tip>Never invent range_checksum. Copy it from fresh read_file or grep_search blocks.</tip>\n    <tip>Prefer set_line or insert_after for small local changes and replace_between for larger bounded rewrites.</tip>\n    <tip>Carry revision from read_file into base_revision on edit_file.</tip>\n    <tip>If edit returns CONFLICT, call verify \u2014 only reread when STALE.</tip>\n    <tip>Avoid large first-pass edit batches. Start with 1-2 hunks, then continue from the returned revision.</tip>\n    <tip>Use write_file for new files (no prior Read needed).</tip>\n  </tips>\n  <exceptions>Built-in tools stay OK for images, PDFs, notebooks, Glob, .claude/settings.json, and .claude/settings.local.json.</exceptions>\n</hex-line_instructions>";
   safeExit(1, JSON.stringify({ systemMessage: msg }), 0);
 }
 var _norm = (p) => p.replace(/\\/g, "/");

package/dist/server.mjs

@@ -107,6 +107,7 @@ import { statSync as statSync4 } from "node:fs";
 
 // lib/security.mjs
 import { realpathSync, statSync as statSync2, existsSync, openSync, readSync, closeSync } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
 import { resolve, isAbsolute, dirname } from "node:path";
 
 // lib/format.mjs
@@ -202,11 +203,43 @@ function readText(filePath) {
 // lib/security.mjs
 var MAX_FILE_SIZE = 10 * 1024 * 1024;
 function normalizePath(p) {
-  if (process.platform === "win32" && /^\/[a-zA-Z]\//.test(p)) {
-    p = p[1] + ":" + p.slice(2);
+  if (process.platform === "win32") {
+    if (p === "/tmp" || p.startsWith("/tmp/")) {
+      const suffix = p.slice("/tmp".length).replace(/^\/+/, "");
+      p = suffix ? resolve(tmpdir2(), suffix) : tmpdir2();
+    } else if (p === "/var/tmp" || p.startsWith("/var/tmp/")) {
+      const suffix = p.slice("/var/tmp".length).replace(/^\/+/, "");
+      p = suffix ? resolve(tmpdir2(), suffix) : tmpdir2();
+    } else if (/^\/[a-zA-Z]\//.test(p)) {
+      p = p[1] + ":" + p.slice(2);
+    }
   }
   return p.replace(/\\/g, "/");
 }
+function normalizeScopeValue(value) {
+  const normalized = value.replace(/\\/g, "/");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function resolveInputPath(filePath) {
+  const normalized = normalizePath(filePath);
+  const abs = isAbsolute(normalized) ? normalized : resolve(process.cwd(), normalized);
+  return abs.replace(/\\/g, "/");
+}
+function isWithinRoot(rootPath, targetPath) {
+  const root = normalizeScopeValue(rootPath).replace(/\/+$/, "");
+  const target = normalizeScopeValue(targetPath);
+  return target === root || target.startsWith(`${root}/`);
+}
+function assertProjectScopedPath(filePath, { allowExternal = false } = {}) {
+  if (!filePath) throw new Error("Empty file path");
+  const abs = resolveInputPath(filePath);
+  if (allowExternal) return abs;
+  const projectRoot = resolve(process.cwd()).replace(/\\/g, "/");
+  if (isWithinRoot(projectRoot, abs)) return abs;
+  throw new Error(
+    `PATH_OUTSIDE_PROJECT: ${abs}. Editing is restricted to the current project by default. If you intentionally need a temp or external path, retry with allow_external=true.`
+  );
+}
 function validatePath(filePath) {
   if (!filePath) throw new Error("Empty file path");
   const normalized = normalizePath(filePath);
@@ -2610,6 +2643,8 @@ try {
 } catch {
 }
 var DEFAULT_LIMIT2 = 100;
+var DEFAULT_TOTAL_LIMIT_CONTENT = 200;
+var DEFAULT_TOTAL_LIMIT_LIST = 1e3;
 var MAX_OUTPUT = 10 * 1024 * 1024;
 var TIMEOUT2 = 3e4;
 var MAX_SEARCH_OUTPUT_CHARS = 8e4;
@@ -2651,12 +2686,19 @@ function grepSearch(pattern, opts = {}) {
   const target = normPath ? resolve2(normPath) : process.cwd();
   const output = opts.output || "content";
   const plain = !!opts.plain;
-  const totalLimit = opts.totalLimit && opts.totalLimit > 0 ? opts.totalLimit : 0;
-  if (output === "files") return filesMode(pattern, target, opts);
-  if (output === "count") return countMode(pattern, target, opts);
+  const defaultTotalLimit = output === "content" ? DEFAULT_TOTAL_LIMIT_CONTENT : DEFAULT_TOTAL_LIMIT_LIST;
+  const totalLimit = opts.totalLimit === 0 ? 0 : opts.totalLimit && opts.totalLimit > 0 ? opts.totalLimit : defaultTotalLimit;
+  if (output === "files") return filesMode(pattern, target, opts, totalLimit);
+  if (output === "count") return countMode(pattern, target, opts, totalLimit);
   return contentMode(pattern, target, opts, plain, totalLimit);
 }
-async function filesMode(pattern, target, opts) {
+function applyListModeTotalLimit(lines, totalLimit) {
+  if (!totalLimit || totalLimit <= 0 || lines.length <= totalLimit) return lines.join("\n");
+  const visible = lines.slice(0, totalLimit);
+  visible.push(`OUTPUT_CAPPED: ${lines.length - totalLimit} more result line(s) omitted. Narrow with path= or glob=, or raise total_limit.`);
+  return visible.join("\n");
+}
+async function filesMode(pattern, target, opts, totalLimit) {
   const realArgs = ["-l"];
   if (opts.caseInsensitive) realArgs.push("-i");
   else if (opts.smartCase) realArgs.push("-S");
@@ -2671,9 +2713,9 @@ async function filesMode(pattern, target, opts) {
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const lines = stdout.trimEnd().split("\n").filter(Boolean);
   const normalized = lines.map((l) => l.replace(/\\/g, "/"));
-  return normalized.join("\n");
+  return applyListModeTotalLimit(normalized, totalLimit);
 }
-async function countMode(pattern, target, opts) {
+async function countMode(pattern, target, opts, totalLimit) {
   const realArgs = ["-c"];
   if (opts.caseInsensitive) realArgs.push("-i");
   else if (opts.smartCase) realArgs.push("-S");
@@ -2688,7 +2730,7 @@ async function countMode(pattern, target, opts) {
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const lines = stdout.trimEnd().split("\n").filter(Boolean);
   const normalized = lines.map((l) => l.replace(/\\/g, "/"));
-  return normalized.join("\n");
+  return applyListModeTotalLimit(normalized, totalLimit);
 }
 async function contentMode(pattern, target, opts, plain, totalLimit) {
   const realArgs = ["--json"];
@@ -2800,7 +2842,7 @@ async function contentMode(pattern, target, opts, plain, totalLimit) {
         flushGroup();
         blocks.push(buildDiagnosticBlock({
           kind: "total_limit",
-          message: `Search stopped after ${totalLimit} match event(s). Narrow the query to continue.`,
+          message: `Search stopped after ${totalLimit} match event(s). Narrow the query, raise total_limit, or pass total_limit=0 to disable the cap.`,
           path: String(target).replace(/\\/g, "/")
         }));
         return blocks.map((block) => block.type === "edit_ready_block" ? serializeSearchBlock(block, { plain }) : serializeDiagnosticBlock(block)).join("\n\n");
@@ -4192,7 +4234,7 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
 }
 
 // server.mjs
-var version = true ? "1.13.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.14.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version
@@ -4261,12 +4303,14 @@ server.registerTool("edit_file", {
     dry_run: flexBool().describe("Preview changes without writing"),
     restore_indent: flexBool().describe("Auto-fix indentation to match anchor (default: false)"),
     base_revision: z2.string().optional().describe("Prior revision from read_file/edit_file. Enables conservative auto-rebase for same-file follow-up edits."),
-    conflict_policy: z2.enum(["strict", "conservative"]).optional().describe('Conflict handling (default: "conservative"). "conservative" returns structured CONFLICT output with recovery_ranges, retry_edit/retry_edits, suggested_read_call, and retry_plan when available.')
+    conflict_policy: z2.enum(["strict", "conservative"]).optional().describe('Conflict handling (default: "conservative"). "conservative" returns structured CONFLICT output with recovery_ranges, retry_edit/retry_edits, suggested_read_call, and retry_plan when available.'),
+    allow_external: flexBool().describe("Allow editing a path outside the current project root. Use only when you intentionally target a temp or external file.")
   }),
   annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
 }, async (rawParams) => {
-  const { path: p, edits: json, dry_run, restore_indent, base_revision, conflict_policy } = rawParams ?? {};
+  const { path: p, edits: json, dry_run, restore_indent, base_revision, conflict_policy, allow_external } = rawParams ?? {};
   try {
+    assertProjectScopedPath(p, { allowExternal: !!allow_external });
     let parsed;
     try {
       parsed = typeof json === "string" ? JSON.parse(json) : json;
@@ -4294,12 +4338,14 @@ server.registerTool("write_file", {
   description: "Create a new file or overwrite existing. Creates parent dirs. For existing files prefer edit_file (shows diff, verifies hashes).",
   inputSchema: z2.object({
     path: z2.string().describe("File path"),
-    content: z2.string().describe("File content")
+    content: z2.string().describe("File content"),
+    allow_external: flexBool().describe("Allow writing a path outside the current project root. Use only when you intentionally target a temp or external file.")
   }),
   annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
 }, async (rawParams) => {
-  const { path: p, content } = rawParams ?? {};
+  const { path: p, content, allow_external } = rawParams ?? {};
   try {
+    assertProjectScopedPath(p, { allowExternal: !!allow_external });
     const abs = validateWritePath(p);
     mkdirSync2(dirname6(abs), { recursive: true });
     writeFileSync4(abs, content, "utf-8");
@@ -4325,7 +4371,7 @@ server.registerTool("grep_search", {
     context_before: flexNum().describe("Context lines BEFORE match (-B)"),
     context_after: flexNum().describe("Context lines AFTER match (-A)"),
     limit: flexNum().describe("Max matches per file (default: 100)"),
-    total_limit: flexNum().describe("Total match events across all files; multiline matches count as 1 (0 = unlimited)"),
+    total_limit: flexNum().describe("Total match events across all files; multiline matches count as 1 (default: 200 for content, 1000 for files/count, 0 = unlimited)"),
     plain: flexBool().describe("Omit hash tags, return file:line:content")
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
@@ -4450,12 +4496,14 @@ server.registerTool("bulk_replace", {
     path: z2.string().describe("Root directory for the replacement scope"),
     dry_run: flexBool().describe("Preview without writing (default: false)"),
     max_files: flexNum().describe("Max files to process (default: 100)"),
-    format: z2.enum(["compact", "full"]).optional().describe('"compact" (default) = summary only, "full" = include capped diffs')
+    format: z2.enum(["compact", "full"]).optional().describe('"compact" (default) = summary only, "full" = include capped diffs'),
+    allow_external: flexBool().describe("Allow a replacement root outside the current project root. Use only when you intentionally target a temp or external directory.")
   }),
   annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
 }, async (rawParams) => {
   try {
     const params = rawParams ?? {};
+    assertProjectScopedPath(params.path, { allowExternal: !!params.allow_external });
     const raw = params.replacements;
     let replacementsInput;
     try {

package/output-style.md

@@ -35,7 +35,9 @@ Prefer `hex-line` for text files you may inspect or modify. Hash-annotated reads
 
 - Auto-fill `path` instead of leaving scope implicit.
 - For file tools (`read_file`, `edit_file`, `outline`, `changes` on one file), use the target file path.
+- Read-only file tools may target explicit temp-file paths outside the repo when you intentionally inspect a scratch file.
 - For repo-wide tools (`bulk_replace`, directory `inspect_path`, broad `grep_search`), use the resolved project root or intended directory scope.
+- Mutating tools stay inside the current project root by default. Add `allow_external=true` only when you intentionally edit a temp or external path.
 - Treat missing or ambiguous scope as an error to fix, not as a reason to guess across repositories.
 
 ## Edit Discipline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 9 tools: inspect_path, read, edit, write, grep, outline, verify, changes, bulk_replace.",