Hashfile MCP

Hashfile MCP サーバー

AI によるファイル操作をきめ細かく制御 — ファイル編集を精密に行い、ファイルアクセスを厳格に管理できる Model Context Protocol（MCP）サーバーです。

Hashfile MCP が選ばれる理由

🎯 精密なファイル編集

ファイルの変更によって機能しなくなる従来の行番号ベースの編集とは異なり、Hashfile はコンテンツを基準にした操作を使用します。

• ハッシュを基準にした行：各行にコンテンツハッシュを付与し、正しい行番号ではなく、正しいコンテンツを対象に編集します
• ファジーマッチング：挿入や削除の後でも、移動した行を自動的に見つけます
• 競合検出：ファイル単位の検証により、古いコンテンツの編集を防ぎます
• 複数操作の編集：1 回のアトミックな操作で複数の変更を正確に適用します

🔒 厳格なアクセス制御

AGENTS.md のフロントマターで、AI エージェントがアクセスできる対象を完全に制御できます。

• 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 — 1 回の操作で複数のファイルをまとめて読み取ります

主な機能

機能	メリット
ハッシュを基準にした編集	ファイルの変更後も編集が可能です。「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

コンテンツを書き込み、ハッシュラインタグ付きの検証結果を返します

ファイルシステムツール（標準操作）

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 より優先されます。

例：モノレポを保護する

---
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 桁の 16 進数、256 バケット）
• ファイルのハッシュ化：FNV-1a（6 桁の 16 進数、1,600 万バケット）
• トランスポート：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 個の LLM のコーディング能力を向上させました。変更したのはハーネスだけです。 - Can Bölük、2026 年 2 月
• AGENTS.md 提案 - エージェントのアクセス制御に関するフロントマター仕様