Safetyops

AI-powered safety incident knowledge base — plug your industrial accident data into any AI assistant in hours, not months.

License: MIT Python 3.10+ MCP Protocol Azure AI Search

---

What is this?

A production-ready MCP (Model Context Protocol) server that turns your workplace incident database into a RAG-powered AI assistant — compatible with Copilot Studio, Claude, ChatGPT, and any MCP-compatible client.

Ask your AI agent:

• "What corrective actions should we take after a welding fire?" → structured IMMEDIATE / SHORT TERM / LONG TERM action plan with source citations
• "How many incidents occurred in the chemical industry last year?" → statistics with AI-generated insights
• "What are the main causes of falls at height?" → RAG answer with document references

No custom development needed for each AI client — one server, every AI tool.

---

Why this is different from Azure AI Search direct connector

Capability	Azure Search connector	SafetyOps MCP
Basic Q&A	✅	✅
Document search with filters	❌	✅ kb_search
Statistics & trends by category	❌	✅ kb_analyze
Prioritized corrective action plan	❌	✅ kb_suggest
Custom domain logic & prompts	❌	✅
Works with Claude, ChatGPT, custom agents	❌	✅
Deployable for any client's private data	❌	✅

---

4 MCP Tools

Tool	Trigger	What it does
kb_search	"find incidents about...", "list accidents where..."	Hybrid search (BM25 + vector) with OData filters. Returns ranked documents with metadata.
kb_converse	"why...", "how...", "what causes..."	RAG Q&A — retrieves relevant incidents and generates an answer with [Document X] citations.
kb_analyze	"how many...", "statistics", "breakdown by..."	Faceted aggregations by severity / hazard type / industry. Returns counts, percentages, AI insights.
kb_suggest	"what should we do?", "corrective actions", "after this incident..."	Finds similar past incidents and generates a prioritized action plan: 🚨 IMMEDIATE (24h) / ⚠️ SHORT TERM (1 week) / 📋 LONG TERM — with source citations.

---

Architecture

┌─────────────────────────────────────────────────────────┐
│               AI Client Layer                           │
│   Copilot Studio │ Claude Desktop │ ChatGPT │ Custom    │
└────────────────────────┬────────────────────────────────┘
                         │  JSON-RPC 2.0 (MCP protocol)
                         ▼
┌─────────────────────────────────────────────────────────┐
│            SafetyOps MCP Server (FastAPI)               │
│                                                         │
│  POST /mcp  ──►  ApiKeyMiddleware                       │
│                       │                                 │
│               ToolRegistry.call()                       │
│          ┌────────────┼────────────┐──────────┐         │
│       kb_search  kb_converse  kb_analyze  kb_suggest    │
└──────────────┬──────────────────────┬───────────────────┘
               │                      │
               ▼                      ▼
    Azure AI Search            Azure OpenAI
    (hybrid retrieval)        (gpt-4o-mini)
    279+ incidents             RAG generation

---

Quick Start

1. Clone & install

git clone https://github.com/<your-username>/safetyops-mcp-server.git
cd safetyops-mcp-server
pip install -e ".[dev]"

2. Configure Azure credentials

cp .env.example .env

Edit .env:

# Azure AI Search
AZURE_SEARCH_ENDPOINT=https://<your-service>.search.windows.net
AZURE_SEARCH_INDEX=safetyops-kb-v2
AZURE_SEARCH_API_KEY=<your-search-admin-key>

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-4o-mini
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-large
AZURE_OPENAI_API_KEY=<your-openai-key>

# MCP Server Auth
MCP_API_KEYS=your-secret-key-here

3. Start the server

python -m uvicorn safetyops_mcp.app.main:app --port 8001 --reload

4. Test it

# Health check
curl http://localhost:8001/health

# List available tools
curl -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key-here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Ask for corrective actions
curl -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key-here" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "kb_suggest",
      "arguments": {
        "incident_description": "A worker was burned during welding operations",
        "language": "en"
      }
    }
  }'

---

Connect to Copilot Studio

Connect your Microsoft 365 AI assistant to real incident data in 5 minutes.

1. Open your agent in Copilot Studio
2. Go to Actions / Extensions → Model Context Protocol (MCP)
3. Click Add existing MCP server
4. Set the server URL:
   • Local (with Cloudflare Tunnel): https://<your-tunnel>.trycloudflare.com/mcp
   • Production (Azure Web App): https://<your-app>.azurewebsites.net/mcp
5. Authentication:
   • Type: API key
   • Header name: X-API-Key
   • Value: your MCP_API_KEYS value
6. Save → the 4 tools appear automatically

See docs/copilot-studio.md for detailed setup.

---

Connect to Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "safetyops": {
      "url": "https://<your-app>.azurewebsites.net/mcp",
      "headers": { "X-API-Key": "<your-key>" }
    }
  }
}

---

Deploy to Production (Azure Web App)

# Production server
gunicorn -c gunicorn.conf.py safetyops_mcp.app.main:app

See docs/azure-deployment.md for full Azure App Service setup.

Never commit .env. Use Azure Key Vault in production.

---

Fully Adaptable to Your Business Needs

The 4 built-in tools are a starting point, not a ceiling. Every layer is designed to be modified or extended without touching the MCP core.

Adapt the existing tools

Each tool has two levers you can tune for your specific context:

1. Output format — change how results are presented to match your organization's language and standards:

Tool	Default output	Example adaptation
kb_suggest	IMMEDIATE / SHORT TERM / LONG TERM	→ PDCA cycle (Plan / Do / Check / Act) for ISO 45001 clients
kb_converse	Free-form answer with [Document X] citations	→ Structured report: Context / Root Cause / Recommendation
kb_analyze	Statistics + AI paragraph	→ Executive summary table ready for board presentations
kb_search	Ranked document list	→ Filtered by user role (manager sees aggregates, operator sees full details)

2. Content & domain logic — the system prompts encode your domain expertise:

The HSE system prompt in kb_suggest was designed for industrial safety. Swap it for a pharma, nuclear, or maritime prompt and the tool becomes a domain expert in that field — no code change required.

---

Add custom tools for your business case

The tool registry accepts any new tool in minutes. Examples of tools built for specific clients:

kb_report     → Auto-generate a formatted incident report (Word/PDF) from a description
kb_compare    → Compare two incidents side by side and identify common root causes
kb_deadline   → Track corrective action deadlines and flag overdue items
kb_escalate   → Score incident severity and route to the right team automatically
kb_translate  → Deliver the action plan in the local language of the site

Adding a tool = one Python file + register it in registry.py. The AI client discovers it automatically via tools/list — no client-side changes needed.

---

What this means for your deployment

When we deploy for your organization, the tools are configured for your workflows, your terminology, and your output formats — not a generic template. The architecture makes this fast: customization is configuration, not reengineering.

---

safetyops_mcp/
├── app/
│   ├── main.py              # FastAPI entry point + /health
│   ├── auth.py              # API key middleware
│   ├── mcp_router.py        # JSON-RPC 2.0 dispatch (/mcp)
│   └── settings.py          # Pydantic settings
└── mcp/
    ├── jsonrpc.py            # JSON-RPC 2.0 models
    ├── registry.py           # Tool registration + dispatch
    └── tools/
        ├── _openai_client.py # Shared Azure OpenAI factory
        ├── kb_search.py      # Hybrid search tool
        ├── kb_converse.py    # RAG Q&A tool
        ├── kb_analyze.py     # Statistical analysis tool
        └── kb_suggest.py     # Corrective action plan tool

data/
└── accidents.csv             # Source dataset (China industrial accidents)

scripts/
├── normalize_china_data.py   # Data normalization pipeline
└── pipeline_blob_to_search.py # Azure Search indexing pipeline

docs/
├── azure-setup.md
├── azure-deployment.md
├── copilot-studio.md
└── runbook.md

---

Adapt to Your Own Data

This template is designed to be deployed for any incident knowledge base:

1. Replace data/accidents.csv with your incident dataset
2. Adjust the field mapping in scripts/normalize_china_data.py
3. Re-run the indexing pipeline
4. The 4 MCP tools work immediately with your data — no code changes

Supported data sources: CSV, JSON, SQL export, SharePoint lists.

See docs/azure-setup.md for the indexing guide.

---

Use Cases & Industries

Industry	Data source	Key tool
Manufacturing / HSE	OSHA API, internal SIRH	kb_suggest — corrective action plans
Nuclear	IRSN, NRC event reports	kb_converse — regulatory Q&A
Maritime	EMSA, MAIB accident reports	kb_search — incident lookup
Pharmaceutical	FDA Warning Letters	kb_analyze — trend analysis
Mining	MSHA USA database	kb_suggest + kb_analyze

---

Tech Stack

Layer	Technology
MCP Server	FastAPI + Uvicorn (Python 3.10+)
Knowledge Base	Azure AI Search (hybrid BM25 + vector)
LLM	Azure OpenAI gpt-4o-mini
Embeddings	text-embedding-3-large
AI Client	Copilot Studio, Claude Desktop, ChatGPT
Public Exposure	Cloudflare Tunnel (dev) / Azure Web App (prod)
Demo UI	Streamlit

---

License

MIT — see LICENSE.

---

Built with the MCP open standard — works with every AI client today and tomorrow.