Content
# @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:
```bash
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:
```bash
npm install -g @jungho-dev/fs-mcp
```
Or install it globally with Bun:
```bash
bun add -g @jungho-dev/fs-mcp
```
## MCP Client Configuration
Use this server command for MCP clients that accept JSON-style `mcpServers` configuration:
```json
{
"mcpServers": {
"fs-mcp": {
"command": "fs-mcp",
"args": []
}
}
}
```
Codex uses TOML instead of JSON. Add the same command to `~/.codex/config.toml` after global install:
```toml
[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.
| Domain | Tools | Purpose |
|--------|-------|---------|
| Filesystem | `file-read`, `file-read-line-range`, `file-write`, `path-stat` | Read, line-range-read, write, and inspect files. |
| Directories | `dir-list`, `dir-create` | List directory trees and create directories. |
| File operations | `path-copy`, `path-move`, `path-remove`, `file-edit`, `file-edit-lines` | Copy, move, remove, exact-edit, and line-range-edit files or directories. |
| Inspect | `fs-inspect` | Bundle count-files, search, json-pick, snippet, and git-status lookups into one read-only call. |
| Search | `fs-search` | Run direct ripgrep-compatible regex scans. |
| Web | `web-fetch`, `web-render`, `web-extract`, `download-to-file` | Fetch URLs, render JS/SPA pages through obscura, extract held HTML, and download files. |
| Git | `git-set-workdir`, `git-status`, `git-diff`, `git-show`, `git-add`, `git-commit`, `git-amend` | Pin repo state, inspect changes, stage, commit, and amend. |
`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
```text
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:
```bash
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:
```bash
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.
