MCP Claude Code

Instructions

Implementation Reference

• mcp_claude_code/tools/filesystem/grep.py:369-435 (handler)

  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)}"

• mcp_claude_code/tools/filesystem/grep.py:47-59 (schema)

  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.