feat: federate search, query_graph, list_graph_stats, and search_docs across namespaces

Add an optional 'namespaces' array parameter to the four read tools.
Federation fans out per namespace at the handler level so every store
query path keeps its single-namespace invariant:

- search merges per-namespace candidate pools, reranks once, and labels
  each item with its namespace (single-namespace responses are
  byte-identical to before).
- query_graph runs the extracted per-namespace body for each namespace
  and groups outcomes; a missing target in one namespace becomes a
  per-namespace error instead of failing the call.
- list_graph_stats and search_docs return per-namespace groups without
  merging counts across unrelated graphs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: tae2089

internal/adapters/inbound/mcp/handler_docs.go

@@ -10,6 +10,8 @@ import (
 	"strings"
 
 	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/tae2089/trace"
+
 	"github.com/tae2089/code-context-graph/internal/app/wiki"
 	requestctx "github.com/tae2089/code-context-graph/internal/ctx"
 )
@@ -104,6 +106,11 @@ func (h *handlers) searchDocs(ctx context.Context, request mcp.CallToolRequest)
 	if h.deps.Docs.Retrieval == nil {
 		return mcp.NewToolResultError("DB is not configured"), nil
 	}
+
+	if namespaces := requestNamespaces(request); len(namespaces) > 0 {
+		return h.searchDocsFederated(ctx, query, limit, namespaces)
+	}
+
 	return finalizeToolResult(h.cachedExecute(ctx, "search_docs:db:", map[string]any{"query": query, "limit": limit, "namespace": namespace}, func() (string, error) {
 		results, err := h.searchDocsFromDB(ctx, namespace, query, limit)
 		if err != nil {
@@ -114,6 +121,34 @@ func (h *handlers) searchDocs(ctx context.Context, request mcp.CallToolRequest)
 	}))
 }
 
+// federatedDocsEntry labels one namespace's documentation candidates in a federated response.
+// @intent keep doc candidates attributable to their source repository.
+type federatedDocsEntry struct {
+	Namespace string              `json:"namespace"`
+	Results   []wiki.SearchResult `json:"results"`
+}
+
+// searchDocsFederated searches documentation candidates across several namespaces.
+// @intent let one docs query cover multiple repositories with per-namespace grouping.
+func (h *handlers) searchDocsFederated(ctx context.Context, query string, limit int, namespaces []string) (*mcp.CallToolResult, error) {
+	return finalizeToolResult(h.cachedExecute(ctx, "search_docs:db:", map[string]any{"query": query, "limit": limit, "namespaces": namespaces}, func() (string, error) {
+		entries := make([]federatedDocsEntry, 0, len(namespaces))
+		for _, ns := range namespaces {
+			nsCtx := requestctx.WithNamespace(ctx, ns)
+			results, err := h.searchDocsFromDB(nsCtx, ns, query, limit)
+			if err != nil {
+				return "", newToolResultErr(err.Error())
+			}
+			entries = append(entries, federatedDocsEntry{Namespace: ns, Results: results})
+		}
+		b, err := json.Marshal(map[string]any{"namespaces": entries})
+		if err != nil {
+			return "", trace.Wrap(err, "marshal result")
+		}
+		return string(b), nil
+	}))
+}
+
 // @intent search persisted graph nodes directly from DB and search backend.
 // @requires ctx must carry the selected namespace for SearchBackend.Query.
 // @ensures returns SearchResult-compatible JSON items without requiring generated index files.

internal/adapters/inbound/mcp/handler_federated_test.go

@@ -0,0 +1,190 @@
+package mcp
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+func seedFederatedNamespaces(t *testing.T, deps *Deps) {
+	t.Helper()
+	write := func(dir, rel, content string) string {
+		t.Helper()
+		full := filepath.Join(dir, rel)
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatalf("mkdir: %v", err)
+		}
+		if err := os.WriteFile(full, []byte(content), 0o644); err != nil {
+			t.Fatalf("write: %v", err)
+		}
+		return full
+	}
+	alphaDir := t.TempDir()
+	betaDir := t.TempDir()
+	deps.Runtime.RepoRoot = filepath.Dir(alphaDir)
+	write(alphaDir, "pay.go", "package alpha\n\nfunc PaymentProcess() string {\n\treturn \"payment\"\n}\n")
+	write(betaDir, "refund.go", "package beta\n\nfunc PaymentRefund() string {\n\treturn \"payment\"\n}\n")
+
+	deps.Runtime.RepoRoot = alphaDir
+	if res := callTool(t, deps, "build_or_update_graph", map[string]any{"path": alphaDir, "namespace": "alpha"}); res.IsError {
+		t.Fatalf("parse alpha failed: %+v", res)
+	}
+	deps.Runtime.RepoRoot = betaDir
+	if res := callTool(t, deps, "build_or_update_graph", map[string]any{"path": betaDir, "namespace": "beta"}); res.IsError {
+		t.Fatalf("parse beta failed: %+v", res)
+	}
+}
+
+func resultTextOf(t *testing.T, result *mcp.CallToolResult) string {
+	t.Helper()
+	if result.IsError {
+		t.Fatalf("tool returned error: %+v", result.Content)
+	}
+	for _, content := range result.Content {
+		if text, ok := content.(mcp.TextContent); ok {
+			return text.Text
+		}
+		if text, ok := content.(*mcp.TextContent); ok {
+			return text.Text
+		}
+	}
+	t.Fatal("no text content in result")
+	return ""
+}
+
+func TestSearch_FederatesAcrossNamespaces(t *testing.T) {
+	deps := setupTestDeps(t)
+	seedFederatedNamespaces(t, deps)
+
+	result := callTool(t, deps, "search", map[string]any{
+		"query":      "Payment",
+		"namespaces": []string{"alpha", "beta"},
+	})
+	var items []struct {
+		QualifiedName string `json:"qualified_name"`
+		Namespace     string `json:"namespace"`
+	}
+	if err := json.Unmarshal([]byte(resultTextOf(t, result)), &items); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	seen := map[string]string{}
+	for _, item := range items {
+		seen[item.QualifiedName] = item.Namespace
+	}
+	if seen["alpha.PaymentProcess"] != "alpha" || seen["beta.PaymentRefund"] != "beta" {
+		t.Fatalf("federated search items = %v, want hits from both namespaces with labels", seen)
+	}
+}
+
+func TestSearch_SingleNamespaceResponseUnchanged(t *testing.T) {
+	deps := setupTestDeps(t)
+	seedFederatedNamespaces(t, deps)
+
+	result := callTool(t, deps, "search", map[string]any{"query": "Payment", "namespace": "alpha"})
+	text := resultTextOf(t, result)
+	var raw []map[string]any
+	if err := json.Unmarshal([]byte(text), &raw); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if len(raw) == 0 {
+		t.Fatal("single-namespace search returned no results")
+	}
+	for _, item := range raw {
+		if _, exists := item["namespace"]; exists {
+			t.Fatalf("single-namespace response gained a namespace field: %v", item)
+		}
+	}
+}
+
+func TestListGraphStats_FederatesAcrossNamespaces(t *testing.T) {
+	deps := setupTestDeps(t)
+	seedFederatedNamespaces(t, deps)
+
+	result := callTool(t, deps, "list_graph_stats", map[string]any{"namespaces": []string{"alpha", "beta"}})
+	var payload struct {
+		Namespaces []struct {
+			Namespace  string `json:"namespace"`
+			TotalNodes int64  `json:"total_nodes"`
+		} `json:"namespaces"`
+	}
+	if err := json.Unmarshal([]byte(resultTextOf(t, result)), &payload); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if len(payload.Namespaces) != 2 {
+		t.Fatalf("stats groups = %d, want 2", len(payload.Namespaces))
+	}
+	for _, group := range payload.Namespaces {
+		if group.TotalNodes == 0 {
+			t.Fatalf("namespace %q has zero nodes in federated stats", group.Namespace)
+		}
+	}
+}
+
+func TestQueryGraph_FederatesAcrossNamespaces(t *testing.T) {
+	deps := setupTestDeps(t)
+	seedFederatedNamespaces(t, deps)
+
+	result := callTool(t, deps, "query_graph", map[string]any{
+		"pattern":    "callers_of",
+		"target":     "alpha.PaymentProcess",
+		"namespaces": []string{"alpha", "beta"},
+	})
+	var payload struct {
+		Pattern    string `json:"pattern"`
+		Namespaces []struct {
+			Namespace string          `json:"namespace"`
+			Response  json.RawMessage `json:"response,omitempty"`
+			Error     string          `json:"error,omitempty"`
+		} `json:"namespaces"`
+	}
+	if err := json.Unmarshal([]byte(resultTextOf(t, result)), &payload); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if len(payload.Namespaces) != 2 {
+		t.Fatalf("query groups = %d, want 2", len(payload.Namespaces))
+	}
+	byNS := map[string]json.RawMessage{}
+	errsByNS := map[string]string{}
+	for _, group := range payload.Namespaces {
+		byNS[group.Namespace] = group.Response
+		errsByNS[group.Namespace] = group.Error
+	}
+	if len(byNS["alpha"]) == 0 {
+		t.Fatalf("alpha response missing: %+v", payload)
+	}
+	if errsByNS["beta"] == "" {
+		t.Fatalf("beta should report a per-namespace error for missing file, got %+v", payload)
+	}
+}
+
+func TestSearchDocs_FederatesAcrossNamespaces(t *testing.T) {
+	deps := setupTestDeps(t)
+	seedFederatedNamespaces(t, deps)
+
+	result := callTool(t, deps, "search_docs", map[string]any{
+		"query":      "Payment",
+		"namespaces": []string{"alpha", "beta"},
+	})
+	var payload struct {
+		Namespaces []struct {
+			Namespace string `json:"namespace"`
+			Results   []struct {
+				Label string `json:"label"`
+			} `json:"results"`
+		} `json:"namespaces"`
+	}
+	if err := json.Unmarshal([]byte(resultTextOf(t, result)), &payload); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if len(payload.Namespaces) != 2 {
+		t.Fatalf("docs groups = %d, want 2", len(payload.Namespaces))
+	}
+	for _, group := range payload.Namespaces {
+		if len(group.Results) == 0 {
+			t.Fatalf("namespace %q returned no doc candidates", group.Namespace)
+		}
+	}
+}