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 <kdegiorgio@bloomberg.net>
This commit is contained in:
parent
dbf99bebf0
commit
c01fd188d2
1 changed files with 2217 additions and 245 deletions
258
go/sdk/README.md
258
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue