Filesystem MCP Server

Instructions

Implementation Reference

• src/handlers/directory-handlers.ts:68-155 (handler)

  Core implementation of the directory_tree tool handler. Parses args, validates path, recursively builds directory tree structure with depth limit and exclude patterns, returns JSON tree.

  export async function handleDirectoryTree(
    args: unknown,
    allowedDirectories: string[],
    symlinksMap: Map<string, string>,
    noFollowSymlinks: boolean
  ) {
    const parsed = parseArgs(DirectoryTreeArgsSchema, args, 'directory_tree');
  
    const { path: startPath, maxDepth, excludePatterns } = parsed; // maxDepth is mandatory (handler default: 2)
    const validatedStartPath = await validatePath(startPath, allowedDirectories, symlinksMap, noFollowSymlinks);
  
    async function buildTree(
      currentPath: string,
      basePath: string,
      currentDepth: number,
      maxDepth?: number,
      excludePatterns?: string[]
    ): Promise<TreeEntry[]> {
      // Depth check
      if (maxDepth !== undefined && currentDepth >= maxDepth) {
        return []; // Stop traversal if max depth is reached
      }
  
      const validPath = await validatePath(currentPath, allowedDirectories, symlinksMap, noFollowSymlinks);
      
      let entries;
      try {
        entries = await fs.readdir(validPath, { withFileTypes: true });
      } catch (error) {
        // Handle cases where directory might not be readable
        console.error(`Error reading directory ${validPath}: ${error}`);
        return [];
      }
      
      const result: TreeEntry[] = [];
  
      for (const entry of entries) {
        const entryFullPath = path.join(currentPath, entry.name);
        const entryRelativePath = path.relative(basePath, entryFullPath);
  
        // Exclusion check using minimatch
        if (excludePatterns && excludePatterns.length > 0) {
          const shouldExclude = excludePatterns.some(pattern =>
            minimatch(entryRelativePath, pattern, { dot: true, matchBase: true })
          );
          if (shouldExclude) {
            continue; // Skip this entry if it matches any exclude pattern
          }
        }
  
        const entryData: TreeEntry = {
          name: entry.name,
          type: entry.isDirectory() ? 'directory' : 'file'
        };
  
        if (entry.isDirectory()) {
          // Recursive call with incremented depth
          entryData.children = await buildTree(
            entryFullPath,
            basePath,
            currentDepth + 1,
            maxDepth,
            excludePatterns
          );
        }
  
        result.push(entryData);
      }
  
      return result;
    }
  
    // Initial call to buildTree with base parameters
    const treeData = await buildTree(
      validatedStartPath, 
      validatedStartPath, 
      0, 
      maxDepth, 
      excludePatterns
    );
    
    return {
      content: [{
        type: "text",
        text: JSON.stringify(treeData, null, 2)
      }],
    };
  }

• src/schemas/directory-operations.ts:13-26 (schema)

  TypeBox schema defining input parameters for directory_tree: path (required), maxDepth (integer >=1), excludePatterns (optional array of glob patterns).

  export const DirectoryTreeArgsSchema = Type.Object({
    path: Type.String(),
    maxDepth: Type.Integer({
      minimum: 1,
      description: 'Maximum depth to traverse. Must be a positive integer. Handler default: 2.'
    }),
    excludePatterns: Type.Optional(
      Type.Array(Type.String(), {
        default: [],
        description: 'Glob patterns for files/directories to exclude (e.g., "*.log", "node_modules").'
      })
    )
  });
  export type DirectoryTreeArgs = Static<typeof DirectoryTreeArgsSchema>;

• index.ts:210-211 (registration)

  Maps the 'directory_tree' tool name to the handleDirectoryTree function in the toolHandlers object, passing server context (allowedDirectories, symlinksMap, noFollowSymlinks). Used by server.addTool loop.

  directory_tree: (a: unknown) =>
    handleDirectoryTree(a, allowedDirectories, symlinksMap, noFollowSymlinks),

• index.ts:308-308 (registration)

  Registers 'directory_tree' tool metadata (name and description) in the allTools array, filtered by permissions, then added to MCP server.

  { name: "directory_tree", description: "Directory tree view" },