기계 유지보수 에이전트: MCP 인터뷰 프로젝트

이것은 에이전트가 MCP 도구를 사용하여 산업용 기계 데이터를 점검하고, 유지보수 지침을 검색하며, 에스컬레이션이 필요할 때 유지보수 티켓을 생성하는 방법을 보여주는 간단한 인터뷰용 프로젝트입니다.

예제 시나리오:

"P-204 기계가 비정상적으로 진동하고 있습니다. 어떻게 해야 하나요?"

에이전트는 가상의 기계 상태를 확인하고, 최근 센서 이상을 검토하며, 유지보수 매뉴얼 데이터셋을 검색하고, 선택적으로 티켓을 생성합니다.

이것이 좋은 MCP 예제인 이유

MCP는 에이전트가 데이터베이스나 파일에 직접 접근할 필요가 없기 때문에 이 상황에서 유용합니다. 대신 에이전트는 통제된 도구 인터페이스를 받습니다:

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

이를 통해 읽기 전용 데이터 접근, 안전한 쓰기 접근, 도구 경계, 그리고 다단계 에이전트 동작을 하나의 작은 프로젝트에서 설명할 수 있습니다.

Related MCP server: Equipment Health MCP Server

프로젝트 구조

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

설정

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

MCP 의존성은 현재 안정적인 Python SDK v1 라인으로 고정되어 있습니다: mcp[cli]>=1.27,<2.

데모 에이전트 실행

이 폴더에서:

python src/agent_demo.py

데모 중 티켓을 생성하려면:

python src/agent_demo.py --create-ticket

예상 동작:

1. P-204의 상태를 읽습니다.

2. 진동과 온도가 정상 범위를 벗어났는지 확인합니다.

3. 심각도가 높은 진동 이상을 발견합니다.

4. 유지보수 매뉴얼에서 펌프 진동 지침을 검색합니다.

5. 부하를 줄이고 베어링/커플링 부분을 검사할 것을 권장합니다.

6. --create-ticket이 사용된 경우에만 티켓을 생성합니다.

MCP 서버 실행

python src/mcp_server.py

이 명령은 stdio MCP 서버를 시작합니다. MCP 클라이언트는 연결하여 노출된 도구를 호출할 수 있습니다.

MCP 클라이언트 설정 형식 예시:

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

테스트 실행

python -m unittest discover -s tests

인터뷰 설명

이 간략한 설명을 사용하세요:

"합성 유지보수 시스템을 기반으로 MCP 서버를 구축했습니다. 이에이전트는 파일이나 데이터베이스를 자유롭게 조회할 수 없습니다. 기계 상태 읽기, 센서 이상 읽기, 매뉴얼 검색, 유지보수 티켓 생성 등 소수의 도구만 사용할 수 있습니다. 펌프장치 P-2 관리자 진동 문제에 대해 에이전트는 실시간 상태를 확인하고, 진동이 임계값을 초과했는지 확인하며, 최근의 고심각도 이상을 찾고, 관련 매뉴얼 지침을 가져온 다음 티켓을 생성합니다. 이는 통제된 엔터프라이즈 접근, 도구 기반 추론, 그리고 이와 운영 시스템 사이의 안전한 경계를 보여줍니다."

더 구조화된 안내는 AZEG_FLOW.md와 TOOL_CONTRACTS.md를 참조하세요.

이 프로젝트가 사용하는 데이터

• 기계 메타데이터: ID, 이름, 구역, 중요도, 정상 운영 범위.

• 기계 상태: 현재 진동, 온도, 압력, 상태, 마지막 서비스 날짜.

• 시작 이상: 타임스탬프, 신호, 값, 임계값, 심각도, 설명.

• 유지보수 매뉴얼: 증상, 키워드, 권장 조치, 안전 수칙.

• 티켓 저장소: 티켓 ID, 기계 ID, 심각도, 요약, 권장 조치, 상태.

확장 방법

포트폴리오 버전을 위한 작은 후속 개선 사항:

• 도구를 동적으로 선택하는 실제 LLM 클라이언트를 추가하기.

• JSON 파일대신의 SQLite 사용하기.

• 읽기 전용 운영자 접근 및 티켓 생성 감독자 접근과 같은 역할 기반 권한 추가하기.

• 긴급상태와 열린 티켓을 보여주는 간단한 대시보드 추가하기.