mcp-fs-shell-windows — filesystem + standalone Windows shell MCP server

A Windows-first MCP server that gives AI clients comprehensive filesystem access (30 tools), reliable local shell execution (8 tools), and a full Beledarian-parity tool set — git, GitHub, system, document, database, web, RAG, browser, and sub-agent tools (82 tools total) — in a single Node.js process with no client-side permission toggles.

Heavily extended fork of fabienvauchelles/mcp-filesystem-extended, which itself extends the official @modelcontextprotocol/server-filesystem. Developed and tested primarily on Windows: drive-letter roots (C:\, D:\) and UNC network-share roots (\\server\\share) are first-class, and the shell tools run commands through cmd.exe byte-for-byte.

npm: mcp-fs-shell-windows · Source: gerarddeluca/mcp-fs-shell-windows

Provenance

| Layer | Source | |---|---| | Official base | @modelcontextprotocol/server-filesystem (Anthropic, PBC; MIT) | | Base fork | fabienvauchelles/mcp-filesystem-extended @ b6c317a (MIT) | | Parity layer (v0.2.21–v0.2.29) | Beledarian/Beledarians_LM_Studio_Toolbox — the “Beledarian” LM Studio plugin (Laurin Feulner; MIT): 42-tool port (git, GitHub, system, document/database, web, RAG, browser, Beledarian-named compatibility aliases, sub-agent) | | This fork | v0.2.1 tool parity + transfer_files rename, robustness patches, 8 shell tools (v0.2.2), verbatim argv (v0.2.4), launch_file launcher (v0.2.7), raw-byte access + dir_diff + text encodings (v0.2.9–v0.2.11), wait_for_file (v0.2.12), replace_regex (v0.2.14), reparse-point & long-path hardening (v0.2.15–v0.2.16), Recycle-Bin deletes (v0.2.17), create_link (v0.2.18), run_javascript_free unrestricted code execution (v0.2.20) — see Differences |

Features

• 30 filesystem tools — batched read/write/append/delete (including raw-byte access, per-file text encodings, Recycle-Bin deletes, and link creation), move/copy, line-number patching, search (name / glob / regex / fuzzy / wait-for-file), in-place regex replacement, tree, counts, checksums, file and directory diffs, exact-match text editing. Confined to the allowed directories passed on the command line.
• 8 shell tools — synchronous, background, and interactive command execution implemented inside the MCP server process: no client-side permission toggles, survives client restarts, works with any MCP client.
• 1 code-execution tool (run_javascript_free) — run a JavaScript/TypeScript snippet on the Deno runtime with unrestricted permissions (full filesystem, network, env, child processes, arbitrary imports): the "free" counterpart to sandboxed run_javascript tools that confine code to a working directory.
• 6 git tools (git_status, git_diff, git_commit, git_log, git_add, git_checkout) — spawn the git CLI against the repo at the server process's current working directory (no new dependency, no working-directory parameter — the same "current working directory context" as the shell tools).
• 8 GitHub tools (gh_auth, gh_create_issue, gh_list_issues, gh_view_comments, gh_create_pr, gh_list_prs, gh_view_pr_diff, gh_push) — spawn the gh CLI (and git push for gh_push) against the repo at the server process's current working directory (no new dependency, no working-directory parameter — the same "current working directory context" as the git/shell tools).
• 6 system tools (get_system_info, read_clipboard, write_clipboard, send_notification, open_file, preview_html) — Beledarian-parity system utilities: OS/CPU/memory info, clipboard read/write (5-second timeout; empty clipboard = empty content, not an error), desktop notifications, opening files/URLs, and HTML preview. New dependency: node-notifier (notifications only; Windows toasts via the bundled snoretoast binary). open_file is the Beledarian-named equivalent of launch_file and delegates to the same internal launch helper.
• 3 document & database tools (read_document, query_database, analyze_project) — PDF/DOCX text extraction, read-only SQLite queries (built-in node:sqlite, no native dependency), and project-wide lint detection (npm lint script → eslint → pylint).
• 3 web tools (web_search, fetch_web_content, wikipedia_search) — multi-provider web search (DuckDuckGo → Google → Bing fallback chain), clean page-text extraction, and Wikipedia extracts.
• 2 RAG tools (rag_local_files, rag_web_content) — retrieval-augmented generation over local text files or a fetched URL, via a local OpenAI-compatible /v1/embeddings endpoint (default: LM Studio on 127.0.0.1:1234, bundled nomic-embed-text v1.5 model).
• 4 browser tools (browser_session_open, browser_session_control, browser_session_close, browser_open_page) — persistent headless Chrome sessions (scripted click/type/press/select/hover/scroll/evaluate actions, screenshots, fuzzy in-page find) plus a stateless one-shot page renderer; Chrome-for-Testing via puppeteer-core.
• 9 Beledarian-compatible aliases (execute_command, run_in_terminal, run_test_command, run_background_command, check_background_command, cancel_background_command, run_python, run_javascript, save_memory) — drop-in names, parameter shapes, and return shapes for the reference Beledarian plugin's tools (60 s sync cap; run_javascript = the confined Deno variant, NOT run_javascript_free).
• 1 sub-agent tool (consult_secondary_agent) — delegates a task to a secondary agent loop running against a local model endpoint (default: LM Studio on http://localhost:1234/v1); the sub-agent's tool calls execute in-process against this server's own handlers.
• 1 launcher tool (launch_file, Windows-only) — opens files, folders, and http(s) links in their OS default app, fully detached: returns the moment the opener is spawned (never waits for the app), no console window, no stdio inheritance; filesystem targets are confined to the allowed directories.
• Windows-first — drive roots, UNC roots, long paths beyond the 260-char MAX_PATH limit, cmd.exe /d /c with verbatim argv, whole-process-tree kills (taskkill /T /F), detached interactive console windows.
• NAS-safe startup — an allowed directory that is missing or offline (e.g., a powered-down network share) logs a warning and the server continues instead of exiting.

Requirements

• Node.js >= 20 (developed and tested on Node 22).
• Windows for the shell tools (they spawn cmd.exe, taskkill, and powershell). The filesystem tools work on any platform Node runs on.
• shell_python requires Python on the system PATH.
• run_javascript_free (unrestricted) and run_javascript (confined compat alias) require a Deno runtime: the $DENO_PATH env var, LM Studio's bundled binary (<home>/.internal/utils/deno(.exe) — auto-located by walking up from the server CWD or the user home), or deno on the PATH.
• The browser tools (browser_*) and web_search's browser legs require a Chrome-for-Testing executable: set MCP_CHROME_PATH, or place a build under the standard puppeteer cache <home>/.cache/puppeteer/chrome/win64-<version>/chrome-win64/chrome.exe (auto-detected, highest version wins).
• rag_local_files / rag_web_content require a local OpenAI-compatible embeddings endpoint (default: http://127.0.0.1:1234/v1/embeddings — LM Studio), and consult_secondary_agent requires a local chat-completions endpoint (default: http://localhost:1234/v1 — LM Studio).

Optional environment variables (all optional; when unset, behavior on the reference machine is preserved):

| Variable | Effect | Default | |---|---|---| | MCP_CHROME_PATH | Explicit Chrome-for-Testing executable | auto-detect the standard puppeteer cache, then the legacy path | | MCP_MEMORY_FILE | save_memory memory-file path | reference workspace memory.md, else <cwd>/memory.md | | MCP_RAG_EMBED_URL | RAG embeddings endpoint | http://127.0.0.1:1234/v1/embeddings | | MCP_RAG_EMBED_MODEL | Embeddings model id | text-embedding-nomic-embed-text-v1.5 | | MCP_API_TOKEN_FILE | API-token file for RAG + sub-agent Bearer auth | reference overnight token file (keyless when missing) | | MCP_SUBAGENT_ENDPOINT | Sub-agent chat-completions endpoint | http://localhost:1234/v1 | | MCP_SUBAGENT_MODEL | Sub-agent model id | local-model | | MCP_SUBAGENT_CWD | Sub-agent working dir (its file tools are confined to it) | server CWD | | MCP_SUBAGENT_PROFILES | JSON string {role: personaText} agent profiles | built-ins | | MCP_SUBAGENT_DEBUG | "1" = [Sub-Agent] console logging | off |

Quick start (npm)

Published on npm — npx downloads the server (and all dependencies) and runs it:

npx -y mcp-fs-shell-windows C:\ D:\

MCP client config (Claude Desktop / LM Studio mcp.json style):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "mcp-fs-shell-windows", "C:\\", "D:\\", "\\\\server\\share"]
    }
  }
}

The filesystem tools can only touch the passed directories (and anything under them). A root that cannot be accessed at startup logs a warning and is skipped; the server keeps running. Note that the shell tools are not root-restricted — see Security.

Build from source

For developers, or to run uncommitted changes:

git clone https://github.com/gerarddeluca/mcp-fs-shell-windows
cd mcp-fs-shell-windows
npm ci
npm run build
node dist\index.js <allowed-dir> [more-dirs...]

Then point your MCP config at node <path-to-repo>\dist\index.js with the allowed directories as the remaining args (same shape as the npx example above).

Unit tests cover the ported pure-function modules (browser actions, fuzzy search, sub-agent call parsing / validation / handoff): npm test.

Filesystem tools (30)

| Tool | Purpose | |---|---| | read_files | Read one or more files, line-numbered; offset/limit paging; per-file encoding (utf8/utf16le/utf16be/cp1252, auto-detected when omitted) | | write_new_files | Create files (per-file overwrite, textEncoding utf8/utf16le/utf16be/cp1252, optional base64 for binary) | | append_files | Append to files (creates them if missing) | | delete_files | Delete files/directories (recursive; junctions/symlinks are removed as links, never followed; toRecycleBin - Windows: send to Recycle Bin instead of permanent delete) | | copy_file | Copy files/directories (recursive, overwrite) | | transfer_files | Move/rename items (overwrite, creates parent dirs) | | patch_files | Patch by line ranges (replace/insertBefore/delete, dryRun, git-diff output) | | create_directories | Create directory paths (nested chains) | | list_directory | Single-level listing ([FILE]/[DIR]/[LINK] prefixes, sizes, pagination, type filter, ignore globs) | | directory_tree | Recursive tree view (JSON) with exclusion patterns; includes empty dirs and link nodes | | search_files | Recursive case-insensitive name-substring search | | search_regex | Content grep over a single file or directory tree (paged; total + per-file match counts, countOnly mode) | | search_glob | Glob-based file search (e.g. **/*.ts, paged) | | fuzzy_find_files | Typo-tolerant name/path search (Levenshtein) | | delete_files_by_pattern | Regex delete within a single directory | | count_lines | Line counts with filters | | file_diff | Unified diff of two files | | content_diff | Unified diff of two strings | | checksum_files | md5/sha1/sha256/sha512 for files | | checksum_files_verif | Verify files against expected hashes | | get_file_info | Size, timestamps, type, permissions, isReparsePoint, (Windows) NTFS attributes | | edit_files | Exact-match text replacement, EOL-tolerant (dominant line ending preserved) | | read_bytes | Read raw bytes at (offset, length) as base64 JSON — any binary file, any size | | write_bytes | Write raw bytes (base64) into an existing file at an offset — in place, or extend past EOF (gap zero-filled) | | replace_regex | In-place regex replacement across one or more files; dryRun defaults to true (unified-diff preview); preserves dominant line endings | | dir_diff | Recursive two-directory comparison (added/removed/changed/identical; unified diff for changed text files; ignore globs, maxFiles cap) | | convert_encoding | Convert a file's text encoding (utf8/utf16le/utf16be/cp1252, source auto-detected) to a new file | | wait_for_file | Poll until at least one file matching a glob appears under a directory (configurable timeout/interval) | | create_link | Create a hardlink, directory junction, or file/directory symlink to an existing target (auto/symlink/junction/hardlink) | | list_allowed_directories | List the allowed root directories |

Shell tools (8, Windows-only)

User commands are spawned as cmd.exe /d /c <command> with verbatim argv — quotes, redirects, and metacharacters arrive byte-for-byte (Node windowsVerbatimArguments), and /d skips AutoRun registry entries.

| Tool | Purpose | |---|---| | shell_run | Synchronous command (default 5 s, max 28 s); non-zero exit or timeout returns the captured stdout/stderr instead of hiding it | | shell_test | Test wrapper (runs with CI=true); never errors on a failing test | | shell_start | Background job — returns immediately with a job ID; auto-kills at timeout_hours (max 10); 256 KB in-memory tail + log file | | shell_check | Job status, stdout/stderr tails, log file path | | shell_cancel | Kill the whole process tree (taskkill /T /F, with PID-liveness fallback) | | shell_terminal | Open a visible, separate, interactive cmd /k console window running the command; the window persists after the command finishes; close it with shell_cancel | | shell_python | Run a Python snippet (temp .py + system Python) | | shell_cwd | Get/set the default working directory for the other shell tools (every tool also accepts a per-call cwd) |

Practical notes:

• Background jobs live in an in-memory registry inside the server process: the table is lost on server restart, but job log files persist (under %TEMP%\mcp-fs-shell-windows\shell-jobs).
• timeout /t can fail when stdin is not an interactive console — use ping -n N 127.0.0.1 >nul for sleeps.
• Synchronous calls are bounded (max 28 s) so they cannot wedge the MCP request channel; anything longer should go through shell_start.

Code-execution tool (1)

| Tool | Purpose | |---|---| | run_javascript_free | Run a JS/TS snippet on the Deno runtime with unrestricted permissions: full filesystem read/write (any drive or UNC path the server user can reach), network, environment, child processes, and arbitrary imports (node:*, npm:*, https:*). Temp .ts file + deno run --allow-read --allow-write --allow-net --allow-env --allow-sys --allow-run --allow-ffi --allow-import. Default 5 s timeout, max 60 s; optional cwd (defaults to the shell_cwd default). Non-zero exit or timeout returns an error that still includes the captured stdout/stderr (100 KB / 20 KB caps). The Deno binary is located via $DENO_PATH → <ancestor>/.internal/utils/deno(.exe) (walk-up) → <home>/.lmstudio/.internal/utils/deno(.exe) → PATH. |

Git tools (6)

Operate against the repo at the server process's current working directory (the directory the server was launched in, e.g. the chat working directory). Implemented by spawning the git CLI directly — no new dependency, and argument values (messages, branch names, file paths) never pass through a shell: they go verbatim as argv elements. Path arguments (git_diff.file_path, git_add.paths) resolve relative to the working directory. A working directory that is not inside a git repository yields a clear {error} string, not a crash.

| Tool | Purpose | |---|---| | git_status | Branch, upstream, ahead/behind, isClean, plus staged / not-staged / untracked file lists (JSON: {current, tracking, ahead, behind, isClean, staged, notStaged, untracked, files}). | | git_diff | Working-tree or staged (cached: true) unified diff, optionally limited to one file (file_path). Returns {diff} (or {diff: "No changes."}). | | git_commit | Commit staged changes with message; returns {success, summary: {changed, insertions, deletions}}. Standard git behavior: only what is staged gets committed. | | git_log | Recent commits, newest first, capped by max_count (default 10): {history: ["<hash> <subject> (<author>, <date relative>)", ...]}. | | git_add | Stage specific paths or, when omitted, all changes (git add .). Returns {success, message}. | | git_checkout | Switch to an existing branch, or create + switch with create_new: true (git checkout -b). Returns {success, message}. |

GitHub tools (8)

Operate against the repo at the server process's current working directory (no working-directory parameter — gh itself resolves the repo from that directory's git remote, exactly as the reference Beledarian tools do). Implemented by spawning the gh CLI directly (no new dependency; gh_push spawns git push origin [branch]), and argument values (titles, bodies, labels, branch names, issue/PR numbers) go verbatim as argv elements — they never pass through a shell. Long issue/PR bodies are written to a temp file in the working directory and passed via --body-file (mirroring the reference); the temp file is always removed. gh is resolved from PATH first (the reference's checkGhInstalled), then from the known portable install <home>\tools\gh\bin\gh.exe (this machine's layout); if neither is found, a clear {error} string is returned. gh_auth runs gh auth status and, on failure, opens a detached terminal window (cmd /k, spawned with ignored stdio so it outlives the tool call) for interactive gh auth login — using the resolved absolute gh path so the window works even when gh is not on the inherited PATH.

| Tool | Purpose | |---|---| | gh_auth | Check GitHub authentication status. On failure, open a detached terminal window for gh auth login (the window persists for the user to sign in). Returns {success: true, message} or {error}. | | gh_create_issue | Create a new issue with title, optional body (temp --body-file) and optional labels (each -l). Returns {success: true, url} or {error}. | | gh_list_issues | List issues in the CWD repo: state (default open), optional labels, limit (default 10, max 50). Returns {issues: [{number, title, state, url, labels}]} (empty array = no matches) or {error}. | | gh_view_comments | View comments on issue/PR number (type default issue). Returns {comments: [...]} or {error}. | | gh_create_pr | Create a PR: title, head_branch, optional body (temp --body-file), base_branch (default main). Returns {success: true, url} or {error}. | | gh_list_prs | List PRs in the CWD repo: state (default open), limit (default 10, max 50). Returns {pull_requests: [{number, title, state, url, headRefName, baseRefName}]} or {error}. | | gh_view_pr_diff | Fetch the PR's patch/diff for number. Returns {diff} (truncated to 50,000 chars with a marker) or {error}. | | gh_push | Push local commits to the remote (git push origin [branch]); branch optional, defaults to the current branch. Returns {success: true, message} or {error}. |

Launcher tool (1, Windows-only)

| Tool | Purpose | |---|---| | launch_file | Launch a file, folder, or http(s) link via the Windows shell opener (explorer.exe — the OS default association: VLC for .mkv, Explorer for folders, default browser for web links). The target is passed as a single argv element (spaces, Unicode, &, apostrophes, parentheses all safe) and the call returns as soon as the opener process is actually spawned — it never waits for the opened app, creates no console window, and inherits no stdio pipes. Filesystem paths are subject to the allowed-root policy and checked for existence; only http:///https:// links are launched, every other URL scheme (file:, javascript:, ms-*, steam:, …) is rejected, so no file: URI can bypass the filesystem policy. A failed opener spawn errors instead of reporting success. The response reports dispatched: true (the opener process was created) — not that the app handled the target. A host-settable LAUNCH_FILE_OPENER env var overrides the opener executable (test seam). |

System tools (6)

Beledarian-parity system utilities, ported from the reference Beledarian toolsProvider (same names, parameter shapes, and return shapes). No working-directory parameter; the clipboard and notification tools work on any platform Node runs on (PowerShell / pbpaste / xclip branches, as in the reference), while open_file and preview_html are Windows-only (they use the same explorer.exe detached opener as launch_file).

| Tool | Purpose | |---|---| | get_system_info | OS/CPU/memory info via the Node os module. No parameters. Returns {platform, arch, release, hostname, total_memory, free_memory, cpus, node_version} (memory in bytes). | | read_clipboard | Read the system clipboard (powershell -command Get-Clipboard on Windows; pbpaste on macOS; xclip elsewhere) with a 5-second race timeout. An empty clipboard returns content "" (not an error). Returns {content} or a clear error. | | write_clipboard | Write text to the clipboard. On Windows the content is base64-encoded into the PowerShell command line and Set-Clipboard stores the decoded text (no escaping issues for quotes / newlines / Unicode); pbcopy on macOS, xclip via stdin elsewhere. 5-second race timeout. Returns {success: true} or a clear error. | | send_notification | Send a desktop notification (title, message) via node-notifier (Windows toast through the bundled snoretoast; balloon fallback) — fire-and-forget (sound: true, wait: false), as in the reference. Returns {success: true, message}. | | open_file | Open a file path or http(s) URL in the OS default app. The Beledarian-named equivalent of launch_file: same target parameter, same policy (allowed-roots for filesystem paths + existence check; only http/https URLs), same internal launch helper. Returns {success: true, message} or a clear error. | | preview_html | Write html_content to a temp .html file in the system temp dir (user-supplied file_name reduced to its last path segment; default preview_<timestamp>.html), launch it in the default browser with the same detached opener, and leave the file on disk. Returns {success: true, path, message}. |

Document & database tools (3)

| Tool | Purpose | |---|---| | read_document | Read text + metadata from a PDF (pdf-parse) or DOCX (mammoth) file; other formats return a clear error. | | query_database | Run a read-only SQL query against a SQLite database via Node's built-in node:sqlite (no native dependency); write statements (INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/REPLACE) are rejected up-front. | | analyze_project | Run project-wide linting: auto-detects the project's linter (npm lint script → eslint → pylint) and runs it with a 60 s timeout, returning the report (capped at 10,000 chars). |

Web tools (3)

Ported from the reference Beledarian plugin (the DuckDuckGo chain and the Wikipedia API are near-verbatim; the browser legs share the single puppeteer launcher above).

| Tool | Purpose | |---|---| | web_search | Multi-provider web search with a fallback chain (DuckDuckGo fetch → api → html, then Google, then Bing — the html/google/bing legs run in the headless browser); per-provider errors are collected, not fatal; optional providers list to force an order; results deduped by link. | | fetch_web_content | Fetch a URL and return clean, text-based page content (title + body via html-to-text, 40,000-char cap). | | wikipedia_search | Search Wikipedia via the MediaWiki API: top-3 pages + intro extracts (2,000-char cap each), optional lang. |

RAG tools (2)

Retrieval-augmented generation over local text or a fetched URL. Embeddings go through a local OpenAI-compatible /v1/embeddings endpoint (default: LM Studio on 127.0.0.1:1234, model text-embedding-nomic-embed-text-v1.5; override with MCP_RAG_EMBED_MODEL / MCP_RAG_EMBED_URL); Bearer token from MCP_API_TOKEN_FILE when present (keyless otherwise).

| Tool | Purpose | |---|---| | rag_local_files | Recursively scan up to 50 text files under a directory (binary extensions skipped), chunk by paragraph, and return the top 10 chunks scoring above cosine similarity 0.4 against the query ({file, score, content}). | | rag_web_content | Fetch a URL, convert it to plain text, and return the top 5 chunks most relevant to the query. |

Browser tools (4)

Headless Chrome-for-Testing via puppeteer-core (executable resolution: MCP_CHROME_PATH → standard puppeteer cache → legacy path). One persistent session per server process: browser_session_open replaces the existing session (closing its browser first), and the session holds its own instance so web_search's legs can never close it mid-session.

| Tool | Purpose | |---|---| | browser_session_open | Open the persistent session, navigate (networkidle0, 30 s timeout), optional wait_for_selector, full page-text capture. | | browser_session_control | Scripted actions on the active page (wait / click / type / press / select / hover / scroll / evaluate), page metadata / full-text reads, screenshots (optionally full page), fuzzy in-page find. | | browser_session_close | Close the active session (idempotent). | | browser_open_page | Stateless one-shot render: navigate, optional scripted actions + screenshot, return page text (5,000-char cap). Never touches the persistent session. |

Beledarian-compat aliases (9)

Drop-in names, parameter shapes, and return shapes for the reference Beledarian plugin's tools, so existing prompts and tool documentation keep working. Each alias delegates to this server's native handler (identical behavior and job-registry lifetime); the synchronous ones keep Beledarian's 60 s cap (the native shell_* tools cap at 28 s).

| Tool | Purpose | |---|---| | execute_command | Bounded synchronous execution — alias of shell_run with the 60 s cap and the same result shape ({command, exitCode, stdout, stderr, timedOut, duration_ms, cwd}). | | run_in_terminal | Open a separate, visible, interactive cmd /k console window — alias of shell_terminal. | | run_test_command | Test wrapper (CI=true), never errors on a failing test — alias of shell_test. | | run_background_command | Start a background job with a descriptive name — alias of shell_start. | | check_background_command | Job status, stdout/stderr tails, log-file path — alias of shell_check. | | cancel_background_command | Kill the whole job process tree — alias of shell_cancel. | | run_python | Run a Python snippet (temp .py + system Python) — alias of shell_python with the 60 s cap. | | run_javascript | Run a JS/TS snippet in the confined Deno sandbox (--allow-read=. --allow-write=., net/env/sys/run/ffi denied) — the reference plugin's run_javascript semantics; NOT an alias of run_javascript_free. | | save_memory | Append a timestamped fact to the memory file (path: MCP_MEMORY_FILE → reference workspace memory.md → <cwd>/memory.md), creating it with a # Long-Term Memory header when missing. No enable gate. |

Sub-agent tool (1)

| Tool | Purpose | |---|---| | consult_secondary_agent | Delegate a task to a secondary agent loop running against a local model endpoint (default http://localhost:1234/v1, model local-model — the LM Studio Developer API). Tool calls are parsed out of prose, validated, and executed in-process against this server's own handlers (file ops confined to the sub-agent's working directory); code blocks from the final response are auto-saved. Returns {response, generated_files, filesModified, handoff_message?} or {error}. |

Docker

docker build -t mcp-fs-shell-windows .
docker run -i --rm -v /path/to/dir:/data mcp-fs-shell-windows /data

The filesystem tools work in the image; the shell tools require a Windows host with cmd.exe.

Differences from the base fork

v0.2.1 — official-server parity: head/tail reads (offset/limit in read_files), sizes in listings, overwrite in write_new_files, exact-match text editing (edit_files).

transfer_files (renamed from move_files): the canonical move/rename tool. Renamed because at least one MCP client (observed in LM Studio) silently drops tools named move_files/mv_files from the exposed tool list; transfer_files is registered last in the tools array.

Robustness patches:

• Missing/offline allowed roots warn at startup instead of exiting (NAS-down safe).
• validatePath walks to the nearest existing ancestor, so writes under brand-new nested directories work.
• ensureDirectoryExists at all mkdir sites (Node EPERM quirk on drive-root writes).
• Move-handler destination checks use errno ENOENT, so moves to fresh destinations succeed.
• zod pinned to ^3.23.8 (zod v4 breaks the SDK's schema conversion).

v0.2.2 — shell tools as listed above, with whole-process-tree kills and the detached interactive console window.

v0.2.4 — verbatim argv: windowsVerbatimArguments + /d on all user-command spawns (run/test/start and the terminal launcher).

v0.2.7 — launch_file: the detached OS launcher (see above). Renamed from a local open_file prototype so it cannot collide with other servers' open_file tools. Hardened: spawn-failure returns an error (the handler awaits the child's spawn/error events — it never reports success for a process Windows refused to create), URLs are restricted to http(s) so file: URIs cannot bypass the allowed-root policy, and non-Windows platforms fail with a clear error.

v0.2.8 — line-ending preservation: patch_files and edit_files preserve the file's dominant line ending (CRLF or LF) on write.

v0.2.9 — read_bytes / write_bytes: raw binary access at (offset, length) — base64 reads from any part of a file (any size, e.g. GGUFs and blobs) and in-place byte writes into existing files (extend: true grows the file past EOF, zero-filling the gap).

v0.2.10 — dir_diff: recursive comparison of two directory trees — added/removed/changed/identical, unified diffs for changed text files, ignore glob patterns, and a maxFiles cap.

v0.2.11 — text encoding support: per-file encoding in read_files (utf8/utf16le/utf16be/cp1252, auto-detected from BOMs when omitted), textEncoding in write_new_files, and convert_encoding to transcode a file into a new encoding.

v0.2.12 — wait_for_file: polling file watcher — waits (up to timeoutMs, default 30 s, max 300 s) until at least one file matching a glob appears under a directory.

v0.2.13 — search_regex match totals: every pattern occurrence is counted (a line matching N times counts N); responses end with the total and per-file counts, and countOnly: true returns counts without the matching line text.

v0.2.14 — replace_regex: in-place regex replacement across one or more files (directories are rejected). dryRun defaults to true with a unified-diff preview; applied replacements preserve each file's dominant line ending; a missing path or invalid regex errors without writing anything.

v0.2.15 — reparse-point safety: junctions/symlinks are never followed. delete_files removes them as links (including nested links inside recursive deletes) without touching their targets; list_directory shows [LINK] entries; directory_tree reports link nodes and includes empty directories; get_file_info adds isReparsePoint and (on Windows) NTFS attributes.

v0.2.16 — long-path support: paths beyond the 260-char MAX_PATH limit work on Windows via \\?\ extended-length form (drive and UNC), transparent to callers.

v0.2.17 — delete_files toRecycleBin: send deletes to the Windows Recycle Bin instead of permanent removal. Reparse points are still removed as links (the bin cannot hold them), and any path that cannot be recycled is reported as an error — never silently hard-deleted.

v0.2.18 — create_link: create hardlinks, directory junctions, and file/directory symlinks (type: auto | symlink | junction | hardlink) with strict checks: the target must exist, the link path must not, and the link path's parent must exist.

v0.2.20 — run_javascript_free: unrestricted JS/TS code execution on the Deno runtime — full filesystem, network, env, child-process, and import permissions (no working-directory sandbox). Reuses the shell layer's spawn/capture machinery (temp .ts in the shell-jobs dir, whole-tree kill on timeout, 100 KB / 20 KB output caps). The Deno binary is auto-located ($DENO_PATH → LM Studio's bundled .internal/utils/deno(.exe) via CWD walk-up or user home → PATH); missing binary yields a clear error. Default 5 s timeout, max 60 s.

v0.2.21 — git tools: six new tools (git_status, git_diff, git_commit, git_log, git_add, git_checkout) that spawn the git CLI against the repo at the server process's current working directory (no working-directory parameter; path arguments resolve against it). No new dependency. Failure (e.g. working directory not inside a git repository) returns a clear {error} string, mirroring the reference Beledarian tool shapes ({diff}, {history}, {success, ...}).

v0.2.22 — GitHub tools: eight new tools (gh_auth, gh_create_issue, gh_list_issues, gh_view_comments, gh_create_pr, gh_list_prs, gh_view_pr_diff, gh_push) that spawn the gh CLI (and git push for gh_push) against the repo at the server process's current working directory — no new dependency, no working-directory parameter (gh resolves the repo from the CWD's git remote, as the reference Beledarian tools do). gh is found on PATH (the reference's checkGhInstalled) with a documented fallback to the known portable install <home>\tools\gh\bin\gh.exe. Long issue/PR bodies go via a temp --body-file in the working directory (always cleaned up); a failed gh auth status opens a detached cmd /k terminal for interactive gh auth login. Failure (missing gh, bad remote/branch, unauthenticated) returns a clear {error} string, mirroring the reference tool shapes ({success, url}, {issues}, {pull_requests}, {comments}, {diff}).

v0.2.23 — system tools: six new tools (get_system_info, read_clipboard, write_clipboard, send_notification, open_file, preview_html) ported from the reference Beledarian toolsProvider (same names, parameter shapes, and return shapes): OS/CPU/memory info via the Node os module; clipboard read/write with the reference's platform branches (PowerShell Get-Clipboard / Set-Clipboard on Windows, pbpaste / pbcopy / xclip elsewhere), its 5-second race timeout, its base64 Set-Clipboard approach (no escaping issues), and its empty-clipboard-is-empty-content behavior; desktop notifications via node-notifier (the only new runtime dependency — Windows toasts through the bundled snoretoast, fire-and-forget sound: true, wait: false); open_file (the Beledarian-named launch_file equivalent: same target parameter, policy, and internal launch helper, reference success shape); and preview_html (temp .html in the system temp dir, launched in the default browser, temp path returned). openerPath() in launch_file/handler.ts gained export (no behavior change) so preview_html reuses the exact same opener resolution.

v0.2.24 — document, database, and project tools: read_document (PDF via pdf-parse 2.x + DOMMatrix polyfill; DOCX via mammoth), query_database (read-only SQLite via Node's built-in node:sqlite — no native dependency; write statements rejected up-front), analyze_project (lint detection: npm lint script → eslint → pylint; 60 s timeout; 10,000-char report cap).

v0.2.25 — web tools: web_search (DuckDuckGo fetch/api/html → Google → Bing fallback chain, ported near-verbatim from the reference; browser legs share the single puppeteer launcher), fetch_web_content (html-to-text clean page text, 40,000-char cap), wikipedia_search (MediaWiki API, top 3 + intro extracts). New deps: duck-duck-scrape, puppeteer-core.

v0.2.26 — RAG tools: rag_local_files / rag_web_content — paragraph chunking, cosine similarity > 0.4, top 10 / top 5; embeddings via the local /v1/embeddings endpoint (default model text-embedding-nomic-embed-text-v1.5; MCP_RAG_EMBED_MODEL / MCP_RAG_EMBED_URL overrides). No new deps (node fetch).

v0.2.27 — browser tools: browser_session_open / browser_session_control / browser_session_close (one persistent session per server process) + stateless browser_open_page; scripted actions, screenshots, fuzzy find; ported browserActions.ts / fuzzySearch.ts with unit tests. No new deps beyond v0.2.25's puppeteer-core.

v0.2.28 — Beledarian-compat aliases: save_memory + 8 aliases (execute_command, run_in_terminal, run_test_command, run_background_command, check_background_command, cancel_background_command, run_python, run_javascript) — drop-in names/shapes for the reference plugin's tools, delegating to native handlers with the reference's 60 s synchronous cap. No new deps.

v0.2.29 — sub-agent tool: consult_secondary_agent — delegated agent loop against the local model endpoint (default http://localhost:1234/v1, model local-model); tool calls parsed from prose, validated, and executed in-process against the fork's own handlers (file ops confined to the sub-agent's CWD); handoff-message extraction + auto-save of final code blocks. No new deps.

Publish portability (v0.2.29): the Chrome-for-Testing executable is resolved as MCP_CHROME_PATH → standard puppeteer cache (<home>/.cache/puppeteer/chrome/, highest version) → legacy path; MCP_API_TOKEN_FILE selects the API-token file for RAG + sub-agent Bearer auth; MCP_RAG_EMBED_URL selects the embeddings endpoint; the save_memory path is MCP_MEMORY_FILE → reference workspace → <cwd>/memory.md. With every env var unset, behavior on the reference machine is unchanged.

Security

• The filesystem tools are confined to the allowed directories passed at startup (and their subtrees).
• The shell tools are not confined: anything the server process's user can execute will run, including against reachable network shares. Grant this server the same trust you would grant an unsandboxed shell.
• launch_file targets are confined to the allowed directories (for paths), but the opened application runs with the full rights of the server user — like anything you double-click.
• run_javascript_free is not confined: the snippet runs as an unsandboxed Deno process with the full rights of the server user (filesystem, network, processes). Grant this server the same trust you would grant an unsandboxed shell.
• consult_secondary_agent delegates to a local model endpoint (default http://localhost:1234/v1); the sub-agent's file tools are confined to its working directory (default: the server's CWD, override with MCP_SUBAGENT_CWD), and its tool calls execute in-process against this server's own handlers.
• The server communicates over stdio and opens no network listeners of its own; the web, RAG, browser, and sub-agent tools make outbound calls to the endpoints documented above.

License

MIT — see LICENSE. This project derives from MIT-licensed code (Anthropic, PBC; fabienvauchelles; Laurin Feulner / Beledarian); all copyright notices are in the LICENSE file.