Rorsa Tools

Το σύστημα

Το Rorsa Tools (το repo λέγεται προσωρινά vertex-img, το rebrand είναι σε εξέλιξη) είναι το published MCP toolkit που επιτρέπει σε AI agents (κυρίως στο Claude) να δημιουργούν, να επεξεργάζονται και να μετασχηματίζουν εικόνες σε production κλίμακα. Εκθέτει 14 εργαλεία τόσο μέσω ενός MCP server (ώστε ένας Claude agent να μπορεί να τα καλεί απευθείας) όσο και ως CLI binary (ώστε ο developer να χρησιμοποιεί το ίδιο toolkit από το terminal). Η δημιουργία εικόνων τρέχει σε Vertex AI Nano Banana για high-quality και text-heavy δουλειά, με Gemini Flash ως γρηγορότερο fallback για thumbnails και απλά edits, και ένα smart model selection routes-άρει τη δουλειά στο σωστό backend αυτόματα. Η επεξεργασία γίνεται με Sharp για resize, compression, και format conversion. Το background removal τρέχει σε ένα Python sidecar process με το RMBG-2.0 model, GPU-accelerated τοπικά. 30 commits, 18 test files. Το toolkit παρήγαγε κάθε pixel-art εικόνα αυτού του portfolio.

Αρχιτεκτονική

• CLI binary: vertex-img (στο repo) / rorsa-img (στο rebrand): Commander-driven
• MCP server: vertex-image-mcp binary, εκθέτει 14 tools στους AI agents
• Image generation: @google/genai 1.50, Vertex AI Nano Banana (pro), Gemini fallback (flash) με smart model selection
• Image processing: Sharp 0.34.5 για resize/compress/format conversion, png-to-ico για favicon bundles
• Background removal: Python sidecar worker (scripts/bg-removal/worker.py) με RMBG-2.0 (HuggingFace gated model, CC-BY-NC-4.0)
• Batch concurrency: Per-item error recovery, retry logic, async batch runner
• Distribution: GitHub source + Claude Code plugin manifest (plugin.json)
• Tests: 18 test files με Vitest

Η συνεισφορά μου

Σχεδίασα και έχτισα ολόκληρο το toolkit ως sole maintainer. Η κεντρική αρχιτεκτονική απόφαση ήταν να εκθέσω το ίδιο tool surface τόσο ως CLI binary όσο και ως MCP server: ένα codebase, δύο interfaces. Ένας Claude Code agent καλεί απευθείας το generate_image ως MCP tool, ένας developer τρέχει την ίδια εντολή από το terminal. Σχεδίασα το 14-tool MCP surface για composability: generate_image → remove_background → generate_responsive_sets → compress_images είναι ένα φυσικό pipeline που ένας Claude agent μπορεί να εκτελέσει αυτόνομα, χωρίς να χρειαστεί να γράψω σενάρια. Το Python sidecar για background removal ήταν αναγκαστική επιλογή (το RMBG-2.0 model τρέχει μόνο σε Python + PyTorch), οπότε έγραψα ένα JSON-over-stdio IPC protocol ανάμεσα στον Node.js MCP server και έναν persistent Python worker, με process health monitoring και αυτόματο respawn αν ο worker καταρρεύσει από OOM σε μεγάλη εικόνα. Ο batch runner έχει per-item error recovery, ώστε μια αποτυχημένη εικόνα να μην σκοτώνει ολόκληρο το batch.

Stack λεπτομέρειες

Το smart model selection logic αξίζει εξήγηση: το Vertex AI Nano Banana (pro model) κοστίζει περισσότερο tokens, αλλά δίνει καλύτερο quality για text rendering και high-resolution output. Το Gemini Flash είναι γρηγορότερο και φθηνότερο για simple edits ή thumbnails. Η λογική: αν η εικόνα είναι > 1024px ή αν το prompt περιέχει text requirements, χρησιμοποιώ pro, αλλιώς flash. Η Python sidecar αρχιτεκτονική: ο Node.js worker spawns ένα Python process που φορτώνει RMBG-2.0 από HuggingFace cache, επικοινωνεί μέσω stdin/stdout JSON protocol. Το license του RMBG-2.0 (CC-BY-NC-4.0) σημαίνει non-commercial only, documented στο README. Τα 18 Vitest test αρχεία καλύπτουν model selection logic, batch runner behavior, και CLI argument parsing.

Αποτελέσματα

• 14 MCP tools που γίνονται κατευθείαν διαθέσιμα σε Claude Code agents
• Production-grade batch processing με retry logic + per-item error recovery
• GPU-accelerated background removal μέσω Python sidecar (RMBG-2.0)
• Συνδυασμός Vertex AI Nano Banana + Gemini με smart model selection

Πρόκληση

Η πιο σύνθετη τεχνική πρόκληση ήταν το Python sidecar IPC για GPU background removal. Το RMBG-2.0 model τρέχει σε Python + PyTorch, δεν υπάρχει Node.js binding. Επομένως: ο MCP server (Node.js) πρέπει να επικοινωνεί με ένα Python process. Η λύση: spawning ενός persistent Python worker process κατά την εκκίνηση του MCP server, με JSON-over-stdio protocol για requests/responses. Κάθε remove_background call στέλνει {"image_path": "...", "output_path": "..."} στο stdin του Python process, που απαντά με {"success": true} ή {"error": "..."}. Το tricky κομμάτι: αν ο Python process crash-άρει (π.χ. OOM λόγω μεγάλης εικόνας), ο MCP server πρέπει να το ανιχνεύσει και να respawn, χωρίς να crash-άρει και ο ίδιος. Υλοποίησα process health monitoring με automatic respawn και graceful degradation (επιστρέφει meaningful error αντί για unhandled rejection).

Σύνδεσμοι

• Repo: jimrarras/vertex-img (private, rebrand to rorsa-tools in flight)

Παρόμοια έργα

• Heartbeat PIM (MCP embedded): άλλο production MCP work, αλλά embedded σε commerce backend αντί standalone