SafetyOps MCP Server
by ANASSIJASSI
README.md
# SafetyOps MCP Server
> **AI-powered safety incident knowledge base** — plug your industrial accident data into any AI assistant in hours, not months.
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://azure.microsoft.com/en-us/products/ai-services/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
```bash
git clone https://github.com/<your-username>/safetyops-mcp-server.git
cd safetyops-mcp-server
pip install -e ".[dev]"
```
### 2. Configure Azure credentials
```bash
cp .env.example .env
```
Edit `.env`:
```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
```bash
python -m uvicorn safetyops_mcp.app.main:app --port 8001 --reload
```
### 4. Test it
```bash
# 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](docs/copilot-studio.md) for detailed setup.
---
## Connect to Claude Desktop
Add to `~/.claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"safetyops": {
"url": "https://<your-app>.azurewebsites.net/mcp",
"headers": { "X-API-Key": "<your-key>" }
}
}
}
```
---
## Deploy to Production (Azure Web App)
```bash
# Production server
gunicorn -c gunicorn.conf.py safetyops_mcp.app.main:app
```
See [docs/azure-deployment.md](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](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](LICENSE).
---
*Built with the MCP open standard — works with every AI client today and tomorrow.*
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues