Performance and Token Optimization

Overview

MCP Filesystem Ultra is optimized for interactive AI workflows. The main performance levers are:

• 3-tier caching — repeated reads, directory listings, and metadata are cached in memory.
• Smart I/O strategy — file size determines whether direct, streaming, or chunked I/O is used.
• Compact mode — short, token-efficient responses for Claude Desktop.
• Pipelines — chain multiple operations in one MCP call to reduce round-trips.
• Internal caches — compiled regex patterns, extension maps, and resolved allowed paths are cached.

None of these optimizations change the correctness of the operations.

Latency Sources

Most latency comes from three places:

1. Disk I/O — reading from or writing to the host filesystem.
2. Serialization — MCP message encoding and decoding.
3. Model tokens — sending long responses back to Claude.

The server optimizes the first two; the third is controlled by how tools are used and whether compact mode is enabled.

Caching

The 3-tier cache stores:

• File contents (BigCache, size-limited by --cache-size).
• Directory listings.
• File metadata.

Repeated reads of the same file or directory skip disk I/O. Cache hit rates are high when a session touches the same files repeatedly — which is common when Claude reads context, edits, then re-reads to verify.

Smart I/O Strategy

Core tools automatically choose a strategy based on file size:

File Size	Strategy
Small (< 100 KB)	Direct I/O
Medium (< 500 KB)	Streaming
Large (< 5 MB)	Chunking
Very large (≥ 5 MB)	Special handling; edits above 50 MB rejected by default

You do not need to pick a different tool for large files.

Compact Mode

Enable --compact-mode to receive shorter tool responses. This is especially useful in Claude Desktop, where verbose responses consume context window and tokens.

Compact mode does not remove important information such as errors, backup IDs, or risk warnings.

Token Optimization

Prefer Surgical Edits Over Full Rewrites

edit_file and multi_edit only send the changed text back to the model. write_file sends the entire file content. For small changes, surgical edits are almost always more token-efficient.

Read Ranges, Not Whole Files

read_file with start_line/end_line returns only the lines you need. This is the most effective way to reduce token usage when working with large files.

Count Before Global Edits

Use search_files with count_only: true before running a global replace. Knowing the scope prevents surprises and helps you decide whether to use edit_file, project_replace, or batch_operations.

Pipeline Multi-Step Work

batch_operations with pipeline_json chains search, read, edit, and verify steps in a single MCP call. This reduces round-trip overhead compared to separate calls.

Example:

{
  "name": "rename-const",
  "create_backup": true,
  "steps": [
    { "id": "find", "action": "search", "params": { "path": "src/", "pattern": "OldConst" } },
    { "id": "edit", "action": "edit", "input_from": "find", "params": { "old_text": "OldConst", "new_text": "NewConst" } },
    { "id": "verify", "action": "count_occurrences", "input_from": "find", "params": { "pattern": "NewConst" } }
  ]
}

Internal Engine Optimizations

AllowedPaths Pre-Resolution

Allowed base paths are resolved once at startup, so every operation only checks against pre-resolved strings instead of calling filepath.EvalSymlinks() repeatedly.

Regex Compilation Cache

Compiled regex patterns are stored in a cache protected by a sync.RWMutex. Repeated searches with the same pattern skip compilation.

Extension Lookup Maps

Text and binary file detection uses O(1) map lookups instead of linear scans. The maps are initialized once at package load time.

Measuring Your Own Performance

Use server_info to see live metrics:

server_info({ action: "stats" })

Returns aggregate counters such as operation count, cache hit rate, and memory usage. The exact fields depend on the current server version.

Honest Limitations

Optimization cannot help when:

• You genuinely need to read a new file for the first time.
• You ask Claude to generate very large outputs.
• You run broad regex searches that produce many matches.
• You are working with binary files.

Results also vary by workload:

• Small projects benefit less from caching because there are fewer repeated reads.
• Write-heavy workloads still pay the cost of output tokens.
• Slow filesystems or network mounts may dominate latency regardless of caching.

Summary

Technique	Benefit
3-tier cache	Faster repeated reads and listings
Smart I/O	No manual tool selection for large files
Compact mode	Smaller tool responses
Surgical edits	Lower token usage than full rewrites
Range reads	Lower token usage than full-file reads
Pipelines	Fewer MCP round-trips for multi-step work
Internal caches	Lower per-operation overhead

The exact speedup and token savings depend on your workload, but these patterns consistently reduce latency and context-window pressure in interactive AI sessions.

---

Version: 4.5.29 Date: 2026-07-11