# Machine Maintenance Agent: MCP Interview Project

This is a small interview-ready project that demonstrates how an agent can use MCP tools to inspect industrial machine data, search maintenance guidance, and create a maintenance ticket when escalation is needed.

The example scenario:

> "Machine P-204 is vibrating abnormally. What should I do?"

The agent checks synthetic machine status, reviews recent sensor anomalies, searches a maintenance manual dataset, and optionally creates a ticket.

## Why This Is a Good MCP Example

MCP is useful here because the agent does not need direct database or file access. Instead, it receives a controlled tool interface:

- `get_machine_status_tool(machine_id)`
- `get_recent_sensor_anomalies_tool(machine_id, hours)`
- `search_maintenance_manual_tool(query, limit)`
- `create_maintenance_ticket_tool(machine_id, severity, summary, recommended_action)`
- `list_open_tickets_tool(machine_id)`

That lets you explain read-only data access, safe write access, tool boundaries, and multi-step agent behavior in one small project.

## Project Structure

```text
machine-maintenance-agent/
  data/
    machines.json              # Machine metadata and normal operating ranges
    machine_status.json        # Current synthetic sensor readings
    anomalies.json             # Recent detected anomalies
    maintenance_manual.json    # Small troubleshooting knowledge base
    tickets.json               # Simple local ticket store
  src/
    maintenance_tools.py       # Core tool logic
    mcp_server.py              # MCP server exposing tools
    agent_demo.py              # Transparent agent flow demo
  tests/
    test_maintenance_tools.py
  AGENT_FLOW.md
  TOOL_CONTRACTS.md
  requirements.txt
  README.md
```

## Setup

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

The MCP dependency is pinned to the current stable Python SDK v1 line: `mcp[cli]>=1.27,<2`.

## Run the Demo Agent

From this folder:

```bash
python src/agent_demo.py
```

To create a ticket during the demo:

```bash
python src/agent_demo.py --create-ticket
```

Expected behavior:

1. Reads status for `P-204`.
2. Finds vibration and temperature outside normal range.
3. Finds high-severity vibration anomaly.
4. Searches the maintenance manual for pump vibration guidance.
5. Recommends reducing load and inspecting the bearing/coupling area.
6. Creates a ticket only if `--create-ticket` is used.

## Run the MCP Server

```bash
python src/mcp_server.py
```

This starts a stdio MCP server. MCP clients can connect to it and call the exposed tools.

Example MCP client configuration shape:

```json
{
  "mcpServers": {
    "machine-maintenance-agent": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "cwd": "/absolute/path/to/machine-maintenance-agent"
    }
  }
}
```

## Run Tests

```bash
python -m unittest discover -s tests
```

## Interview Explanation

Use this short explanation:

> "I built an MCP server around a synthetic maintenance system. The agent cannot freely query files or databases. It only gets a few tools: read machine status, read anomalies, search the manual, and create a maintenance ticket. For a vibration complaint on pump P-204, the agent checks live status, sees vibration above threshold, finds recent high-severity anomalies, retrieves relevant manual guidance, and escalates by creating a ticket. This demonstrates controlled enterprise access, tool-based reasoning, and a safe boundary between the LLM and operational systems."

For a more structured walkthrough, see `AGENT_FLOW.md` and `TOOL_CONTRACTS.md`.

## What Data This Project Uses

- Machine metadata: ID, name, area, criticality, normal operating ranges.
- Machine status: current vibration, temperature, pressure, state, last service date.
- Sensor anomalies: timestamp, signal, value, threshold, severity, description.
- Maintenance manual: symptoms, keywords, recommended actions, safety notes.
- Ticket store: ticket ID, machine ID, severity, summary, recommended action, status.

## How to Extend It

Small follow-up improvements for a portfolio version:

- Add a real LLM client that chooses tools dynamically.
- Add SQLite instead of JSON files.
- Add role-based permissions, such as read-only operator access and ticket-write supervisor access.
- Add a simple dashboard showing machine status and open tickets.