@jungho-dev/fs-mcp

Overview

@jungho-dev/fs-mcp is a stdio-based Model Context Protocol server for local file work, batched search, exact block editing, and essential git workflows.

This package is the MCP server runtime. It is not a VS Code extension bundle, does not require a specific AI client, and does not open a network listener. Any MCP-capable client that can launch a stdio command can use it, including Codex, Claude, Cline, Roo, Cursor, Windsurf, VS Code MCP clients, Gemini CLI, and GitHub Copilot.

The current runtime does not include a SQLite sidecar, context-index store, or MCP resource catalog. Resource and resource-template handlers intentionally return empty lists for client compatibility.

Related MCP server: mcp-server

Measured Performance And Token Savings

The practical baseline for AI file work is often repeated shell calls that each pay process and tool-call overhead. Current benchmarks show where fs-mcp reduces that overhead while keeping full payloads available to the client.

Numbers above were generated on 2026-05-24 from this checkout with seven runs per timed scenario:

bun tests/scripts/performance-benchmark.mjs
bun tests/scripts/write-files-args-path-benchmark.mjs

Token estimates use the project heuristic of 4 characters per token. Actual model billing depends on the client and whether it forwards only content[0].text or also injects structuredContent into model context.

Installation

Install the package globally with npm:

npm install -g @jungho-dev/fs-mcp

Or install it globally with Bun:

bun add -g @jungho-dev/fs-mcp

MCP Client Configuration

Use this server command for MCP clients that accept JSON-style mcpServers configuration:

{
  "mcpServers": {
    "fs-mcp": {
      "command": "fs-mcp",
      "args": []
    }
  }
}

Codex uses TOML instead of JSON. Add the same command to ~/.codex/config.toml after global install:

[mcp_servers.fs-mcp]
enabled = true
startup_timeout_sec = 60.0
tool_timeout_sec = 120.0
command = "fs-mcp"
args = []

If a client cannot resolve global binaries, set command to the absolute fs-mcp executable path.

Current Public Tool Surface

The current source and compiled runtime expose 24 public tools that mirror the rust-fs-mcp surface. Tool names are intentionally short, hyphenated, and stable for clients that cache MCP catalogs.

src/schemas/schemas-git.ts contains schemas for additional git operations, but src/tools/tools-git.ts exports only the essential git set above in this version. Config tools and process controls are outside the current public catalog.

Main Capabilities

• Batch-first filesystem reads, writes, listings, metadata checks, directory creation, copying, moving, deletion, exact block replacement, and 1-based line range edits.

• fs-inspect composite lookups that bundle count-files, search, json-pick, snippet, and git-status into one round-trip.

• Direct ripgrep-compatible regex search through fs-search.

• SSRF-guarded web tier: web-fetch for static pages, web-render for JS/SPA pages via the obscura headless browser, web-extract for offline HTML conversion, and download-to-file for sandboxed downloads.

• Optional DOCX text extraction for content searches when the target inputs or patterns include .docx.

• Essential git session workflows for repository pinning, status, diff, show, staging, and commit.

• Normalized tool responses with a visible display block, machine-readable structuredContent, and compact _meta.fsMcpResult metadata.

Batch-First Tool Use

SERVER_INSTRUCTIONS and batch-capable tool descriptions tell clients to collapse repeated same-kind work into one multi-item call. This applies to:

• File reads through paths or items.

• Directory and file operations through items or paths arrays.

• Search work through fs-search.items.

• Web work through web-fetch.items, web-extract.items, and download-to-file.items.

Large arguments can be moved into a UTF-8 JSON file and passed with args_path. Inline fields supplied beside args_path override fields from the referenced JSON object. Large text payloads can also use path-backed fields such as content_path, old_string_path, new_string_path, pattern_path, and messagePath.

file-read, file-read-line-range, dir-list, and path-stat accept allowMissing=true so exploratory candidate reads can return missing local paths as non-error results.

Runtime Notes

Current compiled catalog metrics from this checkout:

• Tool count: 24.

• list_tools payload: 32,048 characters.

• Tool descriptions: 8,544 characters.

• Tool schemas: 20,097 characters.

Runtime behavior:

• Tool catalogs are assembled once during server creation.

• Zod-to-JSON-schema conversion is lazy-cached per tool entry.

• Tool calls resolve args_path, args_offset, and args_length before controller validation.

• fs-search has no implicit maxResults cap. Set maxResults explicitly when a bounded scan is needed.

• With the default-on compact envelope the body lives once in data.content and the data.text copy is omitted; FS_MCP_COMPACT=0 restores it.

• Stdio filtering captures accidental console output before it can corrupt MCP JSON-RPC frames.

Runtime Configuration

Runtime configuration is in memory only. The server does not create a first-run config file.

Internal runtime configuration keys are:

• allowedDirectories

• blockedCommands

• defaultShell

FS_MCP_ALLOWED_DIRECTORIES can seed allowed directories. On Windows, entries are separated by semicolons. FS_MCP_COMPACT=0 disables the compact envelope and restores the data.text copy. FS_MCP_TOOL_PROFILE=fast-coding narrows tools/list to fs-inspect only.

Client Compatibility

• Client metadata is captured during initialization and can also be refreshed from call metadata.

• Git calls run inside a client-scoped git session key.

• Claude and Codex keep standard server-side notification behavior.

• Gemini CLI and GitHub Copilot suppress server-side JSON-RPC notifications for compatibility.

• Resource and resource-template list handlers return empty lists so probing clients initialize cleanly.

Repository Structure

project root/
|-- src/
|   |-- assets/        shared readers, type declarations, and cross-domain utilities
|   |-- controllers/   MCP request handlers and batch response helpers
|   |-- cores/         runtime, stdio transport, server assembly, and response normalization
|   |-- features/      config, edit, filesystem, git, process, and search behavior
|   |-- schemas/       request argument validation schemas
|   `-- tools/         tool catalog entries and dispatcher
|-- tests/             contract tests, smoke tests, fixtures, and verification scripts
`-- out/               compiled runtime published to npm

Response Shape

Every dispatched tool result is normalized by src/cores/responses/responses-tool-result.ts.

• Visible content[0].text is generated by src/cores/responses/responses-tool-display.ts.

• The default visible rows are tool, items, status, duration, tokens, contents, and structuredText.

• tokens uses a lightweight character-based estimate over content text plus serialized structured content.

• structuredContent stores schema version, tool name, status, duration, error detail, original normalized content, and original structured payload.

• With the default-on compact envelope the body lives once in data.content and the data.text copy is omitted. Batch per-item results carry only structuredContent and isError, and echoed input strings above 256 bytes become <N bytes elided>. FS_MCP_COMPACT=0 restores the previous shape.

• _meta.fsMcpResult stores compact status, duration, content type, error, schema, and tool metadata.

• Already normalized results are not wrapped again; the visible display text is regenerated.

Development

Current development checks use Bun:

bun x tsc --noEmit
bun tests/run-all-tests.js
bun tests/scripts/performance-benchmark.mjs
bun tests/scripts/write-files-args-path-benchmark.mjs

Useful scoped checks:

bun tests/scripts/scripts-verify-release-shape.mjs
bun tests/scripts/scripts-verify-tool-surface.mjs
bun tests/scripts/scripts-verify-optimization-reports.mjs
bun tests/scripts/scripts-verify-doc-sync.mjs

tests/run-all-tests.js rebuilds out unless FS_MCP_SKIP_BUILD=1 is set, then runs contract and smoke tests. Verification scripts under tests/scripts/ check release shape, source boundaries, optimization reports, and the compiled tool surface.

Documentation

• English README: README.md

• Korean README: readme-ko.md

• English architecture: architecture.md

• Korean architecture: architecture-ko.md

• Changelog: changelog.md

Packaging Notes

The npm package exposes the fs-mcp binary through out/index.mjs. Runtime version metadata is read from the package root package.json. The package file allowlist includes out, release documentation, and changelog files. Source files, tests, fixtures, and local runtime artifacts remain development-only surfaces.