# 731. SGMP QA Vector MCP 도구

## 목표

백오피스 MCP에 저장된 QA 벡터 예제를 조회·저장하는 두 도구를 추가한다.

- 조회 도구는 현재 질문과 유사한 예제 SQL을 Select AI 호출 전에 확인하여
  few-shot 컨텍스트로 사용할 수 있게 한다.
- 저장 도구는 검토된 Select AI 결과를 다음 질의 품질 개선용 예제 SQL로 저장한다.

## MCP 계약

| 도구 | 입력 | 반환 | 용도 |
|---|---|---|---|
| `oracle.select_ai.qa_vector_search` | `question`, 선택 `topK`(기본 3) | 예제 ID, 질문, 답 SQL, 답변, cosine distance | Select AI 실행 전 few-shot 후보 확인 |
| `oracle.select_ai.qa_vector_store` | `question`, `answerSql`, 선택 `answer` | 저장된 exampleId, 모델 | 검토된 Select AI 예제 SQL 축적 |

도구 이름·표시명·설명은 모두 `BACKOFFICE_MCP_QA_VECTOR_*` 환경 변수로
바꿀 수 있다. MCP의 공통 `prompt` 인자를 재사용하지 않아 검색과 저장의
입력 의미를 명확히 분리한다.

## 연결 및 보안

1. HTTP Bearer Token은 기존 업무 사용자 토큰 검증을 통과해야 한다.
2. 벡터 DB 호출은 `BACKOFFICE_SELECT_AI_DB_*`로 만든 SGMP_POC 연결만 사용한다.
3. API 서명 키, DB 비밀번호, credential 이름은 MCP 응답·로그에 포함하지 않는다.
4. 검색은 `SG_QA_VECTOR_SEARCH` DB 함수만 호출한다. 저장은
   `SG_QA_VECTOR_STORE` DB 함수만 호출한다.
5. 저장 도구는 호출자가 검토한 결과만 보내는 운영 계약이다. Select AI 실행
   결과를 자동으로 저장하지 않는다.

## Select AI 연계 순서

1. Agent가 사용자 질문으로 `qa_vector_search`를 호출한다.
2. 반환된 상위 2~3개 예제의 질문·답 SQL을 Select AI 프롬프트의 few-shot
   컨텍스트로 사용한다.
3. 기존 Text2SQL 도구로 SQL을 생성·검토·실행한다.
4. 검토 통과한 질문·생성 SQL·필요 시 답변을 `qa_vector_store`로 저장한다.

Text2SQL은 `BACKOFFICE_SELECT_AI_FEW_SHOT_ENABLED`가 true일 때 검색 결과의
상위 `BACKOFFICE_SELECT_AI_FEW_SHOT_TOP_K`개(기본 3, 최대 3)를 내부 프롬프트에
자동 보강한다. 예제는 현재 object list·게임 별칭 해석·정책을 대체하지 않으며,
보강 실패 또는 일치 예제 없음은 기존 Text2SQL 경로를 중단시키지 않는다.

고객 질문 재평가에서 FAIL이 확인되면 기준 SQL을 검토한 뒤에만 저장하고, 같은
질문을 다시 실행해 `fewShotStatus=APPLIED` 및 판정 개선 여부를 기록한다.

## Smilegate 포털 allowlist

`poc4_active_source_20260714/config/mcp_servers.json`의
`smilegate_game_data_mcp` allowlist에는 다음 세 도구만 둔다.

- `oracle.select_ai.smilegate_game_text2sql`
- `oracle.select_ai.qa_vector_search`
- `oracle.select_ai.qa_vector_store`

포털은 이 목록 밖의 백오피스 MCP 도구를 발견하거나 호출하지 않는다.

## 검증

- `tools/list`에 기존 두 도구와 새 두 도구가 함께 노출된다.
- 검색의 `topK` 기본값은 3이고 범위는 1~20이다.
- 저장 도구는 question·answerSql 없이는 호출되지 않는다.
- Bearer Token 누락 시 네 도구 모두 기존과 같은 권한 거절 응답을 반환한다.
- 서비스 단위 테스트는 DB 대신 캡처 구현으로 MCP 입력·응답 계약을 검증한다.
