Multi-MCP Enterprise Operations Copilot

플랜트 운영자를 위한 코파일럿입니다. 자연어 질문에 대해 목적에 맞게 구축된 MCP 서버를 통해 알람 관리 API를 호출하고, 운영 문서 말뭉치에서 관련 구절을 검색한 후, 두 정보를 결합하여 인용문과 가시적인 실행 추적을 포함한 단일 근거 기반 답변을 제공합니다.

git clone <repository-url> && cd senior-copilot-mcp-rag-assignment
cp .env.example .env
docker compose up --build

그런 다음 **http://localhost:5173**을 열고 승인 질문을 하세요. API 키가 필요하지 않습니다. 스택은 기본적으로 LLM 없이 동일한 워크플로를 실행하는 결정론적 공급자를 사용합니다. 생성된 산문을 위해서는 LLM_PROVIDER=anthropic과 ANTHROPIC_API_KEY를 설정하세요.

1 · 선정된 사용 사례

Multi-MCP Enterprise Operations Copilot. 코파일럿은 하드코딩된 통합 대신 두 개의 MCP 서버에서 도구를 발견하고 조정하며, 구조화된 데이터를 비구조화된 문서 증거와 하나의 워크플로에서 결합합니다.

필수 승인 시나리오:

지난 90일 동안 Boiler Feed Pump 101에 대해 반복적으로 발생한 높은 심각도의 알람을 조사하고, 가능한 기여 요인을 식별하며, 관련 운영 절차를 검색하고, 출처 증거와 함께 권장 조치를 제공하십시오.

해당 시나리오는 자동화된 테스트로 실행됩니다(tests/e2e/test_acceptance_scenario.py). 실제 HTTP 서페이스에서 5단계가 실행되고, 2단계가 1단계에서 생성된 자산 ID를 수신했으며, 1단계에서 해결된 자산 이름으로 검색이 좁혀졌으며, 답변에 [tool: …] 및 [source: …] 마커가 모두 포함되어 있는지 확인합니다.

소스 시스템에 대한 참고 사항

요약서에 설명된 알람 관리 API는 실행 중인 서비스로 존재하지 않습니다. 제공된 Postman 컬렉션이 사양입니다. 따라서 여기서도 services/alarm-simulator/로 구축되었습니다. 15개의 엔드포인트, Bearer 인증, 추적 헤더, 오류 봉투, 결정론적 시드 데이터를 포함하며, 제공된 컬렉션의 모든 체이닝 어설션이 비어 있지 않은 결과를 반환하도록 설계되었습니다. make contract는 모든 세 컬렉션을 실행합니다. CI는 모든 푸시에서 동일하게 수행합니다.

2 · 주요 기능

• 실시간 알람 데이터 및 운영 문서에 대한 자연어 채팅

• 두 MCP 서버 간의 런타임 도구 검색 — 하드코딩된 도구 목록 없음

• 다단계 도구 체이닝: 한 도구의 출력이 다음 도구의 입력이 됨

• 하이브리드 문서 검색(BM25 + 밀집 벡터, 상호 순위 융합)과 인라인 인용

• 구조화된 도구 결과와 비구조화된 문서 증거를 결합한 하나의 답변

• 전체 실행 추적: 어떤 서버, 어떤 도구, 어떤 인수, 소요 시간, 어떤 결과

• 쓰기 전 명시적 인간 확인 (도구 계약에 명시)

• 도구 실패, 시간 초과, 잘못된 스키마, 빈 검색 결과, 모델 거부, API 키 누락 시 정상적 저하

3 · 기술 스택

4 · 아키텍처 요약

5개의 서비스. GUI는 REST 및 SSE를 통해 FastAPI 오케스트레이터와 통신합니다. 오케스트레이터는 두 MCP 서버에서 런타임에 발견한 도구 레지스트리에 대해 일련의 단계를 계획하고, 각 단계의 인수(이전 단계에서 생성된 값 포함)를 해결하며, 검색을 단계 중 하나로 실행하고, 하나의 인용된 답변을 구성합니다.

Browser ──HTTP/SSE──▶ backend ──MCP──▶ mcp-alarm-management ──HTTPS+bearer──▶ alarm-simulator
                         │      └────▶ mcp-github-issues    ──────────────▶ GitHub (mocked)
                         └─embedded──▶ Chroma index over rag/documents

MCP 서버만이 그 뒤에 있는 시스템의 자격 증명을 보유합니다. 코파일럿은 알람 관리 API를 직접 호출하지 않습니다. 따라서 언어 모델은 Bearer 토큰에 대한 코드 경로가 없습니다. 토큰을 읽거나, 요청하거나, 프롬프트 인젝션을 통해 공개하도록 유도할 수 없습니다.

• 종단 간 요청 흐름: docs/architecture.md

• 구성 요소, ADR, NFR, 위험, 추적성: docs/hld.md

• 스키마, 시그니처, 알고리즘, 상태 머신: docs/lld.md

5 · MCP 서버 및 도구

후보자가 구축한 두 서버. 전체 계약(입출력 스키마, 인증 동작, 오류 동작, 시간 초과 및 실제 예제 요청 및 응답 포함)은 docs/mcp-tool-catalog.md에 있으며, 이는 라이브 list_tools() 호출에서 생성되고 CI에서 확인되므로 코드와의 불일치가 발생할 수 없습니다.

alarm-management — 14개 도구

github-issues — 3개 도구

단독 실행

python -m alarm_mcp                      # stdio, for a local MCP client
python -m alarm_mcp --transport http     # streamable HTTP, as in compose
python scripts/mcp_smoke.py              # chain two tools, no GUI and no LLM

6 · RAG 말뭉치 및 수집

10개의 마크다운 문서(운영 절차, 문제 해결 가이드, 표준, 안전 지침, 공급업체 게시판) → 49개의 제목 정렬 청크 → 임베디드 Chroma 인덱스.

python -m rag.ingestion.cli --docs ./rag/documents --reset

검색은 BM25와 밀집 벡터를 융합하고, 이전 도구 호출에서 해결된 자산별로 필터링하며, 약한 일치를 꾸미는 대신 low_confidence를 보고합니다. 하나의 말뭉치 문서에는 라이브 프롬프트 인젝션 페이로드가 포함되어 있어, 신뢰 경계가 주장되는 것이 아니라 테스트됩니다.

전체 설계 — 청킹, 메타데이터, 융합, 인용 구성, 신뢰도, 인젝션 방어, 새로 고침: docs/rag-design.md.

7 · 구성

모든 값은 환경 변수입니다. .env.example은 각 키를 안전한 플레이스홀더와 함께 문서화합니다. 비밀은 커밋되지 않으며, 데모를 실행하는 데 필요하지 않습니다.

전체 참조(유형, 기본값, 소비 서비스 포함): docs/lld.md §9.

8 · 빌드 및 실행

make가 표준이며 CI가 사용하는 방식입니다. make가 없는 Windows에서는 tasks.ps1이 동일한 대상 이름을 제공합니다.

포트: GUI 5173, 백엔드 8080, 시뮬레이터 8000 (Postman 컬렉션이 실행할 수 있도록 노출), MCP 서버 9000 / 9001 (내부).

이미 사용 중인 포트가 있으면 .env에서 호스트 쪽을 재정의하세요. 컨테이너 포트는 변경되지 않습니다. VITE_API_BASE_URL을 백엔드 포트와 일치하도록 설정하세요. Vite가 빌드 시 GUI에 인라인으로 포함하기 때문입니다:

BACKEND_HOST_PORT=8090 VITE_API_BASE_URL=http://localhost:8090 docker compose up --build

Docker 없이: make install, 그런 다음 네 개의 Python 서비스를 별도의 터미널에서 실행 — uvicorn alarm_simulator.main:app --port 8000, python -m alarm_mcp --transport http, python -m github_mcp --transport http, make ingest, uvicorn copilot_backend.api.app:app --port 8080 — 그리고 apps/frontend에서 npm run dev.

9 · 테스트

make contract는 newman이 필요합니다(npm install -g newman) 및 실행 중인 시뮬레이터가 필요합니다.

269개의 테스트, 모두 통과, 89% 라인 커버리지 — 세부 내용은 docs/coverage.md에 있습니다. 이들이 커버하는 내용:

LLM은 엔드 투 엔드를 포함한 모든 곳에서 모킹되므로, 스위트는 빠르고 무료이며 반복 가능합니다. 이것이 의미하는 바는 docs/known-limitations.md를 참조하세요.

10 · 샘플 상호작용

반복 알람 (수용 시나리오). 다섯 단계: 자산 식별 → 높은 심각도의 알람 요약 → 동시 발생 쌍 상관관계 → 합리화 후보 찾기 → 방금 식별된 자산으로 필터링된 절차 검색. 답변은 Discharge Pressure Low 다음에 Suction Strainer DP High가 31회 발생(리프트 2.29, 평균 지연 393초) [tool: alarm-management/get_alarm_correlation]이라고 보고하며, 이를 [source: OP-BFP-101#…]의 격리 및 검사 단계와 짝지어 줍니다.

운영자 응답 효율성. generate_calculation → execute_calculation (calculation_id로 체인됨) → 승인 지연 트렌드 → STD-OPRESP의 해당 표준.

에스컬레이션. 활성 알람 → 최상위 알람의 우선순위 점수 → 관련 알람 컨텍스트가 포함된 권장 조치 → 해당 알람 철학 섹션.

이슈 제기. 알람 요약 → 중복 확인 → draft_issue. create_issue는 confirmation.required로 실행을 중단합니다. GUI는 정확한 인수를 표시하고 승인 후에만 진행합니다. MCP 서버는 UI가 무엇을 하든 관계없이 거부합니다.

지원 문서가 없는 질문. 검색이 low_confidence를 보고합니다. 답변은 일반 지식으로 대체하는 대신 관련 절차를 찾을 수 없다고 명확히 말합니다.

11 · 저장소 레이아웃

apps/backend/          FastAPI orchestrator, MCP client, LLM providers
apps/frontend/         React + TypeScript GUI
mcp-servers/           alarm-management (14 tools), github-issues (3 tools)
services/              alarm-simulator — the candidate-built source system
connectors/alarm_api/  Reusable HTTP client, deliberately separate from the MCP server
packages/schemas/      Shared Pydantic tool contracts
rag/                   documents, ingestion, retrieval, tests
tests/                 unit, integration, e2e
docs/                  architecture, HLD, LLD, tool catalog, RAG design, decisions, limits
postman/               The supplied collections — the Alarm API specification

제출 가이드라인 §3의 구조에서 두 가지 문서화된 이탈:

• services/alarm-simulator/ — 브리프는 별도로 후보자가 구축한 백엔드를 요구하며, 이는 미리 명명된 폴더 중 하나가 아닙니다. 시뮬레이터(통합 대상 시스템)를 connectors/(그것에 도달하는 클라이언트)와 분리하여 유지하는 것이 둘을 합치는 것보다 더 깔끔한 분리입니다.

• docs/hld.md 및 docs/lld.md — 필수 docs/architecture.md(진입점 유지)와 함께 추가되었습니다.

가이드라인은 명확히 문서화된 경우 동등한 구조를 허용합니다. 의무화된 디렉토리 이름은 하이픈으로 연결되어 유효한 Python 패키지 이름이 아니기 때문에, 각각은 pyproject.toml에서 최상위 임포트로 매핑된 올바르게 명명된 패키지(mcp-servers/alarm-management/alarm_mcp/)를 보유합니다.

12 · 가정

1. Alarm Management API는 존재하지 않으므로, Postman 컬렉션은 그 사양으로 취급되며 시뮬레이터는 이를 정확히 충족하도록 구축됩니다. 컬렉션이 침묵한 경우(예: 체이닝 컬렉션에만 나타나는 필터) 컬렉션의 어설션이 권위자입니다.

2. 알람 ID, 자산 ID, 타임스탬프는 재현 가능합니다. 시드가 고정되어 있어 데모, 테스트, Postman 실행 모두 동일한 데이터를 봅니다.

3. 상관관계는 동일한 자산의 지연 창 내에서 동시 발생을 의미합니다. 통계적 유의성 검정은 합성 데이터의 범위를 벗어납니다.

4. 단일 테넌트, 단일 사이트 에스테이트. 검색 또는 도구 권한 부여에 테넌트 식별자가 스레드되지 않습니다.

5. GUI-백엔드 홉은 인증되지 않습니다. 이는 로컬 데모에 허용 가능하며 제한 사항에서 언급됩니다.

6. docker compose up이 지원되는 경로입니다. 수동 경로는 §8에 문서화되어 있지만 CI가 실행하는 것은 compose 파일입니다.

13 · 알려진 제한 사항 및 향후 개선 사항

정직한 범위 경계, 각각 더 많은 시간이 있었다면 다르게 할 것에 대한 설명: docs/known-limitations.md. 다음으로 올 것, 제가 할 순서대로: docs/future-improvements.md.

14 · 데모

스크린샷

make screenshots로 실행 중인 스택에서 캡처하여, 재생성 가능하고 오래되지 않습니다: docs/screenshots/.

또한 캡처됨: 빈 상태 및 인용 칩이 포함된 답변.

비디오

링크: 추가 예정 — 녹화된 워크스루 스크립트는 docs/demo.md 참조.

수용 시나리오 전체, 스키마 검사가 포함된 도구 검색, 실행 타임라인, 증거로 해석되는 인용 칩, 쓰기 확인 게이트, 그리고 실패 경로를 다룹니다. 시뮬레이터가 세션 중간에 중지되어 재시도, 성능 저하된 답변, 정직한 공백을 보여줍니다.

라이선스

MIT — LICENSE 참조.