Skip to main content
Glama
file_utils MCP

file_utils MCP

by JEL-LL

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_file_range

Read a contiguous span, addressed by anchors (primary) or line numbers (fallback). Returns a content_hash for staleness-guarded edits.

edit_file_range

Replace a contiguous span with new content, with an optional expected_content_hash staleness guard.

insert_at

Insert content before/after a single target line without replacing it.

prepend_to_file

Concatenate content at the start of a file (optional ensure_newline_after).

append_to_file

Concatenate content at the end of a file (optional ensure_newline_before).

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+

  • uv for environment and dependency management

  • The mcp Python SDK (declared in pyproject.toml; installed automatically by uv)

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 dev

Run the server

The server speaks the MCP JSON-RPC protocol over stdio. Run it directly:

uv run server.py

Run 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-utils

Only 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 pytest

Run 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

project_root state

Result

Absolute

Any

Used as-is; project_root is ignored

Relative

Set

Resolved against the remembered project_root

Relative

Not set

INVALID_PARAMETERS — supply an absolute path or a project_root


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 tools
append_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

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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
    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      7
      1
      MIT