refactor(mcp): type evidence responses

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

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

Author: tae2089

internal/mcp/evidence.go

@@ -14,15 +14,32 @@ import (
 
 // workspaceEvidenceFromContext builds evidence metadata for namespace-scoped graph queries.
 // @intent include workspace path and git state when available so LLM has traceable provenance.
-func (h *handlers) workspaceEvidenceFromContext(ctx context.Context) map[string]any {
+func (h *handlers) workspaceEvidenceFromContext(ctx context.Context) workspaceEvidenceBlock {
 	ns := ctxns.FromContext(ctx)
 	return h.workspaceEvidence(ns)
 }
 
+// workspaceEvidenceBlock captures stable workspace provenance fields shared across MCP responses.
+// @intent keep evidence payloads typed while preserving the legacy namespace/workspace/git JSON shape.
+type workspaceEvidenceBlock struct {
+	Namespace     string                    `json:"namespace"`
+	WorkspacePath string                    `json:"workspace_path,omitempty"`
+	Git           *workspaceGitEvidenceBlock `json:"git,omitempty"`
+}
+
+// workspaceGitEvidenceBlock captures git provenance attached to workspace evidence.
+// @intent preserve the legacy git evidence keys while making nil-versus-false behavior explicit.
+type workspaceGitEvidenceBlock struct {
+	Branch string `json:"branch"`
+	Commit string `json:"commit"`
+	Dirty  *bool  `json:"dirty,omitempty"`
+	Remote string `json:"remote,omitempty"`
+}
+
 // @intent collect namespace-scoped workspace and git provenance so MCP responses can explain where graph evidence came from.
-func (h *handlers) workspaceEvidence(namespace string) map[string]any {
+func (h *handlers) workspaceEvidence(namespace string) workspaceEvidenceBlock {
 	ns := ctxns.Normalize(namespace)
-	evidence := map[string]any{"namespace": ns}
+	evidence := workspaceEvidenceBlock{Namespace: ns}
 
 	root := h.deps.WorkspaceRoot
 	if root == "" {
@@ -35,17 +52,17 @@ func (h *handlers) workspaceEvidence(namespace string) map[string]any {
 		return evidence
 	}
 
-	evidence["workspace_path"] = workspacePath
+	evidence.WorkspacePath = workspacePath
 
 	gitInfo := workspaceGitEvidence(workspacePath)
-	if len(gitInfo) > 0 {
-		evidence["git"] = gitInfo
+	if gitInfo != nil {
+		evidence.Git = gitInfo
 	}
 	return evidence
 }
 
 // @intent summarize git branch, commit, remote, and dirty state for workspace-scoped evidence blocks.
-func workspaceGitEvidence(path string) map[string]any {
+func workspaceGitEvidence(path string) *workspaceGitEvidenceBlock {
 	repo, err := git.PlainOpenWithOptions(path, &git.PlainOpenOptions{DetectDotGit: true})
 	if err != nil {
 		return nil
@@ -56,15 +73,16 @@ func workspaceGitEvidence(path string) map[string]any {
 		return nil
 	}
 
-	info := map[string]any{
-		"branch": branchNameForRef(head.Name()),
-		"commit": head.Hash().String(),
+	info := &workspaceGitEvidenceBlock{
+		Branch: branchNameForRef(head.Name()),
+		Commit: head.Hash().String(),
 	}
 
 	wt, err := repo.Worktree()
 	if err == nil {
 		if status, err := wt.Status(); err == nil {
-			info["dirty"] = !status.IsClean()
+			dirty := !status.IsClean()
+			info.Dirty = &dirty
 		}
 	}
 
@@ -83,16 +101,13 @@ func workspaceGitEvidence(path string) map[string]any {
 					remoteURL = r.URLs[0]
 					break
 				}
+				}
+			}
+			if remoteURL != "" {
+				info.Remote = remoteURL
 			}
 		}
-		if remoteURL != "" {
-			info["remote"] = remoteURL
-		}
-	}
 
-	if len(info) == 0 {
-		return nil
-	}
 	return info
 }
 

internal/mcp/handler_analysis.go

@@ -66,7 +66,7 @@ type traceFlowResponse struct {
 	Name     string            `json:"name"`
 	Members  []traceFlowMember `json:"members"`
 	Metadata traceFlowMetadata `json:"metadata"`
-	Evidence map[string]any    `json:"evidence"`
+	Evidence workspaceEvidenceBlock `json:"evidence"`
 }
 
 // detectChangesEntry summarizes one changed node plus its diff-derived risk score.

internal/mcp/handler_context.go

@@ -67,7 +67,7 @@ type minimalContextResponse struct {
 	TopFlows       []minimalContextFlowInfo `json:"top_flows"`
 	DerivedState   map[string]any           `json:"derived_state"`
 	SuggestedTools []string                 `json:"suggested_tools"`
-	Evidence       map[string]any           `json:"evidence"`
+	Evidence       workspaceEvidenceBlock   `json:"evidence"`
 }
 
 // getMinimalContext returns a compact project snapshot with risk hints and suggested tools.

internal/mcp/handler_query.go

@@ -92,7 +92,7 @@ type queryGraphResponse struct {
 	Target   string                 `json:"target"`
 	Results  []queryGraphResultItem `json:"results"`
 	Metadata queryGraphMetadata     `json:"metadata"`
-	Evidence map[string]any         `json:"evidence"`
+	Evidence workspaceEvidenceBlock `json:"evidence"`
 }
 
 // searchResultItem summarizes one node hit returned by full-text search.
@@ -124,7 +124,7 @@ type nodeResponse struct {
 	StartLine     int            `json:"start_line"`
 	EndLine       int            `json:"end_line"`
 	Language      string         `json:"language"`
-	Evidence      map[string]any `json:"evidence"`
+	Evidence      workspaceEvidenceBlock `json:"evidence"`
 }
 
 // getNode returns detailed metadata for a graph node by qualified name.
@@ -597,7 +597,7 @@ type listGraphStatsResponse struct {
 	NodesByKind     map[string]int64 `json:"nodes_by_kind"`
 	NodesByLanguage map[string]int64 `json:"nodes_by_language"`
 	EdgesByKind     map[string]int64 `json:"edges_by_kind"`
-	Evidence        map[string]any   `json:"evidence"`
+	Evidence        workspaceEvidenceBlock `json:"evidence"`
 }
 
 // listGraphStats returns aggregate node and edge statistics for the graph.