@n0zer0d4y/vulcan-file-ops 1.2.11 → 1.2.14

package/CHANGELOG.md

@@ -9,6 +9,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+## [1.2.14] - 2026-05-16
+
+### Fixed
+
+- **CRITICAL**: Fixed initialization deadlock with `claude-ai` v0.1.0 client (Claude Desktop web client, protocol `2025-11-25`).
+  - **Root Cause**: A custom `setRequestHandler(InitializeRequestSchema, ...)` was overriding the SDK's internal `_oninitialize` handler. This broke the SDK's state machine: `_clientCapabilities` and `_clientVersion` were never set, and protocol version negotiation was bypassed — the server echoed back the client's requested version verbatim rather than responding with the highest version it actually supports. The new client's stricter handshake exposed this latent defect.
+  - **Fix**: Removed the custom initialize handler and restored the SDK's built-in `_oninitialize`. The server now correctly negotiates `2025-06-18` when a client requests `2025-11-25`, which the client accepts per the MCP spec.
+  - **Instructions**: Server instructions (`generateServerDescription()`) are now injected into the SDK's `_instructions` field after directory initialization in `runServer()`, so they remain present in the initialize response without requiring a custom handler.
+- Fixed `oninitialized` callback blocking the MCP handshake. The `listRoots()` call inside `oninitialized` was previously awaited, creating a potential deadlock (client won't respond to `roots/list` until after `initialized` is acknowledged, but the callback blocked acknowledgement). Changed to a detached fire-and-forget promise.
+
+## [1.2.13] - 2026-04-23
+
+### Fixed
+
+- Resolved the remaining MCP client tool discovery failure introduced after the SDK upgrade.
+  - Tool schemas exposed through `tools/list` are now normalized for stricter MCP clients.
+  - Removed client-hostile schema constructs from published tool input schemas, including `$schema`, `$ref`, `anyOf`, `oneOf`, and `allOf`.
+  - Replaced the highest-risk wire schemas with explicit compatibility-first object schemas for `attach_image` and `make_directory`.
+  - Preserved runtime backward compatibility while tightening the schemas advertised to clients.
+- Fixed residual MCP mode detection drift so stdio mode is triggered reliably in local and `npx` execution paths.
+- Added `zod` as a direct runtime dependency to avoid install-time fragility in clean environments and `npx` usage.
+- Synchronized package metadata so published registry metadata and local package metadata report the same release version.
+- Re-enabled and stabilized the previously skipped PDF-related Jest coverage.
+  - Enabled the 10 skipped document tests for PDF read, HTML-to-PDF write, mixed document batches, and PDF round-trip paths.
+  - Updated Jest PDF mocks so document tests exercise meaningful content paths instead of placeholder-only buffers.
+  - Suppressed expected negative-path test diagnostics inside tests so successful runs no longer look like runtime failures.
+- Added a regression test to prevent incompatible tool schema shapes from reappearing in future releases.
+
+### Changed
+
+- Documented the Codex-specific MCP configuration format in the README alongside the JSON-based client examples.
+- Updated `npx` examples to use `-y` explicitly for non-interactive client execution.
+
+## [1.2.12] - 2026-02-21
+
+### Fixed
+
+- **CRITICAL**: Fixed MCP server toggle failure and "no tools configured" error caused by Node.js version incompatibility and restrictive MCP detection.
+  - **Node.js Compatibility**: Replaced `import ... with { type: "json" }` with manual `fs.readFileSync` for `package.json` to support Node.js versions earlier than 20.10.0 and 18.20.0 (including Node 14/16).
+  - **Robust MCP Detection**: Changed TTY detection from AND to OR logic. The server now enters MCP mode (suppressing console output) if *either* stdin or stdout is redirected, improving reliability on Windows when run via `npx`.
+  - **Silenced Dotenv**: Added `quiet: true` to `dotenv.config()` to prevent any leakage into the protocol stream.
+- See `local_docs/RCA-MCP-Toggle-Failure-Node-Compatibility-2026-02-21.md` for full details.
+
 ## [1.2.11] - 2026-02-21
 
 ### Fixed

package/README.md

@@ -124,7 +124,10 @@ This server can be used directly with npx (recommended) or installed globally/lo
 
 ### Basic Configuration
 
-Add to your MCP client configuration (e.g., `claude_desktop_config.json`):
+Add to your MCP client configuration.
+
+For JSON-based clients such as Claude Desktop and Cursor, use their `mcpServers` JSON format.
+For Codex, use `C:\Users\<username>\.codex\config.toml` and the `mcp_servers` TOML table format shown below.
 
 #### Option 1: Using npx (Recommended - No Installation Required)
 
@@ -133,12 +136,22 @@ Add to your MCP client configuration (e.g., `claude_desktop_config.json`):
   "mcpServers": {
     "vulcan-file-ops": {
       "command": "npx",
-      "args": ["@n0zer0d4y/vulcan-file-ops"]
+      "args": ["-y", "@n0zer0d4y/vulcan-file-ops"]
     }
   }
 }
 ```
 
+**Codex (`config.toml`)**
+
+```toml
+[mcp_servers.vulcan_file_ops]
+command = "npx"
+args = ["-y", "@n0zer0d4y/vulcan-file-ops"]
+enabled = true
+startup_timeout_sec = 120.0
+```
+
 #### Option 2: Using Global Installation
 
 After running `npm install -g @n0zer0d4y/vulcan-file-ops`:
@@ -184,14 +197,33 @@ Then configure your MCP client:
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
-      "args": ["--approved-folders", "/path/to/your/allowed/directories"]
+      "command": "node",
+      "args": [
+        "/absolute/path/to/vulcan-file-ops/dist/cli.js",
+        "--approved-folders",
+        "/path/to/your/allowed/directories"
+      ]
     }
   }
 }
 ```
 
-**Note:** The `vulcan-file-ops` command will be available in your PATH after building, or you can use the full path: `./dist/cli.js`
+**Codex (`config.toml`)**
+
+```toml
+[mcp_servers.vulcan_file_ops]
+command = "node"
+args = [
+  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
+  "--approved-folders",
+  'C:\path\to\your\allowed\directories'
+]
+cwd = 'C:\absolute\path\to\vulcan-file-ops'
+enabled = true
+startup_timeout_sec = 120.0
+```
+
+**Note:** For local repository execution, prefer `node dist/cli.js` with an absolute path. This works reliably in Codex and avoids PATH ambiguity.
 
 ### Advanced Configuration
 
@@ -207,6 +239,7 @@ Pre-configure specific directories for immediate access on server start:
     "vulcan-file-ops": {
       "command": "npx",
       "args": [
+        "-y",
         "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
         "/Users/username/projects",
@@ -225,6 +258,7 @@ Pre-configure specific directories for immediate access on server start:
     "vulcan-file-ops": {
       "command": "npx",
       "args": [
+        "-y",
         "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
         "C:/Users/username/projects",
@@ -254,6 +288,22 @@ For users running from a cloned repository (after `npm run build`):
 }
 ```
 
+**Codex with Approved Folders (`config.toml`)**
+
+```toml
+[mcp_servers.vulcan_file_ops]
+command = "node"
+args = [
+  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
+  "--approved-folders",
+  'C:\Users\username\projects',
+  'C:\Users\username\documents'
+]
+cwd = 'C:\absolute\path\to\vulcan-file-ops'
+enabled = true
+startup_timeout_sec = 120.0
+```
+
 **Path Format Note:**
 
 - **Windows**: Include drive letter (e.g., `C:/`, `D:/`). Use forward slashes in JSON to avoid escaping backslashes.

package/dist/cli.js

@@ -3,7 +3,7 @@
 // MCP servers use stdin/stdout for JSON-RPC via stdio transport
 // Detection: stdin/stdout are NOT TTY (piped/redirected) OR explicit MCP flags are present.
 // Note: We exclude help/version flags to allow CLI usage even when piped.
-const isMCP = ((!process.stdin.isTTY && !process.stdout.isTTY) ||
+const isMCP = ((!process.stdin.isTTY || !process.stdout.isTTY) ||
     process.argv.some((arg) => arg.includes("mcp") || arg.includes("stdio") || arg.includes("inspector"))) &&
     !process.argv.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v");
 if (isMCP) {

package/dist/server/index.js

@@ -3,7 +3,7 @@
 // due to ES Module static import execution order (imports are evaluated BEFORE top-level code).
 // Detection: stdin/stdout are NOT TTY (piped/redirected) OR explicit MCP flags are present.
 // Note: We exclude help/version flags to allow CLI usage even when piped.
-const _isMCP = ((!process.stdin.isTTY && !process.stdout.isTTY) ||
+const _isMCP = ((!process.stdin.isTTY || !process.stdout.isTTY) ||
     process.argv.some((arg) => arg.includes("mcp") || arg.includes("stdio") || arg.includes("inspector"))) &&
     !process.argv.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v");
 if (_isMCP) {
@@ -16,11 +16,16 @@ if (_isMCP) {
 }
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, InitializeRequestSchema, PingRequestSchema, RootsListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, PingRequestSchema, RootsListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
 import fs from "fs/promises";
+import { readFileSync } from "fs";
 import path from "path";
+import { fileURLToPath } from "url";
 import dotenv from "dotenv";
-import packageJson from "../../package.json" with { type: "json" };
+// Manual JSON import for compatibility with older Node.js versions
+// (native 'import ... with { type: "json" }' requires Node 20.10+ or 18.20+)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(readFileSync(path.resolve(__dirname, "../../package.json"), "utf-8"));
 import { normalizePath, expandHome } from "../utils/path-utils.js";
 import { getValidRootDirectories } from "../utils/roots-utils.js";
 import { setAllowedDirectories, getAllowedDirectories, setIgnoredFolders, setEnabledTools, } from "../utils/lib.js";
@@ -336,7 +341,7 @@ async function initializeDirectories() {
         // Priority 2: Load from .env file
         try {
             const envPath = path.join(process.cwd(), ".env");
-            dotenv.config({ path: envPath });
+            dotenv.config({ path: envPath, quiet: true });
             if (process.env.APPROVED_COMMANDS) {
                 finalApprovedCommands = process.env.APPROVED_COMMANDS.split(",")
                     .map((c) => c.trim())
@@ -394,26 +399,11 @@ const server = new Server({
         // receive "Method not found" errors, and fail to enable the toggle
     },
 });
-// Initialize handler - required for MCP protocol
-server.setRequestHandler(InitializeRequestSchema, async (request) => {
-    const clientCapabilities = request.params.capabilities;
-    return {
-        // CRITICAL: Return the protocol version the CLIENT requested, not LATEST
-        // Claude Desktop only supports 2025-06-18 and will disconnect if we return 2025-11-25
-        protocolVersion: request.params.protocolVersion,
-        capabilities: {
-            tools: {
-                listChanged: true,
-            },
-            // CRITICAL: Do NOT declare resources or prompts - we don't implement them
-        },
-        serverInfo: {
-            name: "vulcan-file-ops",
-            version: VERSION,
-        },
-        instructions: generateServerDescription(),
-    };
-});
+// The SDK's built-in initialize handler (_oninitialize) is left in place.
+// Overriding it via setRequestHandler breaks the SDK's internal state machine:
+// _clientCapabilities and _clientVersion never get set, and protocol version
+// negotiation is bypassed (should respond with max supported ≤ client's requested).
+// Instructions are injected at runtime in runServer() after directories initialize.
 // Ping handler - for health checks
 server.setRequestHandler(PingRequestSchema, async () => {
     return {};
@@ -618,18 +608,19 @@ server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
     }
 });
 // Handles post-initialization setup, specifically checking for and fetching MCP roots.
-server.oninitialized = async () => {
+// listRoots() is fired detached (no await) so it doesn't block the initialize handshake.
+// Blocking here deadlocks: the client won't respond to roots/list until after initialize
+// completes, but initialize won't complete until this callback returns.
+server.oninitialized = () => {
     const clientCapabilities = server.getClientCapabilities();
     if (clientCapabilities?.roots) {
-        try {
-            const response = await server.listRoots();
+        server.listRoots().then(async (response) => {
             if (response && "roots" in response) {
                 await updateAllowedDirectoriesFromRoots(response.roots);
             }
-        }
-        catch (error) {
+        }).catch(() => {
             // Silently handle errors - dynamic access will work via register_directory tool
-        }
+        });
     }
 };
 // Start server
@@ -643,14 +634,20 @@ export async function runServer() {
     catch (error) {
         // In MCP mode, don't crash the server on init errors
         // Just continue with empty configuration
-        const isMCP = (!process.stdin.isTTY && !process.stdout.isTTY) ||
-            process.argv.some((arg) => arg.includes("mcp") || arg.includes("stdio"));
+        const isMCP = (!process.stdin.isTTY || !process.stdout.isTTY) ||
+            process.argv.some((arg) => arg.includes("mcp") ||
+                arg.includes("stdio") ||
+                arg.includes("inspector"));
         if (!isMCP) {
             // In non-MCP mode, we can show errors and exit
             throw error;
         }
         // In MCP mode, silently continue - server can work without approved folders
     }
+    // Inject instructions now that directories are known. The SDK's built-in
+    // _oninitialize reads this._instructions when building the initialize response.
+    server._instructions =
+        generateServerDescription();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Minimal logging to avoid issues with MCP clients

package/dist/tools/filesystem-tools.js

@@ -7,6 +7,7 @@ import { expandHome, normalizePath } from "../utils/path-utils.js";
 import { isPathWithinAllowedDirectories } from "../utils/path-validation.js";
 import { MakeDirectoryArgsSchema, ListDirectoryArgsSchema, MoveFileArgsSchema, GetFileInfoArgsSchema, RegisterDirectoryArgsSchema, FileOperationsArgsSchema, DeleteFilesArgsSchema, } from "../types/index.js";
 import { validatePath, getFileStats, formatSize, getAllowedDirectories, setAllowedDirectories, shouldIgnoreFolder, } from "../utils/lib.js";
+import { createEmptyObjectSchema, createPathArraySchema, sanitizeToolInputSchema, } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
 export function getFileSystemTools() {
     // Get current allowed directories for dynamic descriptions
@@ -25,7 +26,14 @@ export function getFileSystemTools() {
             description: "Create single or multiple directories with recursive parent creation " +
                 "(like Unix 'mkdir -p'). Idempotent - won't error if directories exist. " +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(MakeDirectoryArgsSchema),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    paths: createPathArraySchema("Directory paths to create. For maximum MCP client compatibility, provide an array even when creating a single directory."),
+                },
+                required: ["paths"],
+                additionalProperties: false,
+            },
         },
         {
             name: "list_directory",
@@ -34,7 +42,7 @@ export function getFileSystemTools() {
                 "Supports simple listings, detailed views with sizes/timestamps, hierarchical " +
                 "tree display, and structured JSON output. Automatically filters globally " +
                 "configured ignored folders. Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(ListDirectoryArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(ListDirectoryArgsSchema)),
         },
         {
             name: "move_file",
@@ -43,7 +51,7 @@ export function getFileSystemTools() {
                 "Fails safely if the destination path already exists to prevent accidental overwrites. " +
                 "Can also perform simple same-directory renames. " +
                 "Both source and destination must be within allowed directories.",
-            inputSchema: zodToJsonSchema(MoveFileArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(MoveFileArgsSchema)),
         },
         {
             name: "get_file_info",
@@ -51,7 +59,7 @@ export function getFileSystemTools() {
                 "Provides detailed information including size, timestamps (creation and last modification), permissions, and entry type. " +
                 "Perfect for inspecting file properties and attributes without accessing the actual content. " +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(GetFileInfoArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(GetFileInfoArgsSchema)),
         },
         {
             name: "register_directory",
@@ -59,7 +67,7 @@ export function getFileSystemTools() {
                 "to directories specified by the human user during conversation. The directory " +
                 "and all its subdirectories will become accessible for all filesystem operations." +
                 generateApprovedDirsText(),
-            inputSchema: zodToJsonSchema(RegisterDirectoryArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(RegisterDirectoryArgsSchema)),
         },
         {
             name: "list_allowed_directories",
@@ -67,11 +75,7 @@ export function getFileSystemTools() {
                 "Note that subdirectories within listed paths are implicitly accessible as well. " +
                 "Use this to determine available filesystem scope and plan operations accordingly before attempting file access." +
                 generateApprovedDirsText(),
-            inputSchema: {
-                type: "object",
-                properties: {},
-                required: [],
-            },
+            inputSchema: createEmptyObjectSchema(),
         },
         {
             name: "file_operations",
@@ -126,7 +130,7 @@ export function getFileSystemTools() {
                 "Operations are processed concurrently for performance. " +
                 "Maximum 100 paths per operation. " +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(DeleteFilesArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(DeleteFilesArgsSchema)),
         },
     ];
 }

package/dist/tools/read-tools.js

@@ -5,6 +5,7 @@ import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { ReadFileArgsSchema, AttachImageArgsSchema, ReadMultipleFilesArgsSchema, } from "../types/index.js";
 import { validatePath, readFileContent, tailFile, headFile, rangeFile, } from "../utils/lib.js";
 import { isDocumentFile, parseDocument } from "../utils/document-parser.js";
+import { createPathArraySchema, sanitizeToolInputSchema, } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
 // Reads a file as a stream of buffers, concatenates them, and then encodes
 // the result to a Base64 string. This is a memory-efficient way to handle
@@ -34,7 +35,7 @@ export function getReadTools() {
                 "range (lines from startLine to endLine, inclusive, 1-indexed). " +
                 "Document files ignore mode parameters and always return full content. " +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(ReadFileArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(ReadFileArgsSchema)),
         },
         {
             name: "attach_image",
@@ -45,7 +46,14 @@ export function getReadTools() {
                 "Supports PNG, JPEG, GIF, WebP, BMP, and SVG formats. " +
                 "Note: This requires the MCP client to support vision capabilities. " +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(AttachImageArgsSchema),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: createPathArraySchema("Path(s) to image file(s) to attach for AI vision analysis. For maximum MCP client compatibility, provide an array even when attaching a single image."),
+                },
+                required: ["path"],
+                additionalProperties: false,
+            },
         },
         {
             name: "read_multiple_files",
@@ -56,7 +64,7 @@ export function getReadTools() {
                 "Document files ignore mode parameters and return full content. " +
                 "Processes files concurrently for performance. Maximum 50 files per operation. " +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(ReadMultipleFilesArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(ReadMultipleFilesArgsSchema)),
         },
     ];
 }

package/dist/tools/search-tools.js

@@ -2,6 +2,7 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { SearchFilesArgsSchema, GrepArgsSchema, } from "../types/index.js";
 import { validatePath, searchFilesWithValidation, grepFilesWithValidation, getAllowedDirectories, getIgnoredFolders, } from "../utils/lib.js";
+import { sanitizeToolInputSchema } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
 export function getSearchTools() {
     return [
@@ -12,7 +13,7 @@ export function getSearchTools() {
                 "Use simple patterns like '*.ext' for current directory matches, or '**/*.ext' for deep subdirectory searches. " +
                 "Returns absolute paths to all discovered items. Excellent for locating files when exact paths are unknown. " +
                 "Only searches within allowed directories.",
-            inputSchema: zodToJsonSchema(SearchFilesArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(SearchFilesArgsSchema)),
         },
         {
             name: "grep_files",
@@ -20,7 +21,7 @@ export function getSearchTools() {
                 "Supports: regex patterns, case-insensitive (-i), context lines (-A/-B/-C), file type filters (type: js/py/ts/etc), glob patterns, multiline mode. " +
                 "Output modes: content (lines+context), files_with_matches (paths only), count (match counts). " +
                 "Respects ignored folders. Use head_limit to cap results. Only searches within allowed directories.",
-            inputSchema: zodToJsonSchema(GrepArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(GrepArgsSchema)),
         },
     ];
 }

package/dist/tools/shell-tool.js

@@ -6,6 +6,7 @@ import { executeShellCommand, } from "../utils/shell-execution.js";
 import { validatePath, getAllowedDirectories } from "../utils/lib.js";
 import { extractPathsFromCommand } from "../utils/command-path-extraction.js";
 import { isPathWithinAllowedDirectories } from "../utils/path-validation.js";
+import { sanitizeToolInputSchema } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
 // Global state for approved commands
 let approvedCommands = new Set();
@@ -62,7 +63,7 @@ export function getShellTools() {
                 `If no workdir is specified, the server's current working directory will be used and validated.` +
                 approvedCommandsText +
                 `\n\nIMPORTANT: Always provide a clear description of what the command does and why it's needed.`,
-            inputSchema: zodToJsonSchema(ShellCommandArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(ShellCommandArgsSchema)),
         },
     ];
 }

package/dist/tools/write-tools.js

@@ -5,6 +5,7 @@ import { promises as fs } from "fs";
 import { WriteFileArgsSchema, WriteMultipleFilesArgsSchema, EditFileArgsSchema, } from "../types/index.js";
 import { validatePath, writeFileContent, readFileContent, applyFileEdits, } from "../utils/lib.js";
 import { isHTMLContent, convertHTMLToPDF, convertHTMLToDOCX, } from "../utils/html-to-document.js";
+import { sanitizeToolInputSchema } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
 /**
  * Helper function to write file content based on file extension
@@ -261,7 +262,7 @@ export function getWriteTools() {
                 "- Correct: Use actual line breaks in your JSON string value\n" +
                 "\n" +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(WriteFileArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(WriteFileArgsSchema)),
         },
         {
             name: "edit_file",
@@ -294,7 +295,7 @@ export function getWriteTools() {
                 "- The MCP/JSON layer handles encoding automatically\n" +
                 "- Using \\n literally will search for/write backslash+n characters (wrong!)\n\n" +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(EditFileArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(EditFileArgsSchema)),
         },
         {
             name: "write_multiple_files",
@@ -310,7 +311,7 @@ export function getWriteTools() {
                 "- Each file's content will be written exactly as provided in the string\n" +
                 "\n" +
                 "Only works within allowed directories.",
-            inputSchema: zodToJsonSchema(WriteMultipleFilesArgsSchema),
+            inputSchema: sanitizeToolInputSchema(zodToJsonSchema(WriteMultipleFilesArgsSchema)),
         },
     ];
 }

package/dist/utils/tool-schema.js

@@ -0,0 +1,87 @@
+function cloneValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function unescapeJsonPointerSegment(segment) {
+    return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function resolveLocalRef(root, ref) {
+    if (!ref.startsWith("#/")) {
+        return undefined;
+    }
+    const segments = ref
+        .slice(2)
+        .split("/")
+        .map((segment) => unescapeJsonPointerSegment(segment));
+    let current = root;
+    for (const segment of segments) {
+        if (current == null || typeof current !== "object" || !(segment in current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function sanitizeSchemaNode(node, root) {
+    if (Array.isArray(node)) {
+        return node.map((item) => sanitizeSchemaNode(item, root));
+    }
+    if (!node || typeof node !== "object") {
+        return node;
+    }
+    const schema = node;
+    if (typeof schema.$ref === "string") {
+        const resolved = resolveLocalRef(root, schema.$ref);
+        if (resolved && typeof resolved === "object") {
+            const { $ref: _ignoredRef, ...siblings } = schema;
+            return sanitizeSchemaNode({
+                ...cloneValue(resolved),
+                ...siblings,
+            }, root);
+        }
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "$schema" || key === "$defs" || key === "definitions") {
+            continue;
+        }
+        result[key] = sanitizeSchemaNode(value, root);
+    }
+    return result;
+}
+export function sanitizeToolInputSchema(schema) {
+    const cloned = cloneValue(schema);
+    const sanitized = sanitizeSchemaNode(cloned, cloned);
+    if (!sanitized || typeof sanitized !== "object" || Array.isArray(sanitized)) {
+        return {
+            type: "object",
+            additionalProperties: false,
+        };
+    }
+    const normalized = sanitized;
+    if (normalized.type !== "object") {
+        normalized.type = "object";
+    }
+    if (!("additionalProperties" in normalized)) {
+        normalized.additionalProperties = false;
+    }
+    return normalized;
+}
+export function createEmptyObjectSchema() {
+    return {
+        type: "object",
+        properties: {},
+        required: [],
+        additionalProperties: false,
+    };
+}
+export function createPathArraySchema(description) {
+    return {
+        type: "array",
+        items: {
+            type: "string",
+        },
+        minItems: 1,
+        description,
+    };
+}
+//# sourceMappingURL=tool-schema.js.map

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@n0zer0d4y/vulcan-file-ops",
-  "version": "1.2.11",
+  "version": "1.2.14",
   "mcpName": "io.github.n0zer0d4y/vulcan-file-ops",
   "description": "MCP server for AI assistants: read, write, edit, and manage files securely on local filesystem.",
   "license": "MIT",
-  "author": "Lloyd Barcatan",
+  "author": "n0zer0d4y",
   "homepage": "https://github.com/n0zer0d4y/vulcan-file-ops",
   "repository": {
     "type": "git",
@@ -79,6 +79,7 @@
     "pdf-lib": "^1.17.1",
     "pdf-parse": "^2.4.5",
     "pdfmake": "^0.2.20",
+    "zod": "^3.25.76",
     "zod-to-json-schema": "^3.25.1"
   },
   "devDependencies": {