# Redmine #735 · SGMP Few-shot NL2SQL MCP

> 상태: Approved
> 구현: `McpSseService`, `SelectAiService`, `McpProperties`

## 목적

기존 Select AI Text2SQL 경로와 분리된 MCP tool을 제공한다. 질문과 의미가 유사한 검토
완료 예제를 DB에서 검색하고, 승인 SQL 구조를 참고자료로 넣은 뒤 `SHOWSQL`로 생성한 SQL을
읽기 전용으로 실행한다.

## MCP 계약

- **tool name**: `oracle.select_ai.smilegate_fewshot_nl2sql` (환경변수로 재정의 가능)
- **입력**: `prompt` (최대 4,000자)
- **출력**: 벡터 Few-shot 예제(질문, SQL, 모델, cosine distance), 생성 SQL, 실행 상태, 행 수, 최대 100건 결과

Few-shot SQL은 실행하지 않는다. 현재 메타데이터·alias 정책을 우선하고, Select AI가 새로
생성한 SQL만 read-only 검증 후 실행한다.

## DB 검색·승인 기준

- `sg_qa_vector_example`의 `reference_status='APPROVED'`,
  `inspection_status='VERIFIED'`, SQL 존재 예제만 후보가 된다.
- `RETIRED`는 동일 질문이라도 후보에서 제외된다. 리타이어 여부는 DB 컬럼으로 저장하며
  Java가 별도 목록으로 판단하지 않는다.
- 벡터 cosine distance가 `QA_VECTOR_MAX_COSINE_DISTANCE` 이하여야 한다.
- 후보 순위는 벡터 유사도와 질문 문자열 유사도를 DB에서 결합한다. 정책값
  `QA_VECTOR_LEXICAL_WEIGHT=0.35`, `QA_VECTOR_HYBRID_SCORE_MARGIN=0.05`는
  유사한 후속 질문에는 참고 범위를 남기되, 핵심 요청어가 다른 예제가 최상위가 되는 문제를
  줄인다.
- 고객 기준 예제는 개별 승인 상태로 관리한다. 같은 문장만 허용하는 방식으로 제한하지 않으며,
  승인된 SQL 구조가 새 질문의 참고 근거가 될 수 있다.

## 안전 규칙

1. 검색 후보가 없으면 `NO_MATCH`로 기록하고 일반 Select AI 생성은 계속한다.
2. 생성 결과는 단일 `SELECT` 또는 `WITH`만 허용한다.
3. DDL, DML, PL/SQL, 시스템 객체, 잠금 구문, 다중 문장은 차단한다.
4. JDBC read-only 트랜잭션과 30초 query timeout, 최대 100행 제한을 적용한다.
5. 기존 `data_text2sql`, `data_showprompt`, `qa_vector_search`, `qa_vector_store` tool은 변경하지 않는다.

## 설정

```text
BACKOFFICE_MCP_FEW_SHOT_NL2SQL_TOOL_NAME
BACKOFFICE_MCP_FEW_SHOT_NL2SQL_TOOL_LABEL
BACKOFFICE_MCP_FEW_SHOT_NL2SQL_TOOL_DESCRIPTION
```

## 추적성

- Redmine: #735
- 테스트: `McpSseServiceTest`