vadik-el/personal-os-file-audit

Personal OS - Intelligent File Audit System

A comprehensive system for auditing and managing files across multiple Google Drive accounts and local directories using AI-powered analysis and automation.

🚀 Features

Core Capabilities

• Multi-Account OAuth: Support for multiple Google accounts (kansofy.com, linchevsky.com)
• Cross-Platform Scanning: Google Drive + local filesystem integration
• Intelligent Duplicate Detection: Content-based deduplication using MD5/SHA256 hashing
• Usage Pattern Analysis: Track file access patterns over 7, 30, 60, 90+ day periods
• Project Detection: Identify and categorize legacy codebases and active projects
• MCP Server Integration: Native support for Claude Code and Cursor IDE

Analytics & Insights

• File Usage Heatmaps: Visual representation of file activity over time
• Category Analysis: Automatic categorization by file type (documents, code, media, etc.)
• Duplicate Reports: Detailed analysis of duplicate files with space savings potential
• Project Detection: Identify legacy codebases and active development projects
• Cross-Account Search: Unified search across all connected Google Drive accounts

🏗️ Architecture

personal-os-project/
├── mcp-servers/
│   └── file-audit-mcp/         # MCP server for file auditing
│       ├── src/
│       │   ├── index.js        # Main server entry point
│       │   ├── scanners/       # Google Drive & local file scanners
│       │   ├── analyzers/      # Duplicate detection & usage analysis
│       │   └── database/       # SQLite database layer
│       └── package.json
├── scripts/                    # OAuth setup and utility scripts
├── config/                     # Configuration templates
├── docs/                       # Comprehensive documentation
└── .env                        # Environment configuration

⚡ Quick Start

1. Clone & Setup

git clone https://github.com/vadik-el/personal-os-file-audit.git
cd personal-os-project

# Copy and configure environment
cp .env.template .env
# Edit .env with your actual file paths

2. OAuth Authentication

# Python setup for OAuth
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure OAuth for both Google accounts
python scripts/oauth-multi-account-setup.py

3. MCP Server Installation

# Install and start MCP server
cd mcp-servers/file-audit-mcp
npm install
npm start

4. IDE Integration

The MCP server integrates automatically with:

• Claude Code: via ~/.claude/mcp-servers.json
• Cursor: via Cursor's MCP settings

📊 Usage Examples

File Scanning & Analysis

// Scan Google Drive (kansofy account)
await scan_location({
  location: 'drive-kansofy',
  limit: 1000
});

// Scan local Downloads folder  
await scan_location({
  location: 'downloads',
  path: '/Users/vadik/Downloads'
});

// Analyze usage patterns
await analyze_usage({
  location: 'all',
  days: [7, 30, 60, 90]
});

Duplicate Detection

// Find duplicates across all locations
await find_duplicates({
  minSize: 1024,  // Files > 1KB
  locations: ['drive-kansofy', 'drive-linchevsky', 'downloads']
});

// Generate comprehensive duplicate report
await generate_report({
  type: 'duplicates',
  format: 'json'
});

Project Discovery

// Detect legacy codebases in Downloads
await detect_projects({
  path: '/Users/vadik/Downloads',
  includeArchived: true
});

🔒 Security & Privacy

• Environment Variables: All credentials stored securely in .env
• OAuth Tokens: Encrypted token storage in config/credentials/
• Git Security: Comprehensive .gitignore prevents credential leaks
• API Compliance: Respects Google API rate limits and quotas
• Local Processing: File analysis performed locally, metadata only

📁 Supported File Types

🛠️ Development

Prerequisites

• Node.js 18+ (for MCP server)
• Python 3.8+ (for OAuth scripts)
• Google Cloud Project with Drive/Gmail APIs enabled

Testing

# Test OAuth status
python scripts/check-api-status.py

# Test MCP server
cd mcp-servers/file-audit-mcp
npm test

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📖 Documentation

• - Complete OAuth configuration
• - MCP server API reference
• - System design and components
• - Common issues and solutions

📈 Roadmap

• Web Dashboard: React-based UI for file analytics
• AI-Powered Insights: GPT-4 analysis of file patterns
• Automated Cleanup: Smart suggestions for file organization
• Cloud Storage: Optional cloud backup integration
• Team Collaboration: Multi-user file sharing analytics

📄 License

MIT License - see for details.

🤝 Acknowledgments

• Built with Model Context Protocol (MCP)
• Integrated with Claude Code and Cursor
• Google Drive API integration via googleapis