feat: Add directory tree tool (mark3labs#8)

Co-authored-by: tomholford <tomholford@users.noreply.github.com>

Author: tomholford

README.md

@@ -11,6 +11,7 @@ Go server implementing Model Context Protocol (MCP) for filesystem operations.
 - Move files/directories
 - Search files
 - Get file metadata
+- Generate directory tree structures
 
 **Note**: The server will only allow operations within directories specified via `args`.
 
@@ -74,6 +75,15 @@ Go server implementing Model Context Protocol (MCP) for filesystem operations.
     - Type (file/directory)
     - Permissions
 
+- **tree**
+  - Returns a hierarchical JSON representation of a directory structure
+  - Inputs:
+    - `path` (string): Directory to traverse (required)
+    - `depth` (number): Maximum depth to traverse (default: 3)
+    - `follow_symlinks` (boolean): Whether to follow symbolic links (default: false)
+  - Returns formatted JSON with file/directory hierarchy
+  - Includes file metadata (name, path, size, modified time)
+
 - **list_allowed_directories**
   - List all directories the server is allowed to access
   - No input required

main.go

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"encoding/base64"
+	"encoding/json"
 	"fmt"
 	"log"
 	"mime"
@@ -33,6 +34,16 @@ type FileInfo struct {
 	Permissions string    `json:"permissions"`
 }
 
+// FileNode represents a node in the file tree
+type FileNode struct {
+	Name     string      `json:"name"`
+	Path     string      `json:"path"`
+	Type     string      `json:"type"` // "file" or "directory"
+	Size     int64       `json:"size,omitempty"`
+	Modified time.Time   `json:"modified,omitempty"`
+	Children []*FileNode `json:"children,omitempty"`
+}
+
 type FilesystemServer struct {
 	allowedDirs []string
 	server      *server.MCPServer
@@ -161,6 +172,21 @@ func NewFilesystemServer(allowedDirs []string) (*FilesystemServer, error) {
 		mcp.WithDescription("Returns the list of directories that this server is allowed to access."),
 	), s.handleListAllowedDirectories)
 
+	s.server.AddTool(mcp.NewTool(
+		"tree",
+		mcp.WithDescription("Returns a hierarchical JSON representation of a directory structure."),
+		mcp.WithString("path",
+			mcp.Description("Path of the directory to traverse"),
+			mcp.Required(),
+		),
+		mcp.WithNumber("depth",
+			mcp.Description("Maximum depth to traverse (default: 3)"),
+		),
+		mcp.WithBoolean("follow_symlinks",
+			mcp.Description("Whether to follow symbolic links (default: false)"),
+		),
+	), s.handleTree)
+
 	return s, nil
 }
 
@@ -192,6 +218,85 @@ func (s *FilesystemServer) isPathInAllowedDirs(path string) bool {
 	return false
 }
 
+// buildTree builds a tree representation of the filesystem starting at the given path
+func (s *FilesystemServer) buildTree(path string, maxDepth int, currentDepth int, followSymlinks bool) (*FileNode, error) {
+	// Validate the path
+	validPath, err := s.validatePath(path)
+	if err != nil {
+		return nil, err
+	}
+
+	// Get file info
+	info, err := os.Stat(validPath)
+	if err != nil {
+		return nil, err
+	}
+
+	// Create the node
+	node := &FileNode{
+		Name:     filepath.Base(validPath),
+		Path:     validPath,
+		Modified: info.ModTime(),
+	}
+
+	// Set type and size
+	if info.IsDir() {
+		node.Type = "directory"
+
+		// If we haven't reached the max depth, process children
+		if currentDepth < maxDepth {
+			// Read directory entries
+			entries, err := os.ReadDir(validPath)
+			if err != nil {
+				return nil, err
+			}
+
+			// Process each entry
+			for _, entry := range entries {
+				entryPath := filepath.Join(validPath, entry.Name())
+
+				// Handle symlinks
+				if entry.Type()&os.ModeSymlink != 0 {
+					if !followSymlinks {
+						// Skip symlinks if not following them
+						continue
+					}
+
+					// Resolve symlink
+					linkDest, err := filepath.EvalSymlinks(entryPath)
+					if err != nil {
+						// Skip invalid symlinks
+						continue
+					}
+
+					// Validate the symlink destination is within allowed directories
+					if !s.isPathInAllowedDirs(linkDest) {
+						// Skip symlinks pointing outside allowed directories
+						continue
+					}
+
+					entryPath = linkDest
+				}
+
+				// Recursively build child node
+				childNode, err := s.buildTree(entryPath, maxDepth, currentDepth+1, followSymlinks)
+				if err != nil {
+					// Skip entries with errors
+					continue
+				}
+
+				// Add child to the current node
+				node.Children = append(node.Children, childNode)
+			}
+		}
+	} else {
+		node.Type = "file"
+		node.Size = info.Size()
+	}
+
+	return node, nil
+}
+
 func (s *FilesystemServer) validatePath(requestedPath string) (string, error) {
 	// Always convert to absolute path first
 	abs, err := filepath.Abs(requestedPath)
@@ -1259,6 +1364,139 @@ func (s *FilesystemServer) handleSearchFiles(
 	}, nil
 }
 
+func (s *FilesystemServer) handleTree(
+	ctx context.Context,
+	request mcp.CallToolRequest,
+) (*mcp.CallToolResult, error) {
+	path, ok := request.Params.Arguments["path"].(string)
+	if !ok {
+		return nil, fmt.Errorf("path must be a string")
+	}
+
+	// Handle empty or relative paths like "." or "./" by converting to absolute path
+	if path == "." || path == "./" {
+		// Get current working directory
+		cwd, err := os.Getwd()
+		if err != nil {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					mcp.TextContent{
+						Type: "text",
+						Text: fmt.Sprintf("Error resolving current directory: %v", err),
+					},
+				},
+				IsError: true,
+			}, nil
+		}
+		path = cwd
+	}
+
+	// Extract depth parameter (optional, default: 3)
+	depth := 3 // Default value
+	if depthParam, ok := request.Params.Arguments["depth"]; ok {
+		if d, ok := depthParam.(float64); ok {
+			depth = int(d)
+		}
+	}
+
+	// Extract follow_symlinks parameter (optional, default: false)
+	followSymlinks := false // Default value
+	if followParam, ok := request.Params.Arguments["follow_symlinks"]; ok {
+		if f, ok := followParam.(bool); ok {
+			followSymlinks = f
+		}
+	}
+
+	// Validate the path is within allowed directories
+	validPath, err := s.validatePath(path)
+	if err != nil {
+		return &mcp.CallToolResult{
+			Content: []mcp.Content{
+				mcp.TextContent{
+					Type: "text",
+					Text: fmt.Sprintf("Error: %v", err),
+				},
+			},
+			IsError: true,
+		}, nil
+	}
+
+	// Check if it's a directory
+	info, err := os.Stat(validPath)
+	if err != nil {
+		return &mcp.CallToolResult{
+			Content: []mcp.Content{
+				mcp.TextContent{
+					Type: "text",
+					Text: fmt.Sprintf("Error: %v", err),
+				},
+			},
+			IsError: true,
+		}, nil
+	}
+
+	if !info.IsDir() {
+		return &mcp.CallToolResult{
+			Content: []mcp.Content{
+				mcp.TextContent{
+					Type: "text",
+					Text: "Error: The specified path is not a directory",
+				},
+			},
+			IsError: true,
+		}, nil
+	}
+
+	// Build the tree structure
+	tree, err := s.buildTree(validPath, depth, 0, followSymlinks)
+	if err != nil {
+		return &mcp.CallToolResult{
+			Content: []mcp.Content{
+				mcp.TextContent{
+					Type: "text",
+					Text: fmt.Sprintf("Error building directory tree: %v", err),
+				},
+			},
+			IsError: true,
+		}, nil
+	}
+
+	// Convert to JSON
+	jsonData, err := json.MarshalIndent(tree, "", "  ")
+	if err != nil {
+		return &mcp.CallToolResult{
+			Content: []mcp.Content{
+				mcp.TextContent{
+					Type: "text",
+					Text: fmt.Sprintf("Error generating JSON: %v", err),
+				},
+			},
+			IsError: true,
+		}, nil
+	}
+
+	// Create resource URI for the directory
+	resourceURI := pathToResourceURI(validPath)
+
+	// Return the result
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{
+			mcp.TextContent{
+				Type: "text",
+				Text: fmt.Sprintf("Directory tree for %s (max depth: %d):\n\n%s", validPath, depth, string(jsonData)),
+			},
+			mcp.EmbeddedResource{
+				Type: "resource",
+				Resource: mcp.TextResourceContents{
+					URI:      resourceURI,
+					MIMEType: "application/json",
+					Text:     string(jsonData),
+				},
+			},
+		},
+	}, nil
+}
+
 func (s *FilesystemServer) handleGetFileInfo(
 	ctx context.Context,
 	request mcp.CallToolRequest,