⚙️ Maintenance & Work-Order Intelligence Copilot

An enterprise-grade, AI-driven Maintenance and Work-Order Intelligence Copilot built for platform architecture.

This copilot empowers reliability engineers and plant operators to investigate recurring alarm storms, query structured CMMS work orders, and extract grounded troubleshooting procedures from technical manuals through a unified natural-language interface.

---

• Architecture Overview:

flowchart TD
    subgraph PRESENTATION["Presentation Layer"]
        GUI["Streamlit Web GUI<br/>• Interactive Chat Panel<br/>• Alarm & Work Order Tables<br/>• Document Citations<br/>• MCP Execution Trace Timeline"]
    end

    subgraph COPILOT["Copilot Orchestration Layer"]
        ORCH["LangGraph Copilot Orchestrator<br/>(Query Decomposition & Agent Logic)"]
        CLIENT["MCP Client Manager<br/>• Tool Discovery & Validation<br/>• Trace Propagation (X-Trace-ID)<br/>• Error & Timeout Handling"]
        RAG_ENG["Document RAG Engine<br/>• Vector Search & Grounding<br/>• Prompt Injection Guardrails<br/>• Citation Metadata Formatter"]
    end

    subgraph MCP_LAYER["Standardized Protocol Layer"]
        SERVER["FastMCP Server<br/>(Alarm-CMMS-MCP)<br/>Port: 9000"]
    end

    subgraph DATA_SOURCES["Data Sources & Core Backend"]
        SIMULATOR["Alarm API Simulator<br/>(FastAPI - Postman Spec Compliant)<br/>Port: 8000"]
        CMMS["CMMS Work-Order DB<br/>(SQLite Database)"]
        VECTOR_DB[("ChromaDB Vector Store<br/>(Equipment Manuals & SOPs)")]
    end

    GUI -->|HTTP / REST| ORCH
    ORCH --> CLIENT
    ORCH --> RAG_ENG

    CLIENT -->|JSON-RPC| SERVER
    RAG_ENG -->|Semantic Vector Search| VECTOR_DB

    SERVER -->|HTTP REST APIs| SIMULATOR
    SERVER -->|SQL Queries| CMMS

🎯 Selected Use Case

Maintenance and Work-Order Intelligence Copilot

🎯 Selected Use Case

Maintenance and Work-Order Intelligence Copilot

• Business Scenario: Industrial reliability teams need to combine telemetry alarm behavior, CMMS maintenance history, and equipment manuals to identify assets requiring immediate intervention.
• Core Value: Reconciles structured alarm and CMMS data with unstructured operating manuals using canonical asset identifiers (BFP-101), eliminating manual cross-referencing during alarm floods.

---

✨ Main Capabilities

1. Natural-Language Query Understanding: Decomposes complex plant queries into structured intent and multi-step tool execution plans.
2. Standardized Model Context Protocol (MCP) Integration: Exposes Alarm Management APIs and CMMS databases as standardized, typed tools using FastMCP.
3. Document RAG with Security Guardrails: Vector search over equipment manuals using ChromaDB and SentenceTransformers, equipped with prompt-injection defenses and strict similarity thresholds.
4. End-to-End Traceability & Observability: Live execution timeline showing tool invocations, inputs, trace headers (X-Trace-ID), and document confidence scores directly in the UI.
5. Zero-Cost Offline Execution: Includes an offline rule-based mock engine that allows running all automated tests and UI demos without requiring paid external LLM API keys.

---

🛠️ Technology Stack

Component	Technology
User Interface	Streamlit
Copilot Orchestration	LangGraph / Python Async Engine
MCP Server & Client	FastMCP / Model Context Protocol SDK
Backend & Simulator	FastAPI, Uvicorn, SQLite
Vector Store & Embeddings	ChromaDB, sentence-transformers/all-MiniLM-L6-v2
Testing & Quality	PyTest, PyTest-Asyncio, Ruff
Packaging & CI	Docker, Docker Compose, GitHub Actions

---

🔌 MCP Server Description & Tool Catalog

The candidate-developed MCP server exposes backend source-system capabilities over standard JSON-RPC interface contracts.

Registered MCP Tools

Tool Name	Description	Source System Operation
search_assets	Resolves asset names/keywords into canonical Asset IDs	GET /assets/search
get_alarms	Fetches active or historical alarm events for an asset	GET /alarms
get_alarm_summary	Calculates aggregated KPIs, recurring rates, and trends	POST /alarms/summary
get_alarm_correlation	Advanced Operation: Performs cross-asset event correlation	POST /alarms/correlation
get_cmms_work_orders	Queries structured maintenance work orders and costs	GET /api/v1/cmms/work_orders

For complete input/output JSON schemas, trace header propagation details, and error mapping, see docs/mcp-tool-catalog.md.

Independent MCP Server Launch Command

$env:PYTHONPATH="."
python -m mcp_servers.alarm_management.server