{"_id":"@247arjun/mcp-grep","name":"@247arjun/mcp-grep","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@247arjun/mcp-grep","version":"1.0.0","description":"An MCP server that exposes grep functionality with natural language search capabilities","main":"build/index.js","type":"module","bin":{"mcp-grep":"build/index.js"},"scripts":{"build":"tsc && chmod +x build/index.js","start":"node build/index.js","dev":"tsc --watch","test":"echo 'Tests will be implemented in future versions'","test:watch":"echo 'Tests will be implemented in future versions'","test:coverage":"echo 'Tests will be implemented in future versions'","lint":"eslint src --ext .ts --fix","lint:check":"eslint src --ext .ts","prepare":"npm run build","prepublishOnly":"npm run lint:check && npm run build"},"keywords":["mcp","grep","search","regex","text-search","model-context-protocol"],"author":{"name":"Your Name","email":"your.email@example.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/247arjun/mcp-grep.git"},"bugs":{"url":"https://github.com/247arjun/mcp-grep/issues"},"homepage":"https://github.com/247arjun/mcp-grep#readme","devDependencies":{"@types/jest":"^29.5.14","@types/node":"^22.16.5","@typescript-eslint/eslint-plugin":"^6.21.0","@typescript-eslint/parser":"^6.21.0","eslint":"^8.57.1","jest":"^29.7.0","ts-jest":"^29.4.0","typescript":"^5.8.3"},"dependencies":{"@modelcontextprotocol/sdk":"^1.16.0","zod":"^3.25.76"},"_id":"@247arjun/mcp-grep@1.0.0","gitHead":"28c08a2ad4c2be5b8cd0f56200911211ebd659eb","_nodeVersion":"24.4.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-ooHMmWPUhNhGNz2PqDIigUVvBgbFrVOj4h4G/mRR+UMPRSgRdEMGi8ZAFmbZ9X19x/nGpLmuUN4czLCOBJh7CA==","shasum":"4200ee50c6c1e3a2c52d08ae2810acc0d966fbe8","tarball":"https://registry.npmjs.org/@247arjun/mcp-grep/-/mcp-grep-1.0.0.tgz","fileCount":4,"unpackedSize":29549,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAw3831oUXxO0cJmFMbR/Uc5z9NzgC0pJwO4w3VvFG45AiBp8WcJk8UuZZaYYO4MW1GkPGxOwpBG1LJMYAo/FsTR5A=="}]},"_npmUser":{"name":"247arjun","email":"247arjun@gmail.com"},"directories":{},"maintainers":[{"name":"247arjun","email":"247arjun@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-grep_1.0.0_1753565941231_0.014331330122683283"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-26T21:39:01.146Z","1.0.0":"2025-07-26T21:39:01.445Z","modified":"2025-07-26T21:39:01.763Z"},"maintainers":[{"name":"247arjun","email":"247arjun@gmail.com"}],"description":"An MCP server that exposes grep functionality with natural language search capabilities","homepage":"https://github.com/247arjun/mcp-grep#readme","keywords":["mcp","grep","search","regex","text-search","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/247arjun/mcp-grep.git"},"author":{"name":"Your Name","email":"your.email@example.com"},"bugs":{"url":"https://github.com/247arjun/mcp-grep/issues"},"license":"MIT","readme":"# MCP Grep Server\n\nA Model Context Protocol (MCP) server that provides powerful text search capabilities using the `grep` command-line utility. This server allows you to search for patterns in files and directories using both natural language descriptions and direct regex patterns.\n\n## Features\n\n### 🧠 Natural Language Search\n- Describe what you're looking for in plain English\n- Automatic conversion to appropriate regex patterns\n- Built-in patterns for common searches (emails, URLs, phone numbers, etc.)\n\n### 🔍 Advanced Search Capabilities\n- Direct regex pattern matching\n- Recursive directory searching\n- File extension filtering\n- Case-sensitive/insensitive search\n- Whole word matching\n- Context line display\n- Match counting\n- File listing with matches\n\n### 🛡️ Security First\n- Safe command execution using `child_process.spawn`\n- Input validation with Zod schemas\n- No shell injection vulnerabilities\n- Path validation and sanitization\n\n## Installation\n\n### Method 1: NPM Installation (Recommended)\n\n```bash\n# Install globally\nnpm install -g @247arjun/mcp-grep\n\n# Or install locally in your project\nnpm install @247arjun/mcp-grep\n```\n\n### Method 2: From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/247arjun/mcp-grep.git\ncd mcp-grep\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Optional: Link globally\nnpm link\n```\n\n### Method 3: Direct from GitHub\n\n```bash\n# Install directly from GitHub\nnpm install -g git+https://github.com/247arjun/mcp-grep.git\n```\n\n## Quick Start\n\n### 1. Configure with Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**Location:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\n**Configuration:**\n```json\n{\n  \"mcpServers\": {\n    \"mcp-grep\": {\n      \"command\": \"mcp-grep\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### 2. Restart Claude Desktop\n\nAfter adding the configuration, restart Claude Desktop to load the MCP server.\n\n### 3. Start Using\n\nAsk Claude to search your files:\n- \"Find all email addresses in my project\"\n- \"Search for TODO comments in JavaScript files\"\n- \"Count function definitions in the src directory\"\n\n## Verification\n\nTest that the server is working:\n\n```bash\n# Test the built server\nnode build/index.js\n\n# Should show: \"Grep MCP Server running on stdio\"\n# Press Ctrl+C to exit\n```\n\n## Available Tools\n\n### 1. `grep_search_intent`\nSearch using natural language descriptions.\n\n**Parameters:**\n- `intent` (string): Plain English description (e.g., \"email addresses\", \"TODO comments\")\n- `target` (string): File or directory path to search\n- `case_sensitive` (boolean, optional): Case-sensitive search (default: false)\n- `max_results` (number, optional): Limit number of results\n- `show_context` (boolean, optional): Show surrounding lines (default: false)\n- `context_lines` (number, optional): Number of context lines (default: 2)\n\n**Example:**\n```javascript\n{\n  \"intent\": \"email addresses\",\n  \"target\": \"./src\",\n  \"show_context\": true,\n  \"context_lines\": 1\n}\n```\n\n### 2. `grep_regex`\nSearch using direct regex patterns.\n\n**Parameters:**\n- `pattern` (string): Regular expression pattern\n- `target` (string): File or directory path to search\n- `case_sensitive` (boolean, optional): Case-sensitive search\n- `whole_words` (boolean, optional): Match whole words only\n- `invert_match` (boolean, optional): Show non-matching lines\n- `max_results` (number, optional): Limit results\n- `show_context` (boolean, optional): Show context lines\n- `context_lines` (number, optional): Context line count\n- `file_extensions` (array, optional): Filter by file extensions\n\n**Example:**\n```javascript\n{\n  \"pattern\": \"function\\\\s+\\\\w+\\\\s*\\\\(\",\n  \"target\": \"./src\",\n  \"file_extensions\": [\"js\", \"ts\"],\n  \"show_context\": true\n}\n```\n\n### 3. `grep_count`\nCount matches for a pattern.\n\n**Parameters:**\n- `pattern` (string): Pattern to count\n- `target` (string): Search target\n- `case_sensitive` (boolean, optional): Case sensitivity\n- `whole_words` (boolean, optional): Whole word matching\n- `by_file` (boolean, optional): Show count per file\n- `file_extensions` (array, optional): File extension filter\n\n### 4. `grep_files_with_matches`\nList files containing the pattern.\n\n**Parameters:**\n- `pattern` (string): Search pattern\n- `target` (string): Directory to search\n- `case_sensitive` (boolean, optional): Case sensitivity\n- `whole_words` (boolean, optional): Whole word matching\n- `file_extensions` (array, optional): File extensions to include\n- `exclude_patterns` (array, optional): File patterns to exclude\n\n### 5. `grep_advanced`\nExecute grep with custom arguments (advanced users).\n\n**Parameters:**\n- `args` (array): Array of grep arguments (excluding 'grep' itself)\n\n## Built-in Natural Language Patterns\n\nThe server recognizes these natural language intents:\n\n### Communication\n- \"email\", \"email address\", \"emails\" → Email address pattern\n- \"url\", \"urls\", \"website\", \"link\", \"links\" → URL pattern\n- \"phone\", \"phone number\", \"phone numbers\" → Phone number pattern\n\n### Network\n- \"ip\", \"ip address\", \"ip addresses\" → IPv4 address pattern\n\n### Data Types\n- \"number\", \"numbers\", \"integer\", \"integers\" → Numeric patterns\n- \"date\", \"dates\" → Date patterns\n\n### Code Patterns\n- \"function\", \"functions\" → Function declarations\n- \"class\", \"classes\" → Class definitions\n- \"import\", \"imports\" → Import statements\n- \"export\", \"exports\" → Export statements\n- \"comment\", \"comments\" → Comment lines\n- \"todo\", \"todos\" → TODO/FIXME/HACK comments\n\n### Error Patterns\n- \"error\", \"errors\" → Error messages\n- \"warning\", \"warnings\" → Warning messages\n\n## Usage Examples\n\n### Search for email addresses in a project\n```javascript\n{\n  \"tool\": \"grep_search_intent\",\n  \"intent\": \"email addresses\",\n  \"target\": \"./src\",\n  \"show_context\": true\n}\n```\n\n### Find all TODO comments\n```javascript\n{\n  \"tool\": \"grep_search_intent\", \n  \"intent\": \"todo comments\",\n  \"target\": \"./\",\n  \"file_extensions\": [\"js\", \"ts\", \"py\"]\n}\n```\n\n### Search for function definitions with regex\n```javascript\n{\n  \"tool\": \"grep_regex\",\n  \"pattern\": \"^\\\\s*function\\\\s+\\\\w+\",\n  \"target\": \"./src\",\n  \"file_extensions\": [\"js\"]\n}\n```\n\n### Count occurrences of a word\n```javascript\n{\n  \"tool\": \"grep_count\",\n  \"pattern\": \"async\",\n  \"target\": \"./src\",\n  \"by_file\": true\n}\n```\n\n### List files containing import statements\n```javascript\n{\n  \"tool\": \"grep_files_with_matches\",\n  \"pattern\": \"^import\",\n  \"target\": \"./src\",\n  \"file_extensions\": [\"js\", \"ts\"]\n}\n```\n\n## Development\n\n### Build and Run\n```bash\n# Development with auto-rebuild\nnpm run dev\n\n# Production build\nnpm run build\n\n# Start the server\nnpm start\n```\n\n### Project Structure\n```\nmcp-grep/\n├── src/\n│   └── index.ts          # Main server implementation\n├── build/                # Compiled JavaScript output\n├── package.json          # Project configuration\n├── tsconfig.json         # TypeScript configuration\n└── README.md            # This file\n```\n\n## MCP Integration\n\nThis server implements the Model Context Protocol and can be used with any MCP-compatible client.\n\n### Supported MCP Clients\n\n- **Claude Desktop** (recommended)\n- **Cline VS Code Extension**\n- **Continue.dev**\n- Any other MCP-compatible client\n\n### Server Configuration Examples\n\n#### Claude Desktop\n```json\n{\n  \"mcpServers\": {\n    \"mcp-grep\": {\n      \"command\": \"mcp-grep\",\n      \"args\": [],\n      \"description\": \"Advanced text search capabilities\"\n    }\n  }\n}\n```\n\n#### Alternative: Using npx (no global install needed)\n```json\n{\n  \"mcpServers\": {\n    \"mcp-grep\": {\n      \"command\": \"npx\",\n      \"args\": [\"@247arjun/mcp-grep\"],\n      \"description\": \"Advanced text search capabilities\"\n    }\n  }\n}\n```\n\n#### Local Development Setup\n```json\n{\n  \"mcpServers\": {\n    \"mcp-grep\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-grep/build/index.js\"],\n      \"description\": \"Advanced text search capabilities\"\n    }\n  }\n}\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Command not found\" error**\n   - Ensure mcp-grep is installed globally: `npm install -g @247arjun/mcp-grep`\n   - Or use npx: `\"command\": \"npx\", \"args\": [\"@247arjun/mcp-grep\"]`\n\n2. **\"Permission denied\" error**\n   - Check file permissions: `chmod +x build/index.js`\n   - Rebuild the project: `npm run build`\n\n3. **MCP server not appearing in Claude**\n   - Verify JSON syntax in configuration file\n   - Restart Claude Desktop completely\n   - Check that the command path is correct\n\n4. **\"grep command not found\"**\n   - Install grep on your system (usually pre-installed on macOS/Linux)\n   - Windows users: Install via WSL or use Git Bash\n\n### Debugging\n\nEnable verbose logging by setting environment variable:\n```bash\n# For development\nDEBUG=1 node build/index.js\n\n# Test with sample input\necho '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}}' | node build/index.js\n```\n\n## Security Notes\n\n- Uses `spawn` with `shell: false` to prevent command injection\n- Validates all file paths before execution\n- Blocks potentially dangerous grep flags in advanced mode\n- Input validation with Zod schemas\n- No access to system files outside specified targets\n\n","readmeFilename":"README.md","_rev":"1-65bd89a3d2ec9606867cd1387e4093a3"}