docs(mcp): annotate graph and workspace tools

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

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

Author: tae2089

internal/mcp/handler_graph.go

@@ -12,6 +12,24 @@ import (
 	"github.com/tae2089/code-context-graph/internal/model"
 )
 
+// graphFlowInfo represents a summarized flow response entry.
+// @intent serialize listFlows results with the legacy response shape.
+type graphFlowInfo struct {
+	ID          uint   `json:"id"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+	NodeCount   int    `json:"node_count"`
+}
+
+// graphCommInfo represents a summarized community response entry.
+// @intent serialize listCommunities results with the legacy response shape.
+type graphCommInfo struct {
+	ID        uint    `json:"id"`
+	Label     string  `json:"label"`
+	NodeCount int     `json:"node_count"`
+	Cohesion  float64 `json:"cohesion"`
+}
+
 // listFlows lists stored flows with optional sorting and truncation.
 // @intent 저장된 호출 흐름을 요약 형태로 노출해 탐색과 우선순위 판단을 돕는다.
 // @param request sort_by와 limit로 정렬 방식과 최대 개수를 제어한다.
@@ -29,13 +47,6 @@ func (h *handlers) listFlows(ctx context.Context, request mcp.CallToolRequest) (
 
 	log.Info("list_flows called", "sort_by", sortBy, "limit", limit)
 
-	// flowCount stores aggregated membership counts per flow.
-	// @intent flow_id별 멤버 수 집계 결과를 스캔하기 위한 임시 구조체다.
-	type flowCount struct {
-		FlowID uint
-		Count  int
-	}
-
 	return finalizeToolResult(h.cachedExecute(ctx, "list_flows:", map[string]any{"sort_by": sortBy, "limit": limit, "namespace": requestNamespace(request)}, func() (string, error) {
 		ns := ctxns.FromContext(ctx)
 		var fcRows []flowCount
@@ -60,18 +71,9 @@ func (h *handlers) listFlows(ctx context.Context, request mcp.CallToolRequest) (
 			return "", trace.Wrap(err, "find flows")
 		}
 
-		// flowInfo represents a summarized flow response entry.
-		// @intent MCP 응답에서 각 flow의 핵심 정보만 직렬화한다.
-		type flowInfo struct {
-			ID          uint   `json:"id"`
-			Name        string `json:"name"`
-			Description string `json:"description"`
-			NodeCount   int    `json:"node_count"`
-		}
-
-		infos := make([]flowInfo, len(flowList))
+		infos := make([]graphFlowInfo, len(flowList))
 		for i, f := range flowList {
-			infos[i] = flowInfo{
+			infos[i] = graphFlowInfo{
 				ID:          f.ID,
 				Name:        f.Name,
 				Description: f.Description,
@@ -119,13 +121,6 @@ func (h *handlers) listCommunities(ctx context.Context, request mcp.CallToolRequ
 
 	log.Info("list_communities called", "sort_by", sortBy, "min_size", minSize)
 
-	// commCount stores aggregated membership counts per community.
-	// @intent community_id별 멤버 수 집계 결과를 스캔하기 위한 임시 구조체다.
-	type commCount struct {
-		CommunityID uint
-		Count       int
-	}
-
 	return finalizeToolResult(h.cachedExecute(ctx, "list_communities:", map[string]any{"sort_by": sortBy, "min_size": minSize, "namespace": requestNamespace(request)}, func() (string, error) {
 		ns := ctxns.FromContext(ctx)
 		var ccRows []commCount
@@ -151,22 +146,13 @@ func (h *handlers) listCommunities(ctx context.Context, request mcp.CallToolRequ
 			return "", trace.Wrap(err, "find communities")
 		}
 
-		// commInfo represents a summarized community response entry.
-		// @intent MCP 응답에서 커뮤니티의 핵심 메타데이터만 직렬화한다.
-		type commInfo struct {
-			ID        uint    `json:"id"`
-			Label     string  `json:"label"`
-			NodeCount int     `json:"node_count"`
-			Cohesion  float64 `json:"cohesion"`
-		}
-
-		infos := make([]commInfo, 0, len(communities))
+		infos := make([]graphCommInfo, 0, len(communities))
 		for _, c := range communities {
 			cnt := ccMap[c.ID]
 			if cnt < minSize {
 				continue
 			}
-			infos = append(infos, commInfo{
+			infos = append(infos, graphCommInfo{
 				ID:        c.ID,
 				Label:     c.Label,
 				NodeCount: cnt,
@@ -228,9 +214,9 @@ func (h *handlers) getCommunity(ctx context.Context, request mcp.CallToolRequest
 		}
 
 		gcData := map[string]any{
-			"id":         comm.ID,
-			"label":      comm.Label,
-			"node_count": memberCount,
+			"id":            comm.ID,
+			"label":         comm.Label,
+			"node_count":    memberCount,
 			"derived_state": derivedStateCommunities(),
 		}
 
@@ -299,9 +285,9 @@ func (h *handlers) getArchitectureOverview(ctx context.Context, request mcp.Call
 
 		if len(communities) == 0 {
 			result, err := marshalJSON(map[string]any{
-				"communities": []any{},
-				"coupling":    []any{},
-				"warnings":    []string{"No communities found. Run community rebuild first."},
+				"communities":   []any{},
+				"coupling":      []any{},
+				"warnings":      []string{"No communities found. Run community rebuild first."},
 				"derived_state": derivedStateSummary(),
 			})
 			if err != nil {
@@ -363,9 +349,9 @@ func (h *handlers) getArchitectureOverview(ctx context.Context, request mcp.Call
 		}
 
 		result, err := marshalJSON(map[string]any{
-			"communities": commInfos,
-			"coupling":    couplingPairs,
-			"warnings":    warnings,
+			"communities":   commInfos,
+			"coupling":      couplingPairs,
+			"warnings":      warnings,
 			"derived_state": derivedStateSummary(),
 		})
 		if err != nil {
@@ -375,6 +361,7 @@ func (h *handlers) getArchitectureOverview(ctx context.Context, request mcp.Call
 	}))
 }
 
+// @intent describe community-membership freshness so callers know when to re-run postprocess.
 func derivedStateCommunities() map[string]any {
 	return map[string]any{
 		"communities": map[string]any{
@@ -385,6 +372,7 @@ func derivedStateCommunities() map[string]any {
 	}
 }
 
+// @intent describe flow-membership freshness so callers know when to re-run postprocess.
 func derivedStateFlows() map[string]any {
 	return map[string]any{
 		"flows": map[string]any{
@@ -395,6 +383,7 @@ func derivedStateFlows() map[string]any {
 	}
 }
 
+// @intent merge community and flow freshness hints into a single derived-state map for status responses.
 func derivedStateSummary() map[string]any {
 	state := derivedStateCommunities()
 	for k, v := range derivedStateFlows() {

internal/mcp/handler_workspace.go

@@ -37,6 +37,7 @@ func (h *handlers) workspaceRoot() string {
 	return root
 }
 
+// @intent resolve the canonical namespace parameter while preserving the deprecated workspace alias.
 func requestWorkspace(request mcp.CallToolRequest) (string, error) {
 	if namespace := request.GetString("namespace", ""); namespace != "" {
 		return namespace, nil
@@ -67,6 +68,8 @@ func validateWorkspacePath(workspace, filePath string) error {
 	return nil
 }
 
+// @intent canonicalize and create the workspace root before file operations rely on it.
+// @sideEffect creates the workspace root directory when it does not yet exist.
 func (h *handlers) safeWorkspaceRoot() (string, error) {
 	root := h.workspaceRoot()
 	absRoot, err := filepath.Abs(root)
@@ -83,11 +86,13 @@ func (h *handlers) safeWorkspaceRoot() (string, error) {
 	return realRoot, nil
 }
 
+// @intent compose filesystem paths without repeating join boilerplate in workspace helpers.
 func safeJoin(base string, parts ...string) string {
 	all := append([]string{base}, parts...)
 	return filepath.Join(all...)
 }
 
+// @intent reject symlink traversal anywhere along a workspace path before file operations touch the filesystem.
 func ensureNoSymlinkInPath(root, relPath string, allowMissingLeaf bool) (string, error) {
 	cleanRel := filepath.Clean(relPath)
 	if cleanRel == "." {
@@ -114,6 +119,7 @@ func ensureNoSymlinkInPath(root, relPath string, allowMissingLeaf bool) (string,
 	return current, nil
 }
 
+// @intent resolve a workspace-relative path under the trusted root after validation and symlink checks.
 func (h *handlers) resolveWorkspacePath(workspace, filePath string, allowMissingLeaf bool) (string, error) {
 	if err := validateWorkspacePath(workspace, filePath); err != nil {
 		return "", err
@@ -137,6 +143,8 @@ func (h *handlers) resolveWorkspacePath(workspace, filePath string, allowMissing
 	return ensureNoSymlinkInPath(root, rel, allowMissingLeaf)
 }
 
+// @intent write workspace files atomically so partial writes are never observed as final state.
+// @sideEffect creates a temp file and renames it into place.
 func safeWriteFile(path string, data []byte, perm os.FileMode) error {
 	tmpFile, err := os.CreateTemp(filepath.Dir(path), filepath.Base(path)+".tmp.*")
 	if err != nil {
@@ -356,12 +364,15 @@ type uploadFileEntry struct {
 	Content   string `json:"content"`
 }
 
+// @intent carry decoded content and the resolved target path through the workspace upload pipeline.
 type preparedUploadFile struct {
 	entry   uploadFileEntry
 	decoded []byte
 	target  string
 }
 
+// @intent hold validated upload payload state so bulk writes can happen after all entries pass validation.
+
 // uploadFiles writes multiple base64-encoded files in one request.
 // @intent 여러 작업공간 파일을 한 번의 MCP 호출로 업로드해 왕복 비용을 줄인다.
 // @param request files는 uploadFileEntry 배열을 담은 JSON 문자열이다.

internal/mcp/handler_workspace_unix.go

@@ -1,12 +1,16 @@
 //go:build !windows
 
+// @index Unix-specific symlink-safe workspace file writes for MCP handlers.
 package mcp
 
 import (
 	"os"
 	"syscall"
 )
 
+// writeFileNoFollow writes workspace files without following symlinks on Unix.
+// @intent prevent workspace upload paths from escaping the allowed root through symlink traversal.
+// @sideEffect creates or truncates the target file and fsyncs it to disk.
 func writeFileNoFollow(path string, data []byte, perm os.FileMode) error {
 	fd, err := syscall.Open(path, syscall.O_WRONLY|syscall.O_CREAT|syscall.O_TRUNC|syscall.O_NOFOLLOW, uint32(perm))
 	if err != nil {

internal/mcp/handler_workspace_windows.go

@@ -1,9 +1,13 @@
 //go:build windows
 
+// @index Windows workspace file writes for MCP handlers.
 package mcp
 
 import "os"
 
+// writeFileNoFollow writes workspace files using the Windows-safe fallback path.
+// @intent provide the same workspace write entry point on Windows where O_NOFOLLOW is unavailable.
+// @sideEffect truncates or creates the target file.
 func writeFileNoFollow(path string, data []byte, perm os.FileMode) error {
 	return os.WriteFile(path, data, perm)
 }

internal/mcp/tools_analysis.go

@@ -1,10 +1,13 @@
+// @index MCP tool registration for analysis-oriented graph operations.
 package mcp
 
 import (
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
 
+// analysisTools registers tools that compute impact, flow, change, and dead-code insights.
+// @intent keep analysis capabilities grouped so server startup can expose them consistently.
 func analysisTools(h *handlers) []server.ServerTool {
 	return []server.ServerTool{
 		{

internal/mcp/tools_context.go

@@ -1,10 +1,13 @@
+// @index MCP tool registration for lightweight context discovery.
 package mcp
 
 import (
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
 
+// contextTools registers compact discovery tools that help callers choose deeper graph operations.
+// @intent keep the context-oriented MCP surface grouped and reusable during server startup.
 func contextTools(h *handlers) []server.ServerTool {
 	return []server.ServerTool{
 		{

internal/mcp/tools_docs.go

@@ -1,10 +1,13 @@
+// @index MCP tool registration for documentation and RAG index operations.
 package mcp
 
 import (
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
 
+// docsTools registers tools that build and query the documentation index.
+// @intent keep documentation retrieval flows discoverable as one MCP tool family.
 func docsTools(h *handlers) []server.ServerTool {
 	return []server.ServerTool{
 		{

internal/mcp/tools_graph.go

@@ -1,10 +1,13 @@
+// @index MCP tool registration for graph summaries and architecture views.
 package mcp
 
 import (
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
 
+// graphTools registers tools that summarize stored flows, communities, and architecture state.
+// @intent expose high-level graph inspection separately from low-level query primitives.
 func graphTools(h *handlers) []server.ServerTool {
 	return []server.ServerTool{
 		{

internal/mcp/tools_parse.go

@@ -1,10 +1,13 @@
+// @index MCP tool registration for parsing, graph build, and postprocess execution.
 package mcp
 
 import (
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
 
+// parseTools registers tools that ingest source code and rebuild derived graph state.
+// @intent keep parsing and postprocess entry points available as one operational tool family.
 func parseTools(h *handlers) []server.ServerTool {
 	return []server.ServerTool{
 		{

internal/mcp/tools_postprocess.go

@@ -1,10 +1,13 @@
+// @index MCP tool registration for automatic postprocess policy control.
 package mcp
 
 import (
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
 
+// postprocessTools registers policy inspection and reset tools for postprocess automation.
+// @intent make postprocess recovery controls available without mixing them into unrelated tool groups.
 func postprocessTools(h *handlers) []server.ServerTool {
 	return []server.ServerTool{
 		{