Virtual Engineer

AI-assisted troubleshooting for field engineers — a runnable demo that shows how an LLM agent grounded in MongoDB Atlas can surface expert-level diagnostic guidance without Level 2 escalation.

When an engineer describes a symptom, the system automatically surfaces the unit's current alarm state, recent operational telemetry, and prior repair history to identify the most likely root cause and recommended next steps. Two audience-specific interfaces are included: a structured evidence view for technical staff and a conversational interface for field teams.

Context

Commercial HVAC equipment generates a constant stream of alarms, telemetry, and work-order data that is rarely connected at the point of diagnosis. A field engineer on-site typically has access to an alarm code and a gut feeling — not the 8-month prior service record, the rising motor temperature trend that preceded the fault, or the knowledge article that recommends PTC sensor inspection before compressor replacement.

Virtual Engineer closes that gap. It is designed to demonstrate MongoDB Atlas as the operational backbone for an agentic field-service AI: deterministic lookups for factual grounding, hybrid semantic search for knowledge and case retrieval, time-series telemetry for trend analysis, and a session/feedback layer for continuous improvement.

Related MCP server: Florentine.ai MCP Server

Architecture

Browser (React + Vite)
    │  SSE /api/chat
    ▼
Express Server  ──► LLM Agent (OpenAI / Anthropic / Grove)
    │                   │  tool calls
    │               MCP HTTP client
    │                   │
    ▼                   ▼
MCP Server (20 tools)
    │
    ▼
MongoDB Atlas
    ├── Atlas Database       chillers, sites, alarms, telemetry, service tickets
    ├── Atlas Vector Search  semantic search on knowledge_documents + service_tickets
    ├── Atlas Text Search    lexical search for $rankFusion hybrid queries
    ├── Native Reranking     Voyage $rerank after hybrid candidate generation
    └── Time Series          7-day hourly telemetry per chiller

Two-layer retrieval strategy

The agent always resolves asset and operational facts first (deterministic), then expands into knowledge and case retrieval (probabilistic). Tool sequences are chosen dynamically by the LLM — nothing is scripted.

Atlas services used

• Atlas Database — operational collections

• Atlas Vector Search — autoEmbed on knowledge_documents.content and service_tickets.case_notes

• Atlas Text Search — lexical index for $rankFusion hybrid search

• Atlas Hybrid Search ($rankFusion) — Reciprocal Rank Fusion combining vector + lexical results natively (requires MongoDB 8.1+ or 8.0 with a support-case feature flag)

• Native Reranking ($rerank) — Voyage cross-encoder rerank in the same aggregation after $rankFusion (MongoDB 8.3+, project toggle; Preview). Default model: rerank-2.5-lite. See Enable Native Reranking below.

• Time Series collection — telemetry, with timeField: timestamp, metaField: chiller_id, granularity: minutes

MCP server

Built on @modelcontextprotocol/sdk with Streamable HTTP transport. The server exposes 20 tools across five categories:

Every tool response includes a query_insight object (access pattern, collection, pipeline summary) that the UI surfaces in real time.

LLM agent

Stateless tool-use loop configured via AGENT_MAX_STEPS (default: 12). Supports four providers:

Demo UI

Single-page React app (Vite) with three tabs, all sharing a single ChatContext SSE stream:

• Overview — architecture diagram, Atlas service inventory, scenario picker with starter prompts

• Evidence Board — technical view: structured evidence cards, agent flow timeline, query inspector (shows MongoDB access patterns as each tool fires)

• Field Chat — conversational interface with X-ray mode to expose tool calls inline

Demo scenarios

Hero demo sequence (CH-ATL-003)

1. Open the Overview tab, select CH-ATL-003, and click a starter prompt.

2. Switch to Evidence Board — watch the agent flow timeline populate as tools fire in sequence: asset lookup → active alarms → telemetry trend → service history → knowledge search → case search.

3. Switch to Field Chat and run the same prompt for the conversational framing.

4. Use the thumbs-up/thumbs-down reaction to capture engineer feedback.

Getting started

Prerequisites

• Node.js 18+

• MongoDB Atlas cluster on 8.3+ for Voyage $rerank (choose Latest version with auto-upgrades in Cluster Builder). $rankFusion hybrid search works on 8.1+ (or 8.0 with a support-case flag); deterministic tools work on earlier versions.

• M10+ recommended for CLI index management (npm run indexes:create); M0 can run the demo if you create the four search indexes in the Atlas UI

• LLM API key — one of OPENAI_API_KEY, ANTHROPIC_API_KEY, or MDB_GROVE_API_KEY

1. Clone and install

git clone <repo-url>
cd virtual-engineer
npm install
cd frontend && npm install && cd ..

2. Configure environment

cp .env.example .env

Edit .env:

# Atlas
MONGODB_URI=mongodb+srv://<user>:<pass>@<cluster>.mongodb.net/
MONGODB_DB=virtual_engineer

# LLM — pick one provider
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

# Local dev
MCP_AUTH_DISABLED=true
MCP_PORT=3100
CORS_ORIGIN=http://localhost:5173

See the full environment variable reference in docs/runbook.md.

3. Seed sample data

npm run seed:drop

This regenerates 7-day hourly telemetry, creates the time-series collection, and inserts all sample documents.

4. Create Atlas search indexes

npm run indexes:check    # reports READY / BUILDING / MISSING
npm run indexes:create   # creates missing indexes and polls until READY

Four indexes are required for hybrid search to work without degraded: true responses: vector + lexical on both knowledge_documents and service_tickets. See docs/indexes.md for manual index definitions.

Note: $rankFusion hybrid search requires MongoDB 8.1+ (or 8.0 with a support-case feature flag). On earlier versions, knowledge and case search tools return empty results with degraded: true — all deterministic tools continue to work.

5. Enable Native Reranking ($rerank)

Knowledge and case search append Voyage $rerank after $rankFusion in the same aggregation. No extra search indexes and no Voyage API key — usage is billed through Atlas (Preview).

Do this once per Atlas project before expecting non-degraded reranked results:

1. Confirm the cluster is MongoDB 8.3+ (Atlas UI → cluster → version, or create/upgrade with Latest version with auto-upgrades). $rerank is not available on 8.1/8.2 even if $rankFusion works.

2. As Project Owner, open Project Settings and set Native Reranking: $rerank in the Aggregation Pipeline to On. Confirm the Voyage model usage / billing dialog.

3. Leave the defaults in .env (or omit them): RERANK_ENABLED=true, RERANK_MODEL=rerank-2.5-lite, RERANK_CANDIDATES=20.

$rerank is not supported on Atlas Local or self-managed mongod. It cannot sit inside $rankFusion input pipelines — this demo runs it after fusion.

If the toggle is off or the cluster is below 8.3, search retries $rankFusion only and returns degraded: true with fusion order. Set RERANK_ENABLED=false to skip $rerank on purpose. Full pipeline notes: docs/indexes.md.

6. Start the backend

npm run mcp:dev

Server starts on http://localhost:3100. Verify with:

curl http://localhost:3100/health

7. Start the demo UI

cd frontend && npm run dev

Open http://localhost:5173. The Vite dev server proxies /api to the backend automatically.

8. Run connectivity tests

npm run test:connectivity   # requires backend running on :3100

API endpoints

Data freshness

Sample data uses Date.now()-relative windows for alarms and telemetry. Re-run npm run seed:drop any time to reset to a fresh baseline anchored to the current hour.

For continuous automated freshness without manual steps, deploy the Atlas Scheduled Trigger at scripts/data/atlas-trigger/refresh-demo-data.js — it fires daily at 02:00 UTC and rolls alarm timestamps and telemetry forward. See docs/data-freshness.md for setup instructions.

Repository layout