superauu/Auu.Mcp.Rg
If you are the rightful owner of Auu.Mcp.Rg and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Auu.Mcp.Rg
A cross-platform MCP (Model Context Protocol) server for ripgrep that provides powerful search capabilities with seamless support for Windows, macOS, and Linux, plus enhanced security features.
Features
- 🌟 Cross-Platform Compatible: Native support for Windows, macOS, and Linux with intelligent path handling (v1.2.6)
- 🔧 Search Tools: Multiple search tools for different use cases
- 📋 Full ripgrep Support: Supports all ripgrep options and flags
- 🚀 npx Deployable: Can be run directly with npx
- 🆕 Global Root Directory: Server-wide root directory configuration via environment variable (v1.2.0)
- 🆕 Enhanced Security: Automatic path validation and directory traversal protection (v1.2.0)
- 🆕 Flexible Configuration: Per-call root override capability (v1.2.0)
- 🆕 Smart Path Handling: Properly combines root and path parameters for intuitive search scope (v1.2.1)
- 🆕 Performance Safeguards: Built-in result limits (default: 100), output size limits (10MB), and timeout protection (30s) (v1.2.1)
- 🆕 Memory Protection: Automatic output truncation to prevent memory leaks (v1.2.1)
- 🆕 Intelligent Path Resolution: Cross-platform path normalization and validation using Node.js path utilities (v1.2.6)
Installation
npm install -g auu-mcp-rg
Or use with npx:
npx auu-mcp-rg
Tools Available
1. search
Basic search with common options:
- pattern: The search pattern (required)
- root: The root directory to limit search scope (optional, search will be restricted to this directory)
- path: Directory to search in (optional, must be within root if specified, combines with root for intuitive search scope)
- include: Glob pattern for files to include
- exclude: Glob pattern for files to exclude
- context: Number of context lines
- max_matches: Maximum number of matches to return (default: 100)
- case_sensitive: Case sensitive search
- word_boundaries: Match whole words only
- file_type: Only search specific file types
2. advanced-search
Full access to all ripgrep options with complete parameter support.
3. count-matches
Count matches instead of showing them:
- pattern: The search pattern (required)
- root: The root directory to limit search scope (optional, search will be restricted to this directory)
- path: Directory to search in (optional, must be within root if specified, combines with root for intuitive search scope)
- include: Glob pattern for files to include
- exclude: Glob pattern for files to exclude
- case_sensitive: Case sensitive search
- file_type: Only search specific file types
4. list-files
List all files that would be searched:
- root: The root directory to limit search scope (optional, search will be restricted to this directory)
- path: Directory to search in (optional, must be within root if specified, combines with root for intuitive search scope)
- include: Glob pattern for files to include
- exclude: Glob pattern for files to exclude
- file_type: Only search specific file types
5. list-file-types
List all supported file types by ripgrep.
Usage Examples
Basic Search
{
"name": "search",
"arguments": {
"pattern": "function",
"max_matches": 10
}
}
Search with Global Root Directory
When ROOT
is configured in the server, all searches are automatically limited to that directory:
{
"name": "search",
"arguments": {
"pattern": "import",
"include": "*.ts",
"max_matches": 5
}
}
Count Files in Project
{
"name": "count-matches",
"arguments": {
"pattern": "TODO",
"include": "*.js"
}
}
List TypeScript Files
{
"name": "list-files",
"arguments": {
"include": "*.ts",
"file_type": "typescript"
}
}
Advanced Search with Context
{
"name": "advanced-search",
"arguments": {
"pattern": "class.*Controller",
"include": "*.ts",
"context": 2,
"case_sensitive": true
}
}
Override Root Directory for Specific Search
{
"name": "search",
"arguments": {
"pattern": "test",
"root": "/path/to/tests",
"include": "*.spec.js"
}
}
Combined Root and Path Search (v1.2.1+)
When both root and path are specified, they are automatically combined:
{
"name": "search",
"arguments": {
"pattern": "config",
"root": "/path/to/project",
"path": "src",
"include": "*.ts",
"max_matches": 50
}
}
This searches in /path/to/project/src
directory.
Safe Search with Built-in Limits (v1.2.1+)
All searches automatically include sensible defaults to prevent excessive output:
{
"name": "search",
"arguments": {
"pattern": "import",
"path": "src"
}
}
This will return at most 100 results and is protected by timeout and size limits.
Configuration
Basic Configuration
Add to your Claude Desktop configuration:
{
"mcpServers": {
"auu-mcp-rg": {
"command": "npx",
"args": ["auu-mcp-rg"]
}
}
}
Root Directory Configuration (Recommended)
For enhanced security, configure a default root directory to limit all search operations:
{
"mcpServers": {
"auu-mcp-rg": {
"command": "npx",
"args": ["auu-mcp-rg"],
"env": {
"ROOT": "/path/to/your/project"
}
}
}
}
Windows Example:
{
"mcpServers": {
"auu-mcp-rg": {
"command": "npx",
"args": ["auu-mcp-rg"],
"env": {
"ROOT": "E:\\code\\my-project"
}
}
}
}
macOS/Linux Example:
{
"mcpServers": {
"auu-mcp-rg": {
"command": "npx",
"args": ["auu-mcp-rg"],
"env": {
"ROOT": "/Users/username/my-project"
}
}
}
}
Configuration Options
- ROOT: Sets the default root directory for all search operations (optional but recommended)
- AUU_MCP_RG_VERSION: Version pinning for stability (optional)
When ROOT
is configured, all tools will automatically use this directory unless explicitly overridden.
Enhanced Cross-Platform Compatibility (v1.2.6)
This server now offers superior cross-platform compatibility with intelligent path handling:
🆕 Advanced Cross-Platform Features
Intelligent Path Resolution:
- Automatic detection and handling of platform-specific path formats
- Smart relative path resolution relative to the root directory
- Cross-platform path validation using Node.js
path.relative()
andpath.isAbsolute()
Universal Path Normalization:
- Automatic conversion of Windows backslashes to forward slashes for ripgrep compatibility
- Consistent path handling across all platforms
- Support for mixed path formats in the same environment
Platform-Specific Optimizations
Windows
- Native Path Support: Full support for Windows-style paths (
C:\project\src
) - Command Escaping: Proper Windows command argument escaping
- Process Management: Windows-optimized process spawning
macOS & Linux
- Unix Path Standards: Native support for POSIX paths (
/home/user/project
) - Shell Integration: Standard Unix shell behavior
- Performance: Optimized for Unix process management
🆕 Cross-Platform Examples
Windows Configuration:
{
"mcpServers": {
"auu-mcp-rg": {
"command": "npx",
"args": ["auu-mcp-rg"],
"env": {
"ROOT": "E:\\code\\my-project"
}
}
}
}
macOS/Linux Configuration:
{
"mcpServers": {
"auu-mcp-rg": {
"command": "npx",
"args": ["auu-mcp-rg"],
"env": {
"ROOT": "/home/username/my-project"
}
}
}
}
Cross-Platform Path Usage:
{
"name": "search",
"arguments": {
"pattern": "import",
"root": "E:\\code\\project", // Windows path
"path": "src/utils" // Relative path works on all platforms
}
}
🆕 Technical Improvements (v1.2.6)
- Enhanced Path Validation: Uses
path.relative()
instead of string matching for reliable cross-platform boundary checking - Improved Relative Path Support: Proper handling of relative paths relative to the root directory
- Memory Safety: Improved path handling to prevent security issues
- Performance: Optimized path resolution and validation algorithms
- Comprehensive Testing: Added extensive cross-platform test coverage
Windows Compatibility Fixes
This server addresses several Windows compatibility issues found in other MCP ripgrep implementations:
- Proper Command Escaping: Uses Windows-appropriate argument escaping
- Process Execution: Direct process spawning without shell dependencies
- Path Handling: Proper handling of Windows paths with spaces and special characters
- Build Process: Removed Unix-specific commands like
chmod
Security & Performance Features (v1.1.0+)
Global Root Directory Configuration
The ROOT
environment variable provides server-wide security by limiting all search operations to a specific directory:
{
"mcpServers": {
"auu-mcp-rg": {
"command": "npx",
"args": ["auu-mcp-rg"],
"env": {
"ROOT": "/path/to/project"
}
}
}
}
Benefits:
- Server-wide Security: All tools automatically respect the root directory boundary
- Zero Configuration Needed: No need to specify root in individual tool calls
- Prevents Accidental Access: Protects sensitive files outside the project directory
- Sandboxed Environment: Provides controlled search scope for enhanced security
- Multi-tenant Support: Ideal for shared environments and team projects
- Directory Traversal Protection: Blocks attempts to access paths outside the root
Per-Call Root Override
You can still specify a different root directory for individual tool calls:
{
"name": "search",
"arguments": {
"pattern": "function",
"root": "/different/path/project",
"max_matches": 10
}
}
Path Validation
- Automatic Validation: All search paths are validated against the root directory
- Clear Error Messages: Attempts to access paths outside the root are blocked with informative errors
- Flexible Path Support: Works with both absolute and relative paths
- Cross-Platform: Proper handling of Windows, macOS, and Linux path formats
Performance & Memory Protection (v1.2.1+)
- Result Limits: Built-in limit of 100 matches per search to prevent excessive output
- Output Size Limits: Automatic truncation at 10MB to prevent memory issues
- Timeout Protection: 30-second timeout to prevent hanging searches
- Memory Safety: Automatic process cleanup and resource management
- Smart Defaults: Sensible defaults that balance functionality with safety
Smart Path Handling (v1.2.1+)
- Path Combination: When both
root
andpath
are specified, they are intelligently combined - Intuitive Search Scope:
root: "/project", path: "src"
searches in/project/src
- Validation: Combined paths are still validated against security boundaries
- Backward Compatible: Existing usage patterns continue to work unchanged
Requirements
- Node.js 18+
- ripgrep installed and available in PATH
- Windows, macOS, or Linux
License
MIT