feat: Complete Preview2 interfaces with bidirectional pattern

[avrabe]

Summary

Completes the Preview2 interface implementation following the same bidirectional architecture as Preview3, adding CI validation workflow.

Changes

New Preview2 Interfaces

• runtime.wit (~140 lines) - Registration and framework APIs (blocking, component imports)
• handlers.wit (~110 lines) - Callback interfaces (blocking, component exports)
• client.wit (~90 lines) - Client operations (blocking, component imports)
• world.wit (~30 lines) - Three bidirectional worlds

Architecture

Both Preview2 and Preview3 now follow the same bidirectional pattern:

┌─────────────────────────────────────────┐
│            Host Runtime                  │
│  - MCP Protocol Implementation           │
│  - Transport Layer (stdio/HTTP/WS)      │
│  - Middleware (auth, logging, etc.)     │
└─────────────────────────────────────────┘
                   ↕
         imports runtime
         exports handlers
                   ↕
┌─────────────────────────────────────────┐
│      Component (Your Code)               │
│  - Registration: register-server(), etc. │
│  - Handlers: call-tool(), read-resource()│
└─────────────────────────────────────────┘

Key Principle:

• Component imports runtime (register capabilities, start serving)
• Component exports handlers (execute tools, read resources)
• Host handles protocol, transport, middleware
• Component handles domain logic only

Difference from Preview3: All operations are blocking (no `future`)

CI Workflow

Added .github/workflows/ci.yml:

• ✅ Validates Preview3 WIT files with Bazel
• ✅ Validates Preview2 WIT files with Bazel
• ✅ Checks WIT formatting with wasm-tools

Updated Documentation

• preview2/README.md: Complete architecture documentation with diagrams
• BUILD.bazel: Comprehensive comments explaining interfaces and worlds

Worlds

All three worlds follow bidirectional pattern:

1. mcp-backend-preview2: import runtime + export handlers

   • For components providing tools/resources/prompts

2. mcp-client-preview2: import client

   • For components consuming MCP servers

3. mcp-proxy-preview2: import runtime + client, export handlers

   • For components aggregating/transforming MCP servers

Benefits

• ✅ Follows WASI patterns: Bidirectional like wasi-http
• ✅ Ready for prototyping: Works with stable toolchains today
• ✅ Easy migration: Same architecture as Preview3, just add `future<>` wrappers
• ✅ Validated: CI ensures WIT files are always valid
• ✅ Clean separation: ~60 lines for hello world vs 150+ with old pattern

Testing

Both Preview2 and Preview3 validate successfully:

bazel build //:mcp          # Preview3 ✅
bazel build //:mcp_preview2 # Preview2 ✅

CI will automatically run these checks on every PR.

Related

• Closes any outstanding Preview2 implementation tasks
• Part of the architectural redesign from export-only to bidirectional pattern
• Enables immediate prototyping while Preview3 toolchains mature

[avrabe]

CI Status

✅ WIT Validation: Both Preview2 and Preview3 validate successfully with Bazel

❌ ABI Check: Failing due to tool version issue in the action itself:

failed to find release for tag 'wasm-tools-1.209.1' for platform 'linux' and arch 'x86_64'

This is a pre-existing issue with the WebAssembly/wit-abi-up-to-date@v20 action, not related to the changes in this PR.

Options:

1. Update the action to use a working wasm-tools version
2. Skip/disable this check temporarily
3. Generate the markdown files locally and commit them

The important validation (Bazel build) is passing, confirming the WIT interfaces are syntactically correct and properly structured.