# LineSight

**An MCP server that turns plant-floor data into continuous-improvement insight.**

LineSight gives an AI assistant the same toolkit a CI engineer carries onto the
shop floor — OEE math, downtime Pareto analysis, SPC control charts, and
yield-loss dollars — exposed through Anthropic's
[Model Context Protocol](https://modelcontextprotocol.io). Ask it *"why is
line-3 slowing down?"* and it doesn't guess: it pulls the control chart, finds
the Western Electric violations, checks the downtime log, and answers with
evidence.

Built by a CI/OE practitioner ([marcoaguzmanjr.com](https://www.marcoaguzmanjr.com))
to bring the DMAIC discipline of the factory floor to AI tooling: every number
the model reports traces back to a formula in
[plant/analytics.py](plant/analytics.py).

---

## What you can ask it

```
> /daily_huddle line-1          # 3-minute tier-1 meeting brief, built from live data
> /dmaic line-2                 # full Define-Measure-Analyze-Improve-Control investigation
> /a3_report line-3             # one-page A3 problem-solving report
> why is @line-3 slowing down?  # @-mention a line to inject its KPI snapshot
> which shift on line-2 has the quality problem, and what is it costing us per year?
```

The kind of exchange this produces (every number below is what the tools
actually return on the demo dataset):

> **You:** which shift on line-2 has the quality problem?
>
> **Claude:** *(calls `get_oee` with `line_id=line-2, group_by=shift`)*
> Shift C. Its quality rate is 96.8% vs ~98.8% on shifts A and B — roughly
> 3× the scrap. *(calls `get_yield_loss`)* At standard cost that's about
> **$480K annualized** across the line, with shift C driving the majority.
> Worth checking what's different on C: staffing, changeover timing, or
> equipment settings that drift outside day-shift support hours.

## The three MCP primitives, applied

| Primitive | What LineSight exposes |
|---|---|
| **Tools** (model-controlled) | `get_oee` · `pareto_downtime` · `spc_analysis` · `get_yield_loss` · `log_action` · `list_actions` · `close_action` |
| **Resources** (app-controlled) | `plant://overview` · `plant://lines` · `plant://lines/{id}` KPI snapshots · `plant://reason-codes` |
| **Prompts** (user-controlled) | `/daily_huddle` · `/dmaic` · `/a3_report` |

The split matters: analysis lives in **tools** so the model can chain them
freely; context the *user* chooses to bring in (an @-mentioned line) comes from
**resources**; and multi-step CI rituals with a defined shape (a DMAIC, an A3)
ship as **prompts** so they run the same way every time.

```mermaid
flowchart LR
    U[You] --> CLI[Chat CLI<br/>prompt-toolkit]
    CLI --> C[Claude<br/>Anthropic API]
    C <-->|MCP stdio| S[LineSight MCP server<br/>FastMCP]
    S --> A[analytics.py<br/>OEE · Pareto · SPC · yield $]
    A --> D[(production_log.csv<br/>downtime_log.csv)]
    S --> R[(action_register.json)]
```

## The demo dataset tells a story

`data/` holds 90 days of seeded, reproducible shift-level records for a
three-line condiment plant (810 production records, ~2,300 downtime events).
Three problems are hidden in it — the same patterns you'd hunt for in a real
plant:

1. **line-2 bleeds availability to changeovers** — one reason code carries
   ~52% of all downtime minutes. A Pareto finds it instantly.
2. **line-2, shift C has a quality problem** — scrap runs ~3× the other
   shifts (cap-seal torque drift). Invisible in the line-level average;
   obvious the moment you group by shift.
3. **line-3 is degrading, not broken** — filler-head bearing wear drags
   performance down over the final three weeks. No single bad day; the SPC
   chart catches the run below center line and the cascade of below-LCL
   points that a "top losses yesterday" report would miss.

Regenerate identical data anytime: `python -m plant.data_gen` (seeded).

## Quick start

Requires Python 3.10+ and an [Anthropic API key](https://console.anthropic.com).

```bash
git clone https://github.com/marcoaguzman/linesight.git && cd linesight
python3 -m venv .venv && source .venv/bin/activate
pip install "anthropic>=0.51.0" "mcp[cli]>=1.8.0" "prompt-toolkit>=3.0.51" "python-dotenv>=1.1.0"
cp .env.example .env      # then add your ANTHROPIC_API_KEY
python main.py
```

Or with [uv](https://docs.astral.sh/uv/): `uv sync`, set `USE_UV=1` in `.env`,
then `uv run main.py`.

### Verify without an API key

The smoke test drives every tool, resource, and prompt over a real MCP stdio
connection — no Anthropic key needed:

```bash
python scripts/smoke_test.py     # 18 checks, should all PASS
```

### Use it from Claude Desktop instead

LineSight is a standard MCP server, so any MCP client can host it. For Claude
Desktop, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "linesight": {
      "command": "/absolute/path/to/linesight/.venv/bin/python",
      "args": ["/absolute/path/to/linesight/mcp_server.py"]
    }
  }
}
```

## Project structure

```
linesight/
├── mcp_server.py        # the MCP server: 7 tools, 4 resources, 3 prompts
├── mcp_client.py        # generic MCP stdio client
├── main.py              # chat CLI entry point
├── core/                # chat loop, Claude wrapper, tool dispatch, terminal UI
├── plant/
│   ├── analytics.py     # OEE, Pareto, XmR control charts, yield-loss math
│   ├── store.py         # CSV-backed data layer (swap for a historian/MES)
│   └── data_gen.py      # seeded demo-data generator
├── data/                # the demo dataset (committed, reproducible)
└── scripts/smoke_test.py
```

Swapping the demo CSVs for a real historian or MES connection only touches
`plant/store.py` — the MCP surface stays identical.

## Credits

The chat-client scaffolding (`core/`, `mcp_client.py`) is adapted from the
project built in [Anthropic's MCP course](https://anthropic.skilljar.com/introduction-to-model-context-protocol);
the plant domain — server, analytics, dataset — is original work.