grep
Search file contents using regular expressions to find specific patterns in codebases. Filter files by pattern and get results sorted by modification time.
Instructions
Fast content search tool that works with any codebase size. Searches file contents using regular expressions. Supports full regex syntax (eg. "log.Error", "function\s+\w+", etc.). Filter files by pattern with the include parameter (eg. ".js", "*.{ts,tsx}"). Returns matching file paths sorted by modification time. Use this tool when you need to find files containing specific patterns. When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | The regular expression pattern to search for in file contents | |
| path | No | The directory to search in. Defaults to the current working directory. | . |
| include | No | File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}") | * |
Implementation Reference
- The main handler function that orchestrates the grep search using ripgrep if available or a pure Python fallback implementation.async def call( self, ctx: MCPContext, **params: Unpack[GrepToolParams], ) -> str: """Execute the grep tool with the given parameters. Args: ctx: MCP context **params: Tool parameters Returns: Tool result """ tool_ctx = self.create_tool_context(ctx) # Extract parameters pattern = params.get("pattern") path: str = params.get("path", ".") # Support both 'include' and legacy 'file_pattern' parameter for backward compatibility include: str = params.get("include") or params.get("file_pattern") # Validate required parameters for direct calls (not through MCP framework) if pattern is None: await tool_ctx.error("Parameter 'pattern' is required but was None") return "Error: Parameter 'pattern' is required but was None" # Validate path if provided if path: path_validation = self.validate_path(path) if path_validation.is_error: await tool_ctx.error(path_validation.error_message) return f"Error: {path_validation.error_message}" # Check if path is allowed allowed, error_msg = await self.check_path_allowed(path, tool_ctx) if not allowed: return error_msg # Check if path exists exists, error_msg = await self.check_path_exists(path, tool_ctx) if not exists: return error_msg # Log operation search_info = f"Searching for pattern '{pattern}'" if include: search_info += f" in files matching '{include}'" search_info += f" in path: {path}" await tool_ctx.info(search_info) # Check if ripgrep is installed and use it if available try: if self.is_ripgrep_installed(): await tool_ctx.info("ripgrep is installed, using ripgrep for search") result = await self.run_ripgrep(pattern, path, tool_ctx, include) return result else: await tool_ctx.info( "ripgrep is not installed, using fallback implementation" ) result = await self.fallback_grep(pattern, path, tool_ctx, include) return result except Exception as e: await tool_ctx.error(f"Error in grep tool: {str(e)}") return f"Error in grep tool: {str(e)}"
- Pydantic-compatible parameter schema defining the input types for the grep tool using Annotated strings for pattern, path, and include.class GrepToolParams(TypedDict): """Parameters for the Grep tool. Attributes: pattern: The regular expression pattern to search for in file contents path: The directory to search in. Defaults to the current working directory. include: File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}") """ pattern: Pattern path: SearchPath include: Include
- mcp_claude_code/tools/filesystem/grep.py:437-459 (registration)The register method that defines and attaches the tool wrapper function to the FastMCP server.def register(self, mcp_server: FastMCP) -> None: """Register this grep tool with the MCP server. Creates a wrapper function with explicitly defined parameters that match the tool's parameter schema and registers it with the MCP server. Args: mcp_server: The FastMCP server instance """ tool_self = self # Create a reference to self for use in the closure @mcp_server.tool(name=self.name, description=self.description) async def grep( ctx: MCPContext, pattern: Pattern, path: SearchPath, include: Include, ) -> str: # Use 'include' parameter if provided, otherwise fall back to 'file_pattern' return await tool_self.call( ctx, pattern=pattern, path=path, include=include )
- mcp_claude_code/tools/filesystem/__init__.py:76-91 (registration)Function that instantiates all filesystem tools (including Grep) via get_filesystem_tools and registers them using ToolRegistry.def register_filesystem_tools( mcp_server: FastMCP, permission_manager: PermissionManager, ) -> list[BaseTool]: """Register all filesystem tools with the MCP server. Args: mcp_server: The FastMCP server instance permission_manager: Permission manager for access control Returns: List of registered tools """ tools = get_filesystem_tools(permission_manager) ToolRegistry.register_tools(mcp_server, tools) return tools
- mcp_claude_code/tools/filesystem/__init__.py:55-56 (registration)Instantiates the Grep tool instance with permission_manager as part of the filesystem tools list.def get_filesystem_tools(permission_manager: PermissionManager) -> list[BaseTool]: """Create instances of all filesystem tools.