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