Files

MCP ツール

エージェントがコードベース内のコードを素早く見つけ、的確に編集できるようにします。シンボルを見つけて、該当箇所をすべて編集できます。

📋 目次

• 🚀 クイックスタート
• 🛠️ 利用可能なツール
• ⚡ 外科的なコード編集：精密な編集
• 🎛️ 環境変数
• 🖥️ サーバーの使い方
• 💻 CLI の使い方
• 🏗️ アーキテクチャ
• 🧪 開発
• 🛠️ トラブルシューティング
• 📝 ライセンス
• 🔗 リンク

🚀 クイックスタート

オプション 1：NPX（推奨）

Cursor の場合は ~/.cursor/mcp.json に、Claude Desktop の場合は ~/.config/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "mcp-files": {
      "command": "npx",
      "args": ["-y", "mcp-files"]
    }
  }
}

オプション 2：Docker

{
  "mcpServers": {
    "mcp-files": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "flesler/mcp-files"
      ]
    }
  }
}

オプション 3：HTTP トランスポート

まずサーバーを起動します：

TRANSPORT=http PORT=3000 npx mcp-files

次に：

{
  "mcpServers": {
    "mcp-files": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp"
    }
  }
}

🛠️ 利用可能なツール

ツール	説明	パラメーター
read_symbol	ファイルからシンボル名に一致するコードブロックを検索して抽出します。配列を使って複数のシンボルを指定できます	symbols (string[]), file_paths[]?, limit?, optimize?
import_symbol	JavaScript／TypeScript のモジュールとそのプロパティをインポートして調べます	module_path, property?
search_replace	空白をインテリジェントに処理し、複数の一致箇所も自動化に適した方法で解決しながら、検索と置換を行います	file_path, old_string, new_string, allow_multiple_matches?
insert_text	正確な行範囲にテキストを挿入／置換します。コード引用（12:15:file.ts）に基づく直接的な行操作や、大きなファイルの精密な編集に最適です	file_path, from_line, text, to_line
os_notification	OS のネイティブ通知システムを使って通知を送信します	message, title?

⚡ 外科的なコード編集：精密な編集

read_symbol と insert_text の組み合わせにより、AI エージェントのコードベースでの作業方法を一変させる、革新的なコード編集機能を利用できます。

🎯 強力な組み合わせ

1. シンボルの検出（read_symbol） - コードベース内のどこにあるシンボルでも見つけます：

// Find single function/class/interface anywhere in repo
read_symbol({symbols: ["generateApiKey"]})
// → Returns: exact location (lines 45-52 in src/auth/tokens.ts)

// Find multiple symbols at once
read_symbol({symbols: ["User", "UserService", "UserInterface"]})
// → Returns: all matching symbols with their locations

// Optimize code for AI context (strips comments, normalizes indentation)
read_symbol({symbols: ["complexFunction"], optimize: true})
// → Returns: clean, tab-indented code without comments for AI processing

2. 精密な編集（insert_text） - 正確な行範囲を指定して、的確に変更します：

// Replace specific lines with surgical precision
insert_text(file: "src/auth/tokens.ts", from_line: 45, to_line: 52, text: "improved implementation")

// Insert new code without disruption
insert_text(file: "src/auth/tokens.ts", from_line: 45, text: "// Added security enhancement")

🚀 強力な機能を解放

🔍 コードベース横断のインテリジェンス

• リポジトリ全体から任意のシンボルを瞬時に見つけます
• ファイルやフォルダーを手作業で検索する必要はありません
• 大規模なコードベースでも高い精度を実現します

✂️ 精密な編集

• 関数、クラス、コードブロックを正確に編集します
• 周囲のコードに影響を与えずに実装を置き換えます
• 最適な位置に機能を追加します

🎛️ エラーのないリファクタリング

• 関数シグネチャを、存在するすべての箇所で更新します
• すべてのファイルの API を同時に変更します
• コードベース全体のバグを精密に修正します

💡 実際の活用例

# Find and enhance any function
read_symbol("validateEmail") → lines 23-35 in utils/validation.ts
insert_text(from_line: 23, to_line: 35, text: "enhanced validation with regex")

# Add documentation to any symbol
read_symbol("processPayment") → line 87 in payment/processor.ts
insert_text(from_line: 87, text: "/** Secure payment processing with fraud detection */")

# Fix bugs anywhere in codebase
read_symbol("parseUserInput") → lines 156-162 in input/parser.ts
insert_text(from_line: 156, to_line: 162, text: "sanitized parsing logic")

これにより、AI は「頼れるアシスタント」から「コードを精密に手術する達人」へと変わります 🦾

🎛️ 環境変数

変数	デフォルト	説明
TRANSPORT	stdio	トランスポートモード：stdio または http
PORT	4657	HTTP サーバーのポート（TRANSPORT=http の場合）
DEBUG	false	デバッグモードと utils_debug ツールを有効にします

🖥️ サーバーの使い方

mcp-files をインストールして使う方法と、npx mcp-files を使う方法があります。

# Show help
mcp-files --help

# Default: stdio transport
mcp-files

# HTTP transport
TRANSPORT=http mcp-files
TRANSPORT=http PORT=8080 mcp-files

# With debug mode
DEBUG=true mcp-files

💻 CLI の使用方法

すべてのツールはコマンドラインから直接使用できます：

# Find single symbol in code (specific file)
mcp-files read_symbol "MyInterface" src/types.ts

# Find multiple symbols at once (comma-separated)
mcp-files read_symbol "User,UserService,UserInterface" src/

# Find symbol in current directory (default)
mcp-files read_symbol "MyInterface"

# Use wildcards for pattern matching
mcp-files read_symbol "get*,User*" src/

# Inspect imports
mcp-files import_symbol lodash get

# Replace text with smart whitespace handling
mcp-files replace_text config.json "old_value" "new_value"

# Send notifications
mcp-files os_notification "Task completed"

🏗️ アーキテクチャ

• Zod による検証を備えた型安全なツール
• src/tools/ 内の自己完結型モジュール
• クロスプラットフォーム対応（Linux、macOS、Windows、WSL）
• メモ化によるパフォーマンス最適化
• 説明的なメッセージによる明確なエラー処理

🧪 開発

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Lint
npm run lint:full

# Test
npm run ts test/index.test.ts

# CLI testing
node dist/index.js read_symbol "functionName" file.ts

# Multiple symbols (comma-separated in CLI)
node dist/index.js read_symbol "func1,func2,Class*" file.ts

# Or search current directory
node dist/index.js read_symbol "functionName"

🧹 コードの最適化

read_symbol ツールには、AI 処理向けにコードを整理する optimize パラメーターが含まれています：

できること：

• コメントの除去：//、/* */、/** */ コメントを削除します
• 改行の集約：連続する複数の改行を単一の改行にします
• インデントの正規化：スペースをタブに変換します（インデントのトークンサイズを自動検出します）
• 基本インデントの削除：共通する先頭の空白を取り除きます

使用方法：

// MCP mode - explicit control
read_symbol({symbols: ["MyClass"], optimize: true})  // optimized
read_symbol({symbols: ["MyClass"], optimize: false}) // raw code (default)

// CLI mode - always optimized
mcp-files read_symbol "MyClass" src/

最適な用途： コードの構造と読みやすさを保ちながら、AI のコンテキストウィンドウ内のトークン数を削減できます。

🛠️ トラブルシューティング

要件

• Node.js ≥20 - このパッケージには Node.js バージョン 20 以降が必要です

よくある問題

npx mcp-files の実行時に ERR_MODULE_NOT_FOUND が発生する

• 問題：npx mcp-files の実行時に Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js' のようなエラーが発生します
• 原因：npx のキャッシュが破損または不完全なため、依存関係を正しく解決できません
• 解決方法：npx のキャッシュをクリアして、もう一度お試しください：

  npx clear-npx-cache
  npx mcp-files
  

• 注記：この問題は Node.js v20 と v22 の両方で発生する可能性があり、キャッシュをクリアすると解決します

MCP クライアントにツールが表示されない場合：

• Node.js のバージョンが 20 以降であることを確認してください
• 設定を変更した後、MCP クライアントを再起動してみてください

ファイル操作が失敗する場合：

• 読み取りまたは変更しようとしているファイルに適切な権限があることを確認してください
• 信頼性を高めるため、可能な場合は絶対パスを使用してください
• 対象ファイルが存在し、アクセス可能であることを確認してください

📝 ライセンス

MIT - LICENSE ファイルをご覧ください。

🔗 リンク

• 📦 NPM パッケージ
• 🐙 GitHub リポジトリ
• 🐛 問題を報告
• 📚 MCP 仕様

---

AI エージェント向けに構築 🤖