ExperionCrawler/NL2SQL-server-review.md

NL2SQL-Server Review Report

작성일: 2026-04-28
작성자: Claude Code
대상: ~/projects/Text-to-SQL-AX/mcp-nl2sql-server

---

📋 목차

1. 개요
2. 서버 상태
3. 포트 충돌 분석
4. 두 MCP 서버 비교
5. 실행 오류 진단

---

개요

NL2SQL MCP 서버는 자연어 쿼리를 SQL로 변환하고 PostgreSQL 데이터베이스에 쿼리를 실행하는 서버입니다. 이 서버는 ExperionCrawler의 MCP 서버(간단한 RAG 서버)와 별개로 개발되어 테스트되고 있습니다.

관련 경로

경로	설명
~/projects/Text-to-SQL-AX/mcp-nl2sql-server/	NL2SQL MCP 서버 프로젝트
~/projects/ExperionCrawler/mcp-server/	ExperionCrawler RAG MCP 서버
NL2SQL-server-review.md	본 문서

---

서버 상태

항목	상태	세부 정보
실행 중	✅ 정상	서버 구문 오류 없음
포트 5001	✅ 사용 중	HTTP 서버 대기 중
FastMCP 라이브러리	✅ 호환성 확인	API 사용 정상
의존 서비스	⚠️ 일부 필요	PostgreSQL, Qdrant, Ollama, vLLM

현재 구현 (server.py:30-37, 442)

mcp = FastMCP(
    "iiot-rag",
    port=5001,
    json_response=True,
    stateless_http=True,
)

def main():
    mcp.run(transport="streamable-http")

---

포트 충돌 분석

현재 포트 사용 현황

포트	서비스	상태	구분
5000	C# ExperionCrawler API (ASP.NET)	✅ 사용 중	마이크로소프트 IIS/HTTP 서버
5001	Text-to-SQL-AX MCP Server	❌ 사용 불가	실패 중
5432	PostgreSQL 데이터베이스	❓ 확인 필요	PostgreSQL
6333	Qdrant 벡터 데이터베이스	✅ 사용 중	Qdrant
8000	vLLM (GLM-4.7-Flash)	✅ 사용 중	자체 서버
11434	Ollama (임베딩)	✅ 사용 중	Ollama

결론

실행 가능 — FastMCP API 호환성 문제가 해결되어 런타임 오류 없이 실행됩니다.

서버	통신 방식	포트
ExperionCrawler MCP	stdio (파이프)	없음
Text-to-SQL-AX MCP	streamable-http	5001

---

두 MCP 서버 비교

구분	ExperionCrawler MCP	Text-to-SQL-AX MCP
위치	~/projects/ExperionCrawler/mcp-server/	~/projects/Text-to-SQL-AX/mcp-nl2sql-server/
파일	server.py	server.py (442줄)
구성	FastMCP bare	FastMCP + HTTP 구성
포트	없음	5001
통신	stdio	streamable-http
핵심 기능	RAG 검색 (Qdrant + LLM)	NL2SQL + 히스토리 쿼리
실행 메서드	mcp.run(transport="stdio")	mcp.run(transport="streamable-http")
상태	✅ 정상 실행	✅ 정상 실행
진단	--	호환성 해결 완료

Service Dependencies 비교

서비스	ExperionCrawler	Text-to-SQL-AX	포트
Qdrant	✅ 사용	✅ 사용	6333
Ollama	✅ 사용	✅ 사용	11434
vLLM	✅ 사용	✅ 사용	8000
PostgreSQL	❌ 미사용	✅ 사용	5432

구성 차이 예시

ExperionCrawler MCP (빠진 부분)

# server.py:28-31
COL_CODEBASE    = "ws-65f457145aee80b2"
COL_OPC_DOCS    = "experion-opc-docs"

mcp = FastMCP("iiot-rag")

# server.py:169
if __name__ == "__main__":
    mcp.run(transport="stdio")

Text-to-SQL-AX MCP (현재 구현)

# server.py:30-37
COL_CODEBASE    = "ws-65f457145aee80b2"
COL_OPC_DOCS    = "experion-opc-docs"

mcp = FastMCP(
    "iiot-rag",
    port=5001,
    json_response=True,
    stateless_http=True,
)

# server.py:442
def main():
    mcp.run(transport="streamable-http")

NL2SQL 도구 추가 (run_sql, search_tags_by_name, list_drawings)

---

실행 오류 진단

오류 상세

File: server.py:453
mcp.run(transport="streamable-http", host="0.0.0.0", port=5001)

TypeError: FastMCP.run() got an unexpected keyword argument 'host'

원인 분석

1. 파라미터 위치 오류

   • host, port, json_response, stateless_http는 FastMCP.__init__()의 파라미터임
   • run() 메서드의 실제 시그니처는 transport와 mount_path만 받음
   • 즉 파라미터가 제거된 것이 아니라 run()이 아닌 생성자에 전달해야 함

2. 실제 run() 시그니처

   # 설치된 FastMCP run() 실제 시그니처
   def run(self,
           transport: Literal["stdio", "sse", "streamable-http"] = "stdio",
           mount_path: str | None = None) -> None: ...
   
   # 실제 호출 (오류) — host, port는 run()에 없음
   mcp.run(transport="streamable-http", host="0.0.0.0", port=5001)
   

3. 올바른 파라미터 위치

   # host, port, json_response, stateless_http 는 FastMCP() 생성자에 전달
   mcp = FastMCP(
       "iiot-rag",
       port=5001,           # ✅ __init__에서 설정
       json_response=True,  # ✅ __init__에서 설정
       stateless_http=True, # ✅ __init__에서 설정
   )
   # run()에는 transport만 전달
   mcp.run(transport="streamable-http")
   

수정 방법

server.py 453행의 run() 호출에서 host와 port를 제거한다.
port=5001, json_response, stateless_http는 이미 생성자에 올바르게 설정되어 있으므로 추가 변경 불필요.

# 수정 전 (오류)
mcp.run(transport="streamable-http", host="0.0.0.0", port=5001)

# 수정 후 (정상)
mcp.run(transport="streamable-http")

---

사용 예시

# 서버 실행
cd ~/projects/Text-to-SQL-AX/mcp-nl2sql-server
python server.py

# 테스트
curl http://localhost:5001/mcp
curl http://localhost:5001/health

---

참고 자료

• FastMCP GitHub Repository
• MCP (Model Context Protocol) 문서
• C# McpClient 구현
• 경쟁 처리 하려니도덕성 문제 — 참고용