Implement variant-aware MCP server (#3)

Summary

Builds on the types and architecture from the previous PR to deliver a
working variant-aware MCP
server that routes requests to inner mcp.Server instances based on
per-request _meta variant selection,
enabling a single MCP endpoint to serve multiple tool/resource/prompt
variants simultaneously.
  
  ```go
 // Create standard mcp.Server instances — one per variant
codeReviewServer := mcp.NewServer(&mcp.Implementation{Name:
"devplatform", Version: "v1.0.0"}, nil)
mcp.AddTool(codeReviewServer, &mcp.Tool{Name: "list_pull_requests",
...}, handler)
mcp.AddTool(codeReviewServer, &mcp.Tool{Name: "get_diff", ...}, handler)

pmServer := mcp.NewServer(&mcp.Implementation{Name: "devplatform",
Version: "v1.0.0"}, nil)
  mcp.AddTool(pmServer, &mcp.Tool{Name: "list_issues", ...}, handler)
  mcp.AddTool(pmServer, &mcp.Tool{Name: "create_issue", ...}, handler)

  // Register them as variants on a single server
vs := variants.NewServer(&mcp.Implementation{Name: "devplatform",
Version: "v1.0.0"}).
      WithVariant(variants.ServerVariant{
          ID:          "code-review",
          Description: "PR and code review operations",
          Status:      variants.Stable,
      }, codeReviewServer, 0).
      WithVariant(variants.ServerVariant{
          ID:          "project-management",
          Description: "Issue and project tracking operations",
          Status:      variants.Stable,
      }, pmServer, 1)

      // Future: register variants backed by remote MCP servers
// WithHTTPVariant(v, mcpServer, priority) — variant backed by an
mcp.Server exposed over HTTP
// WithRemoteVariant(v, "https://...", priority) — variant backed by a
remote MCP endpoint

  // Serve over HTTP for multiple concurrent clients
  handler := variants.NewStreamableHTTPHandler(vs, nil)
  http.ListenAndServe(":8080", handler)

  // Or serve over stdio for single-client use:
  // vs.Run(ctx, &mcp.StdioTransport{})
```
  

  Key additions

  - Backend abstraction (inMemoryBackend) — creates in-memory transport pairs between the variant server and
   inner mcp.Server instances, with notification forwarding for progress and logging events.
  - Request dispatcher (dispatch.go) — handles routing for tools/list, tools/call, resources/list,
  resources/read, resources/subscribe, prompts/list, prompts/get, and completion/complete methods.
  Implements variant-scoped cursor wrapping to correctly paginate across multiple inner servers.
  - Session middleware (session.go) — manages per-session inner connections in stateful mode and shared
  connections in stateless HTTP mode, ensuring proper lifecycle management.
  - Initialize enrichment — injects availableVariants into the server's capabilities response so clients can
   discover which variants are available.
  - Capability discovery — merges inner server capabilities via union to present a unified capability set to
   clients.
  - NewStreamableHTTPHandler — provides an HTTP handler for multi-client serving over Streamable HTTP
  transport.
  - Integration tests (server_test.go, 458 lines) — covers end-to-end variant selection, backward
  compatibility (no variant specified), HTTP transport, and stateless modes.
  - Examples — stdio-based (examples/server/variants/main.go) and HTTP-based
  (examples/server/variants-http/main.go) example servers demonstrating the API.
  - README — rewritten with API documentation and architecture diagrams.


TODO (subsequent PRs):
- Unit Testing 
- More integration tests

Signed-off-by: Kurt Degiorgio <[email protected]>

Author: Degiorgio

go/sdk/README.md

@@ -1,3 +1,259 @@
 # MCP Variants - Go Implementation
 
-This will contain the Go implementation of the MCP Variants based on [SEP-2053](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2053).
+Go implementation of [SEP-2053: Server Variants](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2053) — a server-level variant mechanism for MCP that lets servers expose multiple tool/resource/prompt sets simultaneously, selectable per-request via `_meta`.
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "log"
+    "net/http"
+
+    "github.com/modelcontextprotocol/go-sdk/mcp"
+    "github.com/modelcontextprotocol/experimental-ext-variants/go/sdk/variants"
+)
+
+func main() {
+    // Code review variant: PR-focused tools
+    codeReviewServer := mcp.NewServer(&mcp.Implementation{Name: "devplatform", Version: "v1.0.0"}, nil)
+    mcp.AddTool(codeReviewServer, &mcp.Tool{
+        Name:        "list_pull_requests",
+        Description: "List open pull requests, optionally filtered by author",
+    }, listPullRequests)
+    mcp.AddTool(codeReviewServer, &mcp.Tool{
+        Name:        "get_diff",
+        Description: "Get the diff for a pull request",
+    }, getDiff)
+
+    // Project management variant: issue-focused tools
+    pmServer := mcp.NewServer(&mcp.Implementation{Name: "devplatform", Version: "v1.0.0"}, nil)
+    mcp.AddTool(pmServer, &mcp.Tool{
+        Name:        "list_issues",
+        Description: "List issues, optionally filtered by state and labels",
+    }, listIssues)
+    mcp.AddTool(pmServer, &mcp.Tool{
+        Name:        "create_issue",
+        Description: "Create a new issue with title, body, and optional labels",
+    }, createIssue)
+
+    vs := variants.NewServer(&mcp.Implementation{Name: "devplatform", Version: "v1.0.0"}).
+        WithVariant(variants.ServerVariant{
+            ID:          "code-review",
+            Description: "Pull request and code review operations. Includes diff viewing, review comments, approval workflows, and merge controls.",
+            Hints:       map[string]string{"domain": "code-review", "accessLevel": "read-write"},
+            Status:      variants.Stable,
+        }, codeReviewServer, 0).
+        WithVariant(variants.ServerVariant{
+            ID:          "project-management",
+            Description: "Issue and project tracking operations. Includes issue CRUD, labels, milestones, assignments, and project boards.",
+            Hints:       map[string]string{"domain": "project-management", "accessLevel": "read-write"},
+            Status:      variants.Stable,
+        }, pmServer, 1)
+
+    // Serve over HTTP (or use vs.Run(ctx, &mcp.StdioTransport{}) for stdio)
+    handler := variants.NewStreamableHTTPHandler(vs, nil)
+    log.Fatal(http.ListenAndServe(":8080", handler))
+}
+```
+
+Clients select a variant per-request via `_meta`:
+
+```json
+{
+  "method": "tools/list",
+  "params": {
+    "_meta": {
+      "io.modelcontextprotocol/server-variant": "code-review"
+    }
+  }
+}
+```
+
+Clients that don't know about variants get the default (first-ranked) variant automatically.
+
+## How It Works
+
+During `initialize`, the server responds with ranked `availableVariants`:
+
+```json
+{
+  "capabilities": {
+    "experimental": {
+      "io.modelcontextprotocol/server-variants": {
+        "availableVariants": [
+          {
+            "id": "code-review",
+            "description": "Pull request and code review operations...",
+            "hints": { "domain": "code-review", "accessLevel": "read-write" },
+            "status": "stable"
+          },
+          {
+            "id": "project-management",
+            "description": "Issue and project tracking operations...",
+            "hints": { "domain": "project-management", "accessLevel": "read-write" },
+            "status": "stable"
+          }
+        ],
+        "moreVariantsAvailable": false
+      }
+    }
+  }
+}
+```
+
+Each subsequent request can target a specific variant via `_meta`. The server routes the request to the appropriate backing `mcp.Server`:
+
+```
+Client ── transport ──▸ variants.Server ──▸ sessionMiddleware
+                                                 │
+                                    ┌────────────┼────────────┐
+                                    │            │            │
+                              initialize    route by     pass through
+                              (create        _meta       (ping, etc.)
+                               per-session   variant
+                               connections)     │
+                                                ▼
+                                           dispatcher
+                                                │
+                          ┌────────────┬────────┴────────┬────────────┐
+                          ▼            ▼                 ▼            ▼
+                    code-review  project-mgmt   security-readonly  ci-automation
+                    (mcp.Server) (mcp.Server)   (mcp.Server)       (mcp.Server)
+```
+
+In **stateful mode** (default, stdio and HTTP), per-session inner connections are created during `initialize` and scoped to the client session's lifetime. In **stateless mode** (via `NewStreamableHTTPHandler` with `Stateless: true`), a single set of shared connections is created at construction and reused across all requests.
+
+## Features
+
+- **Variant isolation**: each variant is a full `mcp.Server` with its own tools, resources, and prompts
+- **Per-request selection**: variant chosen via `_meta` field, no session state needed
+- **Default fallback**: clients without variant support get the first-ranked variant
+- **Custom ranking**: provide a `RankingFunc` to rank variants based on client hints
+- **Cursor scoping**: pagination cursors are variant-scoped and cannot be reused across variants (per SEP-2053)
+- **Namespace scoping**: tool names, prompt names, and resource URIs resolve within the active variant's namespace; errors include `activeVariant` in error data
+- **Notification forwarding**: progress and logging notifications from inner servers are forwarded to the front client with variant metadata injected
+- **HTTP and stdio**: works with both `StdioTransport` and `StreamableHTTPHandler`
+
+## Examples
+
+See [`examples/server/`](examples/server/) for runnable examples:
+
+- [`variants/`](examples/server/variants/) — stdio transport (single client)
+- [`variants-http/`](examples/server/variants-http/) — HTTP transport (multiple concurrent clients)
+
+## API
+
+### Server
+
+#### `variants.NewServer(impl *mcp.Implementation) *Server`
+
+Creates a new variant-aware server with no registered variants. `impl` must not be nil.
+
+#### `(*Server).WithVariant(v ServerVariant, mcpServer *mcp.Server, priority int) *Server`
+
+Registers a variant backed by an in-memory `mcp.Server`. `priority` determines the default ordering when no `RankingFunc` is set — lower values rank higher (0 = highest priority). Panics on duplicate variant IDs. Returns the receiver for chaining.
+
+#### `(*Server).WithRanking(fn RankingFunc) *Server`
+
+Sets a custom ranking function used to order variants based on client hints during initialization. If nil, variants are ordered by priority value.
+
+#### `(*Server).Variants() []ServerVariant`
+
+Returns a copy of all registered variants in registration order.
+
+#### `(*Server).RankedVariants(ctx context.Context, hints VariantHints) []ServerVariant`
+
+Returns registered variants ranked by the configured `RankingFunc` (or default priority-based ranking).
+
+#### `(*Server).Run(ctx context.Context, t mcp.Transport) error`
+
+Starts the server on the given transport (e.g., `&mcp.StdioTransport{}`). For multi-client HTTP support, use `NewStreamableHTTPHandler` instead.
+
+#### `(*Server).Close() error`
+
+Releases resources held by all registered backends.
+
+#### `variants.NewStreamableHTTPHandler(vs *Server, opts *mcp.StreamableHTTPOptions) *mcp.StreamableHTTPHandler`
+
+Returns an `http.Handler` for serving multiple concurrent clients over HTTP. Pass `&mcp.StreamableHTTPOptions{Stateless: true}` for stateless mode.
+
+### Types
+
+#### `ServerVariant`
+
+Describes a selectable variant:
+
+```go
+type ServerVariant struct {
+    ID              string            `json:"id"`
+    Description     string            `json:"description"`
+    Hints           map[string]string `json:"hints,omitempty"`
+    Status          VariantStatus     `json:"status,omitempty"`
+    DeprecationInfo *DeprecationInfo  `json:"deprecationInfo,omitempty"`
+}
+```
+
+`Priority() int` returns the priority value set during registration.
+
+#### `VariantStatus`
+
+```go
+const (
+    Stable       VariantStatus = "stable"
+    Experimental VariantStatus = "experimental"
+    Deprecated   VariantStatus = "deprecated"
+)
+```
+
+#### `DeprecationInfo`
+
+Migration guidance for deprecated variants:
+
+```go
+type DeprecationInfo struct {
+    Message     string `json:"message"`
+    Replacement string `json:"replacement,omitempty"`
+    RemovalDate string `json:"removalDate,omitempty"`
+}
+```
+
+#### `VariantHints`
+
+Client-provided hints for variant selection, sent during `initialize`:
+
+```go
+type VariantHints struct {
+    Description string         `json:"description,omitempty"`
+    Hints       map[string]any `json:"hints,omitempty"`
+}
+```
+
+#### `HintValue[T any](h VariantHints, key string) (T, bool)`
+
+Generic helper to extract a typed value from a `VariantHints` map.
+
+#### `RankingFunc`
+
+```go
+type RankingFunc func(ctx context.Context, hints VariantHints, variants []ServerVariant) []ServerVariant
+```
+
+Called during initialization to rank variants based on client hints. Must return variants sorted by relevance, most appropriate first.
+
+#### Well-known hint keys
+
+| Constant | Key | Example values |
+|---|---|---|
+| `HintModelFamily` | `"modelFamily"` | `"anthropic"`, `"openai"`, `"local"`, `"any"` |
+| `HintUseCase` | `"useCase"` | `"autonomous-agent"`, `"ide"`, `"chat"` |
+| `HintContextSize` | `"contextSize"` | `"compact"`, `"standard"`, `"verbose"` |
+| `HintRenderingCapabilities` | `"renderingCapabilities"` | `"rich"`, `"markdown"`, `"text-only"` |
+| `HintLanguageOptimization` | `"languageOptimization"` | `"en"`, `"multilingual"`, `"code-focused"` |
+
+## Known Limitations
+
+- **Default variant resolution**: When a client omits `_meta` variant selection, the server re-ranks variants with empty hints to determine the default. This may differ from the ranking returned during `initialize` (where client hints were used). Per SEP-2053, the default should be the first variant from the `initialize` response. To fix this, the per-session ranked order needs to be stored during `initialize` and reused for subsequent requests.
+- **List-changed notifications**: Dynamic capability changes from inner servers (tool/resource/prompt list changes) are not forwarded to front clients. The Go MCP SDK does not expose generic notification sending on `ServerSession`. In practice this is acceptable because inner servers are typically statically configured.
+- **HTTP and remote backends**: `WithHTTPVariant` and `WithRemoteVariant` are not yet implemented.