@levnikolaevich/hex-line-mcp 1.29.0 → 1.30.0

package/dist/server.mjs

@@ -202,11 +202,12 @@ function readText(filePath) {
 // lib/security.mjs
 var MAX_FILE_SIZE = 10 * 1024 * 1024;
 var EXTERNAL_SAFE_FOLDERS = [
-  ".hex-skills/",
-  ".claude/"
+  ".hex-skills",
+  ".claude"
 ];
 function isInExternalSafeFolder(absPath) {
-  return EXTERNAL_SAFE_FOLDERS.some((folder) => absPath.includes(folder));
+  const parts = normalizeScopeValue(absPath).split("/").filter(Boolean);
+  return EXTERNAL_SAFE_FOLDERS.some((folder) => parts.includes(folder));
 }
 function normalizePath(p) {
   if (process.platform === "win32") {
@@ -5008,6 +5009,85 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
   return output;
 }
 
+// ../hex-common/src/runtime/error-classifier.mjs
+var FAILURE_CLASS = Object.freeze({
+  NONE: "none",
+  TIMEOUT_IDLE: "timeout_idle",
+  TIMEOUT_PRODUCTIVE: "timeout_productive",
+  PERMISSION_DENIAL: "permission_denial",
+  TOOL_MISSING: "tool_missing",
+  AUTH_MISSING: "auth_missing",
+  RATE_LIMITED: "rate_limited",
+  ASKED_QUESTION: "asked_question",
+  AGENT_ERROR: "agent_error",
+  UNKNOWN: "unknown"
+});
+var INPUT_ERROR_CODES = /* @__PURE__ */ new Set([
+  "BAD_INPUT",
+  "BAD_PATH",
+  "BAD_REMOTE_PLATFORM",
+  "INVALID_INPUT",
+  "INVALID_EDIT_PAYLOAD",
+  "INVALID_JSON",
+  "PATH_OUTSIDE_ROOT",
+  "PATH_NOT_FOUND",
+  "FILE_NOT_FOUND",
+  "FILE_OUTSIDE_PROJECT",
+  "OUT_OF_RANGE",
+  "UNSUPPORTED_REMOTE_PLATFORM"
+]);
+var PERMISSION_ERROR_CODES = /* @__PURE__ */ new Set([
+  "SSH_HOST_NOT_ALLOWED",
+  "BLOCKED_COMMAND",
+  "REMOTE_SSH_DISABLED"
+]);
+var AUTH_ERROR_CODES = /* @__PURE__ */ new Set([
+  "SSH_AUTH_FAILED",
+  "SSH_AUTH_MISSING",
+  "SSH_KEY_UNREADABLE"
+]);
+var TIMEOUT_ERROR_CODES = /* @__PURE__ */ new Set([
+  "SSH_EXEC_TIMEOUT",
+  "SSH_CONNECT_TIMEOUT",
+  "EXEC_TIMEOUT",
+  "TRANSFER_TIMEOUT"
+]);
+function textFor(input) {
+  return [
+    input?.code,
+    input?.message,
+    input?.recovery,
+    input?.stderr,
+    input?.error
+  ].filter(Boolean).map(String).join("\n");
+}
+function classifyMcpFailure(input = {}) {
+  const code = String(input.code || "").toUpperCase();
+  const text = textFor(input).toLowerCase();
+  if (/\b(429|rate limit|too many requests|quota exceeded|throttl)/i.test(text) || code.includes("RATE_LIMIT")) {
+    return { failure_class: FAILURE_CLASS.RATE_LIMITED, next_action: "defer_retry" };
+  }
+  if (/\b(auth|authentication|unauthorized|not authorized|login required|credential|token missing|no user for host|permission denied \(publickey\)|publickey)\b/i.test(text) || code.includes("AUTH") || AUTH_ERROR_CODES.has(code)) {
+    return { failure_class: FAILURE_CLASS.AUTH_MISSING, next_action: "authenticate" };
+  }
+  if (/\b(eacces|eperm|permission denied|access denied|operation not permitted|forbidden)\b/i.test(text) || code === "GRAPH_DB_UNREADABLE" || PERMISSION_ERROR_CODES.has(code)) {
+    return { failure_class: FAILURE_CLASS.PERMISSION_DENIAL, next_action: "fix_permissions" };
+  }
+  if (/\b(enoent|command not found|not recognized as|not found in path|required tool|provider setup failed|missing provider|tool missing)\b/i.test(text) || code === "GRAPH_PROVIDER_SETUP_FAILED") {
+    return { failure_class: FAILURE_CLASS.TOOL_MISSING, next_action: "install_tool" };
+  }
+  if (/\b(etimedout|timed out|timeout|transfer_timeout|connection timed out|database is locked|busy or locked)\b/i.test(text) || code.includes("TIMEOUT") || code === "GRAPH_DB_BUSY" || TIMEOUT_ERROR_CODES.has(code)) {
+    return { failure_class: FAILURE_CLASS.TIMEOUT_IDLE, next_action: "retry_after_wait" };
+  }
+  if (/\?\s*$|\b(please confirm|confirm\?|choose one|which option)\b/i.test(text)) {
+    return { failure_class: FAILURE_CLASS.ASKED_QUESTION, next_action: "fix_inputs" };
+  }
+  if (INPUT_ERROR_CODES.has(code) || code.startsWith("INVALID_") || code.endsWith("_REQUIRED")) {
+    return { failure_class: FAILURE_CLASS.UNKNOWN, next_action: "fix_inputs" };
+  }
+  return { failure_class: FAILURE_CLASS.UNKNOWN, next_action: "fix_inputs" };
+}
+
 // ../hex-common/src/runtime/results.mjs
 var LARGE_RESULT_META = { "anthropic/maxResultSizeChars": 5e5 };
 function result(structured, { large = false } = {}) {
@@ -5021,9 +5101,26 @@ function result(structured, { large = false } = {}) {
   return response;
 }
 function errorResult(code, message, recovery, { large = false, extra = null } = {}) {
+  const normalizedCode = String(code || "ERROR");
+  const normalizedMessage = String(message || "Unknown MCP tool error");
+  const normalizedRecovery = String(recovery || "Review the error and retry with corrected inputs");
+  const classification = classifyMcpFailure({
+    code: normalizedCode,
+    message: normalizedMessage,
+    recovery: normalizedRecovery
+  });
   const payload = {
     status: "ERROR",
-    error: { code, message, recovery }
+    code: normalizedCode,
+    summary: normalizedMessage,
+    next_action: classification.next_action,
+    recovery: normalizedRecovery,
+    failure_class: classification.failure_class,
+    error: {
+      code: normalizedCode,
+      message: normalizedMessage,
+      recovery: normalizedRecovery
+    }
   };
   if (extra && typeof extra === "object") {
     Object.assign(payload, extra);
@@ -5032,9 +5129,17 @@ function errorResult(code, message, recovery, { large = false, extra = null } =
 }
 
 // server.mjs
-var version = true ? "1.29.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.30.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var STATUS_ENUM = z2.enum(STATUS_VALUES);
 var ERROR_SHAPE = z2.object({ code: z2.string(), message: z2.string(), recovery: z2.string() }).optional();
+var ERROR_RESULT_FIELDS = {
+  code: z2.string().optional(),
+  summary: z2.string().optional(),
+  next_action: z2.string().optional(),
+  recovery: z2.string().optional(),
+  failure_class: z2.string().optional(),
+  error: ERROR_SHAPE
+};
 var LINE_REPORT_KEYS = /* @__PURE__ */ new Set([
   "status",
   "reason",
@@ -5055,6 +5160,46 @@ var LINE_REPORT_KEYS = /* @__PURE__ */ new Set([
   "remapped_refs",
   "warnings"
 ]);
+var EDIT_PAYLOAD_TYPES = ["set_line", "insert_after", "replace_lines", "replace_between"];
+var EDIT_REQUIRED_FIELDS = {
+  set_line: ["anchor", "new_text"],
+  insert_after: ["anchor", "text"],
+  replace_lines: ["start_anchor", "end_anchor", "new_text"],
+  replace_between: ["start_anchor", "end_anchor", "new_text"]
+};
+function inputError(code, message, recovery) {
+  const error = new Error(message);
+  error.code = code;
+  error.recovery = recovery;
+  return error;
+}
+function validateEditPayload(edits) {
+  if (!Array.isArray(edits) || edits.length === 0) {
+    throw inputError("INVALID_EDIT_PAYLOAD", "BAD_INPUT: edits must be a non-empty JSON array", 'Pass canonical edit objects such as {"set_line":{"anchor":"ab.12","new_text":"..."}}');
+  }
+  edits.forEach((edit, index) => {
+    if (!edit || typeof edit !== "object" || Array.isArray(edit)) {
+      throw inputError("INVALID_EDIT_PAYLOAD", `BAD_INPUT: edit at index ${index} must be an object`, "Use one canonical edit object per array item");
+    }
+    const keys = EDIT_PAYLOAD_TYPES.filter((type2) => Object.prototype.hasOwnProperty.call(edit, type2));
+    if (keys.length === 0) {
+      throw inputError("INVALID_EDIT_PAYLOAD", `BAD_INPUT: unknown edit type at index ${index}`, "Use set_line, insert_after, replace_lines, or replace_between");
+    }
+    if (keys.length > 1) {
+      throw inputError("INVALID_EDIT_PAYLOAD", `BAD_INPUT: edit at index ${index} has multiple edit types`, "Use exactly one edit type per object");
+    }
+    const [type] = keys;
+    const payload = edit[type];
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+      throw inputError("INVALID_EDIT_PAYLOAD", `BAD_INPUT: ${type} payload at index ${index} must be an object`, "Nest fields under the canonical edit type");
+    }
+    for (const field of EDIT_REQUIRED_FIELDS[type]) {
+      if (typeof payload[field] !== "string") {
+        throw inputError("INVALID_EDIT_PAYLOAD", `BAD_INPUT: ${type}.${field} must be a string at index ${index}`, "Provide all required canonical edit fields before retrying");
+      }
+    }
+  });
+}
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version
@@ -5126,7 +5271,7 @@ server.registerTool("read_file", {
     content: z2.string().optional(),
     edit_ready: z2.boolean().optional(),
     next_action: z2.string().optional(),
-    error: ERROR_SHAPE
+    ...ERROR_RESULT_FIELDS
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
@@ -5190,7 +5335,7 @@ server.registerTool("edit_file", {
     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.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), warnings: z2.array(z2.object({ code: z2.string() }).passthrough()).optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), warnings: z2.array(z2.object({ code: z2.string() }).passthrough()).optional(), ...ERROR_RESULT_FIELDS }),
   annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
 }, async (rawParams) => {
   const { file_path: p, edits: json, dry_run, restore_indent, base_revision, conflict_policy, allow_external } = rawParams ?? {};
@@ -5202,7 +5347,7 @@ server.registerTool("edit_file", {
     } catch {
       throw new Error('edits: invalid JSON. Expected: [{"set_line":{"anchor":"xx.N","new_text":"..."}}]');
     }
-    if (!Array.isArray(parsed) || !parsed.length) throw new Error("Edits: non-empty JSON array required");
+    validateEditPayload(parsed);
     const content = editFile(p, parsed, {
       dryRun: dry_run,
       restoreIndent: restore_indent,
@@ -5222,7 +5367,7 @@ server.registerTool("write_file", {
     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.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), lines: z2.number().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), lines: z2.number().optional(), ...ERROR_RESULT_FIELDS }),
   annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
   const { file_path: p, content, allow_external } = rawParams ?? {};
@@ -5259,7 +5404,7 @@ server.registerTool("grep_search", {
     edit_ready: flexBool().describe("Preserve hash/checksum search hunks in `content` mode. Default: false."),
     allow_large_output: flexBool().describe("Bypass the default content-mode block/char caps when you intentionally need a larger payload.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, pattern: z2.string().optional(), content: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, pattern: z2.string().optional(), content: z2.string().optional(), ...ERROR_RESULT_FIELDS }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
 }, async (rawParams) => {
   const {
@@ -5314,7 +5459,7 @@ server.registerTool("outline", {
   inputSchema: z2.object({
     file_path: z2.string().describe("Source file path")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), ...ERROR_RESULT_FIELDS }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
   const { file_path: p } = rawParams ?? {};
@@ -5333,7 +5478,7 @@ server.registerTool("verify", {
     checksums: z2.array(z2.string()).describe('Checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
     base_revision: z2.string().optional().describe("Optional prior revision to compare against latest state.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, file_path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), ...ERROR_RESULT_FIELDS }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
 }, async (rawParams) => {
   const { file_path: p, checksums, base_revision } = rawParams ?? {};
@@ -5360,7 +5505,7 @@ server.registerTool("inspect_path", {
     format: z2.enum(["compact", "full"]).optional().describe('"compact" = shorter path view, "full" = include sizes/metadata where available'),
     verbosity: z2.enum(["minimal", "compact", "full"]).optional().describe("Response budget. `minimal` returns the shortest tree summary.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), ...ERROR_RESULT_FIELDS }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
 }, async (rawParams) => {
   const { path: p, max_depth, max_entries, gitignore, format, pattern, type: entryType, verbosity } = rawParams ?? {};
@@ -5386,7 +5531,7 @@ server.registerTool("changes", {
     path: z2.string().describe("File or directory path"),
     compare_against: z2.string().optional().describe('Git ref to compare against (default: "HEAD")')
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), ...ERROR_RESULT_FIELDS }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
 }, async (rawParams) => {
   const { path: p, compare_against } = rawParams ?? {};
@@ -5409,7 +5554,7 @@ server.registerTool("bulk_replace", {
     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.")
   }),
-  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), summary: z2.string().optional(), next_action: z2.string().optional(), error: ERROR_SHAPE }),
+  outputSchema: z2.object({ status: STATUS_ENUM, path: z2.string().optional(), content: z2.string().optional(), reason: z2.string().optional(), ...ERROR_RESULT_FIELDS }),
   annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
 }, async (rawParams) => {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.29.0",
+  "version": "1.30.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.",