Files Stdio MCP Server

🚀 Files MCP Server

このサーバーは、サンドボックス化されたファイルアクセス用のStdio MCPサーバーです。ディレクトリを探索し、ファイルを読み取り、内容を検索し、チェックサム検証を使用して安全に編集することができます。

作者: overment

⚠️ 重要提示

このサーバーは、AIエージェントにファイルシステムへのアクセスを提供します。特定のディレクトリにサンドボックス化されていますが、常に以下のことを行ってください。

• 変更を確定する前にツールの出力を確認する
• 破壊的な操作をプレビューするにはdryRun=trueを使用する
• 重要なファイルのバックアップを取る
• FS_ROOTSをエージェントがアクセスする必要のあるディレクトリのみに設定する

✨ 主な機能

開発動機

従来のファイル操作には、正確なパスと内容が必要ですが、これは大規模言語モデル（LLM）にとって困難な作業です。このサーバーは、AIエージェントが以下のことを行えるように設計されています。

• 最初に探索する — アクションを実行する前にディレクトリ構造を理解する
• 名前または内容で検索する — 正確なパスを知らなくてもファイルを見つける
• 安全に編集する — チェックサム検証により古い上書きを防止する
• 変更をプレビューする — ドライランモードで適用前に差分を表示する
• エラーから回復する — ヒントに従ってエージェントが間違いを修正する

結果として、エージェントはObsidianボールト、ドキュメント、ノート、またはテキストベースのファイルコレクションを確実に管理できます。

機能一覧

• ✅ ディレクトリ探索 — ファイル数、サイズ、タイムスタンプ付きのツリービュー
• ✅ ファイル読み取り — 安全な編集のためにチェックサム付きの行番号付き内容
• ✅ ファイル検索 — ファイル名パターン（*.md、config.json）による再帰的検索
• ✅ 内容検索 — リテラル、正規表現、ファジーパターンマッチング（大文字小文字を区別しないオプション付き）
• ✅ プリセットパターン — 組み込みのObsidianパターン（ウィキリンク、タグ、タスク、見出し）
• ✅ 安全な編集 — チェックサム検証、ドライランプレビュー、統一差分
• ✅ バッチ操作 — ファイル全体の一括リネーム用のreplaceAll
• ✅ マルチマウントサポート — 複数のディレクトリを仮想マウントポイントとしてアクセスする
• ✅ サンドボックス化 — 構成されたマウント外のパスにはアクセスできない

設計原則

• 編集前に探索する：エージェントはファイルを変更する前に読み取る必要があります（チェックサムと行番号を取得します）
• 適用前にプレビューする：dryRun=trueで正確に何が変更されるかを表示します
• 明確なフィードバック：すべての応答には次のステップとエラー回復のヒントが含まれています
• デフォルトでコンパクト：details=trueの場合のみ、ファイルの詳細（サイズ、変更日時）が表示されます
• 単一マウント最適化：1つのマウントが構成されている場合、fs_read(".")は直接内容を表示します

📦 インストール

クイックスタート

1. インストール

cd files-mcp
bun install

2. 設定

.envファイルを作成します。

# エージェントがアクセスできるディレクトリ（カンマ区切り）
FS_ROOTS=/path/to/vault,/path/to/docs

# または単一のディレクトリの場合
# FS_ROOT=/path/to/vault

# オプション
LOG_LEVEL=info
MAX_FILE_SIZE=1048576

3. 起動

bun dev

4. クライアントに接続

Claude Desktop / Cursor:

{
  "mcpServers": {
    "filesystem": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/files-mcp/src/index.ts"],
      "env": {
        "FS_ROOTS": "/Users/you/vault,/Users/you/docs"
      }
    }
  }
}

MCPバンドル（MCPB）によるインストール

このサーバーは、Claude Desktop、Alice、およびその他のMCPB互換アプリケーションなどのサポートされているアプリでワンクリックインストール用のMCPバンドル（.mcpb）としても利用できます。

MCPBとは何か？

MCPバンドルは、ローカルMCPサーバーとサーバーとその機能を説明するmanifest.jsonを含むZIPアーカイブです。この形式により、エンドユーザーは手動での設定を必要とせずにローカルMCPサーバーをワンクリックでインストールできます。

MCPBからのインストール手順

1. files-mcp.mcpbファイルをダウンロードします。
2. 互換性のあるアプリ（Claude Desktop、Aliceなど）で開きます。
3. 求められたらルートディレクトリを設定します。これはエージェントがアクセスできるディレクトリです。
4. 完了です！サーバーがインストールされ、使用準備が整いました。

manifest.jsonの詳細

このマニフェストは以下を定義します。

• サーバー構成 — コマンド、引数、環境変数
• ツール — fs_readとfs_writeの説明付き
• ユーザー設定 — インストール時にFS_ROOTディレクトリを求める

{
  "manifest_version": "0.2",
  "name": "files-mcp",
  "version": "1.0.0",
  "server": {
    "type": "node",
    "entry_point": "dist/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/dist/index.js"],
      "env": {
        "FS_ROOT": "${user_config.FS_ROOT}"
      }
    }
  },
  "user_config": {
    "FS_ROOT": {
      "type": "directory",
      "title": "Root Directory",
      "description": "The directory the agent will have access to.",
      "required": true
    }
  }
}

${user_config.FS_ROOT}構文は、実行時にユーザーが選択したディレクトリをサーバーの環境に注入します。

📚 ドキュメント

サーバーの使用方法（モデルが見る内容）

🔒 サンドボックス化されたファイルシステム — このツールは特定のマウントされたディレクトリのみにアクセスできます。
   /UsersやC:\などの任意のシステムパスにはアクセスできません。
   常にfs_read(".")から始めて、利用可能なマウントを確認してください。

⚠️ ファイルの内容に関する質問に答える前には必ずファイルを読み取ってください。
⚠️ ファイルを変更する前には必ずファイルを読み取ってください（チェックサムが必要です）。

必須のワークフロー：
1. fs_read(".") → 利用可能なマウントを確認する
2. fs_read("path/file.md") → 内容とチェックサムを取得する
3. dryRun=trueでfs_write → 差分をプレビューする
4. dryRun=false + チェックサムでfs_write → 変更を適用する
5. 応答の差分が意図した内容と一致することを確認する

ツールの説明

fs_read

ディレクトリを探索し、ファイルを読み取り、名前でファイルを検索するか、内容を検索します。

入力:

{
  path: string;                    // ルートの場合は"."、"docs/"、"notes/todo.md"
  
  // 名前でファイルを検索
  find?: string;                   // "*.md"、"config.json"
  
  // 内容を検索
  pattern?: string;                // 検索するテキスト
  patternMode?: "literal" | "regex" | "fuzzy";
  caseInsensitive?: boolean;        // マッチング時に大文字小文字を無視する
  preset?: "wikilinks" | "tags" | "tasks" | "tasks_open" | "tasks_done" 
         | "headings" | "codeblocks" | "frontmatter";
  
  // オプション
  depth?: number;                  // ディレクトリトラバーサルの深さ（デフォルト3）
  details?: boolean;               // サイズ/変更日時を含める（デフォルトfalse）
  lines?: string;                  // "10-50"で部分読み取り
  context?: number;                // マッチの周囲の行数（デフォルト3）
  maxFiles?: number;               // マッチするファイルの最大数（デフォルト：制限なし）
  maxMatches?: number;             // マッチの制限（デフォルト100）
}

出力:

{
  success: boolean;
  path: string;
  type: "directory" | "file" | "search";
  
  // ディレクトリの場合
  tree?: {
    entries: Array<{ path, kind, children?, size?, modified? }>;
    summary: string;
  };
  
  // ファイルの場合
  content?: {
    text: string;        // 行番号付き
    checksum: string;    // fs_writeに渡す
    totalLines: number;
  };
  
  // 検索の場合
  matches?: Array<{ file, line, column, text, context }>;
  matchCount?: number;
  
  hint: string;          // 次のアクションの提案
}

fs_write

安全機能付きでファイルを作成、変更、または削除します。

入力:

{
  path: string;
  operation: "create" | "update" | "delete";
  
  // 作成の場合
  content?: string;
  
  // 更新の場合 — 行またはパターンでターゲットを指定
  lines?: string;                  // "10-15" — 推奨
  pattern?: string;                // 検索するテキスト
  patternMode?: "literal" | "regex" | "fuzzy";
  caseInsensitive?: boolean;       // 大文字小文字を無視する
  
  // 更新の場合 — アクション
  action?: "replace" | "insert_before" | "insert_after" | "delete_lines";
  content?: string;                // 新しい内容
  
  // 一括置換
  replaceAll?: boolean;            // すべての一致を置換する
  
  // 安全対策
  checksum?: string;               // fs_readから取得 — 推奨
  dryRun?: boolean;                // プレビューのみ（デフォルトfalse）
}

出力:

{
  success: boolean;
  path: string;
  operation: "create" | "update" | "delete";
  applied: boolean;
  
  result?: {
    action: string;
    linesAffected?: number;
    newChecksum?: string;
    diff?: string;               // 統一差分
  };
  
  error?: {
    code: string;
    message: string;
    recoveryHint?: string;
  };
  
  hint: string;
}

プリセットパターン（Obsidian/Markdown）

一般的な検索用の組み込みパターンです。

例:

{ "path": ".", "preset": "tasks_open" }

使用例

1. ボールトを探索する

{ "path": "." }

応答:

18 items (15 files, 3 directories)

- Core/
- Projects/
- Books/
- map.md
- inbox.md
...

hint: "Showing contents of 'vault'. Use fs_read on any path to explore deeper."

2. ファイルを検索する

{ "path": ".", "find": "*.md" }

応答:

Found 42 item(s) matching "*.md"

- Core/Values.md
- Core/Process.md
- Projects/Alice.md
...

hint: "Found 42 matching files. Use fs_read on a specific path to see its content."

3. ファイルを読み取る

{ "path": "Core/Values.md" }

応答:

File read complete. Checksum: a1b2c3d4e5f6.

   1| # Values
   2|
   3| ## Integrity
   4| Be honest, even when it's hard.
   5|
   6| ## Growth
   7| Learn something new every day.
...

hint: "To edit this file, use fs_write with checksum a1b2c3d4e5f6."

4. すべての未完了タスクを検索する

{ "path": ".", "preset": "tasks_open" }

応答:

Found 7 matches in 42 files across all mounts.

- Projects/Alice.md:12 — "- [ ] Implement search"
- Projects/Alice.md:15 — "- [ ] Add tests"
- inbox.md:3 — "- [ ] Review PR"
...

5. テキストを置換する（最初にプレビュー）

{
  "path": "Core/Values.md",
  "operation": "update",
  "pattern": "Be honest",
  "action": "replace",
  "content": "Act with integrity",
  "checksum": "a1b2c3d4e5f6",
  "dryRun": true
}

応答:

DRY RUN — no changes applied.

--- a/Core/Values.md
+++ b/Core/Values.md
@@ -3,1 +3,1 @@
-Be honest, even when it's hard.
+Act with integrity, even when it's hard.

hint: "Review the diff above. Run with dryRun=false to apply."

6. ウィキリンクを一括リネームする

{
  "path": "Projects/Alice.md",
  "operation": "update",
  "pattern": "[[Old Name]]",
  "action": "replace",
  "content": "[[New Name]]",
  "replaceAll": true,
  "dryRun": true
}

応答:

DRY RUN — would replace 3 occurrence(s) at lines 5, 12, 28.

7. タスクを完了としてマークする

{
  "path": "inbox.md",
  "operation": "update",
  "pattern": "- [ ] Review PR",
  "action": "replace",
  "content": "- [x] Review PR",
  "checksum": "xyz789"
}

応答:

replaced 1 line(s). New checksum: abc123.

hint: "The diff above shows what changed."

設定

マルチマウント設定

複数のディレクトリにアクセスするには、以下のように設定します。

FS_ROOTS=/Users/me/vault,/Users/me/projects,/Users/me/notes

各パスは、フォルダ名を基にマウント名になります。

• vault/ → /Users/me/vault
• projects/ → /Users/me/projects
• notes/ → /Users/me/notes

クライアント設定

Claude Desktop:

{
  "mcpServers": {
    "filesystem": {
      "command": "bun",
      "args": ["run", "/path/to/files-mcp/src/index.ts"],
      "env": {
        "FS_ROOTS": "/Users/me/vault"
      }
    }
  }
}

Cursor:

{
  "filesystem": {
    "command": "bun",
    "args": ["run", "/path/to/files-mcp/src/index.ts"],
    "env": {
      "FS_ROOTS": "/Users/me/vault"
    }
  }
}

開発

bun dev           # ホットリロードで起動
bun test          # テストを実行
bun run typecheck # TypeScriptチェック
bun run lint      # コードのリント
bun run build     # 本番用ビルド
bun run inspector # MCPインスペクターでテスト

アーキテクチャ

src/
├── index.ts              # エントリポイント：stdioトランスポート
├── config/
│   ├── env.ts            # 環境設定とマウント解析
│   └── metadata.ts       # ツールの説明
├── core/
│   ├── capabilities.ts   # サーバーの機能
│   └── mcp.ts            # McpServerビルダー
├── tools/
│   ├── index.ts          # ツールの登録
│   ├── fs-read.tool.ts   # 読み取り、探索、検索
│   └── fs-write.tool.ts  # 作成、更新、削除
├── lib/
│   ├── checksum.ts       # SHA256チェックサム
│   ├── diff.ts           # 統一差分生成
│   ├── filetypes.ts      # テキスト/バイナリ検出
│   ├── ignore.ts         # .gitignoreサポート
│   ├── lines.ts          # 行操作
│   ├── paths.ts          # マルチマウントパス解決
│   └── patterns.ts       # パターンマッチングとプリセット
└── utils/
    ├── errors.ts         # エラーユーティリティ
    └── logger.ts         # ロギング

トラブルシューティング

📄 ライセンス

MIT