Filesystem MCP Server

Instructions

Implementation Reference

• main.py:461-498 (handler)

  The core handler function for the 'search_files' MCP tool. It is decorated with @mcp.tool, which registers it automatically with the name 'search_files'. The function performs recursive file search using glob patterns, respects .gitignore via _skip_ignored, applies exclusions, and operates only within allowed directories using _resolve. Returns list of matching paths or error string.

  @mcp.tool
  def search_files(dir: str, pattern: str, exclude: str | None = None) -> List[str] | str:
      """Search for files by name pattern in a directory recursively.
  
      Args:
          dir (str): Directory to search in (absolute or relative to allowed directories)
          pattern (str): Glob-style pattern to match file names (e.g., '*.py', 'test_*')
          exclude (str, optional): Glob-style pattern to exclude file names
  
      Returns:
          List[str] | str: List of matching absolute file paths, or error message if failed
  
      Note:
          - Directory must be within allowed directory roots
          - Searches recursively through subdirectories
          - Respects .gitignore files, and ignores hidden files and folders
          - Returns list for successful searches, string for errors
      """
      try:
          root = _resolve(dir)
          if not root.is_dir():
              return f"Error searching files: '{root}' is not a directory"
          spec_cache: Dict[Path, Optional[pathspec.PathSpec]] = {}
          matches: List[str] = []
          for file in root.rglob("*"):
              if file.is_dir():
                  continue
              if exclude and fnmatch.fnmatch(file.name, exclude):
                  continue
              if not fnmatch.fnmatch(file.name, pattern):
                  continue
              if _skip_ignored(file, root, spec_cache):
                  continue
              matches.append(str(file))
          return matches
      except Exception as e:
          return _human_error(e, "searching files")

• main.py:461-461 (registration)

  The @mcp.tool decorator registers the search_files function as an MCP tool named 'search_files'.

  @mcp.tool

• main.py:463-478 (schema)

  The docstring provides the input schema (parameters with descriptions) and output schema for the tool, which FastMCP uses for validation.

  """Search for files by name pattern in a directory recursively.
  
  Args:
      dir (str): Directory to search in (absolute or relative to allowed directories)
      pattern (str): Glob-style pattern to match file names (e.g., '*.py', 'test_*')
      exclude (str, optional): Glob-style pattern to exclude file names
  
  Returns:
      List[str] | str: List of matching absolute file paths, or error message if failed
  
  Note:
      - Directory must be within allowed directory roots
      - Searches recursively through subdirectories
      - Respects .gitignore files, and ignores hidden files and folders
      - Returns list for successful searches, string for errors
  """