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
#25Reading / RangeResolvedv4.5.xread_file start_line off-by-one / range edge cases
#26Editing / multi_editResolvedv4.5.xmulti_edit JSON-newline / quoting mishandling in some call paths
#27Atomicity / multi_editResolvedv4.5.xmulti_edit silently drops edits when old_text no longer matches after a prior edit — risk of file truncation (see MEMORY.md / project_bug27_multi_edit_silent_failure.md)
#28Editing / HTMLResolvedv4.5.xedit_file HTML/Aspx editing edge cases (whitespace, attribute escaping)
#29Search / Param typingResolvedv4.5.3search_files return_lines accepts bool (was rejected as non-string)
#30Edit / ConcatenationResolvedv4.5.10edit_file accidental full-file rewrite guard (allow_rewrite: true to override)
#31Backup / Soft-delete UXResolvedv4.5.11Soft-delete files went to filesdelete/ outside --backup-dir with no SD-ID; added list_trash / restore_trash / purge_trash
#32Search / False negativesResolvedv4.5.24search_files filename-only default returned “No matches” for genuine content matches when path is a file or content-only params are passed (now forces content search)
#B1Edit / Hash presentationResolvedv4.5.13read_file trailing # content_hash: trailer was indistinguishable from Markdown → atomic batches rolled back. Hash moved to StructuredContent["content_hash"]
#B3Edit / OCC parityResolvedv4.5.13multi_edit did not accept expected_hash (OCC only worked for edit_file). Now both support OCC
v4.5.14 itemsReliability / 6 fixesResolvedv4.5.14diff_format, atomic extract batch op, post-edit structural check, partial-read content_hash, allow_rewrite, request-id breadcrumb
v4.5.15 itemsEditor parityResolvedv4.5.15Go AST post-edit validation; post-edit content_hash; structured edit responses
v4.5.20 itemsgit / safetyResolvedv4.5.20git add respects paths (no silent -A)
v4.5.21 itemsgit / stderrResolvedv4.5.21git restore no longer fails with exec: Stderr already set
v4.5.22 itemsgit / restoreResolvedv4.5.22git restore validation order + staged/dry_run non-destructive
v4.5.23 itemsgit / security auditResolvedv4.5.23restore command construction + option-injection (rejectOptionLike) + branch -d/-D safety inversion
v4.5.25 itemsErgonomicsResolvedv4.5.25list_directory output_format (compact/json/tree) + multi_edit aggregate diff_format
v4.5.17 itemsAuto-OCCResolvedv4.5.17--auto-occ off|warn|block (session-scoped OCC)
v4.5.18 itemsAuto-OCC follow-upResolvedv4.5.18External-change warning moved into structured edit payload; batch writes refresh baseline
v4.5.19 itemsPipeline OCCResolvedv4.5.19Pipeline writes refresh auto-OCC baseline (closes the last gap)
v4.5.8 itemsGo CVEsResolvedv4.5.8Go 1.26.3 → 1.26.4 closes GO-2026-5039 (net/textproto) + GO-2026-5037 (crypto/x509)
Path / Case (Mem #22)Path / CaseResolvedv4.5.10 (prevented)Path estats.razor written from memory vs Estats.razor — Windows resolves but downstream Razor compiler fails (RZ10011 class estats). Rule: ALWAYS copy paths from list_directory / read_file
#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 ModelResolvedv3.15.1All risk levels auto-proceed with backup; CRITICAL (>=90%) includes a VERIFY instruction. Other safety guards (rewrite guard, OCC) can block independently.
#15Tool ParityResolvedv3.14.5mcp_edit now respects force:true to bypass risk threshold (tool removed in v4; use edit_file)
#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 (get_help removed in v4; use help or server_info(action:"help"))
#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 edits include a VERIFY instruction.

Risk Model / Agentic Workflow

Section titled “Risk Model / Agentic Workflow”

Bug #16: Edit Risk Model — Auto-Proceed with Backup

  • EditFile() blocked MEDIUM (>=30%), HIGH (>=50%), and CRITICAL (>=90%) risk edits when impact.IsRisky && !force was true, forcing a force:true retry round-trip in agentic workflows.
  • Impact: Every moderate edit required a wasteful retry; backups were created only after the block, leaving blocked operations without a safety net.
  • Result: All risk levels now auto-proceed with an automatic backup and a risk notice. CRITICAL edits include a VERIFY instruction so the caller confirms the file is complete. The code default thresholds were updated to MEDIUM 20% / HIGH 75%. Only independent guards (accidental-rewrite guard, --auto-occ=block) can block an edit.

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: