{
  "markdown": "# Hashfile MCP Server\n\n**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.\n\n## Why Hashfile MCP?\n\n### 🎯 **Surgical File Editing**\nUnlike traditional line-number-based editing that breaks when files change, Hashfile uses **content-anchored operations**:\n- **Hash-Anchored Lines**: Every line tagged with a content hash — edits target the *right content*, not just the right line number\n- **Fuzzy Matching**: Automatically finds moved lines even after insertions/deletions\n- **Collision Detection**: File-level verification prevents editing stale content\n- **Multi-Operation Edits**: Apply multiple precise changes in a single atomic operation\n\n### 🔒 **Ironclad Access Control**\nTake complete control over what AI agents can touch with **AGENTS.md frontmatter**:\n- **`forbidden`**: Block access to secrets, credentials, sensitive data\n- **`read_only`**: Allow reading schemas, configs, lock files — prevent modifications\n- **`ignore`**: Hide generated code, dependencies, build artifacts from AI context\n- **Hierarchical Discovery**: Place AGENTS.md anywhere in your tree — nearest file wins\n- **Glob Patterns**: Fine-tune access with wildcards (`secrets/**`, `**/*.env`)\n\n[📖 Full AGENTS.md Documentation](docs/agents-support.md) | [📋 Proposal Spec](docs/agents.frontmatter.md)\n\n### 🛠️ **Drop-In Filesystem Compatibility**\nAll standard MCP filesystem tools included:\n- `list_directory` — Browse with `[FILE]`/`[DIR]` prefixes\n- `directory_tree` — Compact tree view (10x more token-efficient than JSON)\n- `create_directory` — Recursive directory creation\n- `move_file` — Rename/move files and directories\n- `write_file` — Raw UTF-8 writes (non-hashline)\n- `read_multiple_files` — Batch reads in one operation\n\n## Features at a Glance\n\n| Feature                   | Benefit                                                                |\n| ------------------------- | ---------------------------------------------------------------------- |\n| **Hash-Anchored Editing** | Edits survive file changes — no more \"line 42 doesn't match\" errors    |\n| **Content Verification**  | 6-character file hashing prevents race conditions                      |\n| **AGENTS.md Support**     | Declarative access control — protect secrets, lock schemas, hide noise |\n| **Fuzzy Line Matching**   | Finds the right line even after insertions/deletions                   |\n| **9 MCP Tools**           | 3 hashline tools + 6 standard filesystem tools                         |\n| **Zero Dependencies**     | Pure Rust, compiles to a single binary                                 |\n\n## Installation\n\n```bash\ncargo build --release\n```\n\nThe binary will be at `target/release/hashfile-mcp`.\n\n## Quick Start\n\n### 1. Configure Your MCP Client\n\nAdd to Claude Desktop or your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"hashfile\": {\n      \"command\": \"/path/to/hashfile-mcp/target/release/hashfile-mcp\"\n    }\n  }\n}\n```\n\n### 2. (Optional) Add Access Control\n\nCreate `AGENTS.md` in your project root:\n\n```markdown\n---\nforbidden:\n  - \"secrets/**\"\n  - \"**/*.env\"\n  - \".git/**\"\n\nread_only:\n  - \"package-lock.json\"\n  - \"Cargo.lock\"\n  - \"schema.sql\"\n\nignore:\n  - \"node_modules/**\"\n  - \"target/**\"\n  - \"**/*.generated.ts\"\n---\n\n# Project Instructions\n\nYour custom instructions for AI agents here...\n```\n\n### 3. Start Editing\n\nThe AI can now:\n- ✅ Read and edit source files with hash-anchored precision\n- ✅ Browse directories and create new files\n- ❌ Cannot touch your secrets or `.env` files\n- ❌ Cannot modify lock files or schemas\n- 🙈 Won't see `node_modules` or build artifacts\n\n## How Hashline Works\n\n### The Problem\nTraditional line-number editing fails when files change:\n```\nAgent: \"Replace line 42\"\nReality: Someone inserted 3 lines at the top\nResult: Wrong line replaced! 💥\n```\n\n### The Solution\nContent-anchored editing with hash verification:\n\n1. **Read**: Each line gets a hash tag → `42:a3|const x = 1;`\n2. **Edit**: Operations reference content, not just position → `\"anchor\": \"42:a3\"`\n3. **Apply**: Server finds the line by hash, even if it moved to line 45\n4. **Verify**: File hash must match — detects if content changed since read\n\n### Reliability Features\n\n- **File-Level Verification**: 6-character hash prevents editing stale content\n- **Line-Level Anchoring**: 2-character hash identifies specific lines\n- **Fuzzy Matching**: Searches for unique hash match if line number changed\n- **Conflict Detection**: Clear errors if content diverged\n\n\n## Core Tools\n\n### Hashline Tools (Precision Editing)\n\n#### `read_text_file`\nReturns content with hash-tagged lines for reliable editing:\n\n```\n1:a3|import { useState } from 'react';\n2:7f|\n3:2c|export function Counter() {\n---\nhashline_version: 1\ntotal_lines: 3\nfile_hash: 8f3a9b\n```\n\n#### `edit_text_file`\nApply hash-anchored operations:\n\n```json\n{\n  \"path\": \"/path/to/file.ts\",\n  \"file_hash\": \"8f3a9b\",\n  \"operations\": [\n    {\n      \"op_type\": \"replace\",\n      \"anchor\": \"3:2c\",\n      \"content\": \"export function Counter({ initial = 0 }) {\"\n    }\n  ]\n}\n```\n\n**Operation types**: `replace`, `insert_after`, `insert_before`, `delete`\n\n#### `write_text_file`\nWrite content and get back hashline-tagged verification\n\n### Filesystem Tools (Standard Operations)\n\n#### `list_directory`\n```\n[DIR] src\n[DIR] tests\n[FILE] README.md\n[FILE] Cargo.toml\n```\n\n#### `directory_tree`\n```\nsrc/\n├── agents.rs\n├── config.rs\n├── filesystem.rs\n├── hashline.rs\n├── main.rs\n└── tools.rs\n```\n\nSupports `exclude_patterns` for filtering (e.g., `[\"**/node_modules/**\", \"**/.git/**\"]`)\n\n#### `create_directory`, `move_file`, `write_file`, `read_multiple_files`\nStandard filesystem operations with AGENTS.md enforcement\n\n## AGENTS.md Access Control\n\n### Constraint Types\n\n| Constraint  | Effect                    | Use Case                               |\n| ----------- | ------------------------- | -------------------------------------- |\n| `forbidden` | Block all access          | Secrets, credentials, private keys     |\n| `read_only` | Allow reads, block writes | Schemas, lock files, generated configs |\n| `ignore`    | Hide from AI context      | Dependencies, build artifacts, noise   |\n\n### Automatic .gitignore Support\n\nHashfile MCP automatically respects `.gitignore` files in your project:\n\n- **Hierarchical**: Walks up from target file to find all `.gitignore` files\n- **Standard syntax**: Supports standard `.gitignore` patterns (basename, directory, path)\n- **Combined with AGENTS.md**: Patterns from both sources are merged\n- **Zero config**: Works out of the box with existing projects\n\n**Pattern conversion:**\n```\n# .gitignore\n*.log              → **/*.log\nnode_modules/      → node_modules/**\nbuild/output       → build/output\n```\n\n**Precedence:** AGENTS.md `ignore` patterns take precedence over `.gitignore`.\n\n### Example: Protect a Monorepo\n\n```yaml\n---\nforbidden:\n  - \"**/secrets/**\"\n  - \"**/*.key\"\n  - \"**/*.pem\"\n  - \".env*\"\n\nread_only:\n  - \"**/package-lock.json\"\n  - \"**/Cargo.lock\"\n  - \"db/schema.sql\"\n\nignore:\n  - \"**/node_modules/**\"\n  - \"**/target/**\"\n  - \"**/.next/**\"\n  - \"**/*.generated.*\"\n---\n```\n\n### Hierarchical Control\n\nPlace `AGENTS.md` files at any level:\n```\n/project/AGENTS.md          ← Global rules\n/project/backend/AGENTS.md  ← Backend-specific rules (overrides global)\n/project/frontend/AGENTS.md ← Frontend-specific rules\n```\n\nThe **nearest** `AGENTS.md` in the directory hierarchy applies.\n\n## Development\n\n### Run Tests\n```bash\ncargo test\n```\n\n### Project Structure\n```\nsrc/\n├── main.rs        # MCP server setup\n├── tools.rs       # Tool definitions (9 tools)\n├── hashline.rs    # Hash-anchored editing logic\n├── filesystem.rs  # Standard filesystem operations\n├── agents.rs      # AGENTS.md frontmatter parsing\n├── config.rs      # Configuration (future: tool enablement)\n└── roots.rs       # Root path management (future)\n```\n\n## Technical Details\n\n- **Language**: Rust (edition 2021)\n- **MCP SDK**: rmcp 0.15.0\n- **Line Hashing**: FNV-1a (2 hex chars, 256 buckets)\n- **File Hashing**: FNV-1a (6 hex chars, 16M buckets)\n- **Transport**: stdio\n- **Dependencies**: `rmcp`, `serde`, `serde_json`, `serde_yaml`, `globset`, `anyhow`, `fnv`\n\n## Roadmap\n\n- [ ] Environment variable-based tool enablement (`ENABLE_FILESYSTEM_TOOLS=true`)\n- [ ] Granular tool control (`ENABLE_LIST_DIRECTORY=true`, etc.)\n- [ ] Additional tools: `get_file_info`, `search_files`, `list_directory_with_sizes`\n- [ ] Command-line argument support for configuration\n\n## License\n\nSee LICENSE file for details.\n\n## See Also\n\n- [The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) - I Improved 15 LLMs at Coding in One Afternoon. Only the Harness Changed. - Can Bölük Feb 2026\n- [AGENTS.md Proposal](docs/agents.frontmatter.md) - Frontmatter specification for agent access control\n",
  "bytes": 8853,
  "sha": "1e9546ea4fb7956e34da2a148b0763d3f6201989672e6d0a8953fae13b213133",
  "repo_slug": "mrorigo/hashfile-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mrorigo_hashfile_cd5d0728/readme"
}