file_utils MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@file_utils MCP prepend '#!/usr/bin/env python3' to script.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
file_utils MCP
An anchor-based file reading and editing MCP server for large text files where
the built-in read_file tool fails ("readline was closed") or where encoding
issues (e.g. mojibake em-dashes) cause string-matching tools to miss their
targets.
The headline insight: content-addressed anchors survive line shifts; line numbers don't. When a file is edited mid-session (by you in the IDE, by a formatter, by another tool), line numbers go stale silently. Anchors travel with the content.
The full design lives in SPEC.md; the implementation plan lives in
TODO.md.
Tools
Five stdio MCP tools are exposed (see SPEC.md for full parameter
tables, responses, and error codes):
Tool | Purpose |
| Read a contiguous span, addressed by anchors (primary) or line numbers (fallback). Returns a |
| Replace a contiguous span with new content, with an optional |
| Insert content before/after a single target line without replacing it. |
| Concatenate content at the start of a file (optional |
| Concatenate content at the end of a file (optional |
Anchor matching is substring-based and case-sensitive with a
progressive-disclosure ambiguity guard (occurrence / total). Line numbers are
1-based and support negative indexing (-1 = last line). Edits are written via
an atomic temp-file → fsync → rename. The span content_hash is a SHA-256 of
the raw on-disk bytes, so it is encoding-independent.
Related MCP server: Deskaid
Requirements
Python 3.10+
uvfor environment and dependency managementThe
mcpPython SDK (declared inpyproject.toml; installed automatically byuv)
This project is managed with uv. pyproject.toml is the
single source of truth for dependencies — there is no requirements.txt. Do not
call python, pip, or pytest directly; go through uv so the correct
environment is used.
Installing uv
If uv is not already installed, use the official Astral installer (PowerShell):
powershell -ExecutionPolicy ByPass -Command "irm https://astral.sh/uv/install.ps1 | iex"uv installs to C:\Users\<you>\.local\bin and is added to PATH by the
installer. A newly opened terminal will have uv / uvx on PATH; an
already-open terminal may need to be reopened.
Setup & usage
Sync the environment
uv sync --extra devRun the server
The server speaks the MCP JSON-RPC protocol over stdio. Run it directly:
uv run server.pyRun from a Git repo with uvx
The project is installable as a tool, so uvx can clone the repo into its
cache, build the wheel, install it plus dependencies into an isolated
environment, and run the file-utils entry point — exactly like npx.
From a published GitHub repo:
uvx --from git+https://github.com/JEL-LL/file_utils.git file-utilsOnly committed content is used (it clones from the repo), so commit and
push before a new version becomes available. Use --refresh to pick up new
commits.
Install into a local venv
uv pip install "git+https://github.com/JEL-LL/file_utils.git"Run the tests
uv run --extra dev pytestRun quietly with uv run --extra dev pytest -q.
VS Code / Kilo Code configuration
Recommended: launch globally via uvx straight from the Git repo so any project
gets the tool without a local checkout. Add this to your global
mcp_settings.json:
{
"mcpServers": {
"file_utils": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/JEL-LL/file_utils.git",
"file-utils"
],
"alwaysAllow": []
}
}
}Alternatively, to run from a local working copy through uv (so dependencies
resolve from pyproject.toml):
{
"mcpServers": {
"file_utils": {
"command": "uv",
"args": ["run", "--directory", "/path/to/file_utils", "server.py"],
"env": {}
}
}
}Each spawned process is unique to one agent/session. In-memory state (such as a
remembered project_root) is per-process and safe across calls within a session.
Path resolution
Every tool accepts an optional project_root parameter. Once supplied, it is
remembered in memory for the rest of the session.
Path type |
| Result |
Absolute | Any | Used as-is; |
Relative | Set | Resolved against the remembered |
Relative | Not set |
|
Anchor selection tips
Good anchors are Markdown section headers (## Phase 10), unique prose phrases,
and pure ASCII. Avoid lines containing em-dashes or curly quotes when the file
has encoding issues, very short strings that appear many times, and line numbers
(use from_line / to_line only as a fallback). See
SPEC.md for the full
discipline.
License
Licensed under the MIT License. Copyright (c) 2026 LaserLinc Inc.
Authored by Joshua Lansford. Released as open source with the permission of LaserLinc Inc.
Available Tools
6 toolsappend_to_fileA
Append content to the end of a file (byte concatenation). Optional ensure_newline_before. Writes atomically.
Inputs: path (required), content (required), encoding, project_root, +1 more.
edit_file_rangeA
Replace a contiguous span of a file with new content, addressed by anchors (primary) or line numbers (fallback). Optional expected_content_hash guards against stale edits; writes atomically. IMPORTANT: the from_anchor line and the to_anchor line are BOTH included in the replaced span — they are consumed, not preserved. If you want to keep the boundary lines, you must include them verbatim in new_content. Common mistake: anchoring on the last line of content you want to keep and then omitting it from new_content — that line will be silently dropped.
Inputs: path (required), new_content (required), to_line, encoding, +9 more.
insert_atA
Insert content before or after a single target line (anchor or line number) without replacing existing content. Writes atomically.
Inputs: path (required), new_content (required), anchor, encoding, +6 more.
prepend_to_fileB
Insert content at the very beginning of a file (byte concatenation). Optional ensure_newline_after. Writes atomically.
Inputs: path (required), content (required), encoding, project_root, +1 more.
read_file_rangeA
Read a contiguous span of a file, addressed by anchors (primary) or line numbers (fallback). Streams large files and returns a content_hash for staleness-guarded edits.
Inputs: path (required), to_line, encoding, from_line, +8 more.
strip_conflict_markersA
Remove all Git merge conflict markers (<<<<<<< , =======, >>>>>>>) from a file in a single operation, keeping both sides of every conflict. Reports which lines the markers were on and how many conflicts were resolved. Writes atomically.
Inputs: path (required), encoding, project_root.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct action and target: stripping conflict markers, reading a range, editing a range, inserting at a line, prepending, and appending. No two tools overlap in purpose; even the similar insert/prepend/append are clearly differentiated by operation type and location.
All tool names are snake_case and begin with a verb, but the pattern is inconsistent: some use verb_noun (read_file_range, edit_file_range, strip_conflict_markers) while others use verb_preposition (insert_at, prepend_to_file, append_to_file). This is a minor deviation that could be improved by renaming insert_at to insert_at_line for consistency.
Six tools is a well-scoped set for a file utilities server, covering read, edit, insert, prepend, append, and conflict marker cleanup. It is neither too sparse nor overwhelming, and each tool serves a distinct purpose.
The set covers the core file modification lifecycle: read a range, replace a range, insert line(s), prepend, append, and clean conflict markers. The main gap is the lack of an explicit delete operation, though edit_file_range with empty content can serve that purpose. Minor but workable.
Maintenance
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
A MCP server built for developers enabling Git based project management with project and personal…
MCP server for developer documentation, generated by doc2mcp.
An MCP server that provides congressional transcripts
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA TypeScript-based MCP server that provides tools for making precise line-based edits to text files within allowed directories.34MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides tools for reading, writing, and editing files on the local filesystem.1,603Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides line-oriented text file editing capabilities through a standardized API. Optimized for LLM tools with efficient partial file access to minimize token usage.MIT
- AlicenseAqualityBmaintenanceAn MCP server that provides surgical read/write access to individual sections of Markdown files, allowing agents to fetch, edit, or delete specific slices without touching the entire file.71MIT