refactor(mcp): convert handlers to Result-based error handling

[galligan]

Replace all throw statements in MCP handler and utility files with
Result<T, OutfitterError> return types. Security-boundary throws in
filesystem.ts are converted to ValidationError results propagated
through callers. Tests updated from rejects.toThrow() to isErr() checks.

🤘🏻 In-collaboration-with: Claude Code

Greptile Summary

Systematically converts all MCP handler and utility functions from throwing exceptions to returning Result<T, OutfitterError>. Security-boundary path validation in filesystem.ts now returns ValidationError instead of throwing, with errors propagated through all callers. Tests comprehensively updated from rejects.toThrow() to isErr() assertions.

Key changes:

• Input validation uses safeParse() returning ValidationError on failure
• File operations return NotFoundError for missing files
• Config loading failures return InternalError
• Path traversal security checks return ValidationError
• MCP SDK boundary in resources/index.ts unwraps Results and throws for protocol compliance
• All tests pass with new error handling pattern

Confidence Score: 5/5

• Safe to merge - comprehensive refactor with full test coverage
• All tests pass, error handling is systematic and type-safe, security boundary enforcement preserved, no breaking changes to external API
• No files require special attention

Important Files Changed

Filename	Overview
apps/mcp/src/resources/index.ts	Unwraps Result at SDK boundary, converting errors to thrown Error for MCP protocol compliance
apps/mcp/src/resources/todos.ts	Converted to Result returns, propagating errors from collectRecords() and expandInputPaths()
apps/mcp/src/tools/add.ts	Replaced all throws with Result returns, using ValidationError, NotFoundError, and InternalError appropriately
apps/mcp/src/tools/waymark.ts	Updated return type to Result<ToolContent, OutfitterError>, wrapping help action in Result.ok()
apps/mcp/src/utils/filesystem.ts	Converted security-boundary throws to ValidationError results, maintaining workspace boundary enforcement

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[MCP Client Request] --> B[SDK Server Handler]
    B --> C{Tool or Resource?}
    
    C -->|Tool| D[handleWaymarkTool]
    C -->|Resource| E[handleTodosResource]
    
    D --> F{Action Type}
    F -->|scan| G[handleScan]
    F -->|graph| H[handleGraph]
    F -->|add| I[handleAdd]
    F -->|help| J[handleHelp]
    
    G --> K[collectRecords]
    H --> K
    I --> K
    E --> K
    
    K --> L[expandInputPaths]
    L --> M{Path valid?}
    M -->|No| N[Result.err ValidationError]
    M -->|Yes| O[collectFilesRecursive]
    
    O --> P{Escapes workspace?}
    P -->|Yes| N
    P -->|No| Q[Result.ok files]
    
    I --> R[Input Validation]
    R --> S{Valid?}
    S -->|No| T[Result.err ValidationError]
    S -->|Yes| U[Process & Write]
    
    U --> V[Result.ok ToolContent]
    J --> V
    Q --> V
    
    N --> W[SDK Boundary]
    T --> W
    V --> W
    
    W --> X{isErr?}
    X -->|Yes| Y[throw Error]
    X -->|No| Z[Return Value]
    
    Y --> AA[MCP Error Response]
    Z --> AB[MCP Success Response]

Loading

_{Last reviewed commit: c484757}

[galligan]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• refactor(mcp): convert handlers to Result-based error handling #282 👈 (View in Graphite)
• refactor(cli): convert modify.ts and add.ts to typed error flow #281
• refactor(core): convert edit.ts to Result returns #280
• refactor(cli): simplify output format handling in renderRecords #279
• feat(cli): adopt flag presets for shared CLI options #278
• feat(cli): adopt createCLI() for program bootstrap #277
• chore(deps): bump @outfitter/* packages to latest #276
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.