Claude Desktop Commander MCP

Instructions

Implementation Reference

• src/tools/filesystem.ts:95-99 (handler)

  The core handler function for the list_directory tool. It validates the path, reads directory entries using fs.readdir with file types, and formats each entry as [DIR] or [FILE] followed by the name.

  export async function listDirectory(dirPath: string): Promise<string[]> {
      const validPath = await validatePath(dirPath);
      const entries = await fs.readdir(validPath, { withFileTypes: true });
      return entries.map((entry) => `${entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}`);
  }

• src/tools/schemas.ts:49-51 (schema)

  Zod schema defining the input for list_directory: an object with a required 'path' string.

  export const ListDirectoryArgsSchema = z.object({
    path: z.string(),
  });

• src/server.ts:156-163 (registration)

  Registration of the list_directory tool in the ListToolsRequestHandler, providing name, description, and input schema.

  {
    name: "list_directory",
    description:
      "Get a detailed listing of all files and directories in a specified path. " +
      "Results distinguish between files and directories with [FILE] and [DIR] prefixes. " +
      "Only works within allowed directories.",
    inputSchema: zodToJsonSchema(ListDirectoryArgsSchema),
  },

• src/server.ts:294-300 (registration)

  Dispatch logic in CallToolRequestHandler: parses arguments using the schema and invokes the listDirectory handler, formatting the response.

  case "list_directory": {
    const parsed = ListDirectoryArgsSchema.parse(args);
    const entries = await listDirectory(parsed.path);
    return {
      content: [{ type: "text", text: entries.join('\n') }],
    };
  }

• src/tools/filesystem.ts:24-62 (helper)

  Shared helper function validatePath used by listDirectory (and other filesystem tools) to ensure paths are within allowed directories, handling symlinks and non-existent files securely.

  export async function validatePath(requestedPath: string): Promise<string> {
      const expandedPath = expandHome(requestedPath);
      const absolute = path.isAbsolute(expandedPath)
          ? path.resolve(expandedPath)
          : path.resolve(process.cwd(), expandedPath);
          
      const normalizedRequested = normalizePath(absolute);
  
      // Check if path is within allowed directories
      const isAllowed = allowedDirectories.some(dir => normalizedRequested.startsWith(normalizePath(dir)));
      if (!isAllowed) {
          throw new Error(`Access denied - path outside allowed directories: ${absolute}`);
      }
  
      // Handle symlinks by checking their real path
      try {
          const realPath = await fs.realpath(absolute);
          const normalizedReal = normalizePath(realPath);
          const isRealPathAllowed = allowedDirectories.some(dir => normalizedReal.startsWith(normalizePath(dir)));
          if (!isRealPathAllowed) {
              throw new Error("Access denied - symlink target outside allowed directories");
          }
          return realPath;
      } catch (error) {
          // For new files that don't exist yet, verify parent directory
          const parentDir = path.dirname(absolute);
          try {
              const realParentPath = await fs.realpath(parentDir);
              const normalizedParent = normalizePath(realParentPath);
              const isParentAllowed = allowedDirectories.some(dir => normalizedParent.startsWith(normalizePath(dir)));
              if (!isParentAllowed) {
                  throw new Error("Access denied - parent directory outside allowed directories");
              }
              return absolute;
          } catch {
              throw new Error(`Parent directory does not exist: ${parentDir}`);
          }
      }
  }