文件搜索工具

文件搜索mcp

一个速度极快的MCP服务器，用于在大型代码库和monorepos中搜索文件。

为什么存在

标准工具，如 grep 和 find 在大型代码库上速度非常慢。他们不尊重 .gitignore，它们遵循符号链接循环，并用来自的无关结果淹没您的终端 node_modules.

文件搜索mcp 修复了所有这些问题：

安装

先决条件

• Node.js 18+
• ripgrep（用于内容搜索）

# Install ripgrep
brew install ripgrep    # macOS
apt install ripgrep     # Ubuntu
choco install ripgrep   # Windows

快速入门（npx）

无需安装！只需在MCP客户端配置中添加：

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

全局安装

npm install -g file-search-mcp

然后在你的配置中使用：

{
  "mcpServers": {
    "file-search": {
      "command": "file-search-mcp"
    }
  }
}

使用Claude Desktop

添加到您的Claude Desktop配置中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

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

使用OpenCode

添加到您的OpenCode配置(~/.config/opencode/config.json):

{
  "mcp": {
    "file-search": {
      "type": "local",
      "command": ["npx", "-y", "file-search-mcp"]
    }
  }
}

工具

search_files

按名称或glob模式查找文件。

"Find all TypeScript files"
→ search_files(pattern: "*.ts")

"Find config files modified today"
→ search_files(pattern: "*.config.*", modified_within: "24h")

"Find large log files"
→ search_files(pattern: "*.log", min_size: "10MB")

参数：

• reasoning （必填）-为什么要搜索
• pattern （必填）-球状图案 *.ts, src/**/*.js
• path -要搜索的目录（默认：当前目录）
• include_hidden -包含点文件（默认值：true）
• ignore_gitignore -尊重.gitignore（默认值：true）
• exclude -要跳过的额外模式
• detail_level - minimal | standard | full
• modified_within -只有最近的文件。， 24h, 7d
• min_size -只有大文件。， 1MB

search_content

在文件中查找文本或正则表达式模式。

"Find all TODO comments"
→ search_content(query: "TODO")

"Find API endpoints"
→ search_content(query: "app\.(get|post|put|delete)", file_pattern: "*.ts")

"Find hardcoded secrets"
→ search_content(query: "apiKey|secret|password")

参数：

• reasoning （必填）-为什么要搜索
• query （必填）-要查找的文本或正则表达式
• path -要搜索的目录（默认：当前目录）
• file_pattern -仅搜索匹配的文件
• include_hidden -包含点文件（默认值：true）
• ignore_gitignore -尊重.gitignore（默认值：true）
• exclude -要跳过的额外模式
• detail_level - minimal | standard | full
• context_lines -匹配项周围的线条（默认值：2）

fuzzy_find

模糊搜索，当你不记得确切的名字。

"Find the user controller"
→ fuzzy_find(query: "usrctrl")

"Find that API routes file"
→ fuzzy_find(query: "apirts")

参数：

• reasoning （必填）-为什么要搜索
• query （必填）-模糊搜索词
• path -要搜索的目录（默认：当前目录）
• include_hidden -包含点文件（默认值：true）
• detail_level - minimal | standard | full

tree

可视化目录结构。

"Show me the project structure"
→ tree(depth: 3)

"What's in the src folder?"
→ tree(path: "src", depth: 2)

参数：

• reasoning （必填）-为什么需要此视图
• path -要显示的目录（默认：当前目录）
• depth -遍历深度（默认值：3）
• include_hidden -显示点文件（默认值：false）
• dirs_only -仅显示目录（默认值：false）

细节级别

智能功能

智能案例

默认情况下，搜索不区分大小写，但如果查询包含大写字母，则会区分大小写。这与VS Code、ripgrep和大多数现代工具的工作方式相匹配。

令牌限制

结果会自动截断为约10万个令牌，以防止压倒性的响应。如果发生截断，您将看到警告。

二进制检测

二进制文件（图像、可执行文件、存档等）会自动跳过，以保持结果的干净和相关性。

Symlink安全

遵循符号链接，但检测并阻止循环。不再有无限的遍历！

默认排除

除非你重写，否则这些目录总是会被跳过：

• node_modules
• .git
• dist, build
• coverage
• .next, .nuxt
• __pycache__, .pytest_cache
• venv, .venv
• target （生锈）
• vendor （去）

发展

# Run in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch    # Watch mode

指标

所有工具调用都在本地进行跟踪，以便进行开发分析。指标包括：

• 工具使用计数
• 搜索模式和查询
• 响应时间
• 错误率和截断率
• 用于理解用例的推理文本

# View metrics summary
npm run metrics

# View last 50 raw calls
npm run metrics:raw

# Clear all metrics
npm run metrics:clear

指标存储在 ~/.file-search-mcp/metrics.json

许可证

麻省理工学院