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 top Result: 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: 1 total_lines: 3 file_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 → **/*.log node_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