Alarm Investigation and Procedure Guidance Copilot

This repository implements an evidence-backed alarm investigation workflow using:

• a FastAPI-based Alarm Management API simulator

• a candidate-developed MCP server exposing alarm operations as typed tools

• a Streamlit GUI that discovers and invokes MCP tools

• a document RAG workflow over alarm procedures and troubleshooting guides

Main capabilities

• Natural-language alarm investigation requests

• MCP tool discovery and invocation for asset search, metadata lookup, alarm retrieval, summaries, priority scoring, and recommendations

• RAG-backed evidence using operating procedures and maintenance documents

• Tool trace and raw response inspection in the UI

Related MCP server: OpsLens AI MCP Server

Technology stack

• Python 3.11+

• FastAPI

• Streamlit

• scikit-learn for TF-IDF retrieval

• pytest

MCP server

The MCP server is implemented under apps/mcp_server and exposes the following tools:

• asset_search

• asset_metadata

• alarm_retrieval

• alarm_summary

• priority_score

• operator_recommendations

Start the MCP server independently:

uvicorn apps.mcp_server.main:app --host 0.0.0.0 --port 9000

Alarm API backend

Start the backend simulator:

uvicorn apps.backend.main:app --host 0.0.0.0 --port 8000

Streamlit UI

Start the GUI:

streamlit run apps/frontend/app.py

RAG workflow

Documents are stored under rag/documents and ingested through the existing TF-IDF index in apps/backend/rag.py.

Tests

python -m pytest -q

Configuration

Copy .env.example and adjust values as needed.

Architecture summary

See docs/architecture.md and docs/architecture-diagram.svg.