Add example servers for SEP-2053 variant patterns (#4)

Add four new example servers demonstrating different SEP-2053 variant
patterns:

- model-optimized (same tools, different descriptions per LLM family)
- trading (API versioning with deprecation lifecycle)
- research (context budget management)
- Refactor the existing variants-http example into a GitHub-style server
with custom ranking.

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

Author: Degiorgio

README.md

@@ -13,6 +13,34 @@ This repository provides a multi-language reference implementation of the varian
 | TypeScript | `typescript/sdk/` | `@ext-modelcontextprotocol/variants` | Planned |
 
 
+## Examples (Go)
+
+The Go implementation includes runnable example servers under [`go/sdk/examples/server/`](go/sdk/examples/server/):
+
+### [`model-optimized/`](go/sdk/examples/server/model-optimized/)
+
+Same tools, different descriptions per LLM family.
+
+https://github.com/user-attachments/assets/5bb60cd2-291f-4940-abfe-f53852d35470
+
+### [`github/`](go/sdk/examples/server/github/)
+
+Different tool sets per variant with custom ranking.
+
+https://github.com/user-attachments/assets/d770ac55-e988-4d89-bdf8-bcb3cf1e2e53
+
+### [`research/`](go/sdk/examples/server/research/)
+
+Context budget management via description verbosity.
+
+### [`trading/`](go/sdk/examples/server/trading/)
+
+API versioning, lifecycle statuses, and deprecation info.
+
+### [`variants-stdio/`](go/sdk/examples/server/variants-stdio/)
+
+Minimal single-variant setup.
+
 ## CI/CD
 
 This monorepo uses **path-based CI workflows** to efficiently test only what changes:

go/sdk/README.md

@@ -138,10 +138,7 @@ In **stateful mode** (default, stdio and HTTP), per-session inner connections ar
 
 ## 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)
+See [`examples/server/`](examples/server/) for runnable examples.
 
 ## API
 

go/sdk/examples/server/github/README.md

@@ -0,0 +1,30 @@
+# GitHub Developer Platform
+
+A variant-aware MCP server that exposes different tool sets for different agent types, mirroring the GitHub MCP Server pattern described in SEP-2053's Prior Art section.
+
+**Pattern demonstrated:** Different tool sets per variant with custom ranking.
+
+## Variants
+
+| Variant | Tools | Description |
+|---|---|---|
+| `code-review` | `list_pull_requests`, `get_diff`, `add_review_comment` | PR operations and code review |
+| `project-management` | `list_issues`, `create_issue`, `add_label` | Issue tracking and labels |
+| `security-readonly` | `list_security_alerts`, `get_advisory` | Security scanning (read-only) |
+| `ci-automation` | `list_workflow_runs`, `trigger_workflow` | CI/CD workflow management |
+
+## Custom Ranking
+
+Clients send a `"domain"` hint during initialization. The ranking function boosts variants whose `domain` hint matches the client's requested domain, falling back to priority order.
+
+## Run
+
+```bash
+go run ./examples/server/github
+```
+
+Connect any MCP client to `http://localhost:8080`.
+
+## Demo
+
+See [mcp-inspector-variants-demo.mp4](mcp-inspector-variants-demo.mp4) for a walkthrough using MCP Inspector.

…dk/examples/server/variants-http/main.go go/sdk/examples/server/github/main.gogo/sdk/examples/server/variants-http/main.go renamed to go/sdk/examples/server/github/main.go go/sdk/examples/server/variants-http/main.go renamed to go/sdk/examples/server/github/main.go

@@ -1,6 +1,10 @@
-// Example: A developer productivity platform (à la GitHub) that exposes
-// different tool sets for different agent types using MCP server variants,
-// served over HTTP for multiple concurrent clients.
+// Example: GitHub MCP Server — a developer productivity platform that exposes
+// different tool sets for different agent types using MCP server variants.
+// This mirrors the GitHub MCP Server pattern described in SEP-2053's Prior Art
+// section, where a single server exposes code review, project management,
+// security, and CI/CD tools as separate variants with custom ranking.
+//
+// Capability demonstrated: Different tool sets per variant, custom ranking.
 //
 // Variants:
 //   - code-review: PR operations, diffs, and review comments
@@ -10,18 +14,20 @@
 //
 // Run:
 //
-//	go run .
+//	go run ./examples/server/github
 //
 // Then connect any MCP client to http://localhost:8080.
 package main
 
 import (
+	"context"
 	"log"
 	"net/http"
+	"slices"
+	"strings"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 
-	"github.com/modelcontextprotocol/experimental-ext-variants/go/sdk/examples/server/exampletools"
 	"github.com/modelcontextprotocol/experimental-ext-variants/go/sdk/variants"
 )
 
@@ -31,52 +37,52 @@ func main() {
 	mcp.AddTool(codeReviewServer, &mcp.Tool{
 		Name:        "list_pull_requests",
 		Description: "List open pull requests, optionally filtered by author",
-	}, exampletools.ListPullRequests)
+	}, listPullRequests)
 	mcp.AddTool(codeReviewServer, &mcp.Tool{
 		Name:        "get_diff",
 		Description: "Get the diff for a pull request, including changed files and line counts",
-	}, exampletools.GetDiff)
+	}, getDiff)
 	mcp.AddTool(codeReviewServer, &mcp.Tool{
 		Name:        "add_review_comment",
 		Description: "Post a review comment on a specific line of a pull request",
-	}, exampletools.AddReviewComment)
+	}, addReviewComment)
 
 	// Project management variant: issue-focused tools for PM agents
 	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",
-	}, exampletools.ListIssues)
+	}, listIssues)
 	mcp.AddTool(pmServer, &mcp.Tool{
 		Name:        "create_issue",
 		Description: "Create a new issue with title, body, and optional labels",
-	}, exampletools.CreateIssue)
+	}, createIssue)
 	mcp.AddTool(pmServer, &mcp.Tool{
 		Name:        "add_label",
 		Description: "Add labels to an existing issue",
-	}, exampletools.AddLabel)
+	}, addLabel)
 
 	// Security variant: read-only security scanning tools
 	securityServer := mcp.NewServer(&mcp.Implementation{Name: "devplatform", Version: "v1.0.0"}, nil)
 	mcp.AddTool(securityServer, &mcp.Tool{
 		Name:        "list_security_alerts",
 		Description: "List code scanning alerts for a repository",
-	}, exampletools.ListSecurityAlerts)
+	}, listSecurityAlerts)
 	mcp.AddTool(securityServer, &mcp.Tool{
 		Name:        "get_advisory",
 		Description: "Get details of a security advisory",
-	}, exampletools.GetAdvisory)
+	}, getAdvisory)
 
 	// CI/CD variant: workflow management tools for automation agents
 	ciServer := mcp.NewServer(&mcp.Implementation{Name: "devplatform", Version: "v1.0.0"}, nil)
 	mcp.AddTool(ciServer, &mcp.Tool{
 		Name:        "list_workflow_runs",
 		Description: "List recent workflow runs for a repository",
-	}, exampletools.ListWorkflowRuns)
+	}, listWorkflowRuns)
 	mcp.AddTool(ciServer, &mcp.Tool{
 		Name:        "trigger_workflow",
 		Description: "Trigger a workflow dispatch event",
-	}, exampletools.TriggerWorkflow)
+	}, triggerWorkflow)
 
 	vs := variants.NewServer(&mcp.Implementation{Name: "devplatform", Version: "v1.0.0"}).
 		WithVariant(variants.ServerVariant{
@@ -102,7 +108,23 @@ func main() {
 			Description: "CI/CD workflow management. Trigger runs, monitor jobs, manage deployments designed for automation agents.",
 			Hints:       map[string]string{"domain": "ci-cd", "accessLevel": "automation"},
 			Status:      variants.Stable,
-		}, ciServer, 3)
+		}, ciServer, 3).
+		// Custom ranking: boost variants whose "domain" hint matches the client's.
+		WithRanking(func(_ context.Context, hints variants.VariantHints, vs []variants.ServerVariant) []variants.ServerVariant {
+			requested, _ := variants.HintValue[string](hints, "domain")
+			slices.SortStableFunc(vs, func(a, b variants.ServerVariant) int {
+				aMatch := strings.Contains(strings.ToLower(a.Hints["domain"]), strings.ToLower(requested))
+				bMatch := strings.Contains(strings.ToLower(b.Hints["domain"]), strings.ToLower(requested))
+				if aMatch != bMatch {
+					if aMatch {
+						return -1
+					}
+					return 1
+				}
+				return a.Priority() - b.Priority()
+			})
+			return vs
+		})
 
 	handler := variants.NewStreamableHTTPHandler(vs, nil)
 

…dk/examples/server/exampletools/tools.go go/sdk/examples/server/github/tools.gogo/sdk/examples/server/exampletools/tools.go renamed to go/sdk/examples/server/github/tools.go go/sdk/examples/server/exampletools/tools.go renamed to go/sdk/examples/server/github/tools.go

@@ -1,12 +1,4 @@
-// Package exampletools defines the shared tool types and handlers used by the
-// variant-aware MCP server examples. The tools simulate a developer
-// productivity platform (à la GitHub/GitLab) with four variants:
-//
-//   - code-review: PR operations, diffs, and review comments
-//   - project-management: issue tracking, labels, and assignments
-//   - security-readonly: security scanning alerts and advisories (read-only)
-//   - ci-automation: CI/CD workflow management and dispatch
-package exampletools
+package main
 
 import (
 	"context"
@@ -34,7 +26,7 @@ type ListPullRequestsOutput struct {
 	PullRequests []PullRequest `json:"pullRequests"`
 }
 
-func ListPullRequests(_ context.Context, _ *mcp.CallToolRequest, in ListPullRequestsInput) (*mcp.CallToolResult, ListPullRequestsOutput, error) {
+func listPullRequests(_ context.Context, _ *mcp.CallToolRequest, in ListPullRequestsInput) (*mcp.CallToolResult, ListPullRequestsOutput, error) {
 	return nil, ListPullRequestsOutput{
 		PullRequests: []PullRequest{
 			{Number: 42, Title: "Add retry logic to API client", Author: "alice", State: "open"},
@@ -56,7 +48,7 @@ type GetDiffOutput struct {
 	Deletions int      `json:"deletions"`
 }
 
-func GetDiff(_ context.Context, _ *mcp.CallToolRequest, in GetDiffInput) (*mcp.CallToolResult, GetDiffOutput, error) {
+func getDiff(_ context.Context, _ *mcp.CallToolRequest, in GetDiffInput) (*mcp.CallToolResult, GetDiffOutput, error) {
 	return nil, GetDiffOutput{
 		Diff:      "--- a/client.go\n+++ b/client.go\n@@ -45,6 +45,12 @@\n+  for attempt := 0; attempt < maxRetries; attempt++ {\n+    resp, err := c.do(req)\n+    if err == nil { return resp, nil }\n+    time.Sleep(backoff(attempt))\n+  }",
 		Files:     []string{"client.go", "client_test.go"},
@@ -78,7 +70,7 @@ type AddReviewCommentOutput struct {
 	URL       string `json:"url"`
 }
 
-func AddReviewComment(_ context.Context, _ *mcp.CallToolRequest, in AddReviewCommentInput) (*mcp.CallToolResult, AddReviewCommentOutput, error) {
+func addReviewComment(_ context.Context, _ *mcp.CallToolRequest, in AddReviewCommentInput) (*mcp.CallToolResult, AddReviewCommentOutput, error) {
 	return nil, AddReviewCommentOutput{
 		CommentID: 1001,
 		URL:       fmt.Sprintf("https://github.com/%s/pull/%d#discussion_r1001", in.Repo, in.Number),
@@ -105,7 +97,7 @@ type ListIssuesOutput struct {
 	Issues []Issue `json:"issues"`
 }
 
-func ListIssues(_ context.Context, _ *mcp.CallToolRequest, in ListIssuesInput) (*mcp.CallToolResult, ListIssuesOutput, error) {
+func listIssues(_ context.Context, _ *mcp.CallToolRequest, in ListIssuesInput) (*mcp.CallToolResult, ListIssuesOutput, error) {
 	return nil, ListIssuesOutput{
 		Issues: []Issue{
 			{Number: 101, Title: "API rate limiting returns wrong status code", State: "open", Labels: []string{"bug", "api"}, Assignee: "alice"},
@@ -127,7 +119,7 @@ type CreateIssueOutput struct {
 	URL    string `json:"url"`
 }
 
-func CreateIssue(_ context.Context, _ *mcp.CallToolRequest, in CreateIssueInput) (*mcp.CallToolResult, CreateIssueOutput, error) {
+func createIssue(_ context.Context, _ *mcp.CallToolRequest, in CreateIssueInput) (*mcp.CallToolResult, CreateIssueOutput, error) {
 	return nil, CreateIssueOutput{
 		Number: 102,
 		URL:    fmt.Sprintf("https://github.com/%s/issues/102", in.Repo),
@@ -144,7 +136,7 @@ type AddLabelOutput struct {
 	Labels []string `json:"currentLabels"`
 }
 
-func AddLabel(_ context.Context, _ *mcp.CallToolRequest, in AddLabelInput) (*mcp.CallToolResult, AddLabelOutput, error) {
+func addLabel(_ context.Context, _ *mcp.CallToolRequest, in AddLabelInput) (*mcp.CallToolResult, AddLabelOutput, error) {
 	return nil, AddLabelOutput{
 		Labels: append([]string{"bug", "api"}, in.Labels...),
 	}, nil
@@ -170,7 +162,7 @@ type ListSecurityAlertsOutput struct {
 	Alerts []SecurityAlert `json:"alerts"`
 }
 
-func ListSecurityAlerts(_ context.Context, _ *mcp.CallToolRequest, in ListSecurityAlertsInput) (*mcp.CallToolResult, ListSecurityAlertsOutput, error) {
+func listSecurityAlerts(_ context.Context, _ *mcp.CallToolRequest, in ListSecurityAlertsInput) (*mcp.CallToolResult, ListSecurityAlertsOutput, error) {
 	return nil, ListSecurityAlertsOutput{
 		Alerts: []SecurityAlert{
 			{Number: 1, Rule: "sql-injection", Severity: "critical", State: "open", Path: "src/db/query.go"},
@@ -193,7 +185,7 @@ type GetAdvisoryOutput struct {
 	PatchedIn   string   `json:"patchedIn"`
 }
 
-func GetAdvisory(_ context.Context, _ *mcp.CallToolRequest, in GetAdvisoryInput) (*mcp.CallToolResult, GetAdvisoryOutput, error) {
+func getAdvisory(_ context.Context, _ *mcp.CallToolRequest, in GetAdvisoryInput) (*mcp.CallToolResult, GetAdvisoryOutput, error) {
 	return nil, GetAdvisoryOutput{
 		ID:          in.AdvisoryID,
 		Summary:     "Remote code execution via crafted request payload",
@@ -224,7 +216,7 @@ type ListWorkflowRunsOutput struct {
 	Runs []WorkflowRun `json:"runs"`
 }
 
-func ListWorkflowRuns(_ context.Context, _ *mcp.CallToolRequest, in ListWorkflowRunsInput) (*mcp.CallToolResult, ListWorkflowRunsOutput, error) {
+func listWorkflowRuns(_ context.Context, _ *mcp.CallToolRequest, in ListWorkflowRunsInput) (*mcp.CallToolResult, ListWorkflowRunsOutput, error) {
 	return nil, ListWorkflowRunsOutput{
 		Runs: []WorkflowRun{
 			{ID: 5001, Workflow: "ci.yml", Status: "completed", Conclusion: "success", Branch: "main"},
@@ -246,7 +238,7 @@ type TriggerWorkflowOutput struct {
 	URL   string `json:"url"`
 }
 
-func TriggerWorkflow(_ context.Context, _ *mcp.CallToolRequest, in TriggerWorkflowInput) (*mcp.CallToolResult, TriggerWorkflowOutput, error) {
+func triggerWorkflow(_ context.Context, _ *mcp.CallToolRequest, in TriggerWorkflowInput) (*mcp.CallToolResult, TriggerWorkflowOutput, error) {
 	return nil, TriggerWorkflowOutput{
 		RunID: 5004,
 		URL:   fmt.Sprintf("https://github.com/%s/actions/runs/5004", in.Repo),