File System Explorer MCP Server

Instructions

Implementation Reference

• src/index.ts:297-328 (handler)

  The handler for the 'get_file_info' tool. It validates the input path using FileInfoArgsSchema, resolves it safely, retrieves file/directory stats using fs.stat, optionally lists directory contents, formats the information including size, timestamps, permissions, and returns it as formatted text content.

  case "get_file_info": {
    const { path: targetPath } = FileInfoArgsSchema.parse(args);
    const safePath = validatePath(targetPath);
    
    const stats = await fs.stat(safePath);
    const isDirectory = stats.isDirectory();
    
    let additionalInfo = "";
    if (isDirectory) {
      try {
        const entries = await fs.readdir(safePath);
        additionalInfo = `\nContains: ${entries.length} items`;
      } catch (error) {
        additionalInfo = "\nUnable to read directory contents";
      }
    }
  
    return {
      content: [
        {
          type: "text",
          text: `Path: ${safePath}\n` +
                `Type: ${isDirectory ? 'Directory' : 'File'}\n` +
                `Size: ${formatFileSize(stats.size)}\n` +
                `Created: ${stats.birthtime.toLocaleString()}\n` +
                `Modified: ${stats.mtime.toLocaleString()}\n` +
                `Accessed: ${stats.atime.toLocaleString()}\n` +
                `Permissions: ${stats.mode.toString(8)}${additionalInfo}`
        }
      ]
    };
  }

• src/index.ts:40-42 (schema)

  Zod schema used for input validation in the get_file_info handler.

  const FileInfoArgsSchema = z.object({
    path: z.string().describe("The file or directory path to get info about")
  });

• src/index.ts:172-185 (registration)

  Tool registration in the ListToolsRequestHandler response, defining name, description, and input schema.

  {
    name: "get_file_info",
    description: "Get detailed information about a file or directory",
    inputSchema: {
      type: "object",
      properties: {
        path: {
          type: "string",
          description: "The file or directory path to get info about"
        }
      },
      required: ["path"]
    }
  },

• src/index.ts:52-60 (helper)

  Helper function to safely resolve paths, used in get_file_info handler to prevent directory traversal.

  function validatePath(inputPath: string): string {
    // Resolve the path to prevent directory traversal
    const resolved = path.resolve(inputPath);
    
    // For security, you might want to restrict to certain directories
    // This is a basic example - in production, implement proper access controls
    
    return resolved;
  }

• src/index.ts:65-70 (helper)

  Helper function to format file sizes in human-readable format, used in the get_file_info response.

  function formatFileSize(bytes: number): string {
    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
    if (bytes === 0) return '0 B';
    const i = Math.floor(Math.log(bytes) / Math.log(1024));
    return Math.round(bytes / Math.pow(1024, i) * 100) / 100 + ' ' + sizes[i];
  }