# Factory Supervisor MCP Server

[![NitroStack](https://img.shields.io/badge/Framework-NitroStack-blue)](https://nitrostack.ai)
[![Protocol](https://img.shields.io/badge/Protocol-ModelContextProtocol--v1.0-green)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/Language-TypeScript-3178C6)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/Frontend-React%20%2B%20Vite-61DAFB)](https://react.dev/)

An enterprise-grade Model Context Protocol (MCP) server and interactive supervisory dashboard built with NitroStack, Node.js, Express, and React for real-time factory operations management, telemetry analysis, predictive maintenance, material forecasting, order estimation, and AI supervisor copilot capabilities.

---

## Overview

The Factory Supervisor MCP Server connects AI assistants (such as Claude Desktop, Cursor, Antigravity, or custom MCP clients) directly to industrial shop floor telemetry, equipment diagnostics, inventory levels, maintenance schedules, and production orders.

Featuring 10 modular domains and 18 specialized MCP tools alongside an Express REST API and a React + Tailwind Control Center UI, operators and AI assistants can perform diagnostic checks, detect bottlenecks, forecast equipment failures, calculate risk exposure, and interact via natural language to maintain optimal factory productivity.

---

## Key Features

- **Dual Architecture** -- Serves as a standard Model Context Protocol (MCP) server over Stdio transport as well as a full Express REST API and Web Control Center UI.
- **Real-Time Analytics and Scoring** -- Automated numeric health scoring (0-100), machine severity assessment, inventory stockout warnings, and risk exposure calculations.
- **Predictive Machine Intelligence** -- Risk models for failure prediction, material depletion forecasting, bottleneck detection, and order completion estimation.
- **AI Supervisor Copilot** -- Natural language prompt routing, daily supervisor shift briefings, and executive financial summaries.
- **Web Control Center UI** -- Built with Vite, React 18, TailwindCSS, Lucide icons, and Framer Motion for telemetry visualization and AI interaction.

---

## Modules and Tools Reference

| Module | MCP Tool Name | Description | Key Inputs |
| :--- | :--- | :--- | :--- |
| **Health** | `ping` | System diagnostic health check ping. | None |
| **Machines** | `listMachines` | List all factory machines and operational state. | None |
| | `getMachineStatus` | Get detailed telemetry and job info for a specific machine. | `machineId` (string) |
| **Inventory** | `getInventory` | Get current stock levels for all parts and reorder points. | None |
| | `getLowStockItems` | Retrieve inventory items at or below reorder threshold. | None |
| **Orders** | `getOrders` | Retrieve active factory production orders and progress. | None |
| **Maintenance** | `getMaintenanceLogs` | Retrieve historical and active maintenance logs. | None |
| **Schedule** | `getProductionSchedule` | Fetch master production schedule and operational windows. | None |
| **KPI** | `getFactoryKPIs` | Retrieve key operational performance indicators (OEE, Uptime, Quality). | None |
| **Analytics** | `analyzeFactory` | Consolidated factory report with health score, severity levels, risk assessment, and recommendations. | None |
| **Prediction** | `predictMachineFailure` | Predict failure probability, time window, and recommended actions based on vibration and temperature telemetry. | `machineId` (string) |
| | `forecastInventory` | Predict stockout dates, days remaining, and recommended reorder quantities. | `partId` (optional string) |
| | `estimateOrderCompletion` | Estimate completion time, delay risk, and confidence score for an order. | `orderId` (string) |
| | `detectProductionBottlenecks` | Identify capacity, downtime, and material starvation bottlenecks across all domains. | None |
| | `predictFactoryHealth` | Forecast overall factory health score trends (Today vs. Tomorrow). | None |
| **Assistant** | `factoryCopilot` | AI Supervisor assistant routing natural language questions to appropriate analytics and predictive tools. | `question` (string) |
| | `dailySupervisorBrief` | Concise daily shift briefing highlighting top risks and priority actions. | None |
| | `executiveSummary` | High-level executive performance summary, financial risk exposure, and strategic guidance. | None |

---

## Project Architecture

```
factory-supervisor-mcp/
├── src/
│   ├── index.ts                     Entry point and Express REST API
│   ├── app.module.ts                Root AppModule importing 10 feature modules
│   ├── ai/                          LLM Provider and MCP Client Integration
│   ├── mock/                        Mock telemetry data JSON files
│   └── modules/                     10 MCP Feature Modules
│       ├── analytics/               Consolidated factory analysis
│       ├── assistant/               Copilot, shift brief and executive tools
│       ├── health/                  System ping and health checks
│       ├── inventory/               Stock levels and low-stock detection
│       ├── kpi/                     OEE, Uptime and Quality metrics
│       ├── machines/                Telemetry and status tools
│       ├── maintenance/             Maintenance history and logs
│       ├── orders/                  Work orders and progress tracking
│       ├── prediction/              Prediction tools
│       └── schedule/                Production schedule data
├── ui/                              Web Control Center (React + Vite + Tailwind)
│   ├── src/                         Dashboard components, APIs, and state
│   └── index.html                   UI entry point
├── package.json                     Scripts and dependencies
├── run.bat                          Batch launcher for Backend + Frontend
├── run-server.bat                   Batch launcher for MCP Server
└── README.md
```

---

## Quick Start

**Prerequisites** -- Node.js v18+ and npm v9+.

Clone the repository and install dependencies:
```bash
git clone https://github.com/Heytish-V/factory-supervisor-mcp.git
cd factory-supervisor-mcp
npm install
```

Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

Optionally configure your OpenAI API key in `.env` for LLM Copilot capabilities:
```env
OPENAI_API_KEY=your_openai_api_key_here
REST_PORT=3001
```

**One-Click Launcher (Windows)** -- Run `run.bat` to build the project, launch the backend on port 3001, start the frontend on port 5173, and open the browser automatically.
```cmd
run.bat
```

**Development Mode** -- Start the backend and frontend separately:
```bash
npm run dev          # Terminal 1: Backend MCP server
npm run ui:dev       # Terminal 2: Frontend dashboard
```

**Production Build** -- Compile TypeScript, sync mock data, and build UI assets:
```bash
npm run build
npm start
```

---

## REST API Endpoints

When running the Express REST API (port 3001 by default), the following endpoints are available:

- `GET /health` -- Diagnostic health check.
- `POST /chat` -- Natural language interaction with the Factory Supervisor AI Copilot.
- `GET /api/tools/:toolName` or `POST /api/tools/:toolName` -- Direct execution of any of the 18 MCP tools.

---

## MCP Client Integration

Add this MCP server to your MCP client configuration (such as Claude Desktop, Cursor, or Antigravity):

```json
{
  "mcpServers": {
    "factory-supervisor": {
      "command": "node",
      "args": ["C:/projecctttt/factory-supervisor-mcp/dist/index.js"]
    }
  }
}
```

---

## Example Prompts

When interacting through the web UI or an MCP client, try these sample queries:

- "What is the overall health score of the factory right now?"
- "Are any CNC machines at risk of failing in the next 24 hours?"
- "Which inventory items are currently below reorder thresholds?"
- "Will order ORD-2026-001 complete on time or experience delays?"
- "Generate a daily supervisor shift briefing for the current shift."
- "Provide an executive summary of factory performance and financial risk exposure."

---

## License

Private / Enterprise Proprietary