# 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`로 저장한다.

현재 MCP는 검색 결과를 반환한다. Text2SQL tool의 내부 Select AI prompt에
자동 주입하는 변경은 별도 단계로 두어, 검색 결과와 실제 prompt 구성을
운영자가 먼저 확인할 수 있게 한다.

## 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 입력·응답 계약을 검증한다.