feat(mcp): add retrieve docs explain diagnostics

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: tae2089

internal/mcp/handler_docs.go

@@ -331,6 +331,7 @@ func (h *handlers) retrieveDocs(ctx context.Context, request mcp.CallToolRequest
 	if contentLimit > 20000 {
 		return mcp.NewToolResultError("content_limit must be <= 20000"), nil
 	}
+	explain := request.GetBool("explain", false)
 
 	namespace := requestNamespace(request)
 	indexPath, err := h.resolvedRagIndexPath(namespace)
@@ -349,14 +350,15 @@ func (h *handlers) retrieveDocs(ctx context.Context, request mcp.CallToolRequest
 		"content_limit": contentLimit,
 		"namespace":     namespace,
 		"mtime":         indexMtime,
+		"explain":       explain,
 	}
 	return finalizeToolResult(h.cachedExecute(ctx, "retrieve_docs:", cacheKey, func() (string, error) {
 		idx, err := ragindex.LoadIndex(indexPath)
 		if err != nil {
 			return "", newToolResultErr(fmt.Sprintf("load doc-index: %v", err))
 		}
 
-		candidates := ragindex.Retrieve(idx.Root, query, pageReq.Limit)
+		candidates := ragindex.RetrieveWithOptions(idx.Root, query, pageReq.Limit, ragindex.RetrieveOptions{Explain: explain})
 		response := retrieveDocsResponse{Results: make([]retrieveDocsResult, 0, len(candidates))}
 		for _, candidate := range candidates {
 			result := retrieveDocsResult{RetrieveResult: candidate}

internal/mcp/handler_docs_test.go

@@ -445,6 +445,67 @@ func TestRetrieveDocs_ExposesStructuredMatchedFields(t *testing.T) {
 	}
 }
 
+func TestRetrieveDocs_ExplainFlagControlsDiagnostics(t *testing.T) {
+	deps := setupTestDeps(t)
+	tmpDir := t.TempDir()
+	docsDir := filepath.Join(tmpDir, "docs")
+	deps.RagIndexDir = filepath.Join(tmpDir, ".ccg")
+
+	comm := model.Community{Key: "billing", Label: "Billing", Description: "billing pipeline"}
+	if err := deps.DB.Create(&comm).Error; err != nil {
+		t.Fatalf("create community: %v", err)
+	}
+	node := model.Node{QualifiedName: "billing.PaymentProcessor", Kind: model.NodeKindFunction, Name: "PaymentProcessor", FilePath: "internal/billing/processor.go", StartLine: 1, EndLine: 30, 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, Summary: "payment processor entrypoint"}
+	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.TagIntent, Value: "payment settlement entrypoint", Ordinal: 0}).Error; err != nil {
+		t.Fatalf("create intent tag: %v", err)
+	}
+
+	docPath := filepath.Join(docsDir, "internal/billing/processor.go.md")
+	if err := os.MkdirAll(filepath.Dir(docPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(docPath, []byte("# processor.go\n\npayment processor docs\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	b := &ragindex.Builder{DB: deps.DB, IndexDir: deps.RagIndexDir, OutDir: docsDir}
+	if _, _, err := b.Build(context.Background()); err != nil {
+		t.Fatalf("Build: %v", err)
+	}
+
+	defaultRes := callTool(t, deps, "retrieve_docs", map[string]any{"query": "payment", "limit": float64(3), "content_limit": float64(0)})
+	if defaultRes.IsError {
+		t.Fatalf("retrieve_docs default error: %v", getTextContent(defaultRes))
+	}
+	defaultJSON := getTextContent(defaultRes)
+	for _, key := range []string{"expanded_terms", "field_scores", "literal_score", "expansion_score"} {
+		if strings.Contains(defaultJSON, key) {
+			t.Fatalf("default response must omit %q diagnostic key, got %s", key, defaultJSON)
+		}
+	}
+
+	explainRes := callTool(t, deps, "retrieve_docs", map[string]any{"query": "payment", "limit": float64(3), "content_limit": float64(0), "explain": true})
+	if explainRes.IsError {
+		t.Fatalf("retrieve_docs explain error: %v", getTextContent(explainRes))
+	}
+	explainJSON := getTextContent(explainRes)
+	for _, key := range []string{"field_scores", "literal_score"} {
+		if !strings.Contains(explainJSON, key) {
+			t.Fatalf("explain response must include %q, got %s", key, explainJSON)
+		}
+	}
+}
+
 func TestRetrieveDocs_ContentLimitZeroOmitsContent(t *testing.T) {
 	deps := setupTestDeps(t)
 	tmpDir := t.TempDir()

internal/mcp/tools_docs.go

@@ -53,6 +53,7 @@ func docsTools(h *handlers) []server.ServerTool {
 				mcp.WithNumber("limit", mcp.Description("Maximum number of document results (default: 5, max: 50)")),
 				mcp.WithNumber("content_limit", mcp.Description("Maximum bytes of Markdown content per result (default: 4000, max: 20000; use 0 to omit content)")),
 				mcp.WithString("namespace", mcp.Description("Namespace. When set, retrieves from the namespace-specific doc-index.json.")),
+				mcp.WithBoolean("explain", mcp.Description("When true, include per-result expanded_terms, field_scores, literal_score, and expansion_score diagnostics (default: false).")),
 			),
 			Handler: h.retrieveDocs,
 		},