Add MCP Server Card (SEP-2127) types + handler

Introduce a `servercard` package that defines the GitHub MCP Server's
Server Card (SEP-2127) and a public, no-auth HTTP handler that serves it.

The Server Card is a static, remote-only discovery document: it reuses the
identity fields from the registry `server.json` (name, title, description,
repository) and advertises a single streamable-http remote (default
https://api.githubcopilot.com/mcp/, overridable per environment). Following
the spec it omits installable packages, which stay in the registry document.

The handler mirrors the OAuth protected-resource-metadata handler: it serves
`application/mcp-server-card+json` with read-only CORS, a one-hour
Cache-Control, Accept content negotiation, and no authentication. It is
registered at the reserved `<streamable-http-url>/server-card` location (both
`/server-card` and `/mcp/server-card`) so the remote server repository can
mount it identically.

Tests validate emitted cards against the canonical
experimental-ext-server-card JSON Schema and cover the handler's headers,
media type, and method handling.

Refs github/copilot-mcp-core#1855, github/copilot-mcp-core#1853

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

pkg/http/server.go

@@ -17,6 +17,7 @@ import (
 	"github.com/github/github-mcp-server/pkg/github"
 	"github.com/github/github-mcp-server/pkg/http/middleware"
 	"github.com/github/github-mcp-server/pkg/http/oauth"
+	"github.com/github/github-mcp-server/pkg/http/servercard"
 	"github.com/github/github-mcp-server/pkg/inventory"
 	"github.com/github/github-mcp-server/pkg/lockdown"
 	"github.com/github/github-mcp-server/pkg/observability"
@@ -198,6 +199,12 @@ func RunHTTPServer(cfg ServerConfig) error {
 	})
 	logger.Info("OAuth protected resource endpoints registered", "baseURL", cfg.BaseURL)
 
+	r.Group(func(r chi.Router) {
+		// Register the public, no-auth MCP Server Card (SEP-2127) endpoint.
+		servercard.NewHandler(servercard.Config{Version: cfg.Version}).RegisterRoutes(r)
+	})
+	logger.Info("MCP Server Card endpoint registered", "path", servercard.Path)
+
 	addr := resolveListenAddress(cfg.ListenHost, cfg.Port)
 	httpSvr := http.Server{
 		Addr:              addr,

pkg/http/servercard/card.go

@@ -0,0 +1,196 @@
+// Package servercard provides the GitHub MCP Server's MCP Server Card
+// (SEP-2127) types and a public, no-auth HTTP handler that serves it.
+//
+// A Server Card is a static metadata document that describes a remote MCP
+// server — its identity, repository, and HTTP transport — so clients can
+// discover and connect to it before the protocol handshake. It is remote-only
+// and deliberately does NOT enumerate primitives (tools, resources, prompts)
+// or installable packages; those remain in the MCP Registry document
+// (server.json) and runtime listing.
+//
+// See:
+//   - https://github.com/modelcontextprotocol/experimental-ext-server-card
+//   - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127
+package servercard
+
+const (
+	// SchemaURL is the v1 Server Card JSON Schema URI that emitted cards
+	// conform to. The schema is versioned by its `vN` path segment.
+	SchemaURL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json"
+
+	// MediaType is the media type used to serve and request a Server Card.
+	MediaType = "application/mcp-server-card+json"
+
+	// Path is the suffix, relative to a server's streamable-HTTP URL, at which
+	// MCP reserves the recommended Server Card location. A server hosted at
+	// `https://host/mcp` therefore serves its card at `https://host/mcp/server-card`.
+	Path = "/server-card"
+
+	// DefaultRemoteURL is the streamable-HTTP endpoint of the hosted GitHub MCP
+	// Server on github.com. The remote repository overrides this per environment.
+	DefaultRemoteURL = "https://api.githubcopilot.com/mcp/"
+)
+
+// Identity fields reused from the MCP Registry document (server.json) so the
+// Server Card and the registry entry describe the same server.
+const (
+	serverName        = "io.github.github/github-mcp-server"
+	serverTitle       = "GitHub"
+	serverDescription = "Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language."
+	repositoryURL     = "https://github.com/github/github-mcp-server"
+	repositorySource  = "github"
+	// repositoryID is the github.com repository ID for github/github-mcp-server.
+	// It is stable across renames and changes if the repository is recreated.
+	repositoryID = "942771284"
+)
+
+// ServerCard is a static metadata document describing a remote MCP server,
+// suitable for pre-connection discovery. It mirrors the ServerCard interface in
+// modelcontextprotocol/experimental-ext-server-card. Server Cards are
+// remote-only and never carry installable packages.
+type ServerCard struct {
+	// Schema is the Server Card JSON Schema URI this document conforms to.
+	Schema string `json:"$schema"`
+	// Name is the server name in reverse-DNS format with exactly one slash.
+	Name string `json:"name"`
+	// Version is the server version, equivalent to Implementation.version.
+	Version string `json:"version"`
+	// Description is a short, human-readable explanation of server functionality.
+	Description string `json:"description"`
+	// Title is an optional human-readable display name.
+	Title string `json:"title,omitempty"`
+	// WebsiteURL optionally links to the server's homepage or documentation.
+	WebsiteURL string `json:"websiteUrl,omitempty"`
+	// Repository optionally describes the server's source code for inspection.
+	Repository *Repository `json:"repository,omitempty"`
+	// Icons optionally lists sized icons a client may render.
+	Icons []Icon `json:"icons,omitempty"`
+	// Remotes lists the HTTP-based endpoints for connecting to the server.
+	Remotes []Remote `json:"remotes,omitempty"`
+	// Meta carries vendor-specific metadata using reverse-DNS namespacing.
+	Meta map[string]any `json:"_meta,omitempty"`
+}
+
+// Repository describes the MCP server's source code location.
+type Repository struct {
+	// URL is the repository URL for browsing source and cloning.
+	URL string `json:"url"`
+	// Source is the hosting service identifier (e.g. "github").
+	Source string `json:"source"`
+	// Subfolder is an optional clean relative path within a monorepo.
+	Subfolder string `json:"subfolder,omitempty"`
+	// ID is the optional repository identifier owned by the hosting service.
+	ID string `json:"id,omitempty"`
+}
+
+// Remote describes a remote (HTTP-based) MCP server endpoint.
+type Remote struct {
+	// Type is the transport type ("streamable-http" or "sse").
+	Type string `json:"type"`
+	// URL is the endpoint URL template. Variables in {curly_braces} are
+	// substituted from Variables before the client connects.
+	URL string `json:"url"`
+	// Headers describes HTTP headers required or accepted when connecting.
+	Headers []KeyValueInput `json:"headers,omitempty"`
+	// Variables defines values referenced by {curly_braces} in URL and headers.
+	Variables map[string]Input `json:"variables,omitempty"`
+	// SupportedProtocolVersions lists MCP protocol versions this endpoint serves.
+	SupportedProtocolVersions []string `json:"supportedProtocolVersions,omitempty"`
+}
+
+// Input is a user-supplied or pre-set value for a remote URL variable or
+// header value.
+type Input struct {
+	// Description is a human-readable explanation of the input.
+	Description string `json:"description,omitempty"`
+	// IsRequired indicates the input must be supplied to connect.
+	IsRequired bool `json:"isRequired,omitempty"`
+	// IsSecret indicates the value is sensitive and must be handled securely.
+	IsSecret bool `json:"isSecret,omitempty"`
+	// Format specifies the input format ("string", "number", "boolean", "filepath").
+	Format string `json:"format,omitempty"`
+	// Default is the default value for the input.
+	Default string `json:"default,omitempty"`
+	// Placeholder is example guidance shown during configuration.
+	Placeholder string `json:"placeholder,omitempty"`
+	// Value is a pre-set value that end users should not configure.
+	Value string `json:"value,omitempty"`
+	// Choices, when set, constrains the input to one of the listed values.
+	Choices []string `json:"choices,omitempty"`
+}
+
+// KeyValueInput is a named Input used to describe an HTTP header.
+type KeyValueInput struct {
+	Input
+	// Name is the header name.
+	Name string `json:"name"`
+	// Variables defines values referenced by {curly_braces} in Value.
+	Variables map[string]Input `json:"variables,omitempty"`
+}
+
+// Icon is an optionally-sized icon a client may display.
+type Icon struct {
+	// Src is a URI (HTTP(S) or data:) pointing to an icon resource.
+	Src string `json:"src"`
+	// MimeType optionally overrides the source MIME type.
+	MimeType string `json:"mimeType,omitempty"`
+	// Sizes optionally lists sizes (e.g. "48x48" or "any") the icon supports.
+	Sizes []string `json:"sizes,omitempty"`
+	// Theme optionally indicates the theme ("light" or "dark") the icon suits.
+	Theme string `json:"theme,omitempty"`
+}
+
+// Config controls how the GitHub MCP Server card is built.
+type Config struct {
+	// Version is advertised as the card's version and SHOULD match the
+	// runtime serverInfo version. When empty, "0.0.0-dev" is used.
+	Version string
+
+	// RemoteURL is the absolute streamable-HTTP endpoint advertised in the
+	// card's single remote. When empty, DefaultRemoteURL is used. The remote
+	// repository supplies a per-environment URL here.
+	RemoteURL string
+}
+
+// NewServerCard builds the GitHub MCP Server's Server Card from cfg.
+func NewServerCard(cfg Config) *ServerCard {
+	version := cfg.Version
+	if version == "" {
+		version = "0.0.0-dev"
+	}
+
+	remoteURL := cfg.RemoteURL
+	if remoteURL == "" {
+		remoteURL = DefaultRemoteURL
+	}
+
+	return &ServerCard{
+		Schema:      SchemaURL,
+		Name:        serverName,
+		Version:     version,
+		Description: serverDescription,
+		Title:       serverTitle,
+		WebsiteURL:  repositoryURL,
+		Repository: &Repository{
+			URL:    repositoryURL,
+			Source: repositorySource,
+			ID:     repositoryID,
+		},
+		Remotes: []Remote{
+			{
+				Type: "streamable-http",
+				URL:  remoteURL,
+				Headers: []KeyValueInput{
+					{
+						Input: Input{
+							Description: "Authorization header with authentication token (PAT or App token)",
+							IsRequired:  true,
+							IsSecret:    true,
+						},
+						Name: "Authorization",
+					},
+				},
+			},
+		},
+	}
+}

pkg/http/servercard/card_test.go

@@ -0,0 +1,136 @@
+package servercard
+
+import (
+	_ "embed"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/google/jsonschema-go/jsonschema"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+//go:embed testdata/server-card.schema.json
+var serverCardSchema []byte
+
+// resolvedCardSchema parses the embedded experimental-ext-server-card schema and
+// returns a resolver rooted at the ServerCard definition, so emitted cards can be
+// validated against the canonical JSON Schema.
+func resolvedCardSchema(t *testing.T) *jsonschema.Resolved {
+	t.Helper()
+
+	var schema jsonschema.Schema
+	require.NoError(t, json.Unmarshal(serverCardSchema, &schema))
+
+	root := &jsonschema.Schema{
+		Schema: schema.Schema,
+		Ref:    "#/$defs/ServerCard",
+		Defs:   schema.Defs,
+	}
+
+	resolved, err := root.Resolve(nil)
+	require.NoError(t, err)
+	return resolved
+}
+
+// assertSchemaValid marshals card and validates it against the ServerCard schema.
+func assertSchemaValid(t *testing.T, resolved *jsonschema.Resolved, card *ServerCard) {
+	t.Helper()
+
+	raw, err := json.Marshal(card)
+	require.NoError(t, err)
+
+	var instance any
+	require.NoError(t, json.Unmarshal(raw, &instance))
+
+	require.NoError(t, resolved.Validate(instance), "card must conform to the Server Card schema")
+}
+
+func TestNewServerCard(t *testing.T) {
+	t.Parallel()
+
+	resolved := resolvedCardSchema(t)
+
+	tests := []struct {
+		name              string
+		cfg               Config
+		expectedVersion   string
+		expectedRemoteURL string
+	}{
+		{
+			name:              "defaults",
+			cfg:               Config{},
+			expectedVersion:   "0.0.0-dev",
+			expectedRemoteURL: DefaultRemoteURL,
+		},
+		{
+			name:              "explicit version",
+			cfg:               Config{Version: "1.2.3"},
+			expectedVersion:   "1.2.3",
+			expectedRemoteURL: DefaultRemoteURL,
+		},
+		{
+			name:              "per-environment remote URL",
+			cfg:               Config{Version: "1.2.3", RemoteURL: "https://api.example.test/mcp/"},
+			expectedVersion:   "1.2.3",
+			expectedRemoteURL: "https://api.example.test/mcp/",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			card := NewServerCard(tc.cfg)
+
+			assert.Equal(t, SchemaURL, card.Schema)
+			assert.Equal(t, "io.github.github/github-mcp-server", card.Name)
+			assert.Equal(t, "GitHub", card.Title)
+			assert.Equal(t, tc.expectedVersion, card.Version)
+			assert.LessOrEqual(t, len(card.Description), 100, "description must respect the schema maxLength")
+
+			require.NotNil(t, card.Repository)
+			assert.Equal(t, "https://github.com/github/github-mcp-server", card.Repository.URL)
+			assert.Equal(t, "github", card.Repository.Source)
+			assert.Equal(t, "942771284", card.Repository.ID)
+
+			require.Len(t, card.Remotes, 1)
+			assert.Equal(t, "streamable-http", card.Remotes[0].Type)
+			assert.Equal(t, tc.expectedRemoteURL, card.Remotes[0].URL)
+			require.Len(t, card.Remotes[0].Headers, 1)
+			assert.Equal(t, "Authorization", card.Remotes[0].Headers[0].Name)
+			assert.True(t, card.Remotes[0].Headers[0].IsSecret)
+
+			assertSchemaValid(t, resolved, card)
+		})
+	}
+}
+
+// TestServerCardIsRemoteOnly guards the SEP-2127 requirement that a Server Card
+// never enumerates installable packages — those stay in the registry server.json.
+func TestServerCardIsRemoteOnly(t *testing.T) {
+	t.Parallel()
+
+	raw, err := json.Marshal(NewServerCard(Config{}))
+	require.NoError(t, err)
+
+	var fields map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(raw, &fields))
+
+	_, hasPackages := fields["packages"]
+	assert.False(t, hasPackages, "Server Card must be remote-only and omit packages")
+	assert.Contains(t, fields, "remotes")
+}
+
+// TestServerCardIdentityMatchesRegistry keeps the card's identity fields aligned
+// with the static registry document (server.json).
+func TestServerCardIdentityMatchesRegistry(t *testing.T) {
+	t.Parallel()
+
+	card := NewServerCard(Config{})
+
+	assert.Equal(t, "io.github.github/github-mcp-server", card.Name)
+	assert.Equal(t, "GitHub", card.Title)
+	assert.True(t, strings.HasPrefix(card.Description, "Connect AI assistants to GitHub"))
+}