Implement Go interceptor chain (#4)

## Summary

Implements the Go SDK for MCP interceptors — validation and mutation
middleware for any MCP server.

The framework treats interceptors as first-class MCP primitives: they
are registered on an MCP server, discoverable via `interceptors/list`,
and invocable via `interceptor/invoke` — the same JSON-RPC pattern as
tools, prompts, and resources. A chain engine orchestrates execution
across one or more interceptor servers, and an optional go-sdk
middleware integration applies interceptors automatically on every
matching request/response.

## Architecture

**Three-layer design:**

1. **`interceptors`** — Protocol-agnostic core. Defines interceptor
types (validators, mutators), metadata, invocation, wire types, and
results. Zero MCP dependencies.

2. **`interceptors/mcpserver`** — MCP server integration. Wraps
`mcp.Server` to register `interceptors/list` and `interceptor/invoke` as
custom JSON-RPC methods and advertise interceptor capabilities during
`initialize`.

3. **`interceptors/chain`** — Chain engine. Orchestrates execution
across N interceptor servers with trust-boundary-aware ordering,
priority-based mutation sequencing, parallel validation, audit-mode
isolation, and fail-open/fail-closed semantics.

4. **`interceptors/integrations/gomiddleware`** — Optional go-sdk
middleware. Installs on `mcp.Server` via `AddReceivingMiddleware()` to
automatically run the interceptor chain on every matching
request/response.

**Key design decisions:**

- **Trust-boundary ordering** — request phase: validate → mutate;
response phase: mutate → validate. Validation always guards the boundary
crossing.
- **Wire-level invocation** — the chain calls `interceptor/invoke` over
the MCP transport (even in-process via `LocalChain()`), so local and
remote interceptor servers use the same interface.
- **Audit-mode isolation** — audit-mode mutators compute transformations
without applying them. Only audit mutators pay the serialization cost.
- **Concurrency** — validators run in parallel; mutators run
sequentially in priority order.

### Package Structure

| Package | File | Responsibility |
|---------|------|----------------|
| `interceptors` | `interceptor.go` | Enums, Metadata, Interceptor
interface, Validator/Mutator structs, handler types, Invocation |
| `interceptors` | `wire.go` | Wire types: ListParams/Result,
InvokeParams/Result, InterceptorInfo, event/method constants |
| `interceptors` | `priority.go` | Priority with phase-aware resolution
and JSON marshaling |
| `interceptors` | `doc.go` | Package documentation with examples |
| `interceptors/chain` | `chain.go` | Chain engine: discovery,
filtering, sorting, execution orchestration |
| `interceptors/chain` | `result.go` | ExecutionResult, AbortInfo |
| `interceptors/chain` | `doc.go` | Sub-package documentation |
| `interceptors/mcpserver` | `server.go` | MCP server wrapper,
interceptor registry, capability advertisement, `LocalChain()` |
| `interceptors/mcpserver` | `rpc.go` | `interceptors/list` and
`interceptor/invoke` JSON-RPC handlers |
| `interceptors/mcpserver` | `doc.go` | Sub-package documentation |
| `integrations/gomiddleware` | `middleware.go` | go-sdk `Middleware`
that runs the chain on every request/response |
| `integrations/gomiddleware` | `errors.go` | Abort-to-JSONRPC error
conversion |
| `integrations/gomiddleware` | `doc.go` | Sub-package documentation |

### Documentation

- `doc/DESIGN.md` — architecture, execution model, integration with
go-sdk
- `doc/CONFORMANCE.md` — SEP conformance status
- `doc/PERFORMANCE.md` — per-request cost model

### Examples

- `examples/validator` — blocks dangerous tool calls, demonstrates
`WithContextProvider`
- `examples/mutator` — tags tool responses with audit trail

## Vendor: go-sdk v1.4.0 with custom method support

Vendors `go-sdk` with minimal extensions for custom JSON-RPC methods:

- `Server.AddCustomMethod` — registers a handler that bypasses the typed
pipeline
- `ClientSession.CallCustom` — sends raw JSON-RPC calls for custom
methods

These changes are generic (not interceptor-specific) and enable any MCP
extension to define its own JSON-RPC methods.

## TODO

- More integration tests
- Unit tests
- Support wildcards for event interception (separate PR)

---------

Signed-off-by: Kurt Degiorgio <kdegiorgio@bloomberg.net>

go/sdk/examples/validator/main.go

@@ -0,0 +1,106 @@
+// Example: a simple validator interceptor that rejects tool calls
+// to a tool named "dangerous_tool".
+//
+// Demonstrates WithContextProvider to populate Invocation.Context with
+// caller identity, which interceptor handlers can inspect.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors"
+	"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors/integrations/gomiddleware"
+	"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors/mcpserver"
+)
+
+func main() {
+	mcpServer := mcp.NewServer(&mcp.Implementation{
+		Name:    "example-server",
+		Version: "0.1.0",
+	}, nil)
+
+	mcpServer.AddTool(&mcp.Tool{Name: "echo", Description: "echoes input", InputSchema: map[string]any{"type": "object"}},
+		func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("you said: %s", req.Params.Arguments)}},
+			}, nil
+		},
+	)
+
+	// Build the validator.
+	v := &interceptors.Validator{
+		Metadata: interceptors.Metadata{
+			Name: "block-dangerous-tool",
+			Hook: interceptors.Hook{
+				Events: []string{interceptors.EventToolsCall},
+				Phase:  interceptors.PhaseRequest,
+			},
+			Mode: interceptors.ModeEnforce,
+		},
+		Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.ValidationResult, error) {
+			raw, ok := inv.Payload.(json.RawMessage)
+			if !ok {
+				return nil, fmt.Errorf("unexpected payload type %T", inv.Payload)
+			}
+			var params struct {
+				Name string `json:"name"`
+			}
+			if err := json.Unmarshal(raw, &params); err != nil {
+				return nil, err
+			}
+			if params.Name == "dangerous_tool" {
+				reason := "dangerous_tool is not allowed"
+				if inv.Context != nil && inv.Context.Principal != nil {
+					reason = fmt.Sprintf("dangerous_tool is not allowed for %s", inv.Context.Principal.ID)
+				}
+				return &interceptors.ValidationResult{
+					Valid: false,
+					Messages: []interceptors.ValidationMessage{
+						{Message: reason, Severity: interceptors.SeverityError},
+					},
+				}, nil
+			}
+			return &interceptors.ValidationResult{Valid: true}, nil
+		},
+	}
+
+	// Create the interceptor server (registers interceptors as discoverable
+	// resources via interceptors/list and interceptor/invoke).
+	srv := mcpserver.NewServer(mcpServer)
+	srv.AddInterceptor(v)
+
+	// Create a chain connected via in-memory transport.
+	chain, err := srv.LocalChain(context.Background())
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Install middleware for automatic execution on every request/response.
+	// WithContextProvider populates caller identity for interceptor handlers.
+	mcpServer.AddReceivingMiddleware(
+		gomiddleware.Middleware(chain,
+			gomiddleware.WithContextProvider(
+				func(_ context.Context, _ mcp.Request) *interceptors.InvocationContext {
+					return &interceptors.InvocationContext{
+						Principal: &interceptors.Principal{
+							Type: "user",
+							ID:   "example-user",
+						},
+					}
+				},
+			),
+		),
+	)
+
+	handler := mcpserver.NewStreamableHTTPHandler(srv, nil)
+	log.Println("listening on :8080")
+	if err := http.ListenAndServe(":8080", handler); err != nil {
+		log.Fatal(err)
+	}
+}