Hashfile MCP

哈希文件MCP服务器

AI文件操作的精细控制 --一个模型上下文协议（MCP）服务器，它为您提供了对文件编辑的精确控制和对文件访问的铁腕控制。

为什么选择哈希文件MCP？

🎯 手术文件编辑

与文件更改时中断的传统基于行号的编辑不同，Hashfile使用 内容锚定操作:

• 哈希锚线：每一行都标记有内容哈希值——edits的目标是 *正确的内容*，而不仅仅是正确的行号
• 模糊匹配：即使在插入/删除后，也会自动查找移动的行
• 碰撞检测：文件级验证可防止编辑过时内容
• 多操作编辑：在单个原子操作中应用多个精确更改

🔒 铁壳门禁

完全控制AI代理可以接触的内容 AGENTS.md头版:

• forbidden：阻止访问机密、凭据、敏感数据
• read_only：允许读取架构、配置、锁定文件——防止修改
• ignore：从AI上下文中隐藏生成的代码、依赖关系、构建工件
• 分层发现：将AGENTS.md放在树中的任何位置——最近的文件获胜
• 球形图案：使用通配符微调访问(secrets/**, **/*.env)

📖 完整的AGENTS.md文档 | 📋 建议书规范

🛠️ 插入式文件系统兼容性

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

• list_directory --浏览 [FILE]/[DIR] 前缀
• directory_tree --紧凑的树视图（令牌效率比JSON高10倍）
• create_directory --递归目录创建
• move_file --重命名/移动文件和目录
• write_file --原始UTF-8写入（非哈希行）
• read_multiple_files --一次性批量读取

功能概览

安装

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

写入内容并返回哈希行标记的验证

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

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访问控制

约束类型

自动.gitignore支持

哈希文件MCP自动遵守 .gitignore 项目中的文件：

• 分层的：从目标文件中查找所有文件 .gitignore 文件
• 标准语法：支持标准 .gitignore 模式（基名、目录、路径）
• 与AGENTS.md结合：两个来源的模式被合并
• 零配置：与现有项目一起开箱即用

图案转换：

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

优先： 代理商.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)

技术细节

• 语言：《铁锈》（2021年版）
• MCP-SDK：人民币0.15.0元
• 线路散列：FNV-1a（2个十六进制字符，256个桶）
• 文件哈希：FNV-1a（6个十六进制字符，16M桶）
• 运输标准： 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文件。

另见

• 线束问题 -我在一个下午的时间里提高了15个LLMs的编码能力。只更换了安全带。-2026年2月25日
• AGENTS.md提案 -代理访问控制的前端规范