@n0zer0d4y/vulcan-file-ops 1.2.13 → 1.2.14

package/CHANGELOG.md

@@ -8,33 +8,43 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-
-## [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
+
+## [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).

package/README.md

@@ -124,10 +124,10 @@ This server can be used directly with npx (recommended) or installed globally/lo
 
 ### Basic Configuration
 
-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.
+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)
 
@@ -135,22 +135,22 @@ For Codex, use `C:\Users\<username>\.codex\config.toml` and the `mcp_servers` TO
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "npx",
-      "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
-```
+      "command": "npx",
+      "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
 
@@ -180,7 +180,7 @@ After running `npm install @n0zer0d4y/vulcan-file-ops` in your project:
 }
 ```
 
-#### Option 4: Local Repository Execution (For Developers)
+#### Option 4: Local Repository Execution (For Developers)
 
 If you've cloned this repository and want to run from source:
 
@@ -191,39 +191,39 @@ npm install
 npm run build
 ```
 
-Then configure your MCP client:
-
-```json
-{
-  "mcpServers": {
-    "vulcan-file-ops": {
-      "command": "node",
-      "args": [
-        "/absolute/path/to/vulcan-file-ops/dist/cli.js",
-        "--approved-folders",
-        "/path/to/your/allowed/directories"
-      ]
-    }
-  }
-}
-```
-
-**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.
+Then configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "vulcan-file-ops": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/vulcan-file-ops/dist/cli.js",
+        "--approved-folders",
+        "/path/to/your/allowed/directories"
+      ]
+    }
+  }
+}
+```
+
+**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
 
@@ -237,12 +237,12 @@ Pre-configure specific directories for immediate access on server start:
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@n0zer0d4y/vulcan-file-ops",
-        "--approved-folders",
-        "/Users/username/projects",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@n0zer0d4y/vulcan-file-ops",
+        "--approved-folders",
+        "/Users/username/projects",
         "/Users/username/documents"
       ]
     }
@@ -256,12 +256,12 @@ Pre-configure specific directories for immediate access on server start:
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@n0zer0d4y/vulcan-file-ops",
-        "--approved-folders",
-        "C:/Users/username/projects",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@n0zer0d4y/vulcan-file-ops",
+        "--approved-folders",
+        "C:/Users/username/projects",
         "C:/Users/username/documents"
       ]
     }
@@ -269,7 +269,7 @@ Pre-configure specific directories for immediate access on server start:
 }
 ```
 
-**Alternative: Local Repository Execution**
+**Alternative: Local Repository Execution**
 
 For users running from a cloned repository (after `npm run build`):
 
@@ -277,32 +277,32 @@ For users running from a cloned repository (after `npm run build`):
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
-      "args": [
-        "--approved-folders",
-        "/Users/username/projects",
-        "/Users/username/documents"
+      "command": "vulcan-file-ops",
+      "args": [
+        "--approved-folders",
+        "/Users/username/projects",
+        "/Users/username/documents"
       ]
     }
   }
 }
-```
-
-**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
-```
+```
+
+**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:**
 

package/dist/server/index.js

@@ -16,7 +16,7 @@ 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";
@@ -399,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 {};
@@ -623,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
@@ -658,6 +644,10 @@ export async function runServer() {
         }
         // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n0zer0d4y/vulcan-file-ops",
-  "version": "1.2.13",
+  "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",