Skip to content
MCP Filesystem Ultra

Solved Issues Overview

This section documents all major bugs that have been identified and resolved during the development of MCP Filesystem Ultra. Each issue includes the problem description, root cause analysis, solution implemented, and testing results.

Why This Matters

Section titled “Why This Matters”

Documenting solved issues provides:

  • Transparency: Complete history of problems and solutions
  • Learning: Understanding of technical challenges overcome
  • Confidence: Evidence of thorough testing and bug fixing
  • Reference: Solutions for similar problems in the future

These bugs were discovered during real-world usage with Claude Code on enterprise projects, not theoretical testing. Each fix represents a tangible improvement to daily development workflows.

Issue Summary

Section titled “Issue Summary”
BugCategoryStatusVersionImpact
#24Security / AI-Era HardeningResolvedv4.1.4WSL bypass, NTFS ADS covert channel, Unicode RTLO spoofing, reserved device DoS, cross-platform hook execution — all mitigated
#23Correctness / Line EndingsResolvedv4.0.2CRLF files now match LF old_text in risk assessment
#22Parameter NormalizationResolvedv4.0.2Self-Learning Normalizer auto-corrects Claude Desktop parameter mismatches
#21Pipeline / Compact ModeResolvedv4.0.1formatPipelineResult nil map and missing fields in compact mode
#20Batch OperationsResolvedv4.0.1batchManager.SetEngine() missing — nil engine panic
#19Path NormalizationResolvedv4.0.1NormalizePath() missing in search_files — WSL paths not converted
#18Edit Matching / AliasesResolvedv4.0.1Literal escape normalization + old_str/new_str parameter aliases
#17Correctness / VerificationResolvedv3.16.0multi_edit overlapping edits detected as “already_present”; full parity with EditFile
#16Risk Model / Agentic WorkflowResolvedv3.15.1Only CRITICAL (>=90%) blocks; MEDIUM/HIGH auto-proceed with backup + warning
#15Tool ParityResolvedv3.14.5mcp_edit now respects force:true to bypass risk threshold
#14Correctness / False RejectionResolvedv3.14.4edit_file no longer rejects valid edits due to trailing whitespace
#13PerformanceResolvedv3.14.3smart_search usable on real .NET/Node projects
#12Correctness / Data LossResolvedv3.14.2batch edit no longer silently replaces entire file
#11Path Normalization / CacheResolvedv3.14.1Linux paths no longer corrupted on Windows; stale dir cache invalidated
#10Token OptimizationResolvedv3.14.05-22× fewer MCP calls via pipeline system
#9SearchResolvedv3.7.1Advanced search parameters exposed
#8Developer ExperienceResolvedv3.7.0Self-learning help system
#5Token OptimizationResolvedv3.5.0-v3.7.070-80% token efficiency gain
#2SearchResolvedv3.12.0Correct multi-occurrence positioning

Issue Categories

Section titled “Issue Categories”

Correctness / Line Endings

Section titled “Correctness / Line Endings”

Bug #23: CRLF/LF Mismatch in Edit Risk Assessment

  • Files with CRLF (\r\n) line endings failed to match when Claude Desktop sent old_text with LF (\n). CalculateChangeImpact() reported 0 matches, triggering false CRITICAL risk warnings, even though performIntelligentEdit() would normalize and find the match.
  • Impact: Edits on Windows-style files falsely blocked or reported incorrect risk levels
  • Result: normalizeLineEndings() added to CalculateChangeImpact() and streamingEditLargeFile() entry points

Parameter Normalization

Section titled “Parameter Normalization”

Bug #22: Claude Desktop Parameter Mismatches

  • Claude Desktop sends parameters in unexpected formats: old_str instead of old_text, "true" string instead of true boolean, raw JSON arrays instead of JSON strings, type instead of action in pipeline steps.
  • Impact: Tools failed with “missing required parameter” or type assertion errors
  • Result: Self-Learning Request Normalizer with 14 built-in rules that auto-correct all known patterns

v4 Hotfixes (Bugs #18-21)

Section titled “v4 Hotfixes (Bugs #18-21)”

Bug #18: Literal Escape Normalization

  • Claude Desktop sometimes sent literal \n (two characters) instead of actual newline in old_text. Edit matching failed because the file contained real newlines.
  • Result: Fallback normalization of literal escape sequences + old_str/new_str parameter aliases

Bug #19: WSL Path in search_files

  • search_files handler missing NormalizePath() call — WSL paths like /mnt/c/... were not converted to Windows paths.
  • Result: Added path normalization to search_files handler

Bug #20: batchManager.SetEngine() Missing

  • batch_operations panicked with nil pointer because batchManager.SetEngine() was never called after engine initialization.
  • Result: Added SetEngine() call in engine startup

Bug #21: Pipeline formatPipelineResult Failures

  • formatPipelineResult() in compact mode crashed on nil maps and missing fields when pipeline steps had no results.
  • Result: Added nil checks and safe field access throughout pipeline result formatting

Correctness / Verification

Section titled “Correctness / Verification”

Bug #17: multi_edit Misleading Success Counter

  • multi_edit reported “1/2 edits” when overlapping edits caused Edit 2’s oldText to be absent after Edit 1 subsumed it. The counter was technically correct (1 match), but the file was correct (both changes applied). Additionally, MultiEdit() lacked risk assessment, context validation, hooks, and per-edit status detail that EditFile() had.
  • Impact: Misleading output forced wasteful read_file_range verification calls; CRITICAL risk multi-edits bypassed all safety checks
  • Result: “already_present” detection for subsumed edits; per-edit EditDetail status; full parity with EditFile (risk assessment, context validation, pre/post hooks, CRITICAL blocking)

Risk Model / Agentic Workflow

Section titled “Risk Model / Agentic Workflow”

Bug #16: Edit Risk Model — Only CRITICAL Blocks

  • EditFile() used impact.IsRisky && !force to block edits, which blocked MEDIUM (>=30%), HIGH (>=50%), and CRITICAL (>=90%) risk. The existing ShouldBlockOperation() correctly only blocked CRITICAL but was never called. Backup creation also happened after the block, so blocked operations had no safety net.
  • Impact: Every moderate edit (>30% of file) required a wasteful force: true retry round-trip in agentic workflows
  • Result: Only CRITICAL (>=90%) blocks now. MEDIUM/HIGH auto-proceed with automatic backup + risk notice. Backup created before any blocking decision. Thresholds updated to 20%/75%.

Tool Parity

Section titled “Tool Parity”

Bug #15: mcp_edit Ignored force: true

  • mcp_edit was a stripped alias of edit_file that never declared the force parameter in its tool schema. The handler hardcoded false, so any edit exceeding the 30% change threshold was permanently blocked regardless of what the AI client sent
  • Impact: Claude received the “add force: true” instruction but the server silently ignored it, forcing a fallback to full file rewrite via mcp_write
  • Result: Added force parameter to mcp_edit schema and handler, matching edit_file, intelligent_edit, and auto_recovery_edit

Correctness / False Rejection

Section titled “Correctness / False Rejection”

Bug #14: edit_file Rejected Valid Edits (Trailing Whitespace)

  • validateEditContext used a single byte-exact check that rejected edits when the file had trailing spaces on lines but Claude’s old_text did not — even though performIntelligentEdit’s own fallbacks would have resolved the match
  • Impact: First edit attempt always failed on Windows files from Visual Studio/Rider; Claude wasted 400–800 tokens on a redundant re-read per affected edit
  • Result: Added Level 2 whitespace-tolerant check in validateEditContext; added trimTrailingSpacesPerLine helper; improved error message with actionable root-cause list

Performance

Section titled “Performance”

Bug #13: smart_search Slow on Large Projects

  • smart_search called filepath.EvalSymlinks on every file in the walk (via validatePath), traversed bin/, obj/, node_modules/, and .vs/ without pruning, and opened files with unknown extensions (.aspx, .cshtml, .resx) to classify them as text
  • Impact: Search took tens of seconds or timed out on real .NET/Node projects
  • Result: Removed per-file validatePath; added searchSkipDirs map with filepath.SkipDir; added 14 ASP.NET/MSBuild extensions to textExtensionsMap

Correctness and Data Loss

Section titled “Correctness and Data Loss”

Bug #12: batch_operations Edit Discarded File Content

  • executeEdit was an unfinished TODO placeholder that wrote new_text as the entire file, ignoring old_text and existing content entirely
  • Impact: Every batch edit silently replaced the target file with a single snippet — all original content lost
  • Result: Replaced with strings.Replace on existing content; returns an explicit error if old_text is not found

Path Normalization and Cache

Section titled “Path Normalization and Cache”

Bug #11: Linux Path Corruption + Stale Directory Cache

  • copy_file with a pure Linux path (e.g. /tmp/...) on Windows hit filepath.Clean(), which converted forward slashes to backslashes, producing a broken path; mcp_list returned stale listings after external writes because only TTL, not mtime, was checked
  • Impact: WSL-sourced copies failed with misleading errors; directories appeared empty after bash cp
  • Result: Linux paths mapped to \\wsl.localhost\<distro>\... UNC form; cache entries now store directory mtime and invalidate on external modification

Search and Replace

Section titled “Search and Replace”

Bug #9: Search Optional Parameters

  • Advanced parameters (include_content, file_types, case_sensitive, whole_word, include_context, context_lines) were implemented but not exposed in MCP tool definitions
  • Impact: Claude Desktop could not use powerful search capabilities
  • Result: 90-95% token savings by eliminating workaround tool calls

Bug #2: Multiple Occurrences on Same Line

  • When a pattern appeared multiple times on one line, all matches reported the position of the first occurrence
  • Impact: Edit operations targeted wrong text
  • Result: Accurate coordinate tracking using regexp.FindStringIndex()

Developer Experience

Section titled “Developer Experience”

Bug #8: Help System

  • AI agents had no way to learn optimal workflows, leading to inefficient patterns
  • Impact: Token waste, inconsistent behavior across sessions
  • Result: get_help tool teaches the 4-step efficient workflow

Token Optimization

Section titled “Token Optimization”

Bug #10: Batch Edit Token Overhead

  • Multi-file workflows required N×(search + read + edit + verify) sequential MCP calls, each with ~300-600 tokens overhead
  • Impact: 19-file refactor needed 40+ calls and ~18,000 tokens of pure overhead
  • Result: Pipeline system reduces to 1 call with ~400 tokens overhead (5-22× improvement)

Bug #5: Token Efficiency

  • File operations consumed excessive tokens through verbose output, full file rewrites, and no caching
  • Impact: 2+ million tokens per 2-hour session (~$6-7 USD)
  • Result: 77% reduction through compact mode, surgical editing, and intelligent caching

Testing Approach

Section titled “Testing Approach”

All bug fixes follow this rigorous process:

  1. Reproduction: Create failing test case that demonstrates the bug
  2. Root Cause Analysis: Identify exact cause in the code
  3. Solution Design: Plan minimal, focused fix
  4. Implementation: Code the solution
  5. Testing: Comprehensive test suite including regression tests
  6. Validation: Real-world usage verification
  7. Documentation: Update docs and examples

Recent Major Fixes

Section titled “Recent Major Fixes”

v4.0.2 - Self-Learning Normalizer + CRLF Fix

Section titled “v4.0.2 - Self-Learning Normalizer + CRLF Fix”
  • Bug #22 fix: Data-driven normalizer with 14 rules auto-corrects parameter mismatches
  • Bug #23 fix: CRLF/LF mismatch in CalculateChangeImpact() — normalizeLineEndings() at entry point
  • auditWrap() middleware for all 16 tool handlers
  • Dashboard pages: Normalizer stats + Error Patterns
  • 19 new regression tests

v4.0.1 - v4 Hotfixes

Section titled “v4.0.1 - v4 Hotfixes”
  • Bug #18 fix: Literal escape normalization + old_str/new_str parameter aliases
  • Bug #19 fix: NormalizePath() added to search_files handler
  • Bug #20 fix: batchManager.SetEngine() called during engine startup
  • Bug #21 fix: Nil checks in formatPipelineResult() compact mode

v3.16.0 - multi_edit Verification Fix

Section titled “v3.16.0 - multi_edit Verification Fix”
  • Bug #17 fix: Overlapping edits detected as “already_present” instead of “failed”
  • Per-edit EditDetail with status (applied/already_present/failed) in response
  • MultiEdit() now has full parity with EditFile(): risk assessment, context validation, pre/post hooks
  • CRITICAL risk multi-edits now blocked without force: true
  • 9 new regression tests

v3.15.1 - Edit Risk Model

Section titled “v3.15.1 - Edit Risk Model”
  • Bug #16 fix: Only CRITICAL (>=90% file rewrite) blocks operations
  • MEDIUM and HIGH risk edits auto-proceed with backup + warning
  • Backup created before blocking decision (safety net for all risk levels)
  • Updated thresholds: MEDIUM 20%, HIGH 75%
  • 10 new regression tests

v3.13.0 - Security Hardening

Section titled “v3.13.0 - Security Hardening”
  • 13 vulnerabilities fixed (5 Critical, 3 High, 5 Medium)
  • Symlink traversal protection via filepath.EvalSymlinks()
  • TOCTOU fixes with crypto/rand for temp files
  • Access control enforcement on all write operations
  • Backup ID sanitization against path traversal

v3.12.0 - Coordinate Tracking

Section titled “v3.12.0 - Coordinate Tracking”
  • Bug #2 fix: Correct positioning for multiple occurrences
  • Character-level coordinate tracking in search results
  • Foundation for diff-based editing (future)
  • 7 new tests for coordinate accuracy

v3.7.0-v3.7.1 - Efficiency Improvements

Section titled “v3.7.0-v3.7.1 - Efficiency Improvements”
  • Bug #8: get_help tool for self-learning
  • Bug #9: All search parameters exposed
  • Token telemetry with get_edit_telemetry

v3.5.0-v3.6.0 - Token Optimization

Section titled “v3.5.0-v3.6.0 - Token Optimization”
  • Compact mode (--compact-mode)
  • Range operations (read_file_range, chunked_read_file)
  • 3-tier caching system
  • Multi-edit support

Reporting New Issues

Section titled “Reporting New Issues”

Found a bug? Please report it:

  1. GitHub Issues: Create an issue
  2. Include: Version, OS, reproduction steps, expected vs actual behavior
  3. Logs: Attach relevant log output if available

Detailed Documentation

Section titled “Detailed Documentation”

Explore specific bug fixes: