MCP Filesystem Server

Instructions

Implementation Reference

• src/index.ts:520-575 (handler)

  The main handler for the 'directory_tree' tool. Validates input, recursively builds a tree structure of directories and files starting from the given path, sorts entries (dirs first), handles subdir access errors by setting empty children, and returns pretty-printed JSON.

  case 'directory_tree': {
    const parsed = DirectoryTreeArgsSchema.safeParse(a)
    if (!parsed.success) {
      throw new FileSystemError(`Invalid arguments for ${name}`, 'INVALID_ARGS', undefined, {
        errors: parsed.error.format(),
      })
    }
  
    async function buildTree(currentPath: string): Promise<TreeEntry[]> {
      const validPath = await validatePath(currentPath, config)
      const entries = await fs.readdir(validPath, { withFileTypes: true })
  
      // Sort directories first, then files, both alphabetically
      entries.sort((f, g) => {
        if (f.isDirectory() && !g.isDirectory()) return -1
        if (!f.isDirectory() && g.isDirectory()) return 1
        return f.name.localeCompare(g.name)
      })
  
      const result: TreeEntry[] = []
  
      for (const entry of entries) {
        const entryData: TreeEntry = {
          name: entry.name,
          type: entry.isDirectory() ? 'directory' : 'file',
        }
  
        if (entry.isDirectory()) {
          try {
            const subPath = path.join(currentPath, entry.name)
            entryData.children = await buildTree(subPath)
          } catch (error) {
            // If we can't access a subdirectory, represent it as empty
            entryData.children = []
          }
        }
  
        result.push(entryData)
      }
  
      return result
    }
  
    const treeData = await buildTree(parsed.data.path)
    await logger.debug(`Generated directory tree: ${parsed.data.path}`)
  
    endMetric()
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(treeData, null, 2),
        },
      ],
    }
  }

• src/index.ts:124-126 (schema)

  Zod schema for validating the input arguments to the directory_tree tool, requiring a 'path' string.

  const DirectoryTreeArgsSchema = z.object({
    path: z.string().describe('Path of the directory to create a tree view for'),
  })

• src/index.ts:288-295 (registration)

  Registration of the 'directory_tree' tool in the list of tools returned by ListToolsRequest, including name, description, and input schema.

  {
    name: 'directory_tree',
    description:
      'Get a recursive tree view of files and directories as a JSON structure. ' +
      "Each entry includes 'name', 'type' (file/directory), and 'children' for directories. " +
      'Files have no children array, while directories always have a children array (which may be empty). ' +
      'The output is formatted with 2-space indentation for readability. Only works within allowed directories.',
    inputSchema: zodToJsonSchema(DirectoryTreeArgsSchema) as ToolInput,