Hashfile MCP

Hashfile MCP Server

Fine-Grained Control for AI File Operations — A Model Context Protocol (MCP) server that gives you surgical precision over file editing and ironclad control over file access.

Why Hashfile MCP?

🎯 Surgical File Editing

Unlike traditional line-number-based editing that breaks when files change, Hashfile uses content-anchored operations:

• Hash-Anchored Lines: Every line tagged with a content hash — edits target the right content, not just the right line number
• Fuzzy Matching: Automatically finds moved lines even after insertions/deletions
• Collision Detection: File-level verification prevents editing stale content
• Multi-Operation Edits: Apply multiple precise changes in a single atomic operation

🔒 Ironclad Access Control

Take complete control over what AI agents can touch with AGENTS.md frontmatter:

• forbidden: Block access to secrets, credentials, sensitive data
• read_only: Allow reading schemas, configs, lock files — prevent modifications
• ignore: Hide generated code, dependencies, build artifacts from AI context
• Hierarchical Discovery: Place AGENTS.md anywhere in your tree — nearest file wins
• Glob Patterns: Fine-tune access with wildcards (secrets/**, **/*.env)

📖 Full AGENTS.md Documentation | 📋 Proposal Spec

🛠️ Drop-In Filesystem Compatibility

All standard MCP filesystem tools included:

• list_directory — Browse with [FILE]/[DIR] prefixes
• directory_tree — Compact tree view (10x more token-efficient than JSON)
• create_directory — Recursive directory creation
• move_file — Rename/move files and directories
• write_file — Raw UTF-8 writes (non-hashline)
• read_multiple_files — Batch reads in one operation

Features at a Glance

Installation

cargo build --release

The binary will be at target/release/hashfile-mcp.

Quick Start

1. Configure Your MCP Client

Add to Claude Desktop or your MCP client config:

{  "mcpServers": {    "hashfile": {      "command": "/path/to/hashfile-mcp/target/release/hashfile-mcp"    }  }}

2. (Optional) Add Access Control

Create AGENTS.md in your project root:

---forbidden:  - "secrets/**"  - "**/*.env"  - ".git/**"
read_only:  - "package-lock.json"  - "Cargo.lock"  - "schema.sql"
ignore:  - "node_modules/**"  - "target/**"  - "**/*.generated.ts"---
# Project Instructions
Your custom instructions for AI agents here...

3. Start Editing

The AI can now:

• ✅ Read and edit source files with hash-anchored precision
• ✅ Browse directories and create new files
• ❌ Cannot touch your secrets or .env files
• ❌ Cannot modify lock files or schemas
• 🙈 Won't see node_modules or build artifacts

How Hashline Works

The Problem

Traditional line-number editing fails when files change:

Agent: "Replace line 42"Reality: Someone inserted 3 lines at the topResult: Wrong line replaced! 💥

The Solution

Content-anchored editing with hash verification:

1. Read: Each line gets a hash tag → 42:a3|const x = 1;
2. Edit: Operations reference content, not just position → "anchor": "42:a3"
3. Apply: Server finds the line by hash, even if it moved to line 45
4. Verify: File hash must match — detects if content changed since read

Reliability Features

• File-Level Verification: 6-character hash prevents editing stale content
• Line-Level Anchoring: 2-character hash identifies specific lines
• Fuzzy Matching: Searches for unique hash match if line number changed
• Conflict Detection: Clear errors if content diverged

Core Tools

Hashline Tools (Precision Editing)

read_text_file

Returns content with hash-tagged lines for reliable editing:

1:a3|import { useState } from 'react';2:7f|3:2c|export function Counter() {---hashline_version: 1total_lines: 3file_hash: 8f3a9b

edit_text_file

Apply hash-anchored operations:

{  "path": "/path/to/file.ts",  "file_hash": "8f3a9b",  "operations": [    {      "op_type": "replace",      "anchor": "3:2c",      "content": "export function Counter({ initial = 0 }) {"    }  ]}

Operation types: replace, insert_after, insert_before, delete

write_text_file

Write content and get back hashline-tagged verification

Filesystem Tools (Standard Operations)

list_directory

[DIR] src[DIR] tests[FILE] README.md[FILE] Cargo.toml

directory_tree

src/├── agents.rs├── config.rs├── filesystem.rs├── hashline.rs├── main.rs└── tools.rs

Supports exclude_patterns for filtering (e.g., ["**/node_modules/**", "**/.git/**"])

create_directory, move_file, write_file, read_multiple_files

Standard filesystem operations with AGENTS.md enforcement

AGENTS.md Access Control

Constraint Types

Automatic .gitignore Support

Hashfile MCP automatically respects .gitignore files in your project:

• Hierarchical: Walks up from target file to find all .gitignore files
• Standard syntax: Supports standard .gitignore patterns (basename, directory, path)
• Combined with AGENTS.md: Patterns from both sources are merged
• Zero config: Works out of the box with existing projects

Pattern conversion:

# .gitignore*.log              → **/*.lognode_modules/      → node_modules/**build/output       → build/output

Precedence: AGENTS.md ignore patterns take precedence over .gitignore.

Example: Protect a Monorepo

---forbidden:  - "**/secrets/**"  - "**/*.key"  - "**/*.pem"  - ".env*"
read_only:  - "**/package-lock.json"  - "**/Cargo.lock"  - "db/schema.sql"
ignore:  - "**/node_modules/**"  - "**/target/**"  - "**/.next/**"  - "**/*.generated.*"---

Hierarchical Control

Place AGENTS.md files at any level:

/project/AGENTS.md          ← Global rules/project/backend/AGENTS.md  ← Backend-specific rules (overrides global)/project/frontend/AGENTS.md ← Frontend-specific rules

The nearest AGENTS.md in the directory hierarchy applies.

Development

Run Tests

cargo test

Project Structure

src/├── main.rs        # MCP server setup├── tools.rs       # Tool definitions (9 tools)├── hashline.rs    # Hash-anchored editing logic├── filesystem.rs  # Standard filesystem operations├── agents.rs      # AGENTS.md frontmatter parsing├── config.rs      # Configuration (future: tool enablement)└── roots.rs       # Root path management (future)

Technical Details

• Language: Rust (edition 2021)
• MCP SDK: rmcp 0.15.0
• Line Hashing: FNV-1a (2 hex chars, 256 buckets)
• File Hashing: FNV-1a (6 hex chars, 16M buckets)
• Transport: stdio
• Dependencies: rmcp, serde, serde_json, serde_yaml, globset, anyhow, fnv

Roadmap

• Environment variable-based tool enablement (ENABLE_FILESYSTEM_TOOLS=true)
• Granular tool control (ENABLE_LIST_DIRECTORY=true, etc.)
• Additional tools: get_file_info, search_files, list_directory_with_sizes
• Command-line argument support for configuration

License

See LICENSE file for details.

See Also

• The Harness Problem - I Improved 15 LLMs at Coding in One Afternoon. Only the Harness Changed. - Can Bölük Feb 2026
• AGENTS.md Proposal - Frontmatter specification for agent access control