MCP Filesystem Server

Instructions

Args:
    path: Path to the file or directory
    format: Output format ('text' or 'json')
    ctx: MCP context

Returns:
    Formatted file information

Implementation Reference

• mcp_filesystem/server.py:259-281 (handler)

  MCP tool handler function for 'get_file_info'. Decorated with @mcp.tool() which registers it with the FastMCP server. Handles input parameters, delegates to FileOperations.get_file_info, formats output as text or JSON, and returns error messages.

  @mcp.tool()
  async def get_file_info(path: str, ctx: Context, format: str = "text") -> str:
      """Retrieve detailed metadata about a file or directory.
  
      Args:
          path: Path to the file or directory
          format: Output format ('text' or 'json')
          ctx: MCP context
  
      Returns:
          Formatted file information
      """
      try:
          components = get_components()
          info = await components["operations"].get_file_info(path)
  
          if format.lower() == "json":
              return json.dumps(info.to_dict(), indent=2)
          else:
              return str(info)
      except Exception as e:
          return f"Error getting file info: {str(e)}"

• mcp_filesystem/operations.py:396-417 (helper)

  Core implementation of get_file_info in FileOperations class. Performs path validation using PathValidator, checks existence, and instantiates/returns a FileInfo object.

  async def get_file_info(self, path: Union[str, Path]) -> FileInfo:
      """Get detailed information about a file or directory.
  
      Args:
          path: Path to the file or directory
  
      Returns:
          FileInfo object with detailed information
  
      Raises:
          ValueError: If path is outside allowed directories
          FileNotFoundError: If file does not exist
      """
      abs_path, allowed = await self.validator.validate_path(path)
      if not allowed:
          raise ValueError(f"Path outside allowed directories: {path}")
  
      if not abs_path.exists():
          raise FileNotFoundError(f"File not found: {path}")
  
      return FileInfo(abs_path)

• mcp_filesystem/operations.py:22-102 (schema)

  FileInfo dataclass defining the output schema for file metadata, including methods for dictionary serialization (to_dict) and string representation (__str__). Used by get_file_info implementations.

  class FileInfo:
      """Information about a file or directory."""
  
      def __init__(self, path: Path):
          """Initialize with a file path.
  
          Args:
              path: Path to the file or directory
  
          Raises:
              FileNotFoundError: If the file or directory does not exist
          """
          self.path = path
          self.stat = path.stat()
          self.is_dir = path.is_dir()
          self.is_file = path.is_file()
          self.is_symlink = path.is_symlink()
          self.size = self.stat.st_size
          self.created = datetime.fromtimestamp(self.stat.st_ctime)
          self.modified = datetime.fromtimestamp(self.stat.st_mtime)
          self.accessed = datetime.fromtimestamp(self.stat.st_atime)
          self.name = path.name
  
          # Format permissions similar to Unix 'ls -l'
          mode = self.stat.st_mode
          self.permissions = "".join(
              [
                  "r" if mode & stat.S_IRUSR else "-",
                  "w" if mode & stat.S_IWUSR else "-",
                  "x" if mode & stat.S_IXUSR else "-",
                  "r" if mode & stat.S_IRGRP else "-",
                  "w" if mode & stat.S_IWGRP else "-",
                  "x" if mode & stat.S_IXGRP else "-",
                  "r" if mode & stat.S_IROTH else "-",
                  "w" if mode & stat.S_IWOTH else "-",
                  "x" if mode & stat.S_IXOTH else "-",
              ]
          )
  
          # Numeric permissions in octal
          self.permissions_octal = oct(mode & 0o777)[2:]
  
      def to_dict(self) -> Dict:
          """Convert to dictionary.
  
          Returns:
              Dictionary with file information
          """
          return {
              "name": self.name,
              "path": str(self.path),
              "size": self.size,
              "created": self.created.isoformat(),
              "modified": self.modified.isoformat(),
              "accessed": self.accessed.isoformat(),
              "is_directory": self.is_dir,
              "is_file": self.is_file,
              "is_symlink": self.is_symlink,
              "permissions": self.permissions,
              "permissions_octal": self.permissions_octal,
          }
  
      def __str__(self) -> str:
          """Get string representation.
  
          Returns:
              Formatted string with file information
          """
          file_type = "Directory" if self.is_dir else "File"
          symlink_info = " (symlink)" if self.is_symlink else ""
          size_str = f"{self.size:,} bytes"
  
          return (
              f"{file_type}{symlink_info}: {self.path}\n"
              f"Size: {size_str}\n"
              f"Created: {self.created.isoformat()}\n"
              f"Modified: {self.modified.isoformat()}\n"
              f"Accessed: {self.accessed.isoformat()}\n"
              f"Permissions: {self.permissions} ({self.permissions_octal})"
          )