refactor(mcp): use typed pagination metadata

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_io.go

@@ -111,6 +111,7 @@ type pagedListResponse[T any] struct {
 
 // 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.
+// @domainRule the temporary map allocation remains because the legacy alias key is dynamic per handler and must coexist with the shared typed envelope.
 // @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{

internal/mcp/handler_graph.go

@@ -36,15 +36,15 @@ type graphCommInfo struct {
 type listFlowsResponse struct {
 	Flows        []graphFlowInfo `json:"flows"`
 	DerivedState map[string]any  `json:"derived_state"`
-	Pagination   map[string]any  `json:"pagination"`
+	Pagination   paging.Page     `json:"pagination"`
 }
 
 // listCommunitiesResponse holds the listCommunities wire payload.
 // @intent preserve the legacy listCommunities response shape with typed fields.
 type listCommunitiesResponse struct {
 	Communities  []graphCommInfo `json:"communities"`
 	DerivedState map[string]any  `json:"derived_state"`
-	Pagination   map[string]any  `json:"pagination"`
+	Pagination   paging.Page     `json:"pagination"`
 }
 
 // communityMemberSummary is a typed member entry for getCommunity.
@@ -60,7 +60,7 @@ type getCommunityResponse struct {
 	DerivedState      map[string]any           `json:"derived_state"`
 	Coverage          *float64                 `json:"coverage,omitempty"`
 	Members           []communityMemberSummary `json:"members,omitempty"`
-	MembersPagination map[string]any           `json:"members_pagination,omitempty"`
+	MembersPagination *paging.Page             `json:"members_pagination,omitempty"`
 }
 
 // archCommCount is a helper struct for counting community nodes in architecture overview.
@@ -92,9 +92,9 @@ type architectureOverviewCoupling struct {
 // @intent preserve the legacy architecture overview response shape with typed fields.
 type architectureOverviewResponse struct {
 	Communities           []architectureOverviewCommunity `json:"communities"`
-	CommunitiesPagination map[string]any                  `json:"communities_pagination"`
+	CommunitiesPagination paging.Page                     `json:"communities_pagination"`
 	Coupling              []architectureOverviewCoupling  `json:"coupling"`
-	CouplingPagination    map[string]any                  `json:"coupling_pagination"`
+	CouplingPagination    paging.Page                     `json:"coupling_pagination"`
 	Warnings              []string                        `json:"warnings"`
 	DerivedState          map[string]any                  `json:"derived_state"`
 }
@@ -182,7 +182,7 @@ func (h *handlers) listFlows(ctx context.Context, request mcp.CallToolRequest) (
 		result, err := marshalJSON(listFlowsResponse{
 			Flows:        infos,
 			DerivedState: derivedStateFlows(),
-			Pagination:   buildPaginationMetadata(limit, offset, len(infos), hasMore),
+			Pagination:   paging.BuildPage(paging.Request{Limit: limit, Offset: offset}, len(infos), hasMore),
 		})
 		if err != nil {
 			return "", trace.Wrap(err, "marshal result")
@@ -255,7 +255,7 @@ func (h *handlers) listCommunities(ctx context.Context, request mcp.CallToolRequ
 		result, err := marshalJSON(listCommunitiesResponse{
 			Communities:  infos,
 			DerivedState: derivedStateCommunities(),
-			Pagination:   buildPaginationMetadata(limit, offset, len(infos), hasMore),
+			Pagination:   paging.BuildPage(paging.Request{Limit: limit, Offset: offset}, len(infos), hasMore),
 		})
 		if err != nil {
 			return "", trace.Wrap(err, "marshal result")
@@ -350,7 +350,8 @@ func (h *handlers) getCommunity(ctx context.Context, request mcp.CallToolRequest
 				members[i] = nodeToSummary(n)
 			}
 			gcData.Members = members
-			gcData.MembersPagination = buildPaginationMetadata(memberLimit, memberOffset, len(members), hasMore)
+			page := paging.BuildPage(paging.Request{Limit: memberLimit, Offset: memberOffset}, len(members), hasMore)
+			gcData.MembersPagination = &page
 		}
 
 		result, err := marshalJSON(gcData)
@@ -443,9 +444,9 @@ func (h *handlers) getArchitectureOverview(ctx context.Context, request mcp.Call
 
 		result, err := marshalJSON(architectureOverviewResponse{
 			Communities:           commInfos,
-			CommunitiesPagination: buildPaginationMetadata(communityLimit, communityOffset, len(commInfos), communityHasMore),
+			CommunitiesPagination: paging.BuildPage(paging.Request{Limit: communityLimit, Offset: communityOffset}, len(commInfos), communityHasMore),
 			Coupling:              couplingPairs,
-			CouplingPagination:    buildPaginationMetadata(couplingLimit, couplingOffset, len(couplingPairs), couplingHasMore),
+			CouplingPagination:    paging.BuildPage(paging.Request{Limit: couplingLimit, Offset: couplingOffset}, len(couplingPairs), couplingHasMore),
 			Warnings:              warnings,
 			DerivedState:          derivedStateSummary(),
 		})

internal/mcp/handlers.go

@@ -138,22 +138,6 @@ func validateOffset(offset int) error {
 	return nil
 }
 
-// buildPaginationMetadata builds a compact pagination descriptor for tool consumers.
-// @intent provide one consistent pagination metadata shape across tool responses.
-// @ensures includes next_offset only when hasMore is true.
-func buildPaginationMetadata(limit, offset, returned int, hasMore bool) map[string]any {
-	pagination := map[string]any{
-		"limit":    limit,
-		"offset":   offset,
-		"returned": returned,
-		"has_more": hasMore,
-	}
-	if hasMore {
-		pagination["next_offset"] = offset + limit
-	}
-	return pagination
-}
-
 // unwrapToolResultErr extracts an embedded MCP tool result from an error.
 // @intent recover user-facing MCP tool results from the internal error flow at one shared exit point.
 // @return returns the embedded MCP result and true when err is a toolResultErr.
@@ -250,17 +234,3 @@ func nodeToSummary(n model.Node) nodeSummary {
 		FilePath:      n.FilePath,
 	}
 }
-
-// nodeToBasicMap converts a graph node into a compact response payload.
-// @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 with identifier, name, kind, and file path fields.
-func nodeToBasicMap(n model.Node) map[string]any {
-	return map[string]any{
-		"id":             n.ID,
-		"qualified_name": n.QualifiedName,
-		"kind":           n.Kind,
-		"name":           n.Name,
-		"file_path":      n.FilePath,
-	}
-}