feat: Complete Preview2 interfaces with bidirectional pattern

.github/workflows/main.yml

@@ -6,9 +6,58 @@ on:
     branches: [main]
 
 jobs:
+  pre-commit:
+    name: Pre-commit checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Bazel
+        uses: bazel-contrib/setup-bazel@0.8.1
+        with:
+          bazelisk-cache: true
+          disk-cache: ${{ github.workflow }}
+          repository-cache: true
+
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: Cache pre-commit environments
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files --show-diff-on-failure
+
   abi-up-to-date:
     name: Check ABI files are up-to-date
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: WebAssembly/wit-abi-up-to-date@v19
+    - uses: WebAssembly/wit-abi-up-to-date@v20
+
+  validate-wit:
+    name: Validate WIT Files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bazel
+        uses: bazel-contrib/setup-bazel@0.8.1
+        with:
+          bazelisk-cache: true
+          disk-cache: ${{ github.workflow }}
+          repository-cache: true
+
+      - name: Validate Preview3 WIT
+        run: bazel build //:mcp
+
+      - name: Validate Preview2 WIT
+        run: bazel build //:mcp_preview2

.markdownlint.yaml

@@ -0,0 +1,45 @@
+# Markdownlint configuration for WASI MCP
+# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+# Default state for all rules
+default: true
+
+# MD013/line-length - Line length
+MD013:
+  # Number of characters
+  line_length: 120
+  # Number of characters for headings
+  heading_line_length: 120
+  # Number of characters for code blocks
+  code_block_line_length: 120
+  # Include code blocks
+  code_blocks: true
+  # Include tables
+  tables: true
+  # Include headings
+  headings: true
+  # Strict length checking
+  strict: false
+  # Stern length checking
+  stern: false
+
+# MD033/no-inline-html - Inline HTML
+MD033:
+  # Allowed elements
+  allowed_elements: []
+
+# MD041/first-line-heading - First line in a file should be a top-level heading
+MD041: false
+
+# MD046/code-block-style - Code block style
+MD046:
+  # Block style
+  style: fenced
+
+# MD049/emphasis-style - Emphasis style
+MD049:
+  style: asterisk
+
+# MD050/strong-style - Strong style
+MD050:
+  style: asterisk

.pre-commit-config.yaml

@@ -0,0 +1,61 @@
+# Pre-commit hooks for WASI MCP
+# Install: pip install pre-commit && pre-commit install
+# Run manually: pre-commit run --all-files
+
+repos:
+  # Standard pre-commit hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        name: Trim trailing whitespace
+      - id: end-of-file-fixer
+        name: Fix end of files
+      - id: check-yaml
+        name: Check YAML syntax
+        args: ['--unsafe']  # Allow custom tags in GitHub Actions
+      - id: check-added-large-files
+        name: Check for large files
+        args: ['--maxkb=1000']
+      - id: check-merge-conflict
+        name: Check for merge conflicts
+      - id: mixed-line-ending
+        name: Fix mixed line endings
+        args: ['--fix=lf']
+
+  # Bazel validation (includes WIT validation via rules_wasm_component)
+  - repo: local
+    hooks:
+      - id: bazel-build-preview3
+        name: Bazel build Preview3
+        entry: bazel build //:mcp
+        language: system
+        files: '^(wit/.*\.wit|BUILD\.bazel|WORKSPACE|\.bazelrc|deps\.toml)$'
+        exclude: '^wit/preview2/.*\.wit$'
+        pass_filenames: false
+        verbose: true
+
+      - id: bazel-build-preview2
+        name: Bazel build Preview2
+        entry: bazel build //:mcp_preview2
+        language: system
+        files: '^(wit/preview2/.*\.wit|BUILD\.bazel|WORKSPACE|\.bazelrc|deps\.toml)$'
+        pass_filenames: false
+        verbose: true
+
+  # Markdown linting
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.12.1
+    hooks:
+      - id: markdownlint-cli2
+        name: Lint Markdown files
+        args: ['--config', '.markdownlint.yaml']
+
+  # TOML validation
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    hooks:
+      - id: prettier
+        name: Format TOML files
+        types: [toml]
+        args: ['--write', '--tab-width=2']

BUILD.bazel

@@ -1,4 +1,13 @@
-"""WASI MCP - Model Context Protocol Interface Definitions"""
+"""WASI MCP - Model Context Protocol Interface Definitions
+
+WASI MCP follows a bidirectional system interface pattern:
+- Components IMPORT runtime (register capabilities, start serving)
+- Components EXPORT handlers (execute tools, read resources)
+
+Architecture:
+  Host: Protocol, transport, auth, middleware
+  Component: Domain logic (tools, resources, prompts)
+"""
 
 load("@rules_wasm_component//wit:defs.bzl", "wit_library")
 
@@ -9,6 +18,17 @@ package(default_visibility = ["//visibility:public"])
 # ============================================================================
 
 # WASI MCP WIT Library - Preview3
+#
+# Interfaces:
+# - runtime.wit: Registration and framework APIs (component imports)
+# - handlers.wit: Callback interfaces (component exports)
+# - client.wit: Client operations (component imports)
+# - world.wit: Bidirectional worlds
+#
+# Worlds:
+# - mcp-backend: import runtime + export handlers
+# - mcp-client: import client
+# - mcp-proxy: import runtime + client, export handlers
 wit_library(
     name = "mcp",
     srcs = glob(
@@ -27,11 +47,22 @@ wit_library(
 # ============================================================================
 
 # WASI MCP WIT Library - Preview2
+#
+# Interfaces (blocking versions):
+# - runtime.wit: Registration and framework APIs (component imports)
+# - handlers.wit: Callback interfaces (component exports)
+# - client.wit: Client operations (component imports)
+# - world.wit: Bidirectional worlds
+#
+# Worlds:
+# - mcp-backend-preview2: import runtime + export handlers
+# - mcp-client-preview2: import client
+# - mcp-proxy-preview2: import runtime + client, export handlers
 wit_library(
     name = "mcp_preview2",
     srcs = glob(["wit/preview2/*.wit"]),
     package_name = "wasi:mcp@0.1.0-preview2",
     deps = [
-        "@wasi_clocks_v020//:clocks",   # Preview2 uses 0.2.0
+        "@wasi_clocks_v020//:clocks",   # Preview2 uses WASI 0.2.0
     ],
 )