본 부록은 2.5 보조 도구 개요의 상세판이다. 23+1(retriever)개 도구를 PoC 진입 필수도 기준으로 P0~P3 4단계로 분류한다 (운영 마이그레이션 도구는 외부 노출 제외).
정식 시그니처는 /docs Swagger UI 또는 MCP tools/list 응답에서 직접 수신.
노출 컬럼 범례 — 0.1 노출 방향성 기반: 양쪽 = MCP tools/list + REST /mcpapi/rag/* 동시 제공 / MCP 전용 = REST 미노출 = 미구현 또는 PoC 단계 협의. MCP 도구명은 첫 번째 컬럼이며, "HTTP" 컬럼은 REST 노출 시의 엔드포인트이다.
A.1 P0 — PoC 진입 필수 (4 + 1개)
도입사 측이 첫 질의·인입을 검증하기 위해 반드시 통합해야 하는 도구.
| 도구 | 도구군 | 노출 | HTTP | 용도 |
|---|---|---|---|---|
retriever | 검색 | MCP 전용 | - | 자연어 질의 → 답변 본문 + 인라인 시테이션 + 참조 문서 목록 (2.2) |
index_local_files | 인입 | 양쪽 | POST /mcpapi/rag/index_local_files | 로컬 디렉토리 파일 인입 (동기 완료, 응답 IndexJobResult) |
index_data_files | 인입 | 양쪽 | POST /mcpapi/rag/index_data_files | 배치 인입 (응답 IndexJobResult, 폴링 필요 — 14.3) |
get_rag_status | 인입 | 양쪽 | GET /mcpapi/rag/get_rag_status | 인입 진행 상태 폴링 — pending / in_progress / done / failed |
get_indexed_file | 인입 | 양쪽 | GET /mcpapi/rag/get_indexed_file | 단건 인입 파일 메타·상태 조회 |
A.2 P1 — 운영 진입 필수 (6개)
PoC 검증 후 운영 전환 시 통합 권장.
| 도구 | 도구군 | 노출 | HTTP | 용도 |
|---|---|---|---|---|
delete_document | 인입 | 양쪽 | POST /mcpapi/rag/delete_document | 문서 철회 (그래프·청크·임베딩 cascade) |
get_document_metadata | 인입 | 양쪽 | POST /mcpapi/rag/get_document_metadata | 문서 메타 조회 (classification·author·created_at 등) |
update_document_metadata | 인입 | 양쪽 | POST /mcpapi/rag/update_document_metadata | 문서 메타 갱신 |
get_entity | 엔티티 | 양쪽 | POST /mcpapi/rag/get_entity | 단건 엔티티 조회 (호스트 엔티티 페이지 UI 용) |
get_entity_edges | 엔티티 | 양쪽 | POST /mcpapi/rag/get_entity_edges | 엔티티 그래프 탐색 (UI) |
search_graph_labels | 그래프 | 양쪽 | POST /mcpapi/rag/search_graph_labels | 라벨 자동완성 |
A.3 P2 — 편집 기능 (10개)
엔티티 별칭 통합·관계 편집·섹션 편집 등 운영 단계 편집 기능.
| 도구군 | 도구 | 노출 | HTTP |
|---|---|---|---|
| 엔티티 | create_entity / edit_entity / delete_entity / merge_entities | 양쪽 | POST / PATCH / DELETE /v1/entities, POST /v1/entities/merge |
| 관계 | create_relation / edit_relation / delete_relation | 양쪽 | POST / PATCH / DELETE /v1/relations |
| 섹션 | get_section / edit_section / delete_section | 양쪽 | GET / PATCH / DELETE /v1/sections/{section_id} |
쓰기 도구는 rag:write scope 필요. 별칭 통합 (merge_entities) 은 비가역 — 호출 전 사용자 확정 권장.
A.4 P3 — 그래프 조회 (3개)
전체 그래프·문서별 그래프 조회. 큰 그래프는 페이지네이션 협의 필요.
| 도구 | 노출 | HTTP | 용도 |
|---|---|---|---|
get_graph_labels | 양쪽 | POST /mcpapi/rag/get_graph_labels | 라벨 카탈로그 (UI 사이드바·필터) |
get_knowledge_graph | 양쪽 | POST /mcpapi/rag/get_knowledge_graph | 전체 그래프 (sub-graph 옵션 권장) |
get_document_graph | 양쪽 | POST /mcpapi/rag/get_document_graph | 특정 문서의 sub-graph |
A.5 공통 응답·에러 모델
모든 도구가 공유하는 모델은 /openapi.json components.schemas에서 직접 수신. 핵심 4종은 다음과 같다.
| 모델 | 용도 | 참조 |
|---|---|---|
RetrieverResponse | 검색 응답 | 6.2 (content / metadata.references[] / score[] / latency) |
IndexJobResult | 인입 응답 | processed / skipped / errors[] |
RagStatus | 인입 진행 상태 | status / progress / error |
ErrorResponse | 공통 에러 | 16.0 에러 코드 표 |
A.6 부록 활용 가이드
- PoC 1차 통합 — A.1의 5개 도구만으로 첫 검증 가능
- A.2의 P1 6개 — 운영 진입 시 호스트 UI 메뉴 항목 (문서 관리·엔티티 페이지·자동완성) 과 직접 매핑
- A.3·A.4의 P2/P3 — 운영 1~3개월 후 단계 도입 권장 (편집 워크플로 합의·페이지네이션 정책 확정 후)
| 필드 | 의미 |
|---|---|
content | 검색 결과 본문 (엔티티·관계·청크·출처 목록을 마크다운 섹션으로 합성) |
metadata.references[] | 참조 문서 목록 (reference_id, file_path, page) — 호스트 측 원문 뷰어 점프에 사용 |
score[] | 청크 단위 재정렬 점수 — mode="deep" 호출 시 채워짐 |
latency | 검색 단계 지연 (초) |