FactoryLens MCP

FactoryLens is a Model Context Protocol (MCP) server for smart factory operations. It exposes machine telemetry, maintenance records, equipment manuals, and production schedules as structured MCP tools, resources, and prompts so AI assistants can run a full equipment failure investigation—from sensor anomaly detection through root cause analysis, business impact estimation, work order creation, and report generation—without switching between spreadsheets, log exports, and PDF manuals.

Built for the Factory MCP Hackathon on the NitroStack SDK.

The Problem

When a machine triggers a telemetry alert, plant operators typically pull data from several disconnected sources: CSV sensor exports, SQLite or ERP maintenance logs, plain-text or PDF manuals, and production scheduling spreadsheets. Each hop adds delay, and it is difficult to connect a temperature spike on the shop floor to a specific production line's revenue exposure.

FactoryLens consolidates that workflow behind a single MCP server. An AI client (Cursor, Claude Desktop, NitroStudio, or any MCP-compatible host) can chain seven investigation tools in sequence, read factory data through four resources, and use role-specific prompts to communicate findings to technicians and managers—all from the chat interface.

Related MCP server: Calculator MCP Server

Key Features

• Sensor anomaly analysis — Parses CSV telemetry (timestamp, temperature, vibration, current, voltage) and flags readings against configurable safety thresholds (65 °C, 2.5 mm/s, 4.0–5.5 A).

• Maintenance history lookup — Queries SQLite for repair logs by machine ID, ordered by date.

• Manual search — Full-text search across machine operating manuals with contextual line snippets (supports MCH-001 through MCH-005).

• Root cause synthesis — Combines sensor anomalies, maintenance history, manual excerpts, and live weather from Open-Meteo (factory coordinates: Kerala, India) into a diagnosis with confidence score, evidence, and recommendations.

• Business impact prediction — Estimates downtime hours, production loss in INR, and risk level from the production schedule and severity input.

• Work order management — Inserts maintenance tickets into SQLite and sets machine status to critical for high or emergency urgency.

• Investigation reports — Compiles a Markdown failure report returned in the tool response and saved to uploads/ when the filesystem is writable.

• Interactive widgets — Seven NitroStack widgets (Next.js) render tool output inside MCP ext-apps clients.

• Role-specific prompts — Pre-built prompts for field technicians, plant managers, and emergency shutdown advisories.

• Demo frontend — A standalone React console that walks through the MCH-004 conveyor failure scenario with charts and a NitroChat-style interface (uses simulated data, not the live MCP server).

Tech Stack

Architecture

Module layout

The server follows NitroStack's NestJS-style module pattern:

• AppModule — Root module; registers ConfigModule, FactoryModule, and SystemHealthCheck.

• FactoryModule — Feature module registering FactoryTools, FactoryResources, FactoryPrompts, and DatabaseService.

• DatabaseService — Injectable SQLite service that creates tables and seeds demo data on first run.

Investigation workflow

The intended MCP tool chain for a failure event:

1. analyze_sensor_data — Upload or read sensor CSV; detect threshold breaches.

2. get_maintenance_history — Pull recent repairs for the affected machine.

3. search_machine_manual — Find relevant manual sections (e.g. E101, overheating).

4. analyze_root_cause — Synthesize a diagnosis from the above inputs plus live weather.

5. predict_business_impact — Estimate downtime and revenue loss.

6. create_work_order — Log a maintenance ticket and update machine status.

7. generate_investigation_report — Produce a Markdown report for stakeholders.

The primary demo scenario centers on MCH-004 (Conveyor System, Packaging Line 1). Sample sensor data in database/sensor.csv shows rising temperature, vibration, and current that point to drive belt slippage—the same pattern the rule engine in analyze_root_cause is designed to detect.

Folder Structure

Factory-mcp-Hackathon/
├── src/                              # MCP server source (compiled to dist/)
│   ├── index.ts                      # Server bootstrap (McpApplicationFactory)
│   ├── app.module.ts                 # Root NitroStack module
│   ├── database/
│   │   └── db.ts                     # SQLite service, schema, and seed data
│   ├── health/
│   │   └── system.health.ts          # Memory and uptime health check
│   ├── modules/factory/
│   │   ├── factory.module.ts         # Factory feature module
│   │   ├── factory.tools.ts          # MCP tools (7)
│   │   ├── factory.resources.ts      # MCP resources (4)
│   │   └── factory.prompts.ts        # MCP prompts (3)
│   └── widgets/                      # NitroStack interactive widgets (Next.js)
│       ├── app/
│       │   ├── sensor-anomaly-dashboard/
│       │   ├── root-cause-investigation/
│       │   ├── maintenance-history/
│       │   ├── manual-search/
│       │   ├── business-impact/
│       │   ├── work-order/
│       │   └── investigation-report/
│       └── widget-manifest.json
├── frontend/                         # Standalone demo React app (simulated workflow)
│   └── src/App.tsx                   # FactoryLens investigation console
├── database/
│   ├── factory.db                    # SQLite database (auto-created on first run)
│   └── sensor.csv                    # Sample telemetry for MCH-004
├── resources/manuals/
│   ├── MCH-001-manual.txt            # CNC Milling Machine manual
│   ├── MCH-002-manual.txt            # Robotic Welder manual
│   ├── MCH-003-manual.txt            # Injection Molder manual
│   ├── MCH-004-manual.txt            # CS-400 conveyor maintenance manual
│   └── MCH-005-manual.txt            # Hydraulic Press manual
├── uploads/                          # Uploaded CSVs and generated reports
├── .env.example                      # Environment variable template
├── package.json                      # MCP server dependencies and scripts
├── tsconfig.json                     # TypeScript config (excludes src/widgets)
└── start-mcp.cmd                     # Windows production start helper

Prerequisites

• Node.js 18+ (22 recommended)

• npm 9+

• Network access for live weather lookups in analyze_root_cause (falls back to static values if Open-Meteo is unreachable)

Installation

1. Clone the repository

git clone https://github.com/janakir2006/Factory-mcp-Hackathon.git
cd Factory-mcp-Hackathon

2. Install MCP server dependencies

npm install

Or use the NitroStack installer to pull server and widget dependencies together:

npm run install:all

3. Configure environment

cp .env.example .env

Edit .env only if you need to change transport mode, port, or log level (see Environment Variables below).

4. (Optional) Frontend demo

cd frontend
npm install
cd ..

5. (Optional) Widgets

cd src/widgets
npm install
cd ../..

Running the Project

MCP server (development)

Starts the server over STDIO, which is the default for local MCP clients:

npm run dev

On first start, SQLite creates database/factory.db and seeds five machines (MCH-001 through MCH-005) with maintenance logs and production schedules.

MCP server (production)

Builds TypeScript to dist/ and starts with dual transport (STDIO + HTTP SSE):

npm run build
npm run start:prod

Alternatively:

npm start

This runs build then start:prod in one step.

On Windows, start-mcp.cmd wraps npm run start:prod (update the cd path inside the script to match your local checkout).

Frontend demo console

cd frontend
npm run dev

Open the URL Vite prints (typically http://localhost:5173). The frontend runs a simulated investigation flow for MCH-004 with hardcoded telemetry charts and mock tool outputs—it does not call the MCP server directly.

Widgets (for NitroStack / MCP ext-apps)

cd src/widgets
npm run dev

Widgets serve on port 3001. Each tool that declares a @Widget(...) decorator maps to a page under src/widgets/app/.

Testing with NitroStudio

NitroStudio is the recommended way to exercise tools, resources, prompts, and widgets during development.

Environment Variables

Copy .env.example to .env and adjust as needed:

No API keys are required for the core server. All factory data is local (SQLite + text files). Weather data is fetched from Open-Meteo without authentication.

MCP Server Reference

Server name: factory-mcp-server
Version: 1.0.0

Tools and tasks

Resources

Prompts

Sample data

On first run, SQLite is seeded with five machines, fifteen maintenance log entries, and five production schedules. Sample sensor telemetry lives at database/sensor.csv. Equipment manuals for all five machines are in resources/manuals/.

Connecting an MCP Client

Build the server first, then point your client at the compiled entry point.

Example Cursor MCP config (STDIO):

{
  "mcpServers": {
    "factory-lens": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/Factory-mcp-Hackathon"
    }
  }
}

For development, you can also use npm run dev via your client's preferred command wrapper.

For HTTP transport, set MCP_TRANSPORT_TYPE=http or dual and configure your client to connect to http://localhost:3000 (default port).

Future Improvements

• Live frontend ↔ MCP integration — Wire the React demo console to the MCP server over HTTP instead of mock data and setTimeout simulations.

• Real-time sensor ingestion — Stream telemetry from MQTT or OPC-UA instead of CSV uploads.

• LLM-driven root cause analysis — Replace the rule-based diagnosis in analyze_root_cause with model inference while keeping structured tool outputs.

• Multi-machine correlation — Detect failures that span production lines or shared utilities.

• Authentication and RBAC — Role-based access for operators, engineers, and managers.

• Dedicated work order schema — Separate pending work orders from completed maintenance history records.

• Alert webhooks — Notify Slack or Teams when anomalies or emergency work orders are created.

• Configurable thresholds — Move safety limits (65 °C, 2.5 mm/s, etc.) to environment variables or per-machine specs.

Team

Built for the Factory MCP Hackathon.

Repository: github.com/janakir2006/Factory-mcp-Hackathon

License

MIT License — see project footer in the frontend demo.

🚀 Live Deployment

🌐 NitroChat:
https://nitrochat-factory-metaminds-amrita-university-amritapuri-campus.app.nitrocloud.ai/

⚙️ MCP Server:
https://factory-mcp-6a5a6-metaminds-amrita-university-amritapuri-campus.app.nitrocloud.ai/

Related Links

• NitroStack Documentation

• NitroStudio — MCP testing and debugging

• Model Context Protocol

• Open-Meteo API — Weather data used in root cause analysis