# Google Drive MCP Server

AI-powered Google Drive integration through Model Context Protocol (MCP) providing intelligent file management, content analysis, and organization insights.

## 🚀 Features

### Core MCP Tools
- **`list_files`** - List files and folders with advanced filtering and pagination
- **`get_file_content`** - Extract and retrieve file content with metadata
- **`search_files`** - Full-text search with relevance scoring and filtering
- **`analyze_content`** - AI-powered content analysis with summarization and categorization
- **`get_organization_insights`** - Drive organization analysis with actionable recommendations

### Key Capabilities
- 🔐 **Secure OAuth2 Authentication** with Google Drive API
- 📊 **Content Analysis** - AI-powered summarization, categorization, and keyword extraction
- 🔍 **Advanced Search** - Full-text search with relevance scoring and filtering
- 📁 **Organization Insights** - Duplicate detection and structure optimization
- ⚡ **Performance Optimized** - Intelligent caching and rate limiting
- 🛡️ **Production Ready** - Comprehensive error handling and logging

## 📋 Prerequisites

- **Node.js** 18.0.0 or higher
- **Google Cloud Project** with Drive API enabled
- **OAuth2 Credentials** from Google Cloud Console

## 🛠️ Installation

### 1. Clone and Install Dependencies

```bash
git clone <repository-url>
cd gdrive-sparc-mcp
npm install
```

### 2. Google Cloud Setup

1. **Create Google Cloud Project**
   - Go to [Google Cloud Console](https://console.cloud.google.com/)
   - Create a new project or select existing one

2. **Enable Google Drive API**
   ```bash
   # Using gcloud CLI
   gcloud services enable drive.googleapis.com
   ```

3. **Create OAuth2 Credentials**
   - Navigate to APIs & Services > Credentials
   - Click "Create Credentials" > "OAuth 2.0 Client IDs"
   - Application type: "Web application"
   - Add authorized redirect URI: `http://localhost:3000/auth/callback`
   - Download credentials JSON

### 3. Environment Configuration

Create `.env` file from template:

```bash
cp .env.example .env
```

Configure required environment variables:

```env
# Google OAuth Configuration (Required)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

# Session Configuration (Required)
SESSION_SECRET=your-secure-session-secret-at-least-32-characters

# Optional Configuration
NODE_ENV=production
LOG_LEVEL=info
CACHE_TTL=300
CACHE_MAX_SIZE=1000
RATE_LIMIT_WINDOW=60000
RATE_LIMIT_MAX_REQUESTS=100
```

### 4. Build and Start

```bash
# Build TypeScript
npm run build

# Start server
npm start

# Or for development
npm run dev
```

## 🔧 Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GOOGLE_CLIENT_ID` | ✅ | - | Google OAuth2 Client ID |
| `GOOGLE_CLIENT_SECRET` | ✅ | - | Google OAuth2 Client Secret |
| `GOOGLE_REDIRECT_URI` | ✅ | - | OAuth2 Redirect URI |
| `SESSION_SECRET` | ✅ | - | Session encryption secret (32+ chars) |
| `NODE_ENV` | ❌ | `development` | Environment mode |
| `LOG_LEVEL` | ❌ | `info` | Logging level (error, warn, info, debug) |
| `CACHE_TTL` | ❌ | `300` | Cache TTL in seconds |
| `CACHE_MAX_SIZE` | ❌ | `1000` | Maximum cache entries |
| `RATE_LIMIT_WINDOW` | ❌ | `60000` | Rate limit window (ms) |
| `RATE_LIMIT_MAX_REQUESTS` | ❌ | `100` | Max requests per window |

### Google Drive API Scopes

The server requests the following OAuth2 scopes:
- `https://www.googleapis.com/auth/drive.readonly` - Read access to Google Drive files
- `https://www.googleapis.com/auth/userinfo.profile` - Basic profile information

## 📖 Usage

### MCP Client Integration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "gdrive-sparc-mcp": {
      "command": "node",
      "args": ["path/to/gdrive-sparc-mcp/dist/server.js"]
    }
  }
}
```

### Tool Examples

#### List Files
```json
{
  "name": "list_files",
  "arguments": {
    "folderId": "optional-folder-id",
    "recursive": true,
    "maxResults": 50,
    "orderBy": "modifiedTime"
  }
}
```

#### Search Files
```json
{
  "name": "search_files",
  "arguments": {
    "query": "project proposal",
    "filters": {
      "mimeTypes": ["application/pdf", "application/vnd.google-apps.document"]
    },
    "options": {
      "maxResults": 20,
      "includeSnippets": true
    }
  }
}
```

#### Analyze Content
```json
{
  "name": "analyze_content",
  "arguments": {
    "fileIds": ["file-id-1", "file-id-2"],
    "analysisOptions": {
      "enableSummarization": true,
      "enableCategorization": true,
      "enableKeywordExtraction": true
    }
  }
}
```

#### Get Organization Insights
```json
{
  "name": "get_organization_insights",
  "arguments": {
    "scope": {
      "folderId": "optional-folder-id",
      "includeSubfolders": true,
      "fileLimit": 1000
    },
    "analysisOptions": {
      "enableDuplicateDetection": true,
      "enableStructureAnalysis": true
    }
  }
}
```

## 🧪 Testing

### Run Tests

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm test -- tests/auth/auth-service.test.ts

# Run integration tests
npm test -- tests/integration/
```

### Test Server

Test the MCP server functionality:

```bash
# Test server startup and tool listing
node test-server.js
```

## 🚀 Deployment

### Docker Deployment

1. **Build Docker Image**
   ```bash
   docker build -t gdrive-sparc-mcp .
   ```

2. **Run Container**
   ```bash
   docker run -d \
     --name gdrive-mcp \
     -p 3000:3000 \
     --env-file .env \
     gdrive-sparc-mcp
   ```

### Production Deployment

1. **Environment Setup**
   ```bash
   # Set production environment
   export NODE_ENV=production
   export LOG_LEVEL=warn
   
   # Configure production secrets
   export SESSION_SECRET="your-production-session-secret"
   export GOOGLE_CLIENT_ID="your-production-client-id"
   export GOOGLE_CLIENT_SECRET="your-production-client-secret"
   ```

2. **Process Management**
   ```bash
   # Using PM2
   npm install -g pm2
   pm2 start dist/server.js --name gdrive-mcp
   pm2 save
   pm2 startup
   ```

3. **Health Monitoring**
   ```bash
   # Check server health
   curl -X POST http://localhost:3000 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   ```

## 🔍 Monitoring and Logging

### Log Levels
- **error** - Error conditions only
- **warn** - Warning and error conditions
- **info** - Informational, warning, and error messages (default)
- **debug** - All messages including debug information

### Performance Metrics
- Request/response times
- Cache hit/miss ratios
- Rate limiting statistics
- Authentication success/failure rates

### Health Checks
- Configuration validation
- Google API connectivity
- Cache system status
- Memory and performance metrics

## 🛡️ Security

### Authentication
- Secure OAuth2 flow with Google
- Session-based authentication
- Automatic token refresh
- Secure credential storage

### Data Protection
- No persistent storage of user data
- Encrypted session management
- Rate limiting and abuse prevention
- Input validation and sanitization

### Best Practices
- Regular security updates
- Environment variable protection
- Secure communication (HTTPS in production)
- Audit logging for security events

## 🐛 Troubleshooting

### Common Issues

#### Configuration Errors
```bash
# Check configuration validation
npm run build && node dist/server.js
```

#### Authentication Issues
- Verify Google Cloud credentials
- Check OAuth2 redirect URI configuration
- Ensure Drive API is enabled

#### Performance Issues
- Monitor cache hit rates
- Check rate limiting settings
- Review log levels and output

#### Connection Issues
- Verify network connectivity
- Check firewall settings
- Validate environment variables

### Debug Mode
```bash
# Enable debug logging
export LOG_LEVEL=debug
npm start
```

### Support
- Check [documentation](docs/)
- Review [troubleshooting guide](docs/troubleshooting.md)
- Submit issues on GitHub

## 📚 Documentation

- [Functional Requirements](docs/01_functional_requirements.md)
- [Domain Model](docs/02_domain_model.md)
- [API Specifications](docs/03_api_specifications.md)
- [Implementation Architecture](docs/05_implementation_architecture.md)
- [Testing and Deployment](docs/06_testing_and_deployment.md)

## 🤝 Contributing

1. Fork the repository
2. Create 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 Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- [Google Drive API](https://developers.google.com/drive) for file access capabilities
- [SPARC Development Team](https://github.com/sparc-dev) for the development methodology

---

**Version**: 1.0.0  
**Last Updated**: 2025-01-30  
**Maintainer**: SPARC Development Team