Industrial IoT Monitoring

Unified, lightweight stack for:

• MCP gateway (FastAPI) exposing database-backed tools + a local LLM (llama.cpp via llama-cpp-python) in-process.
• Insight backend (FastAPI) providing anomaly scoring (LSTM-AE) and operator-facing explanations via MCP tools.
• MySQL for the sensor schema (with read-only LLM user provisioning).
• OPC UA simulator (optional) to produce streaming values.

System Architecture

graph TD
    Sim["Simulator<br/>(OPC UA)"] -->|Stream Data| Backend[Insight Backend]
    Backend -->|Store Metrics| DB[(MySQL)]
    Backend -->|Request Context| MCP[MCP Server]
    MCP -->|Query| DB
    MCP -->|Inference| LLM["LLM<br/>(llama.cpp)"]
    HMI[WebIQ HMI] -->|Visualize| Backend
    HMI -->|Ask Questions| MCP

Modules

This repository is organized into the following modules, each with its own documentation:

• Insight Backend: Main backend service for anomaly detection and explanations.
• MCP Server: Model Context Protocol server bridging the LLM with system data.
• Simulator: OPC UA production machine simulator for data generation.
• WebIQ LLM MCP: Integration components for the WebIQ HMI.
• Shared: Shared configuration and resources.

Reference & Guides

• Configuration: Environment variables and settings.
• Troubleshooting: Solutions for common issues.
• API Reference: API documentation for the Insight Backend.
• GPU Prerequisites: Requirements for GPU acceleration.
• ML Training & Dataset Generation: Instructions for generating historical data and training.

Quick Start

1. Prerequisite Checks

Ensure you have Docker and Docker Compose installed.

Windows Users: If you are unable to run .ps1 scripts, you may need to set the execution policy. Run the following command in PowerShell:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Configuration: Copy the example environment file:

cp .env.example .env

To enable GPU support, please refer to the GPU Prerequisites guide.

2. Bootstrap Data & Model

Option A: Smart Scripts (Recommended) Automatically generates data, trains the model (detecting GPU if available), and avoids orphan container warnings.

Linux/Mac/Git Bash:

./bootstrap.sh

Windows PowerShell:

./bootstrap.ps1

Option B: Manual Docker Compose Run manually if you prefer explicitly defining flags.

docker compose -f compose.bootstrap.yml up --build

For GPU training:

docker compose -f compose.bootstrap.yml -f compose.bootstrap.gpu.yml up --build

3. Start the Stack

Option A: Smart Scripts (Recommended) Automatically detects GPU and includes the simulator.

Linux/Mac:

./start.sh

Windows:

./start.ps1

Option B: Manual Docker Compose

docker compose -f compose.yml -f compose.sim.yml up -d --build

For GPU Inference support:

docker compose -f compose.yml -f compose.gpu.yml -f compose.sim.yml up -d --build

Local Development

To run components locally (without Docker) for development:

1. Python Environment: It is recommended to use a virtual environment.

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # Linux/Mac:
   source .venv/bin/activate
   

2. Install Dependencies:

   pip install -r requirements.txt
   # Or specific requirements for sub-modules
   pip install -r mcp-server/requirements.txt
   pip install -r insight-backend/requirements.txt
   

Development Tools & Verification

Verifying LLM Tool Use

You can verify the MCP server tools using curl:

• List tools:

  curl -s -X POST http://localhost:8090/mcp \
    -H 'Content-Type: application/json' -H 'MCP-Protocol-Version: 2025-06-18' \
    -d '{"jsonrpc":"2.0","id":"list-1","method":"tools/list"}'
  

Performance Profiles

The MCP server uses a unified performance profile system (cpu_only or gpu_accel) for llama.cpp inference. The system automatically detects available hardware.

See MCP Server Documentation for detailed configuration options.