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):

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.

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.