Remove the retrieve_docs MCP tool; keep search_docs + get_doc_content

retrieve_docs was search_docs (find relevant docs) + get_doc_content (read one)
composed into a single call, plus opt-in scoring "explain" diagnostics agents
rarely use. It overlapped the core doc-search surface, so drop it and let
callers compose search_docs -> get_doc_content.

- remove the retrieve_docs MCP tool: handler, DB helper, response DTO aliases,
  and the retrieve_docs-only doc-content readers (readIndexedDocContent /
  resolveIndexedDocPath) in internal/mcp/handler_docs.go; registration in
  tools_docs.go
- collapse the shared retrieval engine now that the explain path is gone:
  FromDBWithOptions folds into FromDB, BuildDBResultWithOptions into
  BuildDBResult; delete the Options{Explain} type and the dead MatchedFields /
  ScoreDBFieldBreakdown helpers
- drop the four explain-only fields (field_scores, literal_score,
  expanded_terms, expansion_score) from ragindex.RetrieveResult
- sweep docs/skills to route doc retrieval through search_docs + get_doc_content

search_docs, get_doc_content, the retrieval scoring core, ragindex, and the Wiki
are unchanged — they only ever used the non-explain path, so their behavior is
byte-identical (independently reviewed). MCP tools 26 -> 25.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: tae2089

AGENTS.md

@@ -14,7 +14,7 @@ The ccg MCP server registered in `.mcp.json` provides 33 tools:
 - `detect_changes`, `get_affected_flows`, `list_flows`
 - `list_communities`, `get_community`, `get_architecture_overview`
 - `get_annotation`
-- `build_rag_index`, `get_rag_tree`, `get_doc_content`, `search_docs`, `retrieve_docs`
+- `build_rag_index`, `get_rag_tree`, `get_doc_content`, `search_docs`
 - `upload_file`, `upload_files`, `list_namespaces`, `list_files`, `delete_file`, `delete_namespace`
 
 `ccg serve` is the local stdio MCP entry point. Self-hosted HTTP mode is provided by
@@ -58,7 +58,7 @@ Use `.ccg.yaml` to manage project defaults such as exclude patterns and DB setti
 When looking for code locations, related implementations, call relationships, impact radius, or architecture context,
 use ccg MCP tools and Agent Skills first.
 
-- For natural-language code understanding, module exploration, and architecture context, prefer the `/ccg-docs` skill and `retrieve_docs`, `get_rag_tree`, `get_doc_content`.
+- For natural-language code understanding, module exploration, and architecture context, prefer the `/ccg-docs` skill: use `search_docs` to find relevant docs, then `get_doc_content` to read one (with `get_rag_tree` for module context).
 - For exact symbol locations, call relationships, and graph metadata, use ccg MCP `query_graph`, `get_node`, `get_minimal_context`, or the `/ccg` skill.
 - For annotation/keyword-based candidate search, use ccg MCP `search` or `ccg search` as a supplement.
 - For impact radius, flows, dead code, and structural analysis, prefer the `/ccg-analyze` skill and related MCP tools (`get_impact_radius`, `trace_flow`, `find_dead_code`, `get_architecture_overview`).

CLAUDE.md

@@ -6,15 +6,15 @@ Follow the global prompt rules first. This file adds project-specific skill rout
 
 ## MCP 서버
 
-`.mcp.json`에 등록된 ccg MCP 서버가 26개 도구를 제공합니다:
+`.mcp.json`에 등록된 ccg MCP 서버가 25개 도구를 제공합니다:
 
 - `parse_project`, `build_or_update_graph`, `run_postprocess`
 - `get_postprocess_policy`, `reset_postprocess_policy`
 - `get_node`, `search`, `query_graph`, `list_graph_stats`, `get_minimal_context`
 - `get_impact_radius`, `trace_flow`, `find_suspect_fallback_edges`
 - `detect_changes`, `get_affected_flows`, `list_flows`
 - `get_annotation`
-- `get_doc_content`, `search_docs`, `retrieve_docs`
+- `get_doc_content`, `search_docs`
 - `upload_file`, `upload_files`, `list_files`, `delete_file`, `list_namespaces`, `delete_namespace`
 
 HTTP 모드 (`--transport streamable-http`)에서는 `/health` 및 `/webhook` 엔드포인트도 제공합니다.

README.md

@@ -94,18 +94,18 @@ Wiki compatibility snapshot. The Wiki prefers the graph database for tree
 navigation and search, then uses `wiki-index.json` only when DB-backed
 navigation is unavailable. By default `ccg docs` also refreshes community
 structure and writes `.ccg/doc-index.json` as a compatibility snapshot for
-manual RAG-index workflows; runtime `retrieve_docs` uses DB-backed graph and
+manual RAG-index workflows; runtime `search_docs` uses DB-backed graph and
 annotation evidence. Use `--rag=false` when you only want Markdown and the Wiki
 snapshot, or `--rag-refresh=false` when you want to rebuild the RAG index from
 existing community rows without recalculating communities.
 
-For LLM agents, use DB-backed `retrieve_docs` as the first stop for broad
+For LLM agents, use DB-backed `search_docs` as the first stop for broad
 natural-language questions such as "how does webhook sync work?" or "where are
 the operational risks?". It is not a Top1 search engine; it is an
 evidence-driven narrowing layer that should return a small set of relevant
-files with `matched_fields`, `matched_terms`, and evidence nodes. Use
-`get_doc_content`, `get_node`, `query_graph`, `trace_flow`, and impact tools
-only after the route is narrowed. Use `ccg search` as a focused
+files with `matched_fields`, `matched_terms`, and evidence nodes. Read the
+narrowed docs with `get_doc_content`, then use `get_node`, `query_graph`,
+`trace_flow`, and impact tools only after the route is narrowed. Use `ccg search` as a focused
 annotation/keyword candidate search rather than the first tool for broad code
 understanding.
 
@@ -125,7 +125,7 @@ size stays small.
 The Wiki is meant for developers and agents inspecting a generated codebase:
 
 - Tree navigation over folders, packages, files, and annotated symbols
-- Keyword search and DB-backed `retrieve_docs` with matched evidence and small
+- Keyword search and DB-backed `search_docs` with matched evidence and small
   file-level result sets
 - Rich symbol detail cards from CCG annotations even when a symbol has no
   generated Markdown file

guide/README.md

@@ -2,10 +2,11 @@
 
 Documentation index for code-context-graph.
 
-For LLM-agent workflows, start natural-language code exploration from
-DB-backed `retrieve_docs`. It is an evidence-driven narrowing layer, not a Top1
-search engine: use its small file-level candidates, matched fields, and evidence
-nodes to choose the shortest route into docs or graph tools.
+For LLM-agent workflows, start natural-language code exploration from the
+docs/RAG path: use `search_docs` to find relevant docs, then `get_doc_content`
+to read one. Treat these as an evidence-driven narrowing layer, not a Top1
+search engine: use the small file-level candidates to choose the shortest route
+into docs or graph tools.
 
 The browser Wiki is served by `ccg-server` when `--wiki-dir` points at built
 React assets. It prefers the graph database for presentation, uses

guide/annotations.md

@@ -6,9 +6,9 @@ focused search can leverage business context. Annotations are indexed for
 index.
 
 For LLM-agent natural-language exploration, prefer the docs/RAG path first:
-`ccg docs`, then MCP `retrieve_docs`, `get_rag_tree`, and `get_doc_content`.
-Use `ccg search` when you need a focused list of
-annotation/keyword-matched symbol candidates.
+`ccg docs`, then use MCP `search_docs` to find relevant docs and `get_doc_content`
+to read one (with `get_rag_tree` for module context). Use `ccg search` when you
+need a focused list of annotation/keyword-matched symbol candidates.
 
 Annotation quality is validated by `ccg lint`. For category meanings such as `unannotated`, `incomplete`, `dead-ref`, `contradiction`, and `drifted`, see [Lint Guide](lint.md).
 
@@ -65,7 +65,7 @@ The path and symbol are optional, so `ccg://auth-svc/internal/auth` can point at
 
 ## Retrieval Quality
 
-Annotations are retrieval features. `retrieve_docs` and generated docs rank
+Annotations are retrieval features. `search_docs` and generated docs rank
 file-level evidence from structured buckets such as `@index`, `@intent`,
 `@domainRule`, `@sideEffect`, `@requires`, `@ensures`, and `@see`. Better
 annotations make natural-language retrieval more precise, but only when the

guide/cli-reference.md

@@ -72,7 +72,7 @@ CCG has two search surfaces with different jobs:
 
 | Use case | Preferred entrypoint |
 |----------|----------------------|
-| Natural-language code understanding, module exploration, architecture questions | `ccg docs`, then MCP `retrieve_docs`, `get_rag_tree`, `get_doc_content` |
+| Natural-language code understanding, module exploration, architecture questions | `ccg docs`, then MCP `search_docs`, `get_rag_tree`, `get_doc_content` |
 | Exact symbol lookup, callers/callees, imports, bounded graph traversal | MCP `get_node`, `query_graph`, `get_minimal_context` |
 | Impact analysis, flow tracing | MCP analysis tools such as `get_impact_radius`, `trace_flow` |
 | Focused annotation/keyword candidate search | `ccg search` or MCP `search` |
@@ -104,12 +104,11 @@ Use `--rag-refresh=false` only when you intentionally want to reuse existing
 community rows. The standalone `ccg rag-index` command remains available for
 manual rebuilds from generated docs and already-computed communities.
 
-Then use MCP `retrieve_docs` to retrieve file-level candidates and bounded
-Markdown content with matched fields and graph evidence. Use `get_rag_tree` to expand the
-module/community context and `get_doc_content` to read a specific generated doc
-directly. `search_docs` and `ccg search` remain useful for quick keyword or
-annotation matches, but they should not be treated as the primary answering
-surface for broad natural-language questions.
+Then use MCP `search_docs` to find relevant docs and `get_doc_content` to read
+one directly. Use `get_rag_tree` to expand the module/community context before
+drilling into a specific generated doc. `ccg search` remains useful for quick
+keyword or annotation matches over symbols, but it should not be treated as the
+primary answering surface for broad natural-language questions.
 
 ### Database Choice
 

guide/ko/README.md

@@ -6,10 +6,10 @@ code-context-graph의 문서 인덱스입니다. 한국어 문서는 영어 가
 
 CCG는 GPT, Claude, Codex 같은 LLM 기반 코딩 에이전트가 개발 중 코드베이스 맥락을 정확하고 작게 가져오도록 만든 로컬/셀프호스트 context infrastructure입니다. 일반 SaaS 관리자용 제품이 아니라, CLI, MCP, 로그, 문서를 이해하는 개발자와 코딩 에이전트가 코드 검색, 영향 분석, 호출 그래프, 문서/RAG, bounded response를 활용하도록 설계되었습니다.
 
-LLM 에이전트 워크플로우에서는 자연어 기반 코드 탐색을 DB-backed
-`retrieve_docs`에서 시작하십시오. Top1 정답을 강제하기보다 작은 파일 후보,
-matched fields, evidence node로 빠르게 경로를 좁힌 뒤 graph/search 도구로
-정확한 위치와 관계를 확인하는 흐름을 권장합니다.
+LLM 에이전트 워크플로우에서는 자연어 기반 코드 탐색을 docs/RAG 경로에서
+시작하십시오. `search_docs`로 관련 문서를 찾은 뒤 `get_doc_content`로 하나를
+읽습니다. Top1 정답을 강제하기보다 작은 파일 후보로 빠르게 경로를 좁힌 뒤
+graph/search 도구로 정확한 위치와 관계를 확인하는 흐름을 권장합니다.
 
 브라우저 Wiki는 `ccg-server`에서 `--wiki-dir`가 빌드된 React asset을
 가리킬 때 제공됩니다. 표시는 graph database를 우선 사용하고,

guide/ko/annotations.md

@@ -4,7 +4,7 @@
 
 코드에 구조화된 메타데이터를 추가하여 AI, 생성 문서, RAG, 집중 검색이 비즈니스 컨텍스트를 활용할 수 있도록 합니다. 어노테이션은 `ccg search`를 위해 인덱싱되며, RAG 인덱스의 입력이 되는 생성 Markdown에도 반영됩니다.
 
-LLM 에이전트의 자연어 기반 코드 탐색에는 docs/RAG 경로를 먼저 사용하십시오. `ccg docs`를 실행한 뒤 MCP `retrieve_docs`, `get_rag_tree`, `get_doc_content`를 사용합니다. `ccg search`는 어노테이션/키워드에 매칭되는 심볼 후보 목록이 필요할 때 사용하십시오.
+LLM 에이전트의 자연어 기반 코드 탐색에는 docs/RAG 경로를 먼저 사용하십시오. `ccg docs`를 실행한 뒤 MCP `search_docs`로 관련 문서를 찾고 `get_doc_content`로 하나를 읽습니다(모듈 맥락은 `get_rag_tree`). `ccg search`는 어노테이션/키워드에 매칭되는 심볼 후보 목록이 필요할 때 사용하십시오.
 
 어노테이션 품질은 `ccg lint`에 의해 검증됩니다. `unannotated`, `incomplete`, `dead-ref`, `contradiction`, `drifted`와 같은 카테고리의 의미는 [Lint 가이드](lint.md)를 참조하십시오.
 
@@ -61,7 +61,7 @@ path와 symbol은 선택 사항입니다. `ccg://auth-svc/internal/auth`는 패
 
 ## Retrieval 품질 (Retrieval Quality)
 
-어노테이션은 retrieval feature입니다. `retrieve_docs`와 생성 문서는
+어노테이션은 retrieval feature입니다. `search_docs`와 생성 문서는
 `@index`, `@intent`, `@domainRule`, `@sideEffect`, `@requires`, `@ensures`,
 `@see` 같은 구조화된 bucket을 파일 단위 근거로 점수화합니다. 자연어 검색
 품질은 좋은 어노테이션으로 올라가지만, 태그가 실제 동작을 설명할 때만

guide/ko/cli-reference.md

@@ -74,7 +74,7 @@ CCG에는 역할이 다른 두 검색 표면이 있습니다.
 
 | 사용 사례 | 우선 진입점 |
 |----------|-------------|
-| 자연어 기반 코드 이해, 모듈 탐색, 아키텍처 질문 | `ccg docs`, 이후 MCP `retrieve_docs`, `get_rag_tree`, `get_doc_content` |
+| 자연어 기반 코드 이해, 모듈 탐색, 아키텍처 질문 | `ccg docs`, 이후 MCP `search_docs`, `get_rag_tree`, `get_doc_content` |
 | 정확한 심볼 조회, caller/callee, import, bounded graph traversal | MCP `get_node`, `query_graph`, `get_minimal_context` |
 | 영향 분석, flow 추적 | `get_impact_radius`, `trace_flow` 같은 MCP 분석 도구 |
 | 어노테이션/키워드 기반 후보 검색 | `ccg search` 또는 MCP `search` |
@@ -105,7 +105,7 @@ file/symbol node를 같은 문서 viewer로 엽니다.
 `--rag-refresh=false`를 사용하십시오. 독립 `ccg rag-index` 명령은 생성 문서와
 이미 계산된 community를 사용한 수동 재생성 용도로 남아 있습니다.
 
-그 다음 MCP `retrieve_docs`로 파일 단위 후보와 제한된 Markdown 본문을 matched fields 및 graph evidence와 함께 가져옵니다. `get_rag_tree`로 모듈/커뮤니티 맥락을 펼치고, `get_doc_content`로 특정 생성 문서를 직접 읽은 뒤 정확한 graph 도구로 내려갑니다. `search_docs`와 `ccg search`는 빠른 키워드 또는 어노테이션 매칭에는 유용하지만, 넓은 자연어 질문의 기본 응답 표면으로 보기는 어렵습니다.
+그 다음 MCP `search_docs`로 관련 문서를 찾고 `get_doc_content`로 하나를 직접 읽습니다. `get_rag_tree`로 모듈/커뮤니티 맥락을 펼친 뒤 특정 생성 문서로 내려갑니다. `ccg search`는 빠른 키워드 또는 심볼 어노테이션 매칭에는 유용하지만, 넓은 자연어 질문의 기본 응답 표면으로 보기는 어렵습니다.
 
 ### 데이터베이스 선택 (Database Choice)
 

guide/ko/mcp-tools.md

@@ -103,39 +103,23 @@ CCG는 아직 Prometheus `/metrics` 엔드포인트를 제공하지 않습니다
 | `get_rag_tree` | node ID 기반 RAG 문서 트리 탐색 (네임스페이스 지원) |
 | `get_doc_content` | 문서 파일 내용 확인 (네임스페이스 지원) |
 | `search_docs` | 키워드로 RAG 문서 트리 검색 (네임스페이스 지원) |
-| `retrieve_docs` | DB-backed graph evidence에서 관련 문서를 찾고, matched fields, evidence node, 제한된 Markdown 본문 반환 |
 
-자연어 기반 코드 이해에는 `retrieve_docs`를 먼저 사용하십시오.
-`retrieve_docs`는 file-level graph/annotation evidence를 점수화하므로 여러
-키워드가 관련 심볼에 나뉘어 있어도 같은 문서를 후보로 찾고, 제한된 Markdown
-본문과 evidence를 반환합니다. Top1 정답을 보장하기보다 Top10 후보를 작게
-좁히는 evidence-driven retrieval layer입니다. `get_rag_tree`는 주변 모듈 구조를 펼칩니다. 먼저
+자연어 기반 코드 이해에는 `search_docs`로 관련 문서를 찾은 뒤
+`get_doc_content`로 하나를 읽으십시오. `search_docs`는 키워드로 RAG 문서
+트리를 검색해 후보 문서를 반환하고, `get_doc_content`는 특정 생성 Markdown
+파일을 직접 읽습니다. `get_rag_tree`는 주변 모듈 구조를 펼칩니다. 먼저
 인자 없이 호출해 tree를 받고, 반환된 `node_id`를 넘겨 `community`,
 `package`, `file`, `symbol` 노드로 내려갑니다. 기존 `community_id`
-파라미터는 `node_id`의 호환 alias로 유지됩니다. `get_doc_content`는
-특정 생성 Markdown 파일을 직접 읽습니다. 이후 정확한
+파라미터는 `node_id`의 호환 alias로 유지됩니다. 이후 정확한
 심볼, edge, flow, 영향 범위가 필요할 때 `get_node`, `query_graph`,
 `trace_flow`, `get_impact_radius` 같은 graph 도구로 내려가십시오.
-`search_docs` 또는 MCP `search`는 넓은 아키텍처 질문이나 "어떻게
-동작하나?" 류의 기본 표면이 아니라, 어노테이션/키워드 기반 후보 검색에
-사용하는 것을 권장합니다.
-
-`retrieve_docs`의 score는 같은 query 결과 안에서 순위를 정하기 위한
-신호이며, 절대적인 품질 점수가 아닙니다. 서로 다른 query의 score를 직접
-비교하는 용도로는 사용하지 마십시오. 현재 DB-backed 점수는 정확한 심볼/파일
-이름과 high-signal annotation bucket을 우선합니다. exact label, label
-contains, `qualified_name`, `@intent`, `@index`, `@domainRule`, `@requires`,
-`@ensures`, `@sideEffect`, `@mutates`, `@see`, generic annotation text가
-가중치에 반영되고, 매칭된 고유 query term마다 ranking bonus가 추가됩니다.
-`matched_fields`, `matched_terms`, `matches`가 어떤 field, term, graph node가
-근거로 사용됐는지 보여줍니다.
+MCP `search`는 심볼 대상 어노테이션/키워드 기반 후보 검색에 사용하십시오.
 
 RAG 인덱스 품질은 생성 문서와 비어 있지 않은 community postprocess 결과에
 의존합니다. CLI `ccg docs` 명령은 community를 갱신하고 기본
 `doc-index.json` 호환 snapshot을 수동 RAG-index workflow용으로 자동
 기록합니다. 또한 브라우저 Wiki를 위한 별도 `wiki-index.json` 호환 snapshot도
-기록합니다. Runtime `retrieve_docs`와 Wiki Retrieve는 DB가 설정된 경우 DB를
-사용합니다. MCP만 사용하는 워크플로우에서 community가 없을 수 있으면 `build_rag_index` 전에
+기록합니다. Wiki Retrieve는 DB가 설정된 경우 DB를 사용합니다. MCP만 사용하는 워크플로우에서 community가 없을 수 있으면 `build_rag_index` 전에
 `run_postprocess`를 `communities=true`, `flows=false`, `fts=false`로
 호출하십시오.