Hashfile MCP

Hashfile MCP 服务

精细控制 AI 文件操作 —— 一个 Model Context Protocol（MCP）服务，让你能够精准编辑文件，并对文件访问进行严密控制。

为什么选择 Hashfile MCP？

🎯 精准文件编辑

与文件变更后便会失效的传统行号编辑不同，Hashfile 使用内容锚定操作：

• 哈希锚定行：每行都带有内容哈希标记——编辑针对的是正确的内容，而不只是正确的行号
• 模糊匹配：即使插入或删除内容后行发生移动，也能自动找到这些行
• 冲突检测：通过文件级验证，避免编辑过期内容
• 多操作编辑：在一次原子操作中应用多项精准修改

🔒 严密的访问控制

借助 AGENTS.md frontmatter，完全掌控 AI Agent 可以访问的内容：

• forbidden：阻止访问机密、凭据和敏感数据
• read_only：允许读取架构、配置和锁文件，但禁止修改
• ignore：将生成的代码、依赖项和构建产物排除在 AI 上下文之外
• 分层发现：可在目录树中的任意位置放置 AGENTS.md——以最近的文件为准
• Glob 模式：使用通配符精细控制访问权限（secrets/**、**/*.env）

📖 完整的 AGENTS.md 文档 | 📋 提案规范

🛠️ 即插即用的文件系统兼容性

包含所有标准 MCP 文件系统工具：

• list_directory — 使用 [FILE]/[DIR] 前缀浏览
• directory_tree — 紧凑的树状视图（比 JSON 节省 10 倍 Token）
• create_directory — 递归创建目录
• move_file — 重命名或移动文件和目录
• write_file — 写入原始 UTF-8 内容（非哈希行）
• read_multiple_files — 一次操作批量读取

功能一览

功能	优势
哈希锚定编辑	文件变更后编辑仍然有效——不再出现“第 42 行不匹配”错误
内容验证	通过 6 个字符的文件哈希防止竞态条件
AGENTS.md 支持	声明式访问控制——保护机密、锁定架构、隐藏无关内容
模糊行匹配	即使插入或删除内容后，也能找到正确的行
9 个 MCP 工具	3 个哈希行工具 + 6 个标准文件系统工具
零依赖	纯 Rust，可编译为单个二进制文件

安装

cargo build --release

二进制文件将位于 target/release/hashfile-mcp。

快速开始

1. 配置 MCP 客户端

添加到 Claude Desktop 或 MCP 客户端配置中：

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

2. （可选）添加访问控制

在项目根目录中创建 AGENTS.md：

---
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. 开始编辑

现在，AI 可以：

• ✅ 以哈希锚定的精度读取和编辑源文件
• ✅ 浏览目录并创建新文件
• ❌ 无法访问你的机密或 .env 文件
• ❌ 无法修改锁文件或架构
• 🙈 看不到 node_modules 或构建产物

Hashline 的工作原理

问题

文件变更后，传统的行号编辑会失效：

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

解决方案

通过哈希验证进行内容锚定编辑：

1. 读取：每行都会获得一个哈希标记 → 42:a3|const x = 1;
2. 编辑：操作引用内容，而不只是位置 → "anchor": "42:a3"
3. 应用：即使该行已移动到第 45 行，服务也能通过哈希找到它
4. 验证：文件哈希必须匹配——用于检测自读取后内容是否发生变化

可靠性功能

• 文件级验证：6 字符哈希可防止编辑过时内容
• 行级锚定：2 字符哈希用于标识特定行
• 模糊匹配：如果行号发生变化，则搜索唯一匹配的哈希
• 冲突检测：内容不一致时显示明确错误

核心工具

Hashline 工具（精确编辑）

read_text_file

返回带有哈希标记行的内容，便于可靠编辑：

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

应用哈希锚定操作：

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

操作类型：replace、insert_after、insert_before、delete

write_text_file

写入内容并返回带有 hashline 标记的验证结果

文件系统工具（标准操作）

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

支持使用 exclude_patterns 进行筛选（例如，["**/node_modules/**", "**/.git/**"]）

create_directory、move_file、write_file、read_multiple_files

支持 AGENTS.md 强制执行的标准文件系统操作

AGENTS.md 访问控制

约束类型

约束	效果	使用场景
forbidden	禁止所有访问	密钥、凭据、私钥
read_only	允许读取，禁止写入	架构、锁文件、生成的配置
ignore	从 AI 上下文中隐藏	依赖项、构建产物、无关内容

自动支持 .gitignore

Hashfile MCP 会自动遵循项目中的 .gitignore 文件：

• 分层处理：从目标文件所在目录向上查找所有 .gitignore 文件
• 标准语法：支持标准 .gitignore 模式（基本名称、目录、路径）
• 与 AGENTS.md 合并：合并两个来源中的模式
• 零配置：可直接用于现有项目

模式转换：

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

**优先级：**AGENTS.md 的 ignore 模式优先于 .gitignore。

示例：保护 Monorepo

---
forbidden:
  - "**/secrets/**"
  - "**/*.key"
  - "**/*.pem"
  - ".env*"

read_only:
  - "**/package-lock.json"
  - "**/Cargo.lock"
  - "db/schema.sql"

ignore:
  - "**/node_modules/**"
  - "**/target/**"
  - "**/.next/**"
  - "**/*.generated.*"
---

分层控制

可在任意层级放置 AGENTS.md 文件：

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

目录层级中最近的 AGENTS.md 文件会生效。

开发

运行测试

cargo test

项目结构

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)

技术详情

• 语言：Rust（edition 2021）
• MCP SDK：rmcp 0.15.0
• 行哈希：FNV-1a（2 个十六进制字符，256 个桶）
• 文件哈希：FNV-1a（6 个十六进制字符，1600 万个桶）
• 传输方式：stdio
• 依赖项：rmcp、serde、serde_json、serde_yaml、globset、anyhow、fnv

路线图

• 基于环境变量启用工具（ENABLE_FILESYSTEM_TOOLS=true）
• 精细控制工具（ENABLE_LIST_DIRECTORY=true 等）
• 其他工具：get_file_info、search_files、list_directory_with_sizes
• 支持通过命令行参数进行配置

许可证

详情请参阅 LICENSE 文件。

另请参阅

• Harness 问题 - 我在一个下午提升了 15 个 LLM 的编码能力。唯一改变的是 Harness。- Can Bölük，2026 年 2 月
• AGENTS.md 提案 - Agent 访问控制的 Frontmatter 规范