65 lines
3.2 KiB
Markdown
65 lines
3.2 KiB
Markdown
# #743 MCP 광고 Agent Tool 시작 검증
|
|
|
|
## 문제
|
|
|
|
백오피스 MCP의 `tools/list`는 `BACKOFFICE_MCP_TOOLS`에 선언된 공개 계약을 광고한다.
|
|
`AGENT_TOOL`은 `targetName`을 `DBMS_CLOUD_AI_AGENT.RUN_TOOL`에 전달하지만, 현재는 서버
|
|
시작 시 해당 Tool이 ADB에 실제로 등록되어 있는지 확인하지 않는다. 따라서 Discovery는
|
|
성공하고 첫 `tools/call`에서만 실패할 수 있다.
|
|
|
|
## 목표
|
|
|
|
- 공개 Tool 이름과 입력 스키마는 배포 설정에서 안정적으로 관리한다.
|
|
- `AGENT_TOOL`의 내부 `targetName`은 현재 JDBC 실행 사용자의
|
|
`USER_AI_AGENT_TOOLS`에서 존재하고 `ENABLED` 상태여야 한다.
|
|
- 누락·비활성·메타데이터 조회 실패는 서버 시작을 중단한다.
|
|
- Java 자체 구현인 `SELECT_AI`는 ADB Agent Tool 검증 대상에서 제외한다.
|
|
|
|
## 처리 흐름
|
|
|
|
```text
|
|
Spring 설정 로드
|
|
→ EnvironmentMcpToolCatalog가 BACKOFFICE_MCP_TOOLS 검증
|
|
→ SmartInitializingSingleton이 AGENT_TOOL targetName 수집
|
|
→ USER_AI_AGENT_TOOLS 조회
|
|
→ 모두 ENABLED
|
|
├─ 예: MCP endpoint 기동 완료, tools/list 광고
|
|
└─ 아니오: 기동 실패, 외부에 불완전한 Tool 계약을 광고하지 않음
|
|
```
|
|
|
|
Discovery 요청 때마다 DB를 조회하지 않는다. ADB Agent Tool은 운영 설정이므로 시작 시 한 번
|
|
검증하고, 설정이나 DB Tool을 바꾼 뒤에는 애플리케이션을 재기동해 계약을 다시 확정한다.
|
|
|
|
## 실패 정책
|
|
|
|
누락된 Tool을 `tools/list`에서 자동 제외하지 않는다. 호출 가능한 Tool 집합이 환경에 따라
|
|
조용히 축소되면 Agent instruction과 실제 도구 목록이 어긋나기 때문이다. 설정에 선언된
|
|
`AGENT_TOOL`이 하나라도 누락되거나 `ENABLED`가 아니면 fail-closed로 기동을 실패시킨다.
|
|
|
|
오류에는 설정의 내부 Tool 이름과 상태만 포함한다. Bearer Token, Tool 입력, DB 접속정보는
|
|
로그에 기록하지 않는다.
|
|
|
|
## 구현 경계
|
|
|
|
- `EnvironmentMcpToolCatalog`: 공개 이름, 인자, 실행 유형, 내부 target 형식 검증
|
|
- `McpAgentToolStartupValidator`: DB 등록·상태 검증
|
|
- `McpSseService`: 검증 완료된 catalog를 `tools/list`로 광고하고 `tools/call`로 실행
|
|
- `JdbcHmmAiAgentToolRunner`: 검증된 `targetName`을 동일 JDBC 세션에서 실행
|
|
|
|
`USER_AI_AGENT_TOOLS`는 `RUN_TOOL`을 실행하는 기본 datasource 사용자 기준 View다. 다른
|
|
스키마의 Tool을 임의로 검색하거나 `ALL_*` 권한을 요구하지 않는다.
|
|
|
|
## 검증 기준
|
|
|
|
1. `AGENT_TOOL`이 모두 `ENABLED`면 검증이 통과한다.
|
|
2. Tool이 누락되면 누락된 이름을 포함해 실패한다.
|
|
3. Tool이 `DISABLED`면 이름과 상태를 포함해 실패한다.
|
|
4. 같은 ADB Tool을 여러 공개 Tool이 참조해도 한 번만 검증한다.
|
|
5. `SELECT_AI`만 구성되면 `USER_AI_AGENT_TOOLS`를 조회하지 않는다.
|
|
6. 기존 Maven 전체 테스트와 MCP discovery/call 테스트가 통과한다.
|
|
|
|
## 롤백
|
|
|
|
검증 컴포넌트와 테스트를 제거하면 기존 설정 기반 광고 방식으로 돌아간다. DB Tool,
|
|
프로필, VPD 정책과 운영 데이터는 이 변경에서 수정하지 않는다.
|