Ripgrep Mcp

Auu.Mcp.Rg

一款跨平台的 MCP（Model Context Protocol）ripgrep 服务，提供强大的搜索功能，可无缝支持 Windows、macOS 和 Linux，并具有增强的安全特性。

功能

• 🌟 兼容跨平台：原生支持 Windows、macOS 和 Linux，并能智能处理路径（v1.2.6）
• 🔧 搜索工具：提供多种适用于不同场景的搜索工具
• 📋 完整支持 ripgrep：支持 ripgrep 的所有选项和标志
• 🚀 可通过 npx 部署：可直接通过 npx 运行
• 🆕 全局根目录：通过环境变量配置整个服务的根目录（v1.2.0）
• 🆕 增强安全性：自动验证路径并防止目录遍历（v1.2.0）
• 🆕 灵活配置：支持在单次调用中覆盖根目录（v1.2.0）
• 🆕 智能路径处理：正确组合根目录和路径参数，让搜索范围更符合直觉（v1.2.1）
• 🆕 性能保护：内置结果数量限制（默认：100）、输出大小限制（10MB）和超时保护（30s）（v1.2.1）
• 🆕 内存保护：自动截断输出，防止内存泄漏（v1.2.1）
• 🆕 智能路径解析：使用 Node.js 路径工具进行跨平台路径规范化和验证（v1.2.6）

安装

npm install -g auu-mcp-rg

或者通过 npx 使用：

npx auu-mcp-rg

可用工具

1. search

使用常见选项进行基本搜索：

• pattern：搜索模式（必填）
• root：限制搜索范围的根目录（可选，搜索仅限于此目录）
• path：要搜索的目录（可选，如果指定，则必须位于 root 内；与 root 组合后可得到直观的搜索范围）
• include：要包含的文件的 Glob 模式
• exclude：要排除的文件的 Glob 模式
• context：上下文行数
• max_matches：最多返回的匹配数量（默认：100）
• case_sensitive：区分大小写搜索
• word_boundaries：仅匹配完整单词
• file_type：仅搜索特定文件类型

2. advanced-search

完整访问 ripgrep 的所有选项，并支持全部参数。

3. count-matches

统计匹配数量，而不是显示匹配内容：

• pattern：搜索模式（必填）
• root：限制搜索范围的根目录（可选，搜索仅限于此目录）
• path：要搜索的目录（可选，如果指定，则必须位于 root 内；与 root 组合后可得到直观的搜索范围）
• include：要包含的文件的 Glob 模式
• exclude：要排除的文件的 Glob 模式
• case_sensitive：区分大小写搜索
• file_type：仅搜索特定文件类型

4. list-files

列出将要搜索的所有文件：

• root：限制搜索范围的根目录（可选，搜索仅限于此目录）
• path：要搜索的目录（可选，如果指定，则必须位于 root 内；与 root 组合后可得到直观的搜索范围）
• include：要包含的文件的 Glob 模式
• exclude：要排除的文件的 Glob 模式
• file_type：仅搜索特定文件类型

5. list-file-types

列出 ripgrep 支持的所有文件类型。

使用示例

基本搜索

{
  "name": "search",
  "arguments": {
    "pattern": "function",
    "max_matches": 10
  }
}

使用全局根目录进行搜索

在服务中配置 ROOT 后，所有搜索都会自动限制在该目录中：

{
  "name": "search",
  "arguments": {
    "pattern": "import",
    "include": "*.ts",
    "max_matches": 5
  }
}

统计项目中的文件

{
  "name": "count-matches",
  "arguments": {
    "pattern": "TODO",
    "include": "*.js"
  }
}

列出 TypeScript 文件

{
  "name": "list-files",
  "arguments": {
    "include": "*.ts",
    "file_type": "typescript"
  }
}

使用上下文进行高级搜索

{
  "name": "advanced-search",
  "arguments": {
    "pattern": "class.*Controller",
    "include": "*.ts",
    "context": 2,
    "case_sensitive": true
  }
}

为特定搜索覆盖根目录

{
  "name": "search",
  "arguments": {
    "pattern": "test",
    "root": "/path/to/tests",
    "include": "*.spec.js"
  }
}

组合根目录和路径进行搜索（v1.2.1+）

同时指定 root 和 path 时，它们会自动组合：

{
  "name": "search",
  "arguments": {
    "pattern": "config",
    "root": "/path/to/project",
    "path": "src",
    "include": "*.ts",
    "max_matches": 50
  }
}

这会在 /path/to/project/src 目录中搜索。

使用内置限制进行安全搜索（v1.2.1+）

所有搜索都会自动采用合理的默认设置，以防止输出过多内容：

{
  "name": "search",
  "arguments": {
    "pattern": "import",
    "path": "src"
  }
}

最多返回 100 条结果，并受到超时和大小限制的保护。

配置

基本配置

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "auu-mcp-rg": {
      "command": "npx",
      "args": ["auu-mcp-rg"]
    }
  }
}

根目录配置（推荐）

为增强安全性，请配置默认根目录，以限制所有搜索操作：

{
  "mcpServers": {
    "auu-mcp-rg": {
      "command": "npx",
      "args": ["auu-mcp-rg"],
      "env": {
        "ROOT": "/path/to/your/project"
      }
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "auu-mcp-rg": {
      "command": "npx",
      "args": ["auu-mcp-rg"],
      "env": {
        "ROOT": "E:\\code\\my-project"
      }
    }
  }
}

macOS/Linux 示例：

{
  "mcpServers": {
    "auu-mcp-rg": {
      "command": "npx",
      "args": ["auu-mcp-rg"],
      "env": {
        "ROOT": "/Users/username/my-project"
      }
    }
  }
}

配置选项

• ROOT：设置所有搜索操作的默认根目录（可选，但推荐）
• AUU_MCP_RG_VERSION：固定版本以确保稳定性（可选）

配置 ROOT 后，除非明确覆盖，否则所有工具都会自动使用此目录。

增强的跨平台兼容性（v1.2.6）

此服务现在通过智能路径处理提供更出色的跨平台兼容性：

🆕 高级跨平台功能

智能路径解析：

• 自动检测并处理特定于平台的路径格式
• 相对于根目录智能解析相对路径
• 使用 Node.js path.relative() 和 path.isAbsolute() 进行跨平台路径验证

通用路径规范化：

• 自动将 Windows 反斜杠转换为正斜杠，以兼容 ripgrep
• 在所有平台上保持一致的路径处理方式
• 支持在同一环境中混用不同的路径格式

平台特定优化

Windows

• 原生路径支持：全面支持 Windows 风格的路径（C:\project\src）
• 命令转义：正确转义 Windows 命令参数
• 进程管理：针对 Windows 优化的进程启动

macOS 和 Linux

• Unix 路径标准：原生支持 POSIX 路径（/home/user/project）
• Shell 集成：采用标准 Unix shell 行为
• 性能：针对 Unix 进程管理进行了优化

🆕 跨平台示例

Windows 配置：

{
  "mcpServers": {
    "auu-mcp-rg": {
      "command": "npx",
      "args": ["auu-mcp-rg"],
      "env": {
        "ROOT": "E:\\code\\my-project"
      }
    }
  }
}

macOS/Linux 配置：

{
  "mcpServers": {
    "auu-mcp-rg": {
      "command": "npx",
      "args": ["auu-mcp-rg"],
      "env": {
        "ROOT": "/home/username/my-project"
      }
    }
  }
}

跨平台路径用法：

{
  "name": "search",
  "arguments": {
    "pattern": "import",
    "root": "E:\\code\\project",  // Windows path
    "path": "src/utils"           // Relative path works on all platforms
  }
}

🆕 技术改进（v1.2.6）

• 增强路径验证：使用 path.relative() 而非字符串匹配，可靠地检查跨平台路径边界
• 改进相对路径支持：正确处理相对于根目录的相对路径
• 内存安全：改进路径处理，防止安全问题
• 性能：优化路径解析和验证算法
• 全面测试：增加了广泛的跨平台测试覆盖

Windows 兼容性修复

此服务解决了其他 MCP ripgrep 实现中发现的若干 Windows 兼容性问题：

1. 正确转义命令：使用适用于 Windows 的参数转义方式
2. 进程执行：直接启动进程，不依赖 shell
3. 路径处理：正确处理包含空格和特殊字符的 Windows 路径
4. 构建流程：移除了 chmod 等 Unix 专用命令

安全与性能功能（v1.1.0+）

全局根目录配置

ROOT 环境变量通过将所有搜索操作限制在特定目录中，提供服务级别的安全保护：

{
  "mcpServers": {
    "auu-mcp-rg": {
      "command": "npx",
      "args": ["auu-mcp-rg"],
      "env": {
        "ROOT": "/path/to/project"
      }
    }
  }
}

优势：

• 服务级安全：所有工具都会自动遵守根目录边界
• 无需配置：无需在单独的工具调用中指定根目录
• 防止意外访问：保护项目目录之外的敏感文件
• 沙盒环境：提供受控的搜索范围，增强安全性
• 多租户支持：非常适合共享环境和团队项目
• 目录遍历保护：阻止访问根目录之外路径的尝试

单次调用根目录覆盖

你仍可为单独的工具调用指定不同的根目录：

{
  "name": "search",
  "arguments": {
    "pattern": "function",
    "root": "/different/path/project",
    "max_matches": 10
  }
}

路径验证

• 自动验证：根据根目录验证所有搜索路径
• 清晰的错误消息：尝试访问根目录之外的路径时会被阻止，并显示详细错误
• 灵活的路径支持：同时支持绝对路径和相对路径
• 跨平台：正确处理 Windows、macOS 和 Linux 路径格式

性能与内存保护（v1.2.1+）

• 结果限制：每次搜索内置 100 条匹配结果上限，防止输出过多
• 输出大小限制：自动截断超过 10MB 的输出，防止内存问题
• 超时保护：设置 30 秒超时，防止搜索卡住
• 内存安全：自动清理进程并管理资源
• 智能默认值：采用合理的默认值，兼顾功能与安全性

智能路径处理（v1.2.1+）

• 路径组合：同时指定 root 和 path 时，会智能地将两者组合
• 直观的搜索范围：root: "/project", path: "src" 会在 /project/src 中搜索
• 验证：组合后的路径仍会根据安全边界进行验证
• 向后兼容：现有用法保持不变，继续正常工作

要求

• Node.js 18+
• 已安装 ripgrep，且可通过 PATH 使用
• Windows、macOS 或 Linux

许可证

MIT