Agente de mantenimiento de máquinas: Proyecto de entrevista MCP

Este es un pequeño proyecto listo para entrevistas que demuestra cómo un agente puede usar herramientas MCP para inspeccionar datos industriales de máquinas, buscar orientación de mantenimiento y crear un ticket de mantenimiento cuando se necesita escalar.

El escenario de ejemplo:

"La máquina P-204 vibra de forma anormal. ¿Qué debo hacer?"

El agente consulta el estado sintético de la máquina, revisa las anomalías recientes de los sensores, busca en un conjunto de datos del manual de mantenimiento y, opcionalmente, crea un ticket.

Por qué es un buen ejemplo de MCP

MCP es útil aquí porque el agente no necesita acceso directo a bases de datos ni archivos. En su lugar, recibe una interfaz de herramientas controlada:

• 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)

Eso permite explicar el acceso de solo lectura a los datos, el acceso seguro de escritura, los límites de las herramientas y el comportamiento del agente en varios pasos en un solo proyecto pequeño.

Related MCP server: Equipment Health MCP Server

Estructura del proyecto

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

Configuración

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

La dependencia de MCP está fijada en la línea actual estable v1 del SDK de Python: mcp[cli]>=1.27,<2.

Ejecutar el agente de demostración

Desde esta carpeta:

python src/agent_demo.py

Para crear un ticket durante la demostración:

python src/agent_demo.py --create-ticket

Comportamiento esperado:

1. Lee el estado de P-204.

2. Detecta vibración y temperatura fuera del rango normal.

3. Detecta una anomalía de vibración de alta severidad.

4. Busca en el manual de mantenimiento orientación sobre vibración de bombas.

5. Recomienda reducir la carga e inspeccionar el área del rodamiento/acoplamiento.

6. Crea un ticket solo si se usa --create-ticket.

Ejecutar el servidor MCP

python src/mcp_server.py

Esto inicia un servidor MCP stdio. Los clientes MCP pueden conectarse a él y llamar a las herramientas expuestas.

Formato de configuración de un cliente MCP:

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

Ejecutar las pruebas

python -m unittest discover -s tests

Explicación para la entrevista

Usa esta breve explicación:

"He construido un servidor MCP en torno a un sistema de mantenimiento sintético. El agente no puede consultar archivos ni bases de datos libremente. Solo recibe unas pocas herramientas: leer el estado de la máquina, leer anomalías, buscar el manual y crear un ticket de mantenimiento. Para una queja de vibración en la bomba P-204, el agente comprueba el estado en tiempo real, ve que la vibración supera el umbral, encuentra anomalías recientes de alta severidad, recupera la orientación relevante del manual y escala la situación creando un ticket. Esto demuestra acceso empresarial controlado, razonamiento basado en herramientas y un límite seguro entre el LLM y los sistemas operativos."

Para un recorrido más estructurado, consulta AGENT_FLOW.md y TOOL_CONTRACTS.md.

Qué datos utiliza este proyecto

• Metadatos de la máquina: ID, nombre, área, criticidad, rangos de funcionamiento normales.

• Estado de la máquina: vibración actual, temperatura, presión, estado, fecha del último servicio.

• Anomalías de sensores: marca de tiempo, señal, valor, umbral, severidad, descripción.

• Manual de mantenimiento: síntomas, palabras clave, acciones recomendadas, notas de seguridad.

• Almacén de tickets: ID del ticket, ID de la máquina, severidad, resumen, acción recomendada, estado.

Cómo extenderlo

Pequeñas mejoras de seguimiento para una versión de portafolio:

• Añade un cliente LLM real que elija las herramientas de forma dinámica.

• Añade SQLite en lugar de archivos JSON.

• Añade permisos basados en roles, como acceso de solo lectura para operadores y acceso de supervisión para escribir tickets.

• Añade un panel simple que muestre el estado de la máquina y los tickets abiertos.