chuk-mcp-vfs

Instructions

Implementation Reference

• src/chuk_mcp_vfs/vfs_tools.py:101-146 (handler)

  The core handler function for the 'ls' tool. Resolves the path, lists filenames using the VFS, fetches detailed node info for each entry, constructs FileEntry objects, and returns a ListDirectoryResponse.

  async def ls(self, path: str = ".") -> ListDirectoryResponse:
      """
      List directory contents.
  
      Args:
          path: Directory path (default: current directory)
  
      Returns:
          ListDirectoryResponse with entries
      """
      vfs = self.workspace_manager.get_current_vfs()
      resolved_path = self.workspace_manager.resolve_path(path)
  
      # ls() returns list of filenames
      filenames = await vfs.ls(resolved_path)
  
      file_entries = []
      for name in filenames:
          # Construct full path
          if resolved_path == "/":
              full_path = f"/{name}"
          else:
              full_path = f"{resolved_path}/{name}"
  
          # Get node info for each entry
          node_info = await vfs.get_node_info(full_path)
          if node_info:
              # Parse modified_at timestamp if it's a string
              modified: datetime | None = None
              if node_info.modified_at:
                  if isinstance(node_info.modified_at, str):
                      modified = datetime.fromisoformat(node_info.modified_at)
                  else:
                      modified = node_info.modified_at
  
              file_entries.append(
                  FileEntry(
                      name=name,
                      path=full_path,
                      type=NodeType.DIRECTORY if node_info.is_dir else NodeType.FILE,
                      size=node_info.size,
                      modified=modified,
                  )
              )
  
      return ListDirectoryResponse(path=resolved_path, entries=file_entries)

• src/chuk_mcp_vfs/server.py:97-100 (registration)

  Registers the 'ls' tool in the MCP server using the @server.tool decorator. Delegates execution to the VFSTools.ls handler method.

  @server.tool
  async def ls(path: str = "."):
      """List directory contents."""
      return await vfs_tools.ls(path)

• src/chuk_mcp_vfs/models.py:153-158 (schema)

  Pydantic model defining the output schema for the 'ls' tool response, consisting of the path and a list of FileEntry objects.

  class ListDirectoryResponse(BaseModel):
      """Response from ls operation"""
  
      path: str
      entries: list[FileEntry]

• src/chuk_mcp_vfs/models.py:120-128 (schema)

  Pydantic model for individual file/directory entries returned by the 'ls' tool.

  class FileEntry(BaseModel):
      """A file or directory entry"""
  
      name: str
      path: str
      type: NodeType
      size: int
      modified: datetime | None = None

• src/chuk_mcp_vfs/models.py:22-27 (schema)

  Enum used in FileEntry to indicate whether an entry is a file or directory.

  class NodeType(str, Enum):
      """Filesystem node types"""
  
      FILE = "file"
      DIRECTORY = "directory"