@hybridlabor-api/aos 4.2.0 → 4.4.0

package/mcps/windows-computer-use-mcp/docs/_stale/development/archive/DEVELOPMENT_PAIN_POINTS.md

@@ -1,699 +0,0 @@
-> **Archived fleet import** — From **notepadpp-mcp** / generic fleet dev notes. **Not** pywinauto-mcp source of truth. See [DEVELOPMENT.md](../../DEVELOPMENT.md) and [TESTING.md](../../TESTING.md).
-# 🔧 Development Pain Points & Solutions
-
-**Real-World Issues and Practical Solutions**  
-**Based on Actual Development Experience**  
-**Timeline**: September 2025
-
----
-
-## 🚨 Port Conflict Hell & How to Avoid It
-
-### **The Port Conflict Problem**
-
-**What happens when you run multiple projects**:
-- ❌ **Port 3000 conflicts**: Every React app wants port 3000
-- ❌ **Database port clashes**: Multiple PostgreSQL instances on 5432
-- ❌ **Monitoring stack conflicts**: Grafana, Prometheus, Redis all have standard ports
-- ❌ **Development vs production**: Same ports in different environments
-- ❌ **Docker compose conflicts**: Multiple stacks trying to bind same ports
-
-**Real example of chaos**:
-```bash
-# This will fail spectacularly
-docker-compose up -d  # veogen project (uses 3000, 5432, 6379)
-docker-compose -f monitoring-stack.yml up -d  # Grafana on 3000 - CONFLICT!
-npm start  # Another React app on 3000 - CONFLICT!
-```
-
-### **Smart Port Management Strategies**
-
-#### **1. Port Range Allocation Strategy**
-
-**Assign port ranges by project type**:
-```yaml
-# Port allocation scheme
-Frontend Apps:     3000-3099
-Backend APIs:      8000-8099  
-Databases:         5000-5099
-Monitoring:        9000-9099
-Cache/Redis:       6000-6099
-Message Queues:    4000-4099
-```
-
-**Example implementation**:
-```yaml
-# veogen project - docker-compose.yml
-services:
-  frontend:
-    ports:
-      - "3001:3000"  # External: 3001, Internal: 3000
-  backend:
-    ports:
-      - "8001:8000"
-  database:
-    ports:
-      - "5001:5432"
-  redis:
-    ports:
-      - "6001:6379"
-
-# monitoring stack - docker-compose.monitoring.yml
-services:
-  grafana:
-    ports:
-      - "9001:3000"  # Grafana internally uses 3000, exposed on 9001
-  prometheus:
-    ports:
-      - "9002:9090"
-
-# ring-mcp development - docker-compose.yml
-services:
-  ring-mcp:
-    ports:
-      - "8000:8000"  # Ring MCP server
-  grafana:
-    ports:
-      - "9001:3000"  # Grafana monitoring
-  prometheus:
-    ports:
-      - "9002:9090"  # Prometheus metrics
-  loki:
-    ports:
-      - "9003:3100"  # Loki logging
-  promtail:
-    ports:
-      - "9004:9080"  # Promtail log shipping
-  node-exporter:
-    ports:
-      - "9005:9100"  # System metrics
-```
-
-#### **2. Environment-Based Port Mapping**
-
-**Use .env files for port configuration**:
-```bash
-# .env.development
-FRONTEND_PORT=3001
-BACKEND_PORT=8001
-DB_PORT=5001
-REDIS_PORT=6001
-
-# .env.staging
-FRONTEND_PORT=3002
-BACKEND_PORT=8002
-DB_PORT=5002
-REDIS_PORT=6002
-
-# .env.production
-FRONTEND_PORT=80
-BACKEND_PORT=8000
-DB_PORT=5432
-REDIS_PORT=6379
-```
-
-**Docker compose with environment variables**:
-```yaml
-services:
-  frontend:
-    ports:
-      - "${FRONTEND_PORT}:3000"
-  backend:
-    ports:
-      - "${BACKEND_PORT}:8000"
-  database:
-    ports:
-      - "${DB_PORT}:5432"
-```
-
-#### **3. Dynamic Port Assignment**
-
-**For development environments**:
-```bash
-# Script to find available ports
-#!/bin/bash
-find_free_port() {
-    local port=$1
-    while netstat -tuln | grep -q ":$port "; do
-        ((port++))
-    done
-    echo $port
-}
-
-# Auto-assign ports
-FRONTEND_PORT=$(find_free_port 3000)
-BACKEND_PORT=$(find_free_port 8000)
-DB_PORT=$(find_free_port 5432)
-
-echo "Frontend: http://localhost:$FRONTEND_PORT"
-echo "Backend: http://localhost:$BACKEND_PORT"
-echo "Database: localhost:$DB_PORT"
-```
-
-#### **4. Portainer Port Management**
-
-**Visual port conflict detection**:
-- ✅ **Port mapping overview**: See all active port bindings
-- ✅ **Conflict detection**: Warns before starting conflicting services
-- ✅ **Port suggestion**: Suggests alternative ports automatically
-- ✅ **Environment separation**: Different port schemes per environment
-
----
-
-## 🌐 Tailscale: The Networking Game-Changer
-
-### **Why Tailscale is Perfect for Development**
-
-**Traditional networking pain**:
-- ❌ **VPN complexity**: Complex setup, maintenance, performance issues
-- ❌ **Port forwarding hell**: Router configuration, security risks
-- ❌ **Firewall management**: Complex rules, hard to maintain
-- ❌ **Dynamic IP issues**: Home IP changes, services become unreachable
-- ❌ **Team access problems**: Sharing development environments
-
-**Tailscale solution**:
-- ✅ **Zero-config networking**: Automatic mesh network setup
-- ✅ **Secure by default**: WireGuard encryption, key management
-- ✅ **Cross-platform**: Works on everything (Windows, Linux, Mac, mobile)
-- ✅ **Simple sharing**: Share services with team members easily
-- ✅ **Performance**: Direct peer-to-peer connections when possible
-
-### **Tailscale Use Cases for Our Projects**
-
-#### **1. Remote Access to Home Lab**
-
-**Access your home monitoring stack from anywhere**:
-```bash
-# At home: Start your monitoring stack
-docker-compose up -d grafana prometheus loki
-
-# Install Tailscale on home server
-curl -fsSL https://tailscale.com/install.sh | sh
-sudo tailscale up
-
-# From anywhere: Access via Tailscale IP
-http://100.64.0.1:9001  # Grafana dashboard
-http://100.64.0.1:9002  # Prometheus metrics
-```
-
-**Benefits**:
-- ✅ **No port forwarding**: No router configuration needed
-- ✅ **Secure access**: Encrypted tunnel, no exposed ports
-- ✅ **Mobile friendly**: Check home monitoring from phone
-- ✅ **Team sharing**: Give team members access to your home lab
-
-#### **2. Development Environment Sharing**
-
-**Share your veogen development with team**:
-```bash
-# Developer 1: Start development environment
-docker-compose up -d
-tailscale up
-
-# Developer 2: Access shared environment
-http://100.64.0.5:3001  # Frontend
-http://100.64.0.5:8001  # Backend API
-```
-
-**Perfect for**:
-- Code reviews with live environment access
-- Client demonstrations without deployment
-- Cross-platform testing (iOS dev accessing Windows backend)
-- Remote pair programming sessions
-
-#### **3. MCP Server Development**
-
-**Test MCP servers across different machines**:
-```bash
-# Development machine: Run Ring MCP server
-python -m ring_mcp
-tailscale status  # Get your Tailscale IP
-
-# Testing machine: Configure Claude Desktop
-{
-  "mcpServers": {
-    "remote-ring-mcp": {
-      "command": "ssh",
-      "args": ["100.64.0.10", "python", "-m", "ring_mcp"]
-    }
-  }
-}
-```
-
-### **Tailscale Setup for Development Teams**
-
-#### **Quick Team Setup**:
-```bash
-# Each team member
-curl -fsSL https://tailscale.com/install.sh | sh
-sudo tailscale up
-
-# Share specific services
-tailscale serve 3000  # Share local port 3000
-tailscale funnel 3000  # Make it publicly accessible (optional)
-```
-
-#### **Advanced Configuration**:
-```yaml
-# docker-compose.yml with Tailscale
-services:
-  tailscale:
-    image: tailscale/tailscale:latest
-    network_mode: host
-    cap_add:
-      - NET_ADMIN
-      - SYS_MODULE
-    volumes:
-      - /dev/net/tun:/dev/net/tun
-      - tailscale-data:/var/lib/tailscale
-    environment:
-      - TS_AUTHKEY=${TAILSCALE_AUTHKEY}
-      - TS_HOSTNAME=myproject-dev
-
-  app:
-    depends_on:
-      - tailscale
-    # Your app services here
-```
-
----
-
-## 🌍 CORS: The Frontend Developer's Nemesis
-
-### **Understanding CORS Pain**
-
-**Typical CORS error scenario**:
-```bash
-# Frontend (localhost:3000) trying to call backend (localhost:8000)
-fetch('http://localhost:8000/api/devices')
-# Error: CORS policy blocked request
-
-# Console shows:
-# "Access to fetch at 'http://localhost:8000/api/devices' from origin 
-# 'http://localhost:3000' has been blocked by CORS policy"
-```
-
-### **CORS Solutions by Environment**
-
-#### **1. Development Environment**
-
-**FastAPI backend (Python)**:
-```python
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-
-app = FastAPI()
-
-# Development CORS setup
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=[
-        "http://localhost:3000",      # React dev server
-        "http://localhost:3001",      # Alternative port
-        "http://127.0.0.1:3000",     # Alternative localhost
-        "http://100.64.0.*",         # Tailscale network
-    ],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-```
-
-**Express.js backend (Node.js)**:
-```javascript
-const express = require('express');
-const cors = require('cors');
-
-const app = express();
-
-// Development CORS setup
-app.use(cors({
-  origin: [
-    'http://localhost:3000',
-    'http://localhost:3001', 
-    'http://127.0.0.1:3000',
-    /^http:\/\/100\.64\.0\.\d+:\d+$/  // Tailscale network regex
-  ],
-  credentials: true
-}));
-```
-
-#### **2. Production Environment**
-
-**Strict CORS for production**:
-```python
-# Production CORS setup
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=[
-        "https://yourdomain.com",
-        "https://www.yourdomain.com",
-        "https://app.yourdomain.com",
-    ],
-    allow_credentials=True,
-    allow_methods=["GET", "POST", "PUT", "DELETE"],
-    allow_headers=["Content-Type", "Authorization"],
-)
-```
-
-#### **3. Docker Development Setup**
-
-**CORS-friendly docker-compose**:
-```yaml
-services:
-  frontend:
-    build: ./frontend
-    ports:
-      - "3000:3000"
-    environment:
-      - REACT_APP_API_URL=http://localhost:8000
-      - CHOKIDAR_USEPOLLING=true  # For hot reload
-
-  backend:
-    build: ./backend
-    ports:
-      - "8000:8000"
-    environment:
-      - CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
-      - NODE_ENV=development
-```
-
-### **CORS Debugging Tools**
-
-#### **Browser Developer Tools**:
-```bash
-# Check CORS headers in Network tab
-Access-Control-Allow-Origin: http://localhost:3000
-Access-Control-Allow-Methods: GET, POST, PUT, DELETE
-Access-Control-Allow-Headers: Content-Type, Authorization
-Access-Control-Allow-Credentials: true
-```
-
-#### **Testing CORS with curl**:
-```bash
-# Test preflight request
-curl -X OPTIONS \
-  -H "Origin: http://localhost:3000" \
-  -H "Access-Control-Request-Method: POST" \
-  -H "Access-Control-Request-Headers: Content-Type" \
-  http://localhost:8000/api/devices
-
-# Test actual request
-curl -X GET \
-  -H "Origin: http://localhost:3000" \
-  http://localhost:8000/api/devices
-```
-
----
-
-## 🔍 MCP Development Tools
-
-### **Anthropic Inspector vs MCPJam**
-
-#### **Anthropic Inspector (Traditional Approach)**
-
-**What it is**:
-- Official debugging tool from Anthropic
-- Built-in Claude Desktop integration
-- Basic MCP server testing capabilities
-
-**Limitations**:
-- ❌ **Limited features**: Basic debugging only
-- ❌ **Claude Desktop dependency**: Requires full setup
-- ❌ **Debugging complexity**: Hard to isolate issues
-- ❌ **Limited visualization**: Basic tool listing
-
-**Use case**: Basic validation that MCP server loads
-
-#### **MCPJam: The Better Alternative**
-
-**Why MCPJam is superior**:
-- ✅ **Standalone testing**: Test MCP servers without Claude Desktop
-- ✅ **Advanced debugging**: Detailed error messages and stack traces
-- ✅ **Interactive testing**: Call tools directly, see raw responses
-- ✅ **Performance monitoring**: Response times, error rates
-- ✅ **Schema validation**: Verify tool schemas and parameters
-- ✅ **Development workflow**: Hot reload, live debugging
-
-### **MCPJam Setup and Usage**
-
-#### **Installation**:
-```bash
-# Install MCPJam
-npm install -g mcpjam
-
-# Or use directly with npx
-npx mcpjam
-```
-
-#### **Testing Our Ring MCP Server**:
-```bash
-# Start MCPJam with our server
-mcpjam --server "python -m ring_mcp"
-
-# Or test specific configuration
-mcpjam --config ring-mcp-config.json
-```
-
-**MCPJam config file**:
-```json
-{
-  "server": {
-    "command": "python",
-    "args": ["-m", "ring_mcp"],
-    "cwd": "/path/to/ring-mcp"
-  },
-  "environment": {
-    "RING_USERNAME": "your-email@example.com",
-    "RING_PASSWORD": "your-password"
-  }
-}
-```
-
-#### **MCPJam Features for Development**:
-
-**Interactive tool testing**:
-```bash
-# List all available tools
-mcpjam list-tools
-
-# Test specific tool with parameters
-mcpjam call-tool list_devices
-mcpjam call-tool get_device_status --device-id "enterprises/123/devices/456"
-
-# Validate tool schemas
-mcpjam validate-schemas
-
-# Performance testing
-mcpjam benchmark --tool list_devices --iterations 100
-```
-
-**Live debugging session**:
-```bash
-# Start interactive debugging session
-mcpjam debug
-
-# Commands in debug session:
-> tools                    # List available tools
-> call list_devices        # Call tool
-> schema get_device_status # Show tool schema
-> logs                     # Show server logs
-> reload                   # Hot reload server
-```
-
-### **Development Workflow with MCPJam**
-
-#### **1. Development Cycle**:
-```bash
-# Terminal 1: Start MCPJam in watch mode
-mcpjam --server "python -m ring_mcp" --watch
-
-# Terminal 2: Make changes to code
-# MCPJam automatically reloads and retests
-
-# Terminal 3: Test specific scenarios
-mcpjam call-tool get_camera_status
-```
-
-#### **2. Debugging Tool Issues**:
-```bash
-# Debug specific tool
-mcpjam debug-tool get_device_status
-
-# Shows:
-# - Parameter validation
-# - Function execution 
-# - Return value validation
-# - Error stack traces
-# - Performance metrics
-```
-
-#### **3. Schema Validation**:
-```bash
-# Validate all tool schemas
-mcpjam validate
-
-# Output shows:
-# ✅ list_devices: Valid schema
-# ✅ get_device_status: Valid schema  
-# ❌ sound_alarm: Missing required parameter description
-# ✅ about_server: Valid schema
-```
-
-### **MCPJam vs Anthropic Inspector Comparison**
-
-| Feature | Anthropic Inspector | MCPJam | Winner |
-|---------|-------------------|---------|--------|
-| **Standalone Testing** | No | Yes | 🏆 MCPJam |
-| **Interactive Debugging** | Limited | Advanced | 🏆 MCPJam |
-| **Schema Validation** | Basic | Comprehensive | 🏆 MCPJam |
-| **Performance Testing** | No | Yes | 🏆 MCPJam |
-| **Hot Reload** | No | Yes | 🏆 MCPJam |
-| **Error Details** | Limited | Detailed | 🏆 MCPJam |
-| **Tool Visualization** | Basic | Advanced | 🏆 MCPJam |
-| **Development Workflow** | Poor | Excellent | 🏆 MCPJam |
-
-### **Integration with Our Development Stack**
-
-#### **MCPJam + Portainer + Monitoring**:
-```yaml
-# docker-compose.dev.yml
-services:
-  mcpjam:
-    image: mcpjam/mcpjam:latest
-    ports:
-      - "4000:4000"
-    volumes:
-      - .:/workspace
-    command: mcpjam serve --port 4000
-    
-  ring-mcp:
-    build: .
-    volumes:
-      - .:/app
-    command: python -m ring_mcp
-    
-  monitoring:
-    # Grafana + Prometheus stack
-    # Monitor MCPJam testing metrics
-```
-
-#### **CI/CD Integration**:
-```yaml
-# .github/workflows/mcp-test.yml
-- name: Test MCP Server
-  run: |
-    mcpjam test --server "python -m ring_mcp" --exit-code
-    mcpjam validate --strict
-    mcpjam benchmark --tools all --min-performance 100ms
-```
-
----
-
-## 🎯 Putting It All Together
-
-### **Complete Development Environment**
-
-**Port allocation for full stack**:
-```yaml
-# docker-compose.full-dev.yml
-services:
-  # Application stack (3000-3099)
-  frontend:
-    ports: ["3001:3000"]
-
-  # Backend APIs (8000-8099)
-  backend:
-    ports: ["8001:8000"]
-  ring-mcp:
-    ports: ["8000:8000"]
-
-  # Databases (5000-5099)
-  postgres:
-    ports: ["5001:5432"]
-
-  # Cache/Redis (6000-6099)
-  redis:
-    ports: ["6001:6379"]
-
-  # Monitoring (9000-9099)
-  grafana:
-    ports: ["9001:3000"]
-  prometheus:
-    ports: ["9002:9090"]
-  loki:
-    ports: ["9003:3100"]
-  promtail:
-    ports: ["9004:9080"]
-
-  # Development tools (4000-4099)
-  mcpjam:
-    ports: ["4001:4000"]
-  portainer:
-    ports: ["9000:9000"]
-```
-
-**CORS configuration for full stack**:
-```python
-# Backend CORS setup
-CORS_ORIGINS = [
-    "http://localhost:3001",      # Frontend
-    "http://localhost:4001",      # MCPJam
-    "http://100.64.0.*",          # Tailscale network
-]
-```
-
-**Tailscale access for team**:
-- Frontend: `http://100.64.0.10:3001`
-- Backend: `http://100.64.0.10:8001`
-- Ring MCP: `http://100.64.0.10:8000`
-- Monitoring: `http://100.64.0.10:9001`
-- Grafana: `http://100.64.0.10:9001`
-- Prometheus: `http://100.64.0.10:9002`
-- MCP Testing: `http://100.64.0.10:4001`
-
-### **Development Workflow**
-
-#### **Daily Development**:
-1. **Start environment**: `docker-compose up -d`
-2. **Check ports**: Portainer dashboard at `localhost:9000`
-3. **Test MCP**: MCPJam at `localhost:4001`
-4. **Monitor performance**: Grafana at `localhost:9001`
-5. **Share with team**: Tailscale IPs for remote access
-
-#### **Debugging Issues**:
-1. **Port conflicts**: Check Portainer port mappings
-2. **CORS errors**: Verify origins in backend configuration
-3. **MCP issues**: Use MCPJam interactive debugging
-4. **Performance problems**: Check Grafana dashboards
-5. **Network issues**: Tailscale status and connectivity
-
----
-
-## 💡 Pro Tips
-
-### **Port Management**:
-- Use consistent port ranges across projects
-- Document port assignments in README
-- Use environment variables for flexibility
-- Check ports before starting new services
-
-### **Tailscale**:
-- Set meaningful hostnames for devices
-- Use Tailscale serve for temporary sharing
-- Enable MagicDNS for easy device discovery
-- Regularly update Tailscale client
-
-### **CORS**:
-- Be permissive in development, strict in production
-- Use environment variables for origin configuration
-- Test CORS with multiple origins
-- Monitor CORS errors in browser console
-
-### **MCP Development**:
-- Use MCPJam for all MCP server development
-- Set up automated testing with MCPJam
-- Monitor MCP server performance with Grafana
-- Use Portainer for easy container management
-
-**Bottom Line**: These pain points are universal in modern development. Having systematic solutions for port conflicts, networking, CORS, and MCP testing makes development much smoother and more professional! 🚀🔧