refactor(mcp): type shared analysis responses

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

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

Author: tae2089

internal/mcp/handler_analysis.go

@@ -27,23 +27,31 @@ const (
 	defaultTraceMaxNodes  = 200
 )
 
+// impactRadiusMetadata records bounded traversal settings and truncation state.
+// @intent explain how getImpactRadius constrained the blast-radius traversal for the returned payload.
 type impactRadiusMetadata struct {
 	Truncated     bool `json:"truncated"`
 	MaxDepth      int  `json:"max_depth"`
 	MaxNodes      int  `json:"max_nodes"`
 	ReturnedNodes int  `json:"returned_nodes"`
 }
 
+// impactRadiusResponse is the typed wire payload for getImpactRadius.
+// @intent preserve a stable typed response envelope for impact-radius queries.
 type impactRadiusResponse struct {
-	Nodes    []map[string]any     `json:"nodes"`
+	Nodes    []nodeSummary        `json:"nodes"`
 	Metadata impactRadiusMetadata `json:"metadata"`
 }
 
+// traceFlowMember captures one ordered member inside a traced flow.
+// @intent serialize flow member references without exposing the full node record.
 type traceFlowMember struct {
 	NodeID  uint `json:"node_id"`
 	Ordinal int  `json:"ordinal"`
 }
 
+// traceFlowMetadata records bounded trace settings and fallback-edge summary data.
+// @intent explain whether traceFlow truncated members and whether fallback edges contributed to the result.
 type traceFlowMetadata struct {
 	Truncated             bool `json:"truncated"`
 	MaxNodes              int  `json:"max_nodes"`
@@ -52,33 +60,43 @@ type traceFlowMetadata struct {
 	FallbackEdgesCount    int  `json:"fallback_edges_count"`
 }
 
+// traceFlowResponse is the typed wire payload for traceFlow.
+// @intent preserve a stable response envelope for traced flow results and their evidence.
 type traceFlowResponse struct {
 	Name     string            `json:"name"`
 	Members  []traceFlowMember `json:"members"`
 	Metadata traceFlowMetadata `json:"metadata"`
 	Evidence map[string]any    `json:"evidence"`
 }
 
+// detectChangesEntry summarizes one changed node plus its diff-derived risk score.
+// @intent preserve a stable per-item DTO for detectChanges pagination results.
 type detectChangesEntry struct {
 	Name      string  `json:"name"`
 	File      string  `json:"file"`
 	HunkCount int     `json:"hunk_count"`
 	RiskScore float64 `json:"risk_score"`
 }
 
+// detectChangesResponse is the typed wire payload for detectChanges.
+// @intent expose diff-risk results with both legacy entries and shared pagination fields.
 type detectChangesResponse struct {
 	Base       string               `json:"base"`
 	Entries    []detectChangesEntry `json:"entries"`
 	Items      []detectChangesEntry `json:"items"`
 	Pagination paging.Page          `json:"pagination"`
 }
 
+// affectedFlowEntry summarizes one stored flow touched by changed nodes.
+// @intent preserve a stable DTO for getAffectedFlows items while retaining changed node identifiers.
 type affectedFlowEntry struct {
 	ID            uint   `json:"id"`
 	Name          string `json:"name"`
 	AffectedNodes []uint `json:"affected_nodes"`
 }
 
+// affectedFlowsResponse is the typed wire payload for getAffectedFlows.
+// @intent expose affected stored flows with backward-compatible aliases and pagination metadata.
 type affectedFlowsResponse struct {
 	Base          string              `json:"base"`
 	AffectedFlows []affectedFlowEntry `json:"affected_flows"`
@@ -87,13 +105,17 @@ type affectedFlowsResponse struct {
 	Pagination    paging.Page         `json:"pagination"`
 }
 
+// deadCodeItem summarizes one node reported as dead code.
+// @intent preserve a stable per-item DTO for findDeadCode responses.
 type deadCodeItem struct {
 	Name      string         `json:"name"`
 	Kind      model.NodeKind `json:"kind"`
 	File      string         `json:"file"`
 	StartLine int            `json:"start_line"`
 }
 
+// suspectFallbackEdgeItem summarizes one fallback edge inspected for suspicion.
+// @intent preserve a stable per-item DTO for findSuspectFallbackEdges responses.
 type suspectFallbackEdgeItem struct {
 	EdgeKind    model.EdgeKind `json:"edge_kind"`
 	Fingerprint string         `json:"fingerprint"`
@@ -168,9 +190,9 @@ func (h *handlers) getImpactRadius(ctx context.Context, request mcp.CallToolRequ
 
 		log.InfoContext(ctx, "get_impact_radius completed", append(obs.TraceLogArgs(ctx), "qualified_name", qn, "result_count", len(nodes))...)
 
-		impactResult := make([]map[string]any, len(nodes))
+		impactResult := make([]nodeSummary, len(nodes))
 		for i, n := range nodes {
-			impactResult[i] = nodeToBasicMap(n)
+			impactResult[i] = nodeToSummary(n)
 		}
 		result, err := marshalJSON(impactRadiusResponse{
 			Nodes: impactResult,

internal/mcp/handler_analysis_io.go

@@ -100,16 +100,21 @@ func normalizeListPaging(limit, offset int) (paging.Request, error) {
 	return pageReq, nil
 }
 
+// pagedListResponse preserves the shared {legacyKey, items, count, pagination} list envelope.
+// @intent let analysis handlers reuse one typed pagination DTO while keeping historical alias fields.
 type pagedListResponse[T any] struct {
 	LegacyKey  string
 	Items      []T         `json:"items"`
 	Count      int         `json:"count"`
 	Pagination paging.Page `json:"pagination"`
 }
 
+// MarshalJSON emits both the legacy alias key and the shared paging fields.
+// @intent preserve backward-compatible response keys while allowing handlers to work with typed slices.
+// @return returns a JSON object containing the legacy alias, items, count, and pagination fields.
 func (r pagedListResponse[T]) MarshalJSON() ([]byte, error) {
 	resp := map[string]any{
-		r.LegacyKey: r.Items,
+		r.LegacyKey:  r.Items,
 		"items":      r.Items,
 		"count":      r.Count,
 		"pagination": r.Pagination,

internal/mcp/handler_context.go

@@ -55,6 +55,21 @@ type minimalContextFlowInfo struct {
 	NodeCount int    `json:"node_count"`
 }
 
+// minimalContextResponse is the typed minimal-context payload sent over MCP.
+// @intent keep the minimal-context wire shape explicit without changing serialized output.
+type minimalContextResponse struct {
+	Summary        string                   `json:"summary"`
+	Risk           string                   `json:"risk"`
+	RiskScore      float64                  `json:"risk_score"`
+	KeyEntities    []string                 `json:"key_entities"`
+	TestGaps       int                      `json:"test_gaps"`
+	TopCommunities []minimalContextCommInfo `json:"top_communities"`
+	TopFlows       []minimalContextFlowInfo `json:"top_flows"`
+	DerivedState   map[string]any           `json:"derived_state"`
+	SuggestedTools []string                 `json:"suggested_tools"`
+	Evidence       map[string]any           `json:"evidence"`
+}
+
 // getMinimalContext returns a compact project snapshot with risk hints and suggested tools.
 // @intent give agents a cheap first read of namespace state before they spend tokens on deeper graph queries.
 func (h *handlers) getMinimalContext(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
@@ -218,17 +233,17 @@ func (h *handlers) getMinimalContext(ctx context.Context, request mcp.CallToolRe
 
 		suggestedTools := suggestTools(task)
 
-		resp := map[string]any{
-			"summary":         summary,
-			"risk":            risk,
-			"risk_score":      riskScore,
-			"key_entities":    keyEntities,
-			"test_gaps":       testGaps,
-			"top_communities": commInfos,
-			"top_flows":       flowInfos,
-			"derived_state":   derivedStateSummary(),
-			"suggested_tools": suggestedTools,
-			"evidence":        h.workspaceEvidenceFromContext(ctx),
+		resp := minimalContextResponse{
+			Summary:        summary,
+			Risk:           risk,
+			RiskScore:      riskScore,
+			KeyEntities:    keyEntities,
+			TestGaps:       testGaps,
+			TopCommunities: commInfos,
+			TopFlows:       flowInfos,
+			DerivedState:   derivedStateSummary(),
+			SuggestedTools: suggestedTools,
+			Evidence:       h.workspaceEvidenceFromContext(ctx),
 		}
 
 		result, err := marshalJSON(resp)

internal/mcp/handler_query.go

@@ -24,12 +24,16 @@ const (
 	maxQueryGraphLimit     = 500
 )
 
+// largeFunctionItem summarizes one oversized function candidate.
+// @intent preserve a stable per-item DTO for findLargeFunctions responses.
 type largeFunctionItem struct {
 	Name  string `json:"name"`
 	File  string `json:"file"`
 	Lines int    `json:"lines"`
 }
 
+// annotationTagItem serializes one stored annotation tag.
+// @intent expose annotation tags with typed fields for getAnnotation callers.
 type annotationTagItem struct {
 	Kind    model.TagKind `json:"kind"`
 	Type    string        `json:"type"`
@@ -38,18 +42,24 @@ type annotationTagItem struct {
 	Ordinal int           `json:"ordinal"`
 }
 
+// annotationResponse is the typed wire payload for getAnnotation.
+// @intent preserve a stable response envelope for annotation summary, context, and tags.
 type annotationResponse struct {
 	Summary string              `json:"summary"`
 	Context string              `json:"context"`
 	Tags    []annotationTagItem `json:"tags"`
 }
 
+// queryGraphEvidence records edge evidence backing one queryGraph result item.
+// @intent expose edge location details that justify caller/callee confidence labels.
 type queryGraphEvidence struct {
 	FilePath    string `json:"file_path"`
 	Line        int    `json:"line"`
 	Fingerprint string `json:"fingerprint"`
 }
 
+// queryGraphResultItem summarizes one node returned by queryGraph.
+// @intent preserve a stable DTO for paged graph traversal results.
 type queryGraphResultItem struct {
 	ID            uint                `json:"id"`
 	QualifiedName string              `json:"qualified_name"`
@@ -61,6 +71,8 @@ type queryGraphResultItem struct {
 	Evidence      *queryGraphEvidence `json:"evidence,omitempty"`
 }
 
+// queryGraphMetadata records pagination and fallback-call accounting for queryGraph.
+// @intent explain result counts, truncation, and strict-versus-tentative composition in queryGraph responses.
 type queryGraphMetadata struct {
 	Limit                int   `json:"limit"`
 	Offset               int   `json:"offset"`
@@ -73,14 +85,18 @@ type queryGraphMetadata struct {
 	IncludeFallbackCalls *bool `json:"include_fallback_calls,omitempty"`
 }
 
+// queryGraphResponse is the typed wire payload for queryGraph.
+// @intent preserve a stable response envelope for predefined graph traversals and their evidence.
 type queryGraphResponse struct {
-	Pattern  string               `json:"pattern"`
-	Target   string               `json:"target"`
+	Pattern  string                 `json:"pattern"`
+	Target   string                 `json:"target"`
 	Results  []queryGraphResultItem `json:"results"`
-	Metadata queryGraphMetadata   `json:"metadata"`
-	Evidence map[string]any       `json:"evidence"`
+	Metadata queryGraphMetadata     `json:"metadata"`
+	Evidence map[string]any         `json:"evidence"`
 }
 
+// searchResultItem summarizes one node hit returned by full-text search.
+// @intent preserve a stable per-item DTO for search responses.
 type searchResultItem struct {
 	ID            uint           `json:"id"`
 	QualifiedName string         `json:"qualified_name"`
@@ -89,6 +105,16 @@ type searchResultItem struct {
 	FilePath      string         `json:"file_path"`
 }
 
+// fileSummaryResponse is the typed wire payload for file_summary queryGraph requests.
+// @intent preserve a stable response envelope for file-summary graph queries.
+type fileSummaryResponse struct {
+	Pattern string                `json:"pattern"`
+	Target  string                `json:"target"`
+	Results *querypkg.FileSummary `json:"results"`
+}
+
+// nodeResponse is the typed wire payload for getNode.
+// @intent preserve a stable response envelope for node metadata lookups.
 type nodeResponse struct {
 	ID            uint           `json:"id"`
 	QualifiedName string         `json:"qualified_name"`
@@ -337,12 +363,7 @@ func (h *handlers) queryGraph(ctx context.Context, request mcp.CallToolRequest)
 			if err != nil {
 				return "", newToolResultErr(fmt.Sprintf("file summary error: %v", err))
 			}
-			fsData := map[string]any{
-				"pattern": pattern,
-				"target":  target,
-				"results": summary,
-			}
-			result, err := marshalJSON(fsData)
+			result, err := marshalJSON(fileSummaryResponse{Pattern: pattern, Target: target, Results: summary})
 			if err != nil {
 				return "", trace.Wrap(err, "marshal result")
 			}
@@ -568,6 +589,17 @@ func compactQueryTargetAmbiguity(target string, matches []querypkg.CandidateMatc
 	return fmt.Sprintf("query_graph target %q is ambiguous: %s", target, strings.Join(parts, "; "))
 }
 
+// listGraphStatsResponse is the serialized payload for graph statistics.
+// @intent preserve a stable typed JSON response for graph statistics without changing the wire format.
+type listGraphStatsResponse struct {
+	TotalNodes      int64            `json:"total_nodes"`
+	TotalEdges      int64            `json:"total_edges"`
+	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"`
+}
+
 // listGraphStats returns aggregate node and edge statistics for the graph.
 // @intent summarize the current graph load state with kind and language distributions.
 // @ensures returns total node and edge counts plus kind and language aggregates when the query succeeds.
@@ -634,13 +666,13 @@ func (h *handlers) listGraphStats(ctx context.Context, request mcp.CallToolReque
 			ebk[k.Kind] = k.Count
 		}
 
-		statsData := map[string]any{
-			"total_nodes":       nodeCount,
-			"total_edges":       edgeCount,
-			"nodes_by_kind":     nbk,
-			"nodes_by_language": nbl,
-			"edges_by_kind":     ebk,
-			"evidence":          h.workspaceEvidenceFromContext(ctx),
+		statsData := listGraphStatsResponse{
+			TotalNodes:      nodeCount,
+			TotalEdges:      edgeCount,
+			NodesByKind:     nbk,
+			NodesByLanguage: nbl,
+			EdgesByKind:     ebk,
+			Evidence:        h.workspaceEvidenceFromContext(ctx),
 		}
 		result, err := marshalJSON(statsData)
 		if err != nil {

internal/mcp/handlers.go

@@ -227,10 +227,34 @@ func (h *handlers) cachedExecute(ctx context.Context, prefix string, params map[
 	return result, nil
 }
 
+// nodeSummary is a compact node response payload shared by graph handlers.
+// @intent reuse one typed node representation across multiple tool responses.
+type nodeSummary struct {
+	ID            uint           `json:"id"`
+	QualifiedName string         `json:"qualified_name"`
+	Kind          model.NodeKind `json:"kind"`
+	Name          string         `json:"name"`
+	FilePath      string         `json:"file_path"`
+}
+
+// nodeToSummary converts a graph node into a compact typed response payload.
+// @intent reuse one typed node representation across multiple tool responses.
+// @param n is the graph node to include in an MCP response.
+// @return returns a typed node summary containing identifier, name, kind, and file path fields.
+func nodeToSummary(n model.Node) nodeSummary {
+	return nodeSummary{
+		ID:            n.ID,
+		QualifiedName: n.QualifiedName,
+		Kind:          n.Kind,
+		Name:          n.Name,
+		FilePath:      n.FilePath,
+	}
+}
+
 // nodeToBasicMap converts a graph node into a compact response payload.
-// @intent reuse one compact node representation across multiple tool responses.
+// @intent preserve the legacy map-based node shape for existing MCP callers.
 // @param n is the graph node to include in an MCP response.
-// @return returns a map containing identifier, name, kind, and file path fields.
+// @return returns a map with identifier, name, kind, and file path fields.
 func nodeToBasicMap(n model.Node) map[string]any {
 	return map[string]any{
 		"id":             n.ID,