rust-fs-mcp

rust-fs-mcp is a Rust stdio MCP server that ports the public fs-mcp tool contracts to a native Rust implementation. It exposes filesystem, search, and git tools through line-oriented JSON-RPC over stdin/stdout.

The project keeps the Node fs-mcp contract shape where it matters: public tool names, batch-first inputs, large-argument references through args_path-style fields, and the normalized fs-mcp response envelope.

Status

• 24 MCP tools are exposed through tools/list and covered by the tool matrix integration test.
• The server handles initialize, tools/list, tools/call, resources/list, and resources/templates/list.
• Filesystem and inspection tools run in native Rust code paths.
• Search and git tools wrap external CLI tools resolved from PATH.
• rg, fd, and git must be installed and resolvable on PATH for search, exclude-aware listing, and git tools.
• web-fetch, web-extract, and download-to-file run on a native tokio-free HTTPS client (ureq); web-render optionally shells out to an installed obscura(-like) headless-browser CLI for JS/SPA rendering.
• Resources are currently empty because this project focuses on tool parity first.

Install

Prebuilt binaries are published for every tagged release. Pick the asset that matches your platform from the latest release, or use the direct URL pattern:

https://github.com/jungho-dev/rust-fs-mcp/releases/download/<tag>/rust-fs-mcp-<target>.zip

Each archive ships with a matching <asset>.sha256sum file. A source tarball rust-fs-mcp_src.tar.gz is also attached to every release.

Verify before extracting:

# Unix

shasum -a 256 -c rust-fs-mcp-x86_64-unknown-linux-gnu.zip.sha256sum

# Windows PowerShell
(Get-FileHash -Algorithm SHA256 .\rust-fs-mcp-x86_64-pc-windows-msvc.zip).Hash
# compare against the contents of the .sha256sum file

Releases are produced by .github/workflows/release.yml. The workflow funnels three event shapes through a single resolve job:

• git push origin main reads the version field of Cargo.toml. If v<version> does not exist on origin yet, the workflow creates and pushes that tag, then publishes the release. Pushes whose v<version> tag already exists are no-ops.
• git push origin v<X.Y.Z> releases that exact tag.
• A manual workflow_dispatch with an explicit tag input releases that tag.

In the auto-tag path the workflow commits the tag as github-actions[bot] and uses the default GITHUB_TOKEN, so no extra secrets are required.

Build From Source

cargo build --release
# binary at: target/release/rust-fs-mcp (rust-fs-mcp.exe on Windows)

To cross-build a specific target locally, install the target and pass --target:

rustup target add aarch64-apple-darwin
cargo build --release --target aarch64-apple-darwin

Tool Surface

Runtime Model

The binary runs as a stdio server. Each input line is one JSON-RPC request, and each response is written as one line.

cargo run --release

Example initialize request:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

Example tool listing request:

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

Example tool call:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"dir-list","arguments":{"items":[{"path":"."}]}}}

Fixed Behavior

Runtime behavior is not configurable through project environment variables or process-global settings.

• The full 23-tool catalog is always exposed; the fixed always-load annotations remain on the core file, search, edit, and git read tools.
• Responses always use the compact envelope: {data, durationMs} plus error only on failure.
• Whole-file reads are capped at 100,000 characters; use offset and length to page larger files.
• Batch plans use fixed workload limits (read 3/8, stat 4/16, search 2/2, fetch 2/32, download 2/16).
• fs-inspect uses a fixed 25-second internal deadline.
• Local filesystem paths are resolved without an allowed-root policy. Git tools require an explicit path on every call.
• The SSRF guard always blocks non-public addresses; web-render always rejects evalScript.
• External CLIs, including obscura, are resolved from PATH.

Response Envelope

Every tool call is normalized through the same envelope:

• content contains display text for MCP clients.
• structuredContent.data.content contains normalized content blocks; result bodies (file contents, search lines, diffs, listings) are carried here exactly once.
• structuredContent.data.structuredContent contains tool-specific structured metadata only (counts, paths, backends); it never duplicates the body.
• structuredContent.durationMs is the tool duration.
• structuredContent.error appears only on failure with {message}.
• The compact envelope is always used; it omits data.text, error:null, schemaVersion, status, and toolName on successful calls.
• _meta.fsMcpResult mirrors status, duration, content type, and structured-content presence.
• isError is set on tool failures.

Batch tools return per-item {index, ok, data} entries plus succeededCount, failedCount, and totalCount; the full envelope restores per-item {index, input, ok, result} entries with the verbatim request echo.

Module Layout

See architecture.md for the detailed request flow and module contracts.

Filesystem Tools

Filesystem tools resolve paths through the runtime config boundary before reading or writing. Relative paths are resolved against the current process directory, home paths beginning with ~ are expanded, and lexical components are normalized.

Supported behavior includes:

• Text, binary, image, and directory reads.
• Local text line-range reads with 1-based start_line and optional line_count. file-read-line-range uses native Rust streaming.
• Rewrite and append writes.
• Directory creation and listing with depth, maxEntries, includeFiles, excludePatterns, and allowMissing. dir-list uses native Rust traversal and falls back to fd from PATH when excludePatterns are supplied.
• Copy, move, recursive remove, metadata reads, exact block replacement (file-edit, which rejects an empty old_string), and 1-based line-range replacement (file-edit-lines, which preserves the original line endings including a missing final newline).
• file-read isUrl: true reads HTTP/HTTPS URLs through the shared core::web client: per-hop SSRF guard, redirect following, and a body-size cap. See Web Tools below for the dedicated web-fetch/web-render/web-extract/download-to-file tools.

Search Tools

fs-search runs a ripgrep-compatible regular-expression content search and returns the batch result directly.

Search supports:

• ignoreCase, contextLines, includeHidden, filePattern, and maxResults.
• Binary-file skipping for content search.
• pattern_path indirection for large patterns and filePattern to narrow the target files.
• content search shells out to ripgrep (rg) resolved from PATH, which must be installed.

Git Tools

Git tools require a path for every call, then invoke the git CLI resolved from PATH inside the resolved worktree.

Implemented behavior includes:

• git-status runs status --porcelain --branch and returns the porcelain lines.
• git-add stages paths through git add and forwards all (--all), update (--update), and force (--force); all and update stage changes without an explicit pathspec.
• git-commit injects a default committer identity (user.name=rust-fs-mcp, user.email=rust-fs-mcp@example.invalid) so commits work without local git config, accepts an optional author override, and supports amend, allow-empty, and no-verify.
• git-amend rewrites the last commit: it reuses the existing message with --no-edit when no message is given, otherwise validates a new Conventional Commit message, and supports an author override or reset-author (mutually exclusive), staging files first, allow-empty, and no-verify.
• git-diff runs git diff with optional staged, name-only, stat, source/target, contextLines (mapped to --unified=), check (mapped to --check, flagging whitespace errors and leftover conflict markers), and path filters.
• git-show renders an object or object:path through git show.
• git-diff (source/target) and git-show (object/objects) reject revision values that begin with -, so a revision cannot smuggle git options such as --output.

Commit messages must start with a Conventional Commit header (lowercase English type; the summary may be any language).

Inspect Tool

fs-inspect answers several read-only questions about a directory tree in one batched call. It takes a root and a list of requests and returns one answer per request with status, confidence, evidence snippets, and aggregate metrics. The shared maxSnippetChars budget (default 6000) caps evidence text so large scans stay token-bounded.

Supported request ops:

• count-files: count files matching a glob, with optional recursion and sample paths.
• search: regex or literal content search with optional field extraction and per-file pattern filtering.
• json-pick: read a JSON file and return values at the given JSON pointers.
• snippet: return context-bounded snippets around lines that contain any of the given patterns.
• git-status: fold a git-status lookup into the same call so reads, searches, and git state resolve in one round-trip.

Directory traversal for count-files and search does not follow symlinks or Windows junctions, so reparse-point cycles cannot cause unbounded recursion.

Web Tools

The web tier is a two-tier design: a native fetch path for static content and an external headless-browser path for JS-rendered pages.

• web-fetch (TIER-1): native ureq blocking HTTPS client with no async runtime. Batches items[] or a single url, and dumps html, text, markdown, links, or readability (main-content extraction).
• web-render (TIER-2): shells out to an obscura(-like) headless-browser CLI resolved from PATH for JavaScript/SPA pages, with selector, wait, waitUntil, and stealth. Try web-fetch first; escalate only when the page needs JS execution. evalScript is disabled.
• web-extract: converts HTML you already hold (inline or a local file) into text, markdown, links, or readability, fully offline.
• download-to-file: downloads a URL to the requested resolved local path.

SSRF guard: web-fetch, download-to-file, and file-read isUrl resolve the host and always reject loopback, private, link-local, unique-local, CGNAT, multicast/reserved, and embedded-IPv4 IPv6 addresses (mapped, compatible, NAT64, 6to4), re-checked on every redirect hop. web-render rejects evalScript because it can bypass this guard.

Body size is capped per request (maxBytes, default 5,000,000 for fetch and 50,000,000 for download) and hard-clamped to 200,000,000 bytes regardless of the requested value.

Development

Run the focused checks before changing behavior:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build

The test suite currently includes unit coverage for core behavior and an integration test that verifies the full public tool matrix.

Known Limitations

• Git tools require a git binary on PATH; there is no in-process git object store.
• Git behavior follows the installed git CLI, including its submodule and rename-detection defaults.
• web-render requires a separately installed obscura(-like) headless-browser binary; without it, JS-rendered pages cannot be fetched.
• The SSRF guard checks the resolved address at request time; it does not defend against DNS rebinding between resolution and connection.
• MCP resources and resource templates currently return empty lists.