feat(mcp): add MCP server implementation with typed handlers

[galligan]

Implement MCP server using @modelcontextprotocol/sdk:

• createMcpServer() factory with transport-agnostic architecture
• TypedTool/TypedResource wrappers for schema validation
• Handler-based request processing with Result pattern
• Server lifecycle management (start/stop)
• Comprehensive test coverage (33 tests)

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

Resolves #46

[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

• chore(outfitter): sync templates on pack #108
• chore(changesets): ignore app package #107
• fix(errors): avoid TaggedError extends warnings #106
• chore(release): align package versions to 0.1.0 #105
• docs: add README and CHANGELOG for testing, kit, outfitter #95
• feat(templates): add daemon project template #94
• feat(templates): add MCP server project template #93
• feat(templates): add CLI project template #92
• fix(cli): implement confirmDestructive prompts #104
• fix(cli): implement createCLI and command builder #103
• feat(kit): add @outfitter/kit meta-package #91
• docs(daemon): add README and CHANGELOG #90
• fix(daemon): fix locking module bugs (GREEN phase) #89
• test(daemon): add locking module tests (RED phase) #88
• feat(daemon): add errors, platform, and locking module stubs #87
• feat(outfitter): add doctor command for environment validation #86
• feat(outfitter): add init command with project scaffolding #85
• feat(daemon): add IPC communication and health checks #84
• feat(daemon): add types and lifecycle management #83
• feat(index): add FTS5 full-text search implementation #82
• feat(index): add types for FTS5 full-text search #81
• feat(testing): add MCP and CLI test harnesses #80
• feat(testing): add test fixture utilities #79
• feat(mcp): add MCP server implementation with typed handlers #78 👈 (View in Graphite)
• feat(mcp): add types and interfaces for MCP server #77
• feat(ui): add Shape discriminated union and render() #76
• feat(ui): add createTokens semantic color layer #75
• feat(state): add pagination helpers #74
• feat(logging): add DEFAULT_PATTERNS for common secret redaction #73
• feat(ui): add formatRelative() for human-readable timestamps #72
• feat(state): add encodeCursor/decodeCursor for pagination #71
• feat(types): add hashId() for deterministic short identifiers #70
• feat(contracts): add Logger.child() and fix AssertionError category #69
• feat(config): centralize environment variable access with Zod validation #42
• fix(logging): enable redaction by default when global rules exist #41
• docs(ui): add README, CHANGELOG, and TSDoc comments #39
• docs(state): add README, CHANGELOG, and TSDoc comments #38
• docs(file-ops): add README, CHANGELOG, and TSDoc comments #37
• docs(logging): add README, CHANGELOG, and TSDoc comments #36
• docs(config): add README, CHANGELOG, and TSDoc comments #35
• fix(cli): enforce cursor TTL #114
• fix(tests): remove placeholder tests #113
• chore(gitattributes): prefer ours for bun lockfiles #115
• main

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

[greptile-apps]

Greptile Summary

• Implements MCP (Model Context Protocol) server framework using @modelcontextprotocol/sdk with transport-agnostic architecture, typed handlers, and Result pattern integration
• Adds comprehensive test suite with33 tests covering server creation, tool registration, error handling, and pagination support following TDD principles
• Includes custom Zod-to-JSON Schema converter for MCP protocol compatibility with extensive support for complex Zod types and validation constraints

Important Files Changed

Filename	Overview
packages/mcp/src/server.ts	Core MCP server implementation with tool registration, handler execution, and error translation; start/stop methods are placeholder implementations
packages/mcp/src/schema.ts	Custom Zod-to-JSON Schema converter relying on Zod internals via _def property access which may be brittle across version updates

Confidence score: 4/5

• This PR is generally safe to merge with some considerations around implementation completeness and dependency on Zod internals
• Score reflects solid architecture and comprehensive testing, but deducted one point due to placeholder server lifecycle methods and reliance on potentially unstable Zod internal APIs
• Pay close attention to packages/mcp/src/server.ts for the no-op start/stop methods and packages/mcp/src/schema.ts for Zod internals usage

Sequence Diagram

sequenceDiagram
    participant User
    participant McpServer
    participant ToolHandler
    participant ZodValidator
    participant Logger

    User->>McpServer: "invokeTool(toolName, input)"
    McpServer->>Logger: "debug('Invoking tool')"
    McpServer->>McpServer: "Find tool by name"
    alt Tool not found
        McpServer->>User: "Result.err(McpError 'Tool not found')"
    else Tool found
        McpServer->>ZodValidator: "zodSchema.safeParse(input)"
        alt Input validation fails
            ZodValidator->>McpServer: "parseResult.success = false"
            McpServer->>Logger: "warn('Input validation failed')"
            McpServer->>User: "Result.err(McpError 'Invalid input')"
        else Input valid
            ZodValidator->>McpServer: "parseResult.success = true"
            McpServer->>McpServer: "createHandlerContext()"
            McpServer->>ToolHandler: "handler(validatedInput, ctx)"
            ToolHandler->>McpServer: "Result<output, error>"
            alt Handler returns error
                McpServer->>McpServer: "translateError()"
                McpServer->>Logger: "debug('Tool returned error')"
                McpServer->>User: "Result.err(McpError)"
            else Handler success
                McpServer->>Logger: "debug('Tool completed successfully')"
                McpServer->>User: "Result.ok(output)"
            end
        end
    end

Loading

[greptile-apps]

_{4 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

style: Type assertion loses compile-time safety - the handler types should match but casting bypasses verification

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/mcp/src/server.ts
Line: 169:169

Comment:
**style:** Type assertion loses compile-time safety - the handler types should match but casting bypasses verification

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

[galligan]

Addressed review feedback: schema optional detection now checks both sides of Zod pipelines, added schema tests for effects/pipeline optionality, and aligned the no-op logger with trace/fatal. Submitted via gt.

[galligan]

Addressed review feedback: updated optional detection for Zod pipelines (requires both input/output to allow undefined) and added schema tests covering effects/pipeline optionality. Submitted the update with gt.

[galligan]

Restacked after downstack update (formatRelative test stabilization); no additional changes in this PR.