Files

MCP Tools

让 Agent 能够快速查找和编辑代码库中的代码，并做到精准无误。查找符号，并在所有位置进行编辑。

📋 目录

• 🚀 快速开始
• 🛠️ 可用工具
• ⚡ 精准代码编辑：手术级精度
• 🎛️ 环境变量
• 🖥️ 服务用法
• 💻 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	使用原生通知系统发送操作系统通知	message, title?

⚡ 精准代码编辑：手术级精度

read_symbol + insert_text 的组合解锁了革命性的代码编辑能力，彻底改变 AI Agent 处理代码库的方式。

🎯 强强联手

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

💻 命令行用法

所有工具都可以直接从命令行使用：

# 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 工具包含一个 optimize 参数，可清理代码以便 AI 处理：

功能：

• 移除注释：移除 //、/* */ 和 /** */ 注释
• 合并换行符：将多个连续换行符合并为单个换行符
• 规范缩进：将空格转换为制表符（自动检测缩进标记大小）
• 移除基础缩进：删除共同的前导空白字符

用法：

// 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 Agent 打造 🤖