docs(mcp): annotate context and analysis handlers

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

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

Author: tae2089

internal/mcp/cache.go

@@ -86,6 +86,7 @@ func (c *Cache) Close() {
 	})
 }
 
+// @intent drop one cache entry to keep total size at or below the configured maximum.
 func (c *Cache) evictOneLocked() {
 	if len(c.entries) <= maxCacheEntries {
 		return

internal/mcp/deps.go

@@ -1,3 +1,4 @@
+// @index Dependency contracts and injected services for MCP handlers.
 package mcp
 
 import (
@@ -36,6 +37,8 @@ type ImpactAnalyzer interface {
 	ImpactRadius(ctx context.Context, nodeID uint, depth int) ([]model.Node, error)
 }
 
+// BoundedImpactAnalyzer extends ImpactAnalyzer with node and depth caps to prevent runaway traversal on large graphs.
+// @intent expose bounded blast-radius analysis for handlers that must protect shared MCP requests from unbounded graph walks.
 type BoundedImpactAnalyzer interface {
 	ImpactRadiusBounded(ctx context.Context, nodeID uint, depth int, opts impactpkg.RadiusOptions) (*impactpkg.RadiusResult, error)
 }
@@ -47,6 +50,8 @@ type FlowTracer interface {
 	TraceFlow(ctx context.Context, startNodeID uint) (*model.Flow, error)
 }
 
+// BoundedFlowTracer extends FlowTracer with a node cap to prevent runaway traversal on deeply nested call chains.
+// @intent let MCP handlers trace deep call chains without letting one request expand into an unbounded traversal.
 type BoundedFlowTracer interface {
 	TraceFlowBounded(ctx context.Context, startNodeID uint, opts flowspkg.TraceOptions) (*flowspkg.TraceResult, error)
 }
@@ -117,6 +122,8 @@ type IncrementalSyncer interface {
 	SyncWithExisting(ctx context.Context, files map[string]incremental.FileInfo, existingFiles []string) (*incremental.SyncStats, error)
 }
 
+// PostprocessPolicy gates and records automatic postprocess runs so repeated failures can be detected and suppressed.
+// @intent centralize automatic postprocess decisions so repeated failures can degrade execution before handlers retry expensive work.
 type PostprocessPolicy interface {
 	Resolve(ctx context.Context, input postprocesspolicy.DecisionInput) (string, string, error)
 	RecordRun(ctx context.Context, record postprocesspolicy.RunRecord) error

internal/mcp/handler_analysis.go

@@ -395,10 +395,15 @@ func (h *handlers) findDeadCode(ctx context.Context, request mcp.CallToolRequest
 	}))
 }
 
+// @intent validate repo_root inputs against configured analysis roots before git-based analysis reads the filesystem.
 func (h *handlers) validateRepoRoot(repoRoot string) (string, error) {
 	return validateRepoRootWithin(repoRoot, h.deps.RepoRoot, h.workspaceRoot())
 }
 
+// validateRepoRootWithin checks that repoRoot resolves to a canonical path within one of the allowed analysis roots.
+// @intent prevent git-based analysis from reading paths outside the configured project boundaries.
+// @requires configuredRepoRoot or workspaceRoot must be non-empty; repoRoot must be a valid filesystem path.
+// @ensures returned path is absolute, symlink-resolved, and contained within an allowed root.
 func validateRepoRootWithin(repoRoot, configuredRepoRoot, workspaceRoot string) (string, error) {
 	if repoRoot == "" {
 		return "", fmt.Errorf("repo_root is required")
@@ -421,6 +426,8 @@ func validateRepoRootWithin(repoRoot, configuredRepoRoot, workspaceRoot string)
 	return repo, nil
 }
 
+// configuredAnalysisRoots returns the deduplicated list of allowed root paths derived from server config and workspace.
+// @intent build the allowlist used by path validation so each source of truth contributes exactly once.
 func configuredAnalysisRoots(repoRoot, workspaceRoot string) []string {
 	roots := make([]string, 0, 2)
 	for _, root := range []string{repoRoot, workspaceRoot} {
@@ -434,6 +441,7 @@ func configuredAnalysisRoots(repoRoot, workspaceRoot string) []string {
 	return roots
 }
 
+// @intent linear membership check for small string slices used by allowlist evaluation.
 func sliceContainsString(values []string, target string) bool {
 	for _, value := range values {
 		if value == target {
@@ -443,6 +451,9 @@ func sliceContainsString(values []string, target string) bool {
 	return false
 }
 
+// validatePathWithinAllowedRoots reports whether target falls inside any of the canonical allowed roots.
+// @intent enforce that user-supplied paths cannot escape the configured analysis boundary.
+// @requires allowedRoots must be non-empty and each entry must be a valid filesystem path.
 func validatePathWithinAllowedRoots(target string, allowedRoots []string) (bool, error) {
 	for _, root := range allowedRoots {
 		base, err := canonicalPath(root)
@@ -460,6 +471,8 @@ func validatePathWithinAllowedRoots(target string, allowedRoots []string) (bool,
 	return false, nil
 }
 
+// isWithinRoot reports whether target is the same as root or a descendant of it.
+// @intent detect path traversal by checking the relative path does not escape upward.
 func isWithinRoot(root, target string) (bool, error) {
 	rel, err := filepath.Rel(root, target)
 	if err != nil {
@@ -480,6 +493,8 @@ func isWithinRoot(root, target string) (bool, error) {
 	return true, nil
 }
 
+// canonicalPath resolves path to an absolute, symlink-free, cleaned filesystem path.
+// @intent normalize user-supplied paths before comparison to prevent symlink-based boundary escapes.
 func canonicalPath(path string) (string, error) {
 	abs, err := filepath.Abs(path)
 	if err != nil {

internal/mcp/handler_context.go

@@ -1,3 +1,4 @@
+// @index MCP context handlers that summarize graph state for downstream tool selection.
 package mcp
 
 import (
@@ -14,6 +15,42 @@ import (
 	"github.com/tae2089/code-context-graph/internal/model"
 )
 
+// fileCount carries a single COUNT(DISTINCT file_path) scan result.
+// @intent capture the distinct-file count returned by the minimal-context summary query.
+type fileCount struct {
+	Count int64
+}
+
+// commCount holds aggregated membership counts per community.
+// @intent transport GROUP BY community_id results into MCP response shaping.
+type commCount struct {
+	CommunityID uint
+	Count       int
+}
+
+// commInfo is the summarized community payload shared by MCP responses.
+// @intent serialize minimal-context community summaries without introducing extra response fields.
+type minimalContextCommInfo struct {
+	Label     string `json:"label"`
+	NodeCount int    `json:"node_count"`
+}
+
+// flowCount holds aggregated membership counts per flow.
+// @intent transport GROUP BY flow_id results into MCP response shaping.
+type flowCount struct {
+	FlowID uint
+	Count  int
+}
+
+// flowInfo is the summarized flow payload shared by MCP responses.
+// @intent serialize minimal-context flow summaries without introducing extra response fields.
+type minimalContextFlowInfo struct {
+	Name      string `json:"name"`
+	NodeCount int    `json:"node_count"`
+}
+
+// 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) {
 	ctx = h.applyWorkspace(ctx, request)
 	log := h.logger()
@@ -49,7 +86,6 @@ func (h *handlers) getMinimalContext(ctx context.Context, request mcp.CallToolRe
 			return "", trace.Wrap(err, "count edges")
 		}
 
-		type fileCount struct{ Count int64 }
 		var fc fileCount
 		fileQ := h.deps.DB.WithContext(ctx).Model(&model.Node{}).Select("COUNT(DISTINCT file_path) as count").Where("namespace = ?", ns)
 		if err := fileQ.Scan(&fc).Error; err != nil {
@@ -110,11 +146,6 @@ func (h *handlers) getMinimalContext(ctx context.Context, request mcp.CallToolRe
 		if keyEntities == nil {
 			keyEntities = []string{}
 		}
-
-		type commCount struct {
-			CommunityID uint
-			Count       int
-		}
 		var ccRows []commCount
 		commCountQ := h.deps.DB.WithContext(ctx).
 			Model(&model.CommunityMembership{}).
@@ -136,26 +167,16 @@ func (h *handlers) getMinimalContext(ctx context.Context, request mcp.CallToolRe
 		if err := communityQ.Find(&communities).Error; err != nil {
 			return "", trace.Wrap(err, "find communities")
 		}
-
-		type commInfo struct {
-			Label     string `json:"label"`
-			NodeCount int    `json:"node_count"`
-		}
-		commInfos := make([]commInfo, len(communities))
+		commInfos := make([]minimalContextCommInfo, len(communities))
 		for i, c := range communities {
-			commInfos[i] = commInfo{Label: c.Label, NodeCount: ccMap[c.ID]}
+			commInfos[i] = minimalContextCommInfo{Label: c.Label, NodeCount: ccMap[c.ID]}
 		}
 		sort.Slice(commInfos, func(i, j int) bool {
 			return commInfos[i].NodeCount > commInfos[j].NodeCount
 		})
 		if len(commInfos) > 3 {
 			commInfos = commInfos[:3]
 		}
-
-		type flowCount struct {
-			FlowID uint
-			Count  int
-		}
 		var fcRows []flowCount
 		flowCountQ := h.deps.DB.WithContext(ctx).
 			Model(&model.FlowMembership{}).
@@ -176,14 +197,9 @@ func (h *handlers) getMinimalContext(ctx context.Context, request mcp.CallToolRe
 		if err := flowQ.Find(&flowList).Error; err != nil {
 			return "", trace.Wrap(err, "find flows")
 		}
-
-		type flowInfo struct {
-			Name      string `json:"name"`
-			NodeCount int    `json:"node_count"`
-		}
-		flowInfos := make([]flowInfo, len(flowList))
+		flowInfos := make([]minimalContextFlowInfo, len(flowList))
 		for i, f := range flowList {
-			flowInfos[i] = flowInfo{Name: f.Name, NodeCount: fcMap[f.ID]}
+			flowInfos[i] = minimalContextFlowInfo{Name: f.Name, NodeCount: fcMap[f.ID]}
 		}
 		sort.Slice(flowInfos, func(i, j int) bool {
 			return flowInfos[i].NodeCount > flowInfos[j].NodeCount
@@ -214,6 +230,8 @@ func (h *handlers) getMinimalContext(ctx context.Context, request mcp.CallToolRe
 	}))
 }
 
+// suggestTools maps common task wording to the MCP tools most likely to help.
+// @intent steer callers toward high-signal graph operations without requiring them to know the full tool catalog.
 func suggestTools(task string) []string {
 	lower := strings.ToLower(task)
 

internal/mcp/handler_docs.go

@@ -13,6 +13,7 @@ import (
 	"github.com/tae2089/code-context-graph/internal/ragindex"
 )
 
+// @intent resolve the base directory that stores generated doc-index artifacts for MCP documentation tools.
 func (h *handlers) ragIndexRoot() string {
 	dir := h.deps.RagIndexDir
 	if dir == "" {
@@ -21,6 +22,7 @@ func (h *handlers) ragIndexRoot() string {
 	return dir
 }
 
+// @intent normalize a docs/index root to an absolute, symlink-evaluated path before path checks.
 func resolveSafeRoot(root string, create bool) (string, error) {
 	absRoot, err := filepath.Abs(root)
 	if err != nil {
@@ -43,6 +45,7 @@ func resolveSafeRoot(root string, create bool) (string, error) {
 	return filepath.Clean(absRoot), nil
 }
 
+// @intent reject relative paths that would resolve outside the resolved docs root.
 func safePathUnderRoot(root, relPath, field string, createRoot bool, allowMissingLeaf bool) (string, error) {
 	clean := filepath.Clean(relPath)
 	if filepath.IsAbs(clean) || strings.HasPrefix(clean, "..") {
@@ -63,6 +66,7 @@ func safePathUnderRoot(root, relPath, field string, createRoot bool, allowMissin
 	return target, nil
 }
 
+// @intent derive the safe doc-index.json path for either the shared docs root or one workspace-specific subtree.
 func (h *handlers) resolvedRagIndexPath(workspace string) (string, error) {
 	if workspace != "" {
 		if err := validateWorkspacePath(workspace, ""); err != nil {

internal/mcp/handler_parse.go

@@ -20,6 +20,7 @@ import (
 
 var refreshSearchDocuments = service.RefreshSearchDocuments
 
+// @intent apply per-request parse limits without mutating the shared handler dependency configuration.
 func (h *handlers) withParseLimitsFromRequest(request mcp.CallToolRequest) *handlers {
 	maxFileBytes := int64(request.GetInt("max_file_bytes", int(h.deps.MaxFileBytes)))
 	maxTotalParsedBytes := int64(request.GetInt("max_total_parsed_bytes", int(h.deps.MaxTotalParsedBytes)))
@@ -34,6 +35,7 @@ func (h *handlers) withParseLimitsFromRequest(request mcp.CallToolRequest) *hand
 	return &hCopy
 }
 
+// @intent assemble a short-lived GraphService view from injected MCP dependencies for one parse or update request.
 func (h *handlers) graphService() *service.GraphService {
 	walkers := make(map[string]service.Parser, len(h.deps.Walkers))
 	for ext, parser := range h.deps.Walkers {
@@ -474,6 +476,7 @@ func (h *handlers) runPostprocess(ctx context.Context, request mcp.CallToolReque
 	return mcp.NewToolResultText(jsonStr), nil
 }
 
+// @intent append values to a slice while preserving uniqueness for skipped-step reporting.
 func appendUniqueStrings(dst []string, values ...string) []string {
 	for _, value := range values {
 		if !slices.Contains(dst, value) {
@@ -483,6 +486,7 @@ func appendUniqueStrings(dst []string, values ...string) []string {
 	return dst
 }
 
+// @intent restrict parse and build requests to configured analysis roots before filesystem traversal begins.
 func (h *handlers) validateAnalysisPath(path string) (string, error) {
 	if path == "" {
 		return "", fmt.Errorf("path is required")
@@ -505,6 +509,7 @@ func (h *handlers) validateAnalysisPath(path string) (string, error) {
 	return target, nil
 }
 
+// @intent resolve a path to its absolute, symlink-evaluated form for analysis-root containment checks.
 func canonicalExistingPath(path string) (string, error) {
 	abs, err := filepath.Abs(path)
 	if err != nil {

internal/mcp/handler_postprocess.go

@@ -1,3 +1,4 @@
+// @index MCP handlers for inspecting and resetting automatic postprocess policy state.
 package mcp
 
 import (
@@ -8,6 +9,8 @@ import (
 	postprocesspolicy "github.com/tae2089/code-context-graph/internal/postprocess/policy"
 )
 
+// getPostprocessPolicy returns the recorded postprocess policy summary for a namespace and tool.
+// @intent expose automatic fail-open versus fail-closed decisions so operators can diagnose degraded postprocess behavior.
 func (h *handlers) getPostprocessPolicy(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	ctx = h.applyWorkspace(ctx, request)
 	if h.deps.PostprocessPolicy == nil {
@@ -33,6 +36,8 @@ func (h *handlers) getPostprocessPolicy(ctx context.Context, request mcp.CallToo
 	return finalizeToolResult(result, err)
 }
 
+// resetPostprocessPolicy clears the stored failure streak for a postprocess tool.
+// @intent let operators recover from fail-closed state after they have fixed the underlying issue.
 func (h *handlers) resetPostprocessPolicy(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	ctx = h.applyWorkspace(ctx, request)
 	if h.deps.PostprocessPolicy == nil {

internal/mcp/handlers.go

@@ -1,3 +1,4 @@
+// @index Shared handler helpers and response utilities for MCP tools.
 package mcp
 
 import (
@@ -56,17 +57,20 @@ func (h *handlers) logger() *slog.Logger {
 	return slog.Default()
 }
 
+// @intent attach the requested namespace to handler context before downstream stores and analyzers run.
 func (h *handlers) applyWorkspace(ctx context.Context, request mcp.CallToolRequest) context.Context {
 	return ctxns.WithNamespace(ctx, resolveNamespace(ctx, requestNamespace(request)))
 }
 
+// @intent prefer explicit request namespace while falling back to the namespace already carried on context.
 func resolveNamespace(ctx context.Context, workspace string) string {
 	if workspace != "" {
 		return ctxns.Normalize(workspace)
 	}
 	return ctxns.FromContext(ctx)
 }
 
+// @intent read namespace isolation arguments while supporting the deprecated workspace alias.
 func requestNamespace(request mcp.CallToolRequest) string {
 	if namespace := request.GetString("namespace", ""); namespace != "" {
 		return namespace
@@ -113,6 +117,7 @@ func nodeNotFoundErr(qn string) error {
 	return newToolResultErr(fmt.Sprintf("node %q not found", qn))
 }
 
+// @intent reject zero and negative list limits before handlers hit database queries.
 func validatePositiveLimit(limit int) error {
 	if limit <= 0 {
 		return newToolResultErr(fmt.Sprintf("limit must be > 0, got %d", limit))

internal/mcp/http.go

@@ -1,11 +1,16 @@
+// @index HTTP safety helpers for MCP server endpoints.
 package mcp
 
 import (
 	"net/http"
 )
 
-const maxMCPRequestBodyBytes = 10 << 20 // 10 MB
+// maxMCPRequestBodyBytes caps MCP HTTP request bodies at 10 MB.
+const maxMCPRequestBodyBytes = 10 << 20
 
+// @intent cap request memory usage before MCP handlers allocate or parse large request bodies.
+// @ensures requests larger than the configured limit are rejected with 413.
+// @sideEffect wraps the request body with a MaxBytesReader.
 func LimitHTTPBody(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.ContentLength > maxMCPRequestBodyBytes {

internal/mcp/prompts.go

@@ -42,13 +42,15 @@ func promptResult(text string) *mcp.GetPromptResult {
 	}
 }
 
+// @intent pick the namespace for a prompt invocation, preferring an explicit argument over the workspace fallback.
 func resolvePromptNamespace(ctx context.Context, args map[string]string) string {
 	if namespace := args["namespace"]; namespace != "" {
 		return ctxns.Normalize(namespace)
 	}
 	return resolveNamespace(ctx, args["workspace"])
 }
 
+// @intent resolve the on-disk root used to validate prompt repo paths, falling back through namespace and workspace roots.
 func promptNamespaceRoot(deps *Deps) string {
 	if deps.NamespaceRoot != "" {
 		return deps.NamespaceRoot