@goonnguyen/human-mcp 1.2.0 → 1.3.0

package/plans/003-http-transport-local-file-access-plan.md

@@ -0,0 +1,880 @@
+# Plan: Fix Local File Access in HTTP Transport for Claude Desktop with Cloudflare R2 Integration
+
+## Problem Statement
+
+The Human MCP server's Vision Analysis Tool cannot read local image files when used with HTTP transport in Claude Desktop, while URL images work correctly. The issue occurs because:
+
+1. **Path Translation Issue**: Claude Desktop transforms local file paths to container-style paths (`/mnt/user-data/uploads/`) when using HTTP transport
+2. **File Access Limitation**: The HTTP server cannot access files outside its working directory due to security restrictions
+3. **Missing File Upload Mechanism**: The current HTTP transport doesn't handle file uploads from the client
+
+## Root Cause Analysis
+
+### Current Behavior
+When Claude Desktop uses the HTTP transport with a local file:
+1. Claude Desktop sends: `source: "/mnt/user-data/uploads/CleanShot_2025-09-13_at_13_07_56_2x.png"`
+2. The server tries to read this path using `fs.readFile()`
+3. The file doesn't exist at that path on the server's filesystem
+4. Error: `ENOENT: no such file or directory`
+
+### Why URLs Work
+- URLs are fetched directly using `fetch()` API
+- No filesystem access required
+- Data is downloaded and processed in memory
+
+## Solution Design
+
+### Approach 1: Cloudflare R2 Storage Integration (Recommended)
+Automatically upload local files to Cloudflare R2 and use CDN URLs.
+
+**Pros:**
+- Scalable and reliable cloud storage
+- Fast CDN delivery worldwide
+- No base64 overhead
+- Files accessible via public URLs
+- Automatic file management
+- Works with all file sizes
+
+**Cons:**
+- Requires Cloudflare account setup
+- Network dependency for uploads
+- Storage costs for large volumes
+
+### Approach 2: File Upload via Base64
+Transform local files to base64 data URIs before sending to the server.
+
+**Pros:**
+- Works with existing server code
+- No external dependencies
+- Secure - no filesystem access required
+
+**Cons:**
+- Increased payload size (~33% overhead)
+- Memory usage for large files
+- Size limitations
+
+### Approach 3: Hybrid Approach
+Combine Cloudflare R2 for large files and base64 for small files.
+
+**Pros:**
+- Optimal for all file sizes
+- Fallback mechanism
+- Best performance
+
+**Cons:**
+- More complex implementation
+- Requires both systems
+
+## Recommended Solution: Cloudflare R2 Integration with Automatic Upload
+
+### Implementation Plan
+
+#### Phase 1: Cloudflare R2 Integration
+
+1. **Install Dependencies**
+```bash
+npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner mime-types uuid
+```
+
+2. **Create Cloudflare R2 Client** (`src/utils/cloudflare-r2.ts`)
+```typescript
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+import { v4 as uuidv4 } from 'uuid';
+import mime from 'mime-types';
+import { logger } from './logger.js';
+
+export class CloudflareR2Client {
+  private s3Client: S3Client;
+  private bucketName: string;
+  private baseUrl: string;
+
+  constructor() {
+    const config = {
+      region: 'auto',
+      endpoint: process.env.CLOUDFLARE_CDN_ENDPOINT_URL,
+      credentials: {
+        accessKeyId: process.env.CLOUDFLARE_CDN_ACCESS_KEY!,
+        secretAccessKey: process.env.CLOUDFLARE_CDN_SECRET_KEY!,
+      },
+    };
+
+    this.s3Client = new S3Client(config);
+    this.bucketName = process.env.CLOUDFLARE_CDN_BUCKET_NAME!;
+    this.baseUrl = process.env.CLOUDFLARE_CDN_BASE_URL!;
+  }
+
+  async uploadFile(buffer: Buffer, originalName: string): Promise<string> {
+    try {
+      const fileExtension = originalName.split('.').pop() || 'bin';
+      const mimeType = mime.lookup(originalName) || 'application/octet-stream';
+      const key = `human-mcp/${uuidv4()}.${fileExtension}`;
+
+      const command = new PutObjectCommand({
+        Bucket: this.bucketName,
+        Key: key,
+        Body: buffer,
+        ContentType: mimeType,
+        Metadata: {
+          originalName: originalName,
+          uploadedAt: new Date().toISOString(),
+          source: 'human-mcp-http-transport'
+        }
+      });
+
+      await this.s3Client.send(command);
+      
+      const publicUrl = `${this.baseUrl}/${key}`;
+      logger.info(`File uploaded to Cloudflare R2: ${publicUrl}`);
+      
+      return publicUrl;
+    } catch (error) {
+      logger.error('Failed to upload to Cloudflare R2:', error);
+      throw new Error(`Failed to upload file: ${error.message}`);
+    }
+  }
+
+  async uploadBase64(base64Data: string, mimeType: string, originalName?: string): Promise<string> {
+    const buffer = Buffer.from(base64Data, 'base64');
+    const extension = mimeType.split('/')[1] || 'bin';
+    const fileName = originalName || `upload-${Date.now()}.${extension}`;
+    
+    return this.uploadFile(buffer, fileName);
+  }
+}
+
+// Singleton instance
+export const cloudflareR2 = new CloudflareR2Client();
+```
+
+3. **Update File Path Detection with Auto-Upload** (`src/tools/eyes/processors/image.ts`)
+```typescript
+import { cloudflareR2 } from '@/utils/cloudflare-r2.js';
+
+async function loadImage(source: string, fetchTimeout?: number): Promise<{ imageData: string; mimeType: string }> {
+  // Detect Claude Desktop virtual paths and auto-upload to Cloudflare
+  if (source.startsWith('/mnt/user-data/') || source.startsWith('/mnt/')) {
+    logger.info(`Detected Claude Desktop virtual path: ${source}`);
+    
+    // Extract filename from path
+    const filename = source.split('/').pop() || 'upload.jpg';
+    
+    // Try to read from a temporary upload directory (if middleware saved it)
+    const tempPath = `/tmp/mcp-uploads/${filename}`;
+    
+    try {
+      // Check if file was temporarily saved by middleware
+      if (await fs.access(tempPath).then(() => true).catch(() => false)) {
+        const buffer = await fs.readFile(tempPath);
+        
+        // Upload to Cloudflare R2
+        const publicUrl = await cloudflareR2.uploadFile(buffer, filename);
+        
+        // Clean up temp file
+        await fs.unlink(tempPath).catch(() => {});
+        
+        // Now fetch from the CDN URL
+        return loadImage(publicUrl, fetchTimeout);
+      }
+    } catch (error) {
+      logger.warn(`Could not process temp file: ${error.message}`);
+    }
+    
+    // If no temp file, provide helpful error with Cloudflare upload instructions
+    throw new ProcessingError(
+      `Local file access not supported via HTTP transport.\n` +
+      `The file path "${source}" is not accessible.\n\n` +
+      `Solutions:\n` +
+      `1. Upload your file to Cloudflare R2 first using the /mcp/upload endpoint\n` +
+      `2. Use a public URL instead of a local file path\n` +
+      `3. Convert the image to a base64 data URI\n` +
+      `4. Use the stdio transport for local file access`
+    );
+  }
+  
+  // Existing base64 handling
+  if (source.startsWith('data:image/')) {
+    const [header, data] = source.split(',');
+    if (!header || !data) {
+      throw new ProcessingError("Invalid base64 image format");
+    }
+    const mimeMatch = header.match(/data:(image\/[^;]+)/);
+    if (!mimeMatch || !mimeMatch[1]) {
+      throw new ProcessingError("Invalid base64 image format");
+    }
+    
+    // Optional: For large base64 images, upload to Cloudflare R2
+    if (data.length > 1024 * 1024) { // > 1MB base64
+      logger.info('Large base64 image detected, uploading to Cloudflare R2');
+      const publicUrl = await cloudflareR2.uploadBase64(data, mimeMatch[1]);
+      return loadImage(publicUrl, fetchTimeout);
+    }
+    
+    return {
+      imageData: data,
+      mimeType: mimeMatch[1]
+    };
+  }
+  
+  // Existing URL handling
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    // ... existing code
+  }
+  
+  // Local file handling - auto-upload to Cloudflare for HTTP transport
+  try {
+    const stats = await fs.stat(source);
+    if (!stats.isFile()) {
+      throw new ProcessingError(`Path is not a file: ${source}`);
+    }
+    
+    // If using HTTP transport, upload to Cloudflare
+    if (process.env.TRANSPORT_TYPE === 'http') {
+      logger.info(`HTTP transport detected, uploading local file to Cloudflare R2: ${source}`);
+      const buffer = await fs.readFile(source);
+      const filename = source.split('/').pop() || 'upload.jpg';
+      const publicUrl = await cloudflareR2.uploadFile(buffer, filename);
+      
+      // Fetch from CDN
+      return loadImage(publicUrl, fetchTimeout);
+    }
+    
+    // For stdio transport, process locally as before
+    const buffer = await fs.readFile(source);
+    const processedImage = await sharp(buffer)
+      .resize(1024, 1024, { fit: 'inside', withoutEnlargement: true })
+      .jpeg({ quality: 85 })
+      .toBuffer();
+    
+    return {
+      imageData: processedImage.toString('base64'),
+      mimeType: 'image/jpeg'
+    };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new ProcessingError(
+        `File not found: ${source}\n` +
+        `When using HTTP transport, files are automatically uploaded to Cloudflare R2.`
+      );
+    }
+    throw error;
+  }
+}
+```
+
+4. **Add File Upload Endpoint** (`src/transports/http/routes.ts`)
+```typescript
+import multer from 'multer';
+import { cloudflareR2 } from '@/utils/cloudflare-r2.js';
+
+// Configure multer for memory storage
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: {
+    fileSize: 100 * 1024 * 1024, // 100MB limit
+  },
+  fileFilter: (req, file, cb) => {
+    // Accept images, videos, and GIFs
+    if (file.mimetype.startsWith('image/') || 
+        file.mimetype.startsWith('video/') ||
+        file.mimetype === 'image/gif') {
+      cb(null, true);
+    } else {
+      cb(new Error('Invalid file type. Only images and videos are allowed.'));
+    }
+  }
+});
+
+// POST /mcp/upload - Handle file uploads to Cloudflare R2
+router.post('/upload', upload.single('file'), async (req, res) => {
+  try {
+    if (!req.file) {
+      res.status(400).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32600,
+          message: 'No file uploaded'
+        },
+        id: null
+      });
+      return;
+    }
+    
+    // Upload to Cloudflare R2
+    const publicUrl = await cloudflareR2.uploadFile(
+      req.file.buffer,
+      req.file.originalname
+    );
+    
+    res.json({
+      jsonrpc: '2.0',
+      result: {
+        success: true,
+        url: publicUrl,
+        originalName: req.file.originalname,
+        size: req.file.size,
+        mimeType: req.file.mimetype,
+        message: 'File uploaded successfully to Cloudflare R2'
+      },
+      id: req.body?.id || null
+    });
+  } catch (error) {
+    logger.error('Upload error:', error);
+    res.status(500).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32603,
+        message: `Failed to upload file: ${error.message}`
+      },
+      id: req.body?.id || null
+    });
+  }
+});
+
+// POST /mcp/upload-base64 - Handle base64 uploads
+router.post('/upload-base64', express.json({ limit: '100mb' }), async (req, res) => {
+  try {
+    const { data, mimeType, filename } = req.body;
+    
+    if (!data || !mimeType) {
+      res.status(400).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32600,
+          message: 'Missing required fields: data and mimeType'
+        },
+        id: null
+      });
+      return;
+    }
+    
+    // Remove data URI prefix if present
+    const base64Data = data.replace(/^data:.*?;base64,/, '');
+    
+    // Upload to Cloudflare R2
+    const publicUrl = await cloudflareR2.uploadBase64(
+      base64Data,
+      mimeType,
+      filename
+    );
+    
+    res.json({
+      jsonrpc: '2.0',
+      result: {
+        success: true,
+        url: publicUrl,
+        message: 'Base64 data uploaded successfully to Cloudflare R2'
+      },
+      id: req.body?.id || null
+    });
+  } catch (error) {
+    logger.error('Base64 upload error:', error);
+    res.status(500).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32603,
+        message: `Failed to upload base64 data: ${error.message}`
+      },
+      id: req.body?.id || null
+    });
+  }
+});
+```
+
+5. **Add Configuration Validation** (`src/utils/config.ts`)
+```typescript
+// Add Cloudflare R2 configuration
+cloudflare: z.object({
+  projectName: z.string().optional().default('human-mcp'),
+  bucketName: z.string(),
+  accessKey: z.string(),
+  secretKey: z.string(),
+  endpointUrl: z.string().url(),
+  baseUrl: z.string().url(),
+}).optional(),
+```
+
+#### Phase 2: Client Configuration Documentation
+
+1. **Update README.md** with Cloudflare R2 integration:
+```markdown
+### Using Local Files with HTTP Transport
+
+When using HTTP transport (common with Claude Desktop), local files are automatically uploaded to Cloudflare R2:
+
+#### Automatic Upload (Default Behavior)
+When you provide a local file path, the server automatically:
+1. Detects the local file path
+2. Uploads it to Cloudflare R2
+3. Returns the CDN URL for processing
+4. Uses the fast Cloudflare CDN for delivery
+
+#### Manual Upload Options
+
+##### Option 1: Upload File Directly
+```bash
+# Upload file to Cloudflare R2 and get CDN URL
+curl -X POST http://localhost:3000/mcp/upload \
+  -F "file=@/path/to/image.png" \
+  -H "Authorization: Bearer your_secret"
+
+# Response:
+{
+  "result": {
+    "success": true,
+    "url": "https://cdn.gotest.app/human-mcp/abc123.png",
+    "originalName": "image.png",
+    "size": 102400,
+    "mimeType": "image/png"
+  }
+}
+```
+
+##### Option 2: Upload Base64 Data
+```bash
+# Upload base64 data to Cloudflare R2
+curl -X POST http://localhost:3000/mcp/upload-base64 \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your_secret" \
+  -d '{
+    "data": "iVBORw0KGgoAAAANSUhEUgA...",
+    "mimeType": "image/png",
+    "filename": "screenshot.png"
+  }'
+```
+
+##### Option 3: Use Existing CDN URLs
+If your files are already hosted, use the public URL directly:
+- Cloudflare R2: `https://cdn.gotest.app/path/to/file.jpg`
+- Other CDNs: Any publicly accessible URL
+
+#### Configuration
+Add these to your `.env` file:
+```env
+# Cloudflare R2 Configuration
+CLOUDFLARE_CDN_PROJECT_NAME=human-mcp
+CLOUDFLARE_CDN_BUCKET_NAME=digitop
+CLOUDFLARE_CDN_ACCESS_KEY=your_access_key
+CLOUDFLARE_CDN_SECRET_KEY=your_secret_key
+CLOUDFLARE_CDN_ENDPOINT_URL=https://your-account.r2.cloudflarestorage.com
+CLOUDFLARE_CDN_BASE_URL=https://cdn.gotest.app
+```
+
+#### Benefits of Cloudflare R2 Integration
+- **Fast Global Delivery**: Files served from Cloudflare's global CDN
+- **Automatic Handling**: No manual conversion needed
+- **Large File Support**: Handle files up to 100MB
+- **Persistent URLs**: Files remain accessible for future reference
+- **Cost Effective**: Cloudflare R2 offers competitive pricing
+```
+
+2. **Add Claude Desktop Specific Configuration**:
+```json
+{
+  "mcpServers": {
+    "human-mcp-http": {
+      "command": "node",
+      "args": ["path/to/http-wrapper.js"],
+      "env": {
+        "GOOGLE_GEMINI_API_KEY": "your_key",
+        "TRANSPORT_TYPE": "http",
+        "HTTP_PORT": "3000",
+        "AUTO_CONVERT_FILES": "true"
+      }
+    }
+  }
+}
+```
+
+#### Phase 3: Middleware for Automatic File Handling
+
+Create `src/transports/http/file-interceptor.ts`:
+```typescript
+import { Request, Response, NextFunction } from 'express';
+import { cloudflareR2 } from '@/utils/cloudflare-r2.js';
+import { logger } from '@/utils/logger.js';
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function fileInterceptorMiddleware(
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  // Only intercept tool calls with file paths
+  if (req.body?.method === 'tools/call' && req.body?.params?.arguments) {
+    const args = req.body.params.arguments;
+    
+    // Check for source fields that might contain file paths
+    const fileFields = ['source', 'source1', 'source2', 'path', 'filePath'];
+    
+    for (const field of fileFields) {
+      if (args[field] && typeof args[field] === 'string') {
+        const filePath = args[field];
+        
+        // Detect Claude Desktop virtual paths
+        if (filePath.startsWith('/mnt/user-data/') || filePath.startsWith('/mnt/')) {
+          logger.info(`Intercepting Claude Desktop virtual path: ${filePath}`);
+          
+          try {
+            // Extract filename
+            const filename = path.basename(filePath);
+            
+            // Check if we have a temporary file saved by Claude Desktop
+            const tempPath = path.join('/tmp/claude-uploads', filename);
+            
+            if (await fs.access(tempPath).then(() => true).catch(() => false)) {
+              // File exists in temp, upload to Cloudflare
+              const buffer = await fs.readFile(tempPath);
+              const publicUrl = await cloudflareR2.uploadFile(buffer, filename);
+              
+              // Replace the virtual path with CDN URL
+              args[field] = publicUrl;
+              
+              // Clean up temp file
+              await fs.unlink(tempPath).catch(() => {});
+              
+              logger.info(`Replaced virtual path with CDN URL: ${publicUrl}`);
+            } else {
+              // No temp file, try to extract from request if it's base64
+              // This handles cases where Claude Desktop might send base64 inline
+              if (req.body.params.fileData && req.body.params.fileData[field]) {
+                const base64Data = req.body.params.fileData[field];
+                const mimeType = req.body.params.fileMimeTypes?.[field] || 'image/jpeg';
+                
+                const publicUrl = await cloudflareR2.uploadBase64(
+                  base64Data,
+                  mimeType,
+                  filename
+                );
+                
+                args[field] = publicUrl;
+                logger.info(`Uploaded inline base64 to CDN: ${publicUrl}`);
+              } else {
+                // Provide helpful error response
+                logger.warn(`Cannot access virtual path: ${filePath}`);
+                return res.status(400).json({
+                  jsonrpc: '2.0',
+                  error: {
+                    code: -32602,
+                    message: 'File not accessible via HTTP transport',
+                    data: {
+                      path: filePath,
+                      suggestions: [
+                        'Upload the file using the /mcp/upload endpoint first',
+                        'Use a public URL instead of a local file path',
+                        'Convert the image to a base64 data URI',
+                        'Switch to stdio transport for local file access'
+                      ]
+                    }
+                  },
+                  id: req.body.id
+                });
+              }
+            }
+          } catch (error) {
+            logger.error(`Error processing virtual path: ${error}`);
+            return res.status(500).json({
+              jsonrpc: '2.0',
+              error: {
+                code: -32603,
+                message: `Failed to process file: ${error.message}`
+              },
+              id: req.body.id
+            });
+          }
+        }
+        
+        // Handle regular local paths when in HTTP mode
+        else if (!filePath.startsWith('http') && !filePath.startsWith('data:')) {
+          if (process.env.TRANSPORT_TYPE === 'http') {
+            try {
+              // Check if file exists locally
+              await fs.access(filePath);
+              
+              // Upload to Cloudflare R2
+              const buffer = await fs.readFile(filePath);
+              const filename = path.basename(filePath);
+              const publicUrl = await cloudflareR2.uploadFile(buffer, filename);
+              
+              // Replace local path with CDN URL
+              args[field] = publicUrl;
+              
+              logger.info(`Auto-uploaded local file to CDN: ${publicUrl}`);
+            } catch (error) {
+              if (error.code === 'ENOENT') {
+                logger.warn(`Local file not found: ${filePath}`);
+              }
+              // Continue without modification if file doesn't exist
+            }
+          }
+        }
+      }
+    }
+  }
+  
+  next();
+}
+```
+
+4. **Update HTTP Server to Use Middleware** (`src/transports/http/server.ts`)
+```typescript
+import { fileInterceptorMiddleware } from './file-interceptor.js';
+
+// Add before route handlers
+app.use(fileInterceptorMiddleware);
+
+// Existing routes...
+app.use('/mcp', routes);
+```
+
+#### Phase 4: Testing Strategy
+
+1. **Unit Tests** (`tests/unit/cloudflare-r2.test.ts`):
+```typescript
+import { CloudflareR2Client } from '@/utils/cloudflare-r2';
+
+describe('Cloudflare R2 Integration', () => {
+  let client: CloudflareR2Client;
+  
+  beforeAll(() => {
+    client = new CloudflareR2Client();
+  });
+  
+  it('should upload buffer to Cloudflare R2', async () => {
+    const buffer = Buffer.from('test image data');
+    const url = await client.uploadFile(buffer, 'test.jpg');
+    
+    expect(url).toMatch(/^https:\/\/cdn\.gotest\.app\/human-mcp\//);
+  });
+  
+  it('should upload base64 to Cloudflare R2', async () => {
+    const base64 = Buffer.from('test').toString('base64');
+    const url = await client.uploadBase64(base64, 'image/png', 'test.png');
+    
+    expect(url).toMatch(/^https:\/\/cdn\.gotest\.app\/human-mcp\//);
+  });
+  
+  it('should handle upload errors gracefully', async () => {
+    const invalidBuffer = null as any;
+    
+    await expect(client.uploadFile(invalidBuffer, 'test.jpg'))
+      .rejects.toThrow('Failed to upload file');
+  });
+});
+```
+
+2. **Integration Tests** (`tests/integration/http-transport-files.test.ts`):
+```typescript
+describe('HTTP Transport File Handling', () => {
+  it('should auto-upload Claude Desktop virtual paths to Cloudflare', async () => {
+    const request = {
+      jsonrpc: '2.0',
+      method: 'tools/call',
+      params: {
+        name: 'eyes_analyze',
+        arguments: {
+          source: '/mnt/user-data/uploads/test.png',
+          type: 'image'
+        }
+      }
+    };
+    
+    const response = await sendRequest(request);
+    
+    // Should either upload successfully or provide helpful error
+    if (response.result) {
+      expect(response.result).toBeDefined();
+    } else {
+      expect(response.error.data.suggestions).toContain(
+        'Upload the file using the /mcp/upload endpoint first'
+      );
+    }
+  });
+  
+  it('should handle file upload endpoint', async () => {
+    const response = await request(app)
+      .post('/mcp/upload')
+      .attach('file', 'test/fixtures/test.png');
+    
+    expect(response.body.result.url).toMatch(/^https:\/\/cdn\.gotest\.app\//);
+    expect(response.body.result.success).toBe(true);
+  });
+  
+  it('should handle base64 upload endpoint', async () => {
+    const base64Data = Buffer.from('test image').toString('base64');
+    
+    const response = await request(app)
+      .post('/mcp/upload-base64')
+      .send({
+        data: base64Data,
+        mimeType: 'image/png',
+        filename: 'test.png'
+      });
+    
+    expect(response.body.result.url).toMatch(/^https:\/\/cdn\.gotest\.app\//);
+  });
+  
+  it('should auto-upload local files in HTTP mode', async () => {
+    process.env.TRANSPORT_TYPE = 'http';
+    
+    const result = await processImage(
+      model,
+      './test/fixtures/local-image.png',
+      options
+    );
+    
+    // Should have uploaded to Cloudflare and processed from CDN
+    expect(result.metadata).toBeDefined();
+  });
+});
+```
+
+## Implementation Checklist
+
+### Immediate Actions (Phase 1)
+- [ ] Install AWS SDK S3 client and dependencies
+- [ ] Create Cloudflare R2 client utility class
+- [ ] Add Cloudflare configuration to environment variables
+- [ ] Update config validation schema
+
+### Short-term (Phase 2)
+- [ ] Update `loadImage()` function to auto-upload to Cloudflare
+- [ ] Implement file upload endpoint `/mcp/upload`
+- [ ] Implement base64 upload endpoint `/mcp/upload-base64`
+- [ ] Add file interceptor middleware for automatic handling
+- [ ] Update error messages with Cloudflare upload instructions
+
+### Medium-term (Phase 3)
+- [ ] Add file caching to avoid re-uploading same files
+- [ ] Implement file cleanup/retention policies
+- [ ] Add progress tracking for large uploads
+- [ ] Create upload status endpoint
+
+### Long-term (Phase 4)
+- [ ] Add support for video and GIF uploads
+- [ ] Implement chunked upload for very large files
+- [ ] Add file compression before upload
+- [ ] Create dashboard for managing uploaded files
+
+## Security Considerations
+
+1. **Cloudflare R2 Security**: 
+   - Use secure access keys and never expose them
+   - Implement proper CORS policies on the bucket
+   - Set appropriate ACLs for uploaded files
+   
+2. **Upload Validation**:
+   - Enforce file size limits (100MB default)
+   - Validate MIME types strictly
+   - Scan for malicious content if needed
+   
+3. **Access Control**:
+   - Require authentication for upload endpoints
+   - Implement rate limiting for uploads
+   - Log all upload activities
+   
+4. **Data Privacy**:
+   - Consider file encryption for sensitive content
+   - Implement retention policies
+   - Provide deletion capabilities
+
+## Performance Optimizations
+
+1. **Cloudflare CDN Benefits**:
+   - Global edge caching for fast delivery
+   - Automatic image optimization
+   - WebP conversion for supported browsers
+   - Bandwidth savings through compression
+   
+2. **Upload Optimizations**:
+   - Parallel uploads for multiple files
+   - Resume capability for interrupted uploads
+   - Deduplication based on file hash
+   
+3. **Processing Optimizations**:
+   - Process images directly from CDN URLs
+   - Skip re-upload for already uploaded files
+   - Use Cloudflare Workers for on-the-fly transformations
+
+## Alternative Solutions
+
+### Using stdio Transport
+For users who need direct local file access without cloud uploads:
+```json
+{
+  "mcpServers": {
+    "human-mcp": {
+      "command": "npx",
+      "args": ["@goonnguyen/human-mcp"],
+      "env": {
+        "GOOGLE_GEMINI_API_KEY": "key",
+        "TRANSPORT_TYPE": "stdio"
+      }
+    }
+  }
+}
+```
+
+### Pre-uploading to Cloudflare R2
+Users can pre-upload files using the provided endpoints:
+```bash
+# Upload script
+#!/bin/bash
+for file in *.png; do
+  curl -X POST http://localhost:3000/mcp/upload \
+    -F "file=@$file" \
+    -H "Authorization: Bearer $MCP_SECRET"
+done
+```
+
+### Using Existing CDN URLs
+If files are already hosted on Cloudflare or other CDNs, use the URLs directly without re-uploading.
+
+## Success Metrics
+
+1. **Error Resolution**: Eliminate "file not found" errors for Claude Desktop users
+2. **Upload Performance**: Files uploaded to Cloudflare R2 in under 3 seconds
+3. **CDN Performance**: Image delivery under 100ms from edge locations
+4. **User Experience**: Seamless file handling without manual intervention
+5. **Reliability**: 99.9% upload success rate
+6. **Cost Efficiency**: Under $0.015 per GB stored on Cloudflare R2
+
+## Rollout Plan
+
+1. **Day 1-2**: 
+   - Set up Cloudflare R2 client
+   - Implement upload endpoints
+   - Add configuration validation
+
+2. **Day 3-4**: 
+   - Update image processors with auto-upload
+   - Add file interceptor middleware
+   - Test with Claude Desktop
+
+3. **Day 5-6**: 
+   - Add comprehensive error handling
+   - Update documentation
+   - Create usage examples
+
+4. **Day 7**: 
+   - Deploy to production
+   - Monitor upload metrics
+   - Gather user feedback
+
+## Conclusion
+
+The Cloudflare R2 integration provides a robust, scalable solution for handling local files in HTTP transport. By automatically uploading files to Cloudflare's global CDN, we eliminate file access issues while providing superior performance and reliability. This approach transforms a limitation into an advantage, giving users faster file processing through Cloudflare's edge network.
+
+### Key Benefits:
+- **Zero Configuration for Users**: Automatic file handling without manual steps
+- **Global Performance**: Files served from Cloudflare's 300+ edge locations
+- **Cost Effective**: R2's competitive pricing with no egress fees
+- **Future Proof**: Scalable solution that grows with usage
+- **Enhanced Security**: Files isolated from server filesystem
+
+### Next Steps:
+1. Implement the Cloudflare R2 client
+2. Update file processors with auto-upload logic
+3. Add comprehensive testing
+4. Deploy and monitor performance
+5. Gather user feedback for improvements