🔌 Graph Pipeline Phase 5: MCP 서버 통합 및 시스템 아키텍처 (MCP Integration)

이 문서는 앞서 설계한 1~4단계의 Graph Pipeline을 현재 프로젝트의 **Unified MCP Server (mcp-server/server.py)**에 통합하는 방안과 최종 프로그램 구조를 다룹니다. 이를 통해 C# 메인 서버와 LLM, 그리고 도면 분석 엔진이 하나의 생태계에서 유기적으로 동작하게 합니다.

🏗️ 1. 통합 아키텍처 설계

1.1 전체 데이터 흐름 (End-to-End Flow)

Frontend (UI) \rightarrow C# Server (API) \rightarrow MCP Server (Python) \rightarrow Graph Pipeline Engine \rightarrow Experion DB/OPC UA

요청: 사용자가 UI에서 "P-101 펌프의 영향도 분석" 요청.
중계: C# 서버가 McpClient를 통해 MCP 서버의 analyze_pid_impact 툴 호출.
분석: MCP 서버는 내부적으로 NetworkX 그래프를 로드하여 하류 노드를 계산.
응답: 분석 결과(노드 리스트)를 JSON으로 반환 \rightarrow C# 서버 \rightarrow UI 하이라이트.

1.2 MCP 서버 내 역할 분담

현재 server.py는 RAG, NL2SQL, 단순 태그 추출 기능을 가지고 있습니다. 여기에 Graph Pipeline 전용 도구 세트를 추가합니다.

기존 기능	추가될 Graph Pipeline 기능	역할
`parse_pid_dxf`	`build_pid_graph`	DXF `\rightarrow` 기하 추출 `\rightarrow` 위상 그래프 생성 및 저장
`match_pid_tags`	`resolve_graph_tags`	그래프 맥락을 반영한 지능형 태그 매핑
(신규)	`analyze_pid_impact`	특정 노드 기준 영향도 분석 (Downstream 탐색)
(신규)	`get_graph_topology`	시각화를 위한 노드-엣지 리스트 반환

💻 2. MCP 서버 통합 구현 가이드

2.1 MCP Tool 캡슐화 설계

mcp-server/server.py에 다음과 같은 형태로 툴을 추가합니다.

# mcp-server/server.py 에 추가될 내용 (개념 코드)

@mcp.tool()
def build_pid_graph(filepath: str) -> str:
    """
    P&ID 도면을 분석하여 위상 그래프를 생성하고 저장합니다.
    Phase 1(기하 추출) + Phase 2(위상 모델링) 통합 실행.
    """
    # 1. Phase 1: Geometric Extraction
    extractor = PidGeometricExtractor(filepath)
    geo_data = extractor.extract_all()
    
    # 2. Phase 2: Topology Modeling
    builder = PidTopologyBuilder(geo_data)
    builder.build_graph()
    
    # 3. 그래프 저장 (GraphML 또는 JSON)
    graph_id = os.path.basename(filepath).replace(".dxf", "_graph.json")
    nx.write_graphml(builder.G, f"storage/{graph_id}")
    
    return json.dumps({"success": True, "graph_id": graph_id, "nodes": builder.G.number_of_nodes()})

@mcp.tool()
def analyze_pid_impact(graph_id: str, start_node_id: str) -> str:
    """
    특정 설비의 장애 시 영향을 받는 하류 설비 리스트를 반환합니다.
    """
    # 그래프 로드
    G = nx.read_graphml(f"storage/{graph_id}")
    
    # 영향도 분석 (Phase 4 로직)
    impacted = nx.descendants(G, start_node_id)
    
    return json.dumps({
        "success": True, 
        "start_node": start_node_id, 
        "impacted_nodes": list(impacted)
    })

2.2 C# 서버와의 인터페이스 (`McpClient` 활용)

C# 서버는 src/Infrastructure/Mcp/McpClient.cs를 통해 위 툴들을 호출합니다.

// src/Core/Application/Services/PidGraphService.cs (신규 서비스)
public async Task<ImpactResult> GetImpactAnalysisAsync(string graphId, string nodeId)
{
    var request = new McpToolRequest {
        ToolName = "analyze_pid_impact",
        Arguments = new { graph_id = graphId, start_node_id = nodeId }
    };
    
    var jsonResponse = await _mcpClient.CallToolAsync(request);
    return JsonSerializer.Deserialize<ImpactResult>(jsonResponse);
}

🛠️ 3. 프로그램 구성 및 배포 전략

3.1 디렉토리 구조 확장

mcp-server/
├── server.py              # MCP 메인 서버 (툴 정의)
├── pipeline/              # Graph Pipeline 핵심 로직 (Phase 1~4)
│   ├── __init__.py
│   ├── extractor.py       # Phase 1: Geometric Extraction
│   ├── topology.py        # Phase 2: Topology Modeling
│   ├── mapper.py          # Phase 3: Intelligent Mapping
│   └── analyzer.py        # Phase 4: Impact Analysis
└── storage/               # 생성된 그래프 파일 (.graphml) 저장소

3.2 실행 프로세스

MCP 서버 기동: python mcp-server/server.py --http (포트 5001)
C# 서버 기동: dotnet run (포트 5000)
통신: C# 서버 \xrightarrow{HTTP/JSON} MCP 서버 \xrightarrow{Python\ Libs} 결과 반환.

🚀 4. 최종 완료 기준 (Definition of Done)

mcp-server/server.py에 build_pid_graph, analyze_pid_impact 등 핵심 툴이 정의되었는가?
Phase 1~4의 Python 로직이 mcp-server/pipeline/ 모듈로 구조화되어 통합되었는가?
C# McpClient를 통해 MCP 서버의 그래프 분석 툴을 호출하고 결과를 수신할 수 있는가?
도면 업로드 \rightarrow 그래프 생성 \rightarrow 태그 매핑 \rightarrow 영향도 분석으로 이어지는 End-to-End 파이프라인이 완성되었는가?
모든 과정이 json_response=True 및 stateless_http=True 설정 하에 안정적으로 동작하는가?

5.4 KiB Raw Blame History