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

• 22 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, search, and git tools run in Rust code paths.
• Git operations avoid the git CLI for the implemented surface.
• Search and exclude-aware listing shell out to ripgrep (rg) and fd resolved from PATH; ensure both tools are installed.
• 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":"."}]}}}

Configuration

Runtime configuration is held in process memory.

allowedDirectories can also be seeded from the RUST_FS_MCP_ALLOWED_DIRECTORIES environment variable using the platform path-list separator.

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.
• structuredContent.data.structuredContent contains tool-specific structured data.
• structuredContent.status is success or error.
• structuredContent.schemaVersion is 1.
• _meta.fsMcpResult mirrors status, duration, content type, and structured-content presence.
• isError is set on tool failures.

Batch tools return result indexes, original input snippets, per-item status, succeededCount, failedCount, and totalCount.

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.
• 1-based line reads with offset and length. file-lines 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), and 1-based line-range replacement (file-edit-lines).
• HTTP URL reads for http:// URLs with redirect handling.

Search Tools

search-start stores results in an in-memory session and returns a session id. search-get pages through stored results, and search-stop removes sessions.

Search supports:

• searchType: content or files.
• Regex or literal content search.
• ignoreCase, contextLines, includeHidden, filePattern, and maxResults.
• Binary-file skipping for content search.
• content search shells out to ripgrep (rg) and file search shells out to fd. Both tools are resolved from PATH and must be installed.
• bat, jq, sd, hyperfine, and tokei entries remain in the internal ExternalTool enum for future wrappers but no public MCP tool currently dispatches them.

search-regex runs the same search path without storing a session.

Git Tools

Git tools discover the repository from path, the pinned git-cwd, or the current directory. The implementation reads and writes repository files directly.

Implemented behavior includes:

• git-cwd with optional repository initialization.
• git-status from HEAD, index, and worktree comparisons.
• git-add by writing index v2 entries and loose blob objects.
• git-commit by writing tree and commit objects and updating HEAD.
• git-diff for staged, worktree, target, and source/target comparisons.
• git-show for commits, trees, blobs, and file content at revisions.

Commit messages must start with an English Conventional Commit header.

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

• HTTPS URL reads are rejected until a TLS-capable Rust HTTP client layer is added.
• Git object access reads loose objects. packed-refs are supported for refs, but packfile object storage is not.
• Git index support is version 2.
• Submodules and rename-aware diffs are not implemented.
• MCP resources and resource templates currently return empty lists.