@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.

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.

| Scenario | fs-mcp path | Baseline | Measured effect | |----------|---------------|----------|-----------------| | Read 12 files, 4 KB each | One file-read batch: 3.11 ms avg, 1.86 ms median | Sequential PowerShell reads: 2,617.42 ms avg, 2,579.75 ms median | About 842x faster by average time and 1,387x faster by median time | | Write 20 files, 4 KB each | args_path reference: 140 transport chars, 35 token est | Inline JSON payload: 82,911 transport chars, 20,728 token est | 99.83% fewer transport chars and 20,693 estimated tokens avoided | | Normalize one 128 KB text result | Visible display: 498 chars; duplicated content slots: 817 chars | Raw text body: 131,072 chars | Full text stays in data.text while repeated visible text is kept to a preview |

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 20 public tools. Tool names are intentionally short, hyphenated for filesystem/search/git surfaces, and stable for clients that cache MCP catalogs.

| Domain | Tools | Purpose | |--------|-------|---------| | Filesystem | file-read, file-lines, file-write, file-infos | Read, line-read, write, and inspect files. | | Directories | dir-list, dir-mk | List directory trees and create directories. | | File operations | file-copy, file-move, file-remove, file-edit | Copy, move, remove, and exact-edit files or directories. | | Search | search-regex, search-start, search-get, search-stop | Run direct regex scans or manage paged search sessions. | | Git | git-cwd, git-status, git-diff, git-show, git-add, git-commit | Pin repo state, inspect changes, stage, and commit. |

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, and exact block replacement.
• Direct ripgrep-compatible regex search and asynchronous search sessions with pagination and stop controls.
• 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 search-regex.items, search-start.items, search-get.items, and search-stop.sessionIds.

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-lines, dir-list, and file-infos 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: 20.
• list_tools payload: 24,003 characters.
• Tool descriptions: 5,613 characters.
• Tool schemas: 15,568 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.
• Search sessions have no implicit maxResults cap. Set maxResults explicitly when a bounded scan is needed.
• Large duplicate text is previewed in duplicated envelope slots; full text remains in data.text or structuredContent.textContent.
• 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.

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 visible combined text plus serialized structured content.
• structuredContent stores schema version, tool name, status, duration, error detail, original normalized content, combined text, and original structured payload.
• Large duplicated text fields use previews in repeated content slots while preserving the full text in data.text or nested structuredContent.textContent.
• _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.