convez.ai
MCP ServerDados & AnalyticsAvançado
vero-code

Spatial Optician

vero-code/spatial-optician

Auditoria inteligente de iluminação com IA e cálculo de ROI em tempo real

Ver no GitHub
InicialPluginScore · de 0 a 100

Plataforma de auditoria de iluminação em instalações com cálculo automático de ROI para retrofit. Integra Gemini 3.5 Flash, MongoDB e um MCP server customizado para gerar recomendações de fixtures otimizadas energeticamente. O agente IA é capaz de realizar buscas web dinâmicas e expandir o catálogo de produtos automaticamente.

Instalação

$npx convez-ai vero-code/spatial-optician

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Análise de eficiência energética em edifícios comerciais
  • Cálculo de retorno de investimento para retrofit de iluminação
  • Seleção automática de fixtures de iluminação otimizadas
  • Catalogação dinâmica de produtos com extração de specs via IA

Veredito

MCP server bem arquitetado que combina análise de dados com agência de IA. A capacidade de auto-healing do catálogo (busca web dinâmica + inserção MongoDB) é um diferencial técnico legítimo, embora o foco principal seja analytics para decisões de retrofit. Ideal para gerentes de facilities que precisam de recomendações data-driven.

README

A tradução para o português deste README ainda está na fila.

Spatial Optician

MongoDB for Startups MongoDB React 19 FastAPI TypeScript Python Gemini

Spatial Optician is an intelligent analytical platform designed for performing energy-efficient facility lighting audits, calculating retrofitting Return on Investment (ROI), and conducting automated fixture selection. Supported by the MongoDB for Startups program, the system leverages high-performance cloud databases and a custom Model Context Protocol (MCP) gateway to deliver real-time, data-driven recommendations powered by an AI Agent (Gemini 3.5 Flash) integrated via Google ADK (Agent Development Kit).

The user interface is uniquely styled as an interactive engineering blueprint workspace, catering to facility managers and optics engineers alike.

🏛️ Project Architecture

A comprehensive breakdown of components, databases, data structures, and multi-agent interaction flows can be found in the: 👉 ARCHITECTURE.md

[!TIP] Key Showcase: Agentic Self-Healing Catalog Expansion If a requested lighting fixture is missing from the database, our Gemini agent dynamically triggers a live web search (via the GoogleSearchTool), extracts the precise engineering specifications, and uses the custom MCP insert_document tool to dynamically write the new fixture back into the MongoDB database, completing the ROI calculations on the fly!

🚀 Quick Start Guide

1. Database Configuration (MongoDB)

Ensure you have a running MongoDB database or provide your connection string using the MONGODB_URI environment variable inside your backend configuration.

2. Backend (FastAPI Server)

Navigate to the backend folder and run the following commands:

cd backend
# Synchronize environment and install dependencies
uv sync
# Start the development server
uv run fastapi dev main.py

Alternatively, launch using the PowerShell utility script:

.\run.ps1

3. Frontend (React + Vite)

Navigate to the frontend folder and launch the local development environment:

cd frontend
npm install
npm run dev

4. MongoDB MCP Server

If you need to run the Model Context Protocol database gateway locally:

cd mcp-mongo
npm install
npm run build
npm start

Note: In production, the backend is configured to connect to the deployed SSE MCP endpoint at https://spatial-optician-mcp-601334765015.europe-west1.run.app/sse.

🛠️ Technology Stack

  • Frontend: React 19, Vite, TypeScript, Tailwind CSS v4, Motion, Lucide Icons.
  • Backend: Python, FastAPI, PyMongo, Pydantic, Google ADK (Agent Development Kit).
  • MCP Server: Node.js, Express, TypeScript, Model Context Protocol SDK, MongoDB Driver.

🆕 Recent Updates

  • Backend Modularization & Refactoring: Reorganized the backend code from a monolithic main.py into a highly decoupled, modular structure:
    • config.py — Centralized environment variables (GEMINI_MODEL, MONGODB_URI, etc.).
    • prompts.py Isolated AI agent and Vision prompt constants.
    • schemas.py — Organized Pydantic request and response data models.
    • database.py — Managed MongoDB client setup.
    • agent.py — Constructed Google ADK agents and lifecycle hooks.
  • Dashboard Streamlining & Live MCP Controls: Removed the external floating chat window and replaced it with a dedicated "Optical Analysis Output" tabbed console directly in the dashboard's center console. Below this console, a new panel of live MCP actions was added to interact with MongoDB:
    • 🔍 Find Fixtures — Directs the Gemini agent to query the equipment_catalog collection in the database via MCP and recommend suitable fixture models based on the scan description.
    • ⚡ Calculate ROI — Triggers the agent to fetch electricity rates from energy_tariffs and calculate estimated power draw reduction, financial savings, and the exact payback period (ROI).
    • 💾 Save Audit — Invokes the insert_document MCP tool to save the new spatial audit findings into the audit_history collection, returning the resulting MongoDB insertion ID.
  • Dynamic Auditing & UI Polish (June 9, 2026):
    • Multi-Facility Profiling: Added dynamic space classification supporting warehouses (NY-HUD-01), residential spaces (NY-LIV-01), and commercial offices (NY-OFF-01) live via Gemini Vision.
    • Dynamic Parameter Estimation: Replaced hardcoded audit sizes. The AI agent dynamically calculates and saves the appropriate facility dimensions, ceiling heights, lux levels, and timestamps.
    • Zero Fallbacks: Removed silent fallback mocks from the API to guarantee live, authentic Gemini Vision diagnostics and explicit error reporting.
    • Polished Save Notification: Redesigned the MongoDB response panel with a blueprint-style border, real-time insertedId display, and an expandable [+] View System Report toggle that renders the AI's registration report in rich markdown.
Ver o original no GitHub

Bom para

Relacionados