chuk-mcp-vfs

Instructions

Implementation Reference

• src/chuk_mcp_vfs/vfs_tools.py:148-195 (handler)

  Core handler implementation that recursively traverses the VFS directory structure to build a TreeNode hierarchy up to the specified max_depth, handling files, directories, and truncation.

  async def tree(self, path: str = ".", max_depth: int = 3) -> TreeResponse:
      """
      Display directory tree structure.
  
      Args:
          path: Root path for tree
          max_depth: Maximum depth to traverse
  
      Returns:
          TreeResponse with nested tree structure
      """
      vfs = self.workspace_manager.get_current_vfs()
      resolved_path = self.workspace_manager.resolve_path(path)
  
      async def build_tree(current_path: str, depth: int) -> TreeNode:
          if depth > max_depth:
              return TreeNode(name="...", type=NodeType.DIRECTORY, truncated=True)
  
          node_info = await vfs.get_node_info(current_path)
          if not node_info:
              return TreeNode(name="???", type=NodeType.FILE, size=0)
  
          node_type = NodeType.DIRECTORY if node_info.is_dir else NodeType.FILE
  
          if not node_info.is_dir:
              return TreeNode(
                  name=Path(current_path).name, type=node_type, size=node_info.size
              )
  
          # Recursively build tree for directory
          children: list[TreeNode] = []
          filenames = await vfs.ls(current_path)
          for name in filenames:
              if current_path == "/":
                  child_path = f"/{name}"
              else:
                  child_path = f"{current_path}/{name}"
              child_tree = await build_tree(child_path, depth + 1)
              children.append(child_tree)
  
          return TreeNode(
              name=Path(current_path).name if current_path != "/" else "/",
              type=node_type,
              children=children if children else None,
          )
  
      root = await build_tree(resolved_path, 0)
      return TreeResponse(root=root)

• src/chuk_mcp_vfs/server.py:102-105 (registration)

  MCP server registration of the 'tree' tool using @server.tool decorator, which delegates execution to the VFSTools.tree handler.

  @server.tool
  async def tree(path: str = ".", max_depth: int = 3):
      """Display directory tree structure."""
      return await vfs_tools.tree(path, max_depth)

• src/chuk_mcp_vfs/models.py:160-174 (schema)

  Pydantic models defining the schema for TreeNode (recursive structure for tree nodes) and TreeResponse (output model returned by the tree tool). NodeType enum is also used but defined earlier.

  class TreeNode(BaseModel):
      """Node in a directory tree"""
  
      name: str
      type: NodeType
      size: int | None = None
      children: list["TreeNode"] | None = None
      truncated: bool = False
  
  
  class TreeResponse(BaseModel):
      """Response from tree operation"""
  
      root: TreeNode