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.

Related MCP server: Equipment Health MCP Server

Project Structure

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

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:

python src/agent_demo.py

To create a ticket during the demo:

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

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:

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

Run Tests

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.