Filesystem MCP Server

TypeScript implementation of a local filesystem MCP server with bounded inspection, comparison, and mutation surfaces.

This root README is the DX-first entrypoint. It keeps only shared orientation and routes detailed tool guidance to endpoint-local README.md files.

Read this next

Need	Start here
Shared conventions and cross-endpoint rules	CONVENTIONS.md
Shared architecture and ownership boundaries	DESCRIPTION.md
Tool-specific quick guidance	Endpoint-local README.md links below

Architecture at a glance

Layer	Responsibility
application	MCP bootstrap, tool-catalog composition, stable server framing, and server-scope exposure
domain	Tool-specific handlers, schemas, results, and runtime semantics
infrastructure	Path guarding, logging, persistence, and shared technical helpers

Shared developer rules

• All path-based operations stay inside configured allowed directories.
• Broad-root discovery and recursive inspection default-exclude vendor, cache, and generated trees unless callers explicitly target them or reopen named descendants.
• Resume-capable inspection families stay same-endpoint and continue through resumeToken plus the appropriate resumeMode.
• Primary result data stays complete in content.text; structuredContent adds machine-readable envelope metadata and mirrored structured payloads.
• Public read surfaces remain intentionally split: read_files_with_line_numbers for bounded inline batch reads, read_file_content for advanced single-file modes.

External dependency for content search

The regex, fixed-string, and native pattern-aware count lanes depend on the native ugrep executable.

This dependency is now resolved during MCP server startup preflight, not lazily during request execution. The server expects one of these runtime conditions:

• UGREP_EXECUTABLE_PATH points to the native shell-free ugrep binary, or
• the MCP server process PATH already contains the directory that holds the native ugrep executable.

A successful ugrep --version check in an interactive shell is helpful, but it is not sufficient by itself. The decisive environment is the Node.js process that runs the MCP server.

Common installation examples:

• Debian/Ubuntu: apt-get install ugrep
• Fedora/RHEL/CentOS: dnf install ugrep
• Arch: pacman -S ugrep
• macOS: brew install ugrep
• Windows: winget install Genivia.ugrep or choco install ugrep

After installation, verify with ugrep --version and then restart the MCP client or IDE process that launches the server so the server runtime can inherit the updated environment.

Windows permanent fix when ugrep --version is not available

If ugrep is installed on Windows but ugrep --version still cannot be executed, you MUST apply the permanent Chocolatey fix below.

This usually means ChocolateyInstall is set incorrectly and Chocolatey created the package under the wrong root.

Run:

[Environment]::SetEnvironmentVariable('ChocolateyInstall','C:\ProgramData\chocolatey','Machine')
$env:ChocolateyInstall = 'C:\ProgramData\chocolatey'
$env:Path = "C:\ProgramData\chocolatey\bin;$env:Path"
choco install ugrep --force -y

Then open a new PowerShell window and verify again:

ugrep --version

If the MCP server still cannot start native search afterward, configure UGREP_EXECUTABLE_PATH with the absolute path to ugrep.exe for the process that launches the MCP server.

Endpoint README TOC

Application/server scope

• list_allowed_directories

Inspection — discovery

• list_directory_entries
• find_paths_by_name
• find_files_by_glob

Inspection — metadata and integrity

• get_path_metadata
• get_file_checksums
• verify_file_checksums

Inspection — search family and count

• inspection/search family README
• search_file_contents_by_regex
• search_file_contents_by_fixed_string
• count_lines

Inspection — read

• read_files_with_line_numbers
• read_file_content

Comparison

• diff_files
• diff_text_content

Mutation — content

• create_files
• append_files
• replace_file_line_ranges

Mutation — path

• create_directories
• copy_paths
• move_paths
• delete_paths

Documentation boundary

Root documentation stays shared and non-redundant:

• README.md = DX-first entrypoint
• DESCRIPTION.md = architecture index
• CONVENTIONS.md = shared conventions and leaf-slice routing
• endpoint-local README.md files = detailed developer-facing guidance per public endpoint

This root file is intentionally a navigation surface, not a second endpoint-by-endpoint manual.