feat: add search_docs MCP tool for keyword search in RAG tree

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tae2089

internal/mcp/handlers.go

@@ -1463,6 +1463,41 @@ func (h *handlers) getDocContent(ctx context.Context, request mcp.CallToolReques
 	return mcp.NewToolResultText(result), nil
 }
 
+func (h *handlers) searchDocs(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	query, err := request.RequireString("query")
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("missing parameter: %v", err)), nil
+	}
+	limit := request.GetInt("limit", 10)
+	if limit <= 0 {
+		limit = 10
+	}
+
+	key := "search_docs:" + mustJSON(map[string]any{"query": query, "limit": limit})
+	if h.cache != nil {
+		if cached, ok := h.cache.Get(key); ok {
+			return mcp.NewToolResultText(cached), nil
+		}
+	}
+
+	idx, err := ragindex.LoadIndex(h.ragIndexPath())
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("load doc-index: %v", err)), nil
+	}
+
+	results := ragindex.Search(idx.Root, query, limit)
+
+	b, err := json.Marshal(results)
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("marshal results: %v", err)), nil
+	}
+	resultStr := string(b)
+	if h.cache != nil {
+		h.cache.Set(key, resultStr)
+	}
+	return mcp.NewToolResultText(resultStr), nil
+}
+
 func getBool(request mcp.CallToolRequest, name string, defaultVal bool) bool {
 	if args, ok := request.Params.Arguments.(map[string]any); ok {
 		if v, ok := args[name]; ok {

internal/mcp/handlers_test.go

@@ -2177,3 +2177,67 @@ func TestGetRagTree_DepthLimitsChildren(t *testing.T) {
 		t.Fatalf("expected 0 file children at depth=1, got %d", len(communityNode.Children))
 	}
 }
+
+// TestSearchDocs_ReturnsMatches: query 매칭 결과를 JSON으로 반환한다.
+func TestSearchDocs_ReturnsMatches(t *testing.T) {
+	deps := setupTestDeps(t)
+	tmpDir := t.TempDir()
+	deps.RagIndexDir = tmpDir
+
+	comm := model.Community{Key: "auth", Label: "Auth Service", Description: "인증 레이어"}
+	if err := deps.DB.Create(&comm).Error; err != nil {
+		t.Fatalf("create community: %v", err)
+	}
+	node := model.Node{QualifiedName: "auth/handler.go/Login", Kind: model.NodeKindFunction,
+		Name: "Login", FilePath: "auth/handler.go", StartLine: 1, EndLine: 20, Language: "go"}
+	if err := deps.DB.Create(&node).Error; err != nil {
+		t.Fatalf("create node: %v", err)
+	}
+	if err := deps.DB.Create(&model.CommunityMembership{CommunityID: comm.ID, NodeID: node.ID}).Error; err != nil {
+		t.Fatalf("create membership: %v", err)
+	}
+	ann := model.Annotation{NodeID: node.ID}
+	if err := deps.DB.Create(&ann).Error; err != nil {
+		t.Fatalf("create annotation: %v", err)
+	}
+	if err := deps.DB.Create(&model.DocTag{AnnotationID: ann.ID, Kind: model.TagIndex, Value: "Auth 서비스 핸들러", Ordinal: 0}).Error; err != nil {
+		t.Fatalf("create doc tag: %v", err)
+	}
+
+	b := &ragindex.Builder{DB: deps.DB, IndexDir: tmpDir, OutDir: filepath.Join(tmpDir, "docs")}
+	if _, _, err := b.Build(); err != nil {
+		t.Fatalf("Build: %v", err)
+	}
+
+	result := callTool(t, deps, "search_docs", map[string]any{"query": "auth", "limit": float64(10)})
+	if result.IsError {
+		t.Fatalf("search_docs error: %v", getTextContent(result))
+	}
+
+	var results []ragindex.SearchResult
+	if err := json.Unmarshal([]byte(getTextContent(result)), &results); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if len(results) == 0 {
+		t.Fatal("expected at least 1 search result")
+	}
+}
+
+// TestSearchDocs_MissingQuery: query 파라미터 없으면 에러 반환.
+func TestSearchDocs_MissingQuery(t *testing.T) {
+	deps := setupTestDeps(t)
+	result := callTool(t, deps, "search_docs", map[string]any{})
+	if !result.IsError {
+		t.Fatal("expected error for missing query")
+	}
+}
+
+// TestSearchDocs_NoIndex: doc-index.json 없으면 에러 반환.
+func TestSearchDocs_NoIndex(t *testing.T) {
+	deps := setupTestDeps(t)
+	deps.RagIndexDir = t.TempDir()
+	result := callTool(t, deps, "search_docs", map[string]any{"query": "something"})
+	if !result.IsError {
+		t.Fatal("expected error when index file missing")
+	}
+}

internal/mcp/server.go

@@ -277,6 +277,14 @@ func NewServer(deps *Deps) *server.MCPServer {
 			),
 			Handler: h.getDocContent,
 		},
+		server.ServerTool{
+			Tool: mcp.NewTool("search_docs",
+				mcp.WithDescription("Search the RAG document tree by keyword. Matches against node labels and summaries. Returns breadcrumb paths to matching nodes."),
+				mcp.WithString("query", mcp.Description("Search keyword (case-insensitive)"), mcp.Required()),
+				mcp.WithNumber("limit", mcp.Description("Maximum number of results (default: 10)")),
+			),
+			Handler: h.searchDocs,
+		},
 	)
 
 	log.Info("MCP server created", "name", "code-context-graph", "version", "1.0.0", "prompts", 5)

internal/mcp/server_test.go

@@ -33,6 +33,7 @@ func TestMCPServer_ListTools(t *testing.T) {
 		"build_rag_index",
 		"get_rag_tree",
 		"get_doc_content",
+		"search_docs",
 	}
 
 	if len(tools) != len(expected) {
@@ -62,8 +63,8 @@ func TestMCPServer_ListTools_18(t *testing.T) {
 	srv := NewServer(deps)
 	tools := srv.ListTools()
 
-	if len(tools) != 21 {
-		t.Fatalf("expected 21 tools, got %d", len(tools))
+	if len(tools) != 22 {
+		t.Fatalf("expected 22 tools, got %d", len(tools))
 	}
 }
 

internal/ragindex/builder.go

@@ -351,6 +351,52 @@ func LoadIndex(path string) (*Index, error) {
 	return &idx, nil
 }
 
+// SearchResult는 Search 함수가 반환하는 단일 매칭 결과이다.
+type SearchResult struct {
+	ID      string   `json:"id"`
+	Label   string   `json:"label"`
+	Summary string   `json:"summary"`
+	DocPath string   `json:"doc_path,omitempty"`
+	Path    []string `json:"path"` // root부터 해당 노드까지의 Label 경로
+}
+
+// Search는 root 트리를 DFS로 순회하며 query를 Label과 Summary에서
+// case-insensitive 검색하여 최대 maxResults개의 결과를 반환한다.
+// root 노드 자체는 결과에 포함하지 않는다.
+func Search(root *TreeNode, query string, maxResults int) []SearchResult {
+	if root == nil || query == "" {
+		return nil
+	}
+	q := strings.ToLower(query)
+	results := make([]SearchResult, 0)
+	searchNode(root, q, []string{root.Label}, &results, maxResults)
+	return results
+}
+
+func searchNode(n *TreeNode, query string, path []string, results *[]SearchResult, maxResults int) {
+	for _, child := range n.Children {
+		if len(*results) >= maxResults {
+			return
+		}
+		// 슬라이스 공유 방지를 위해 새 슬라이스로 복사
+		childPath := make([]string, len(path)+1)
+		copy(childPath, path)
+		childPath[len(path)] = child.Label
+
+		if strings.Contains(strings.ToLower(child.Label), query) ||
+			strings.Contains(strings.ToLower(child.Summary), query) {
+			*results = append(*results, SearchResult{
+				ID:      child.ID,
+				Label:   child.Label,
+				Summary: child.Summary,
+				DocPath: child.DocPath,
+				Path:    childPath,
+			})
+		}
+		searchNode(child, query, childPath, results, maxResults)
+	}
+}
+
 // FindNode는 root 트리에서 id와 일치하는 TreeNode를 재귀적으로 찾아 반환한다.
 // 없으면 nil을 반환한다.
 func FindNode(root *TreeNode, id string) *TreeNode {

internal/ragindex/builder_test.go

@@ -516,6 +516,98 @@ func TestBuilder_NoSymbolsWithoutIntent(t *testing.T) {
 	}
 }
 
+// TestSearch_MatchesLabel: query가 label에 매칭되면 결과를 반환한다.
+func TestSearch_MatchesLabel(t *testing.T) {
+	root := &ragindex.TreeNode{
+		ID:    "root",
+		Label: "Root",
+		Children: []*ragindex.TreeNode{
+			{
+				ID:      "community:auth",
+				Label:   "MCP Server",
+				Summary: "핸들러 레이어",
+				Children: []*ragindex.TreeNode{
+					{ID: "file:handlers.go", Label: "handlers.go", Summary: "MCP 핸들러"},
+				},
+			},
+			{
+				ID:      "community:core",
+				Label:   "Core Logic",
+				Summary: "비즈니스 로직",
+			},
+		},
+	}
+
+	results := ragindex.Search(root, "mcp", 10)
+	if len(results) != 2 {
+		t.Fatalf("expected 2 results (community + file), got %d", len(results))
+	}
+}
+
+// TestSearch_CaseInsensitive: 검색은 대소문자를 구분하지 않는다.
+func TestSearch_CaseInsensitive(t *testing.T) {
+	root := &ragindex.TreeNode{
+		ID:    "root",
+		Label: "Root",
+		Children: []*ragindex.TreeNode{
+			{ID: "c1", Label: "Auth Service", Summary: "JWT 인증"},
+		},
+	}
+	results := ragindex.Search(root, "AUTH", 10)
+	if len(results) != 1 {
+		t.Fatalf("expected 1 result, got %d", len(results))
+	}
+}
+
+// TestSearch_MaxResults: maxResults 파라미터가 결과 수를 제한한다.
+func TestSearch_MaxResults(t *testing.T) {
+	children := make([]*ragindex.TreeNode, 10)
+	for i := range children {
+		children[i] = &ragindex.TreeNode{ID: fmt.Sprintf("c%d", i), Label: "test node", Summary: "test"}
+	}
+	root := &ragindex.TreeNode{ID: "root", Children: children}
+
+	results := ragindex.Search(root, "test", 3)
+	if len(results) != 3 {
+		t.Fatalf("expected 3 results (maxResults), got %d", len(results))
+	}
+}
+
+// TestSearch_IncludesBreadcrumb: 결과에 Path(breadcrumb)가 포함된다.
+func TestSearch_IncludesBreadcrumb(t *testing.T) {
+	root := &ragindex.TreeNode{
+		ID:    "root",
+		Label: "Root",
+		Children: []*ragindex.TreeNode{
+			{
+				ID:    "community:auth",
+				Label: "Auth",
+				Children: []*ragindex.TreeNode{
+					{ID: "file:login.go", Label: "login.go", Summary: "로그인 처리"},
+				},
+			},
+		},
+	}
+	results := ragindex.Search(root, "로그인", 10)
+	if len(results) != 1 {
+		t.Fatalf("expected 1 result, got %d", len(results))
+	}
+	if len(results[0].Path) != 3 {
+		t.Fatalf("expected path length 3 (root→auth→file), got %d: %v", len(results[0].Path), results[0].Path)
+	}
+}
+
+// TestSearch_NoMatch: 매칭 없으면 빈 슬라이스 반환.
+func TestSearch_NoMatch(t *testing.T) {
+	root := &ragindex.TreeNode{ID: "root", Label: "Root", Children: []*ragindex.TreeNode{
+		{ID: "c1", Label: "Auth", Summary: "인증"},
+	}}
+	results := ragindex.Search(root, "zzznomatch", 10)
+	if len(results) != 0 {
+		t.Fatalf("expected 0 results, got %d", len(results))
+	}
+}
+
 // TestFindNode: FindNode가 재귀적으로 트리에서 노드를 찾는지 검증한다.
 func TestFindNode(t *testing.T) {
 	root := &ragindex.TreeNode{