|
| 1 | +// Package servercard provides the GitHub MCP Server's MCP Server Card |
| 2 | +// (SEP-2127) types and a public, no-auth HTTP handler that serves it. |
| 3 | +// |
| 4 | +// A Server Card is a static metadata document that describes a remote MCP |
| 5 | +// server — its identity, repository, and HTTP transport — so clients can |
| 6 | +// discover and connect to it before the protocol handshake. It is remote-only |
| 7 | +// and deliberately does NOT enumerate primitives (tools, resources, prompts) |
| 8 | +// or installable packages; those remain in the MCP Registry document |
| 9 | +// (server.json) and runtime listing. |
| 10 | +// |
| 11 | +// See: |
| 12 | +// - https://github.com/modelcontextprotocol/experimental-ext-server-card |
| 13 | +// - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127 |
| 14 | +package servercard |
| 15 | + |
| 16 | +import ( |
| 17 | + "net/http" |
| 18 | + |
| 19 | + "github.com/github/github-mcp-server/pkg/octicons" |
| 20 | +) |
| 21 | + |
| 22 | +const ( |
| 23 | + // SchemaURL is the v1 Server Card JSON Schema URI that emitted cards |
| 24 | + // conform to. The schema is versioned by its `vN` path segment. |
| 25 | + SchemaURL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json" |
| 26 | + |
| 27 | + // MediaType is the media type used to serve and request a Server Card. |
| 28 | + MediaType = "application/mcp-server-card+json" |
| 29 | + |
| 30 | + // Path is the suffix, relative to a server's streamable-HTTP URL, at which |
| 31 | + // MCP reserves the recommended Server Card location. A server hosted at |
| 32 | + // `https://host/mcp` therefore serves its card at `https://host/mcp/server-card`. |
| 33 | + Path = "/server-card" |
| 34 | + |
| 35 | + // DefaultRemoteURL is the streamable-HTTP endpoint of the hosted GitHub MCP |
| 36 | + // Server on github.com. The remote repository overrides this per environment. |
| 37 | + DefaultRemoteURL = "https://api.githubcopilot.com/mcp/" |
| 38 | + |
| 39 | + // iconName is the Octicon used as the server's icon (the GitHub mark). |
| 40 | + iconName = "mark-github" |
| 41 | + |
| 42 | + // iconSize is the pixel dimension of the embedded Octicon PNGs (square). |
| 43 | + iconSize = "24x24" |
| 44 | +) |
| 45 | + |
| 46 | +// Identity fields reused from the MCP Registry document (server.json) so the |
| 47 | +// Server Card and the registry entry describe the same server. |
| 48 | +const ( |
| 49 | + serverName = "io.github.github/github-mcp-server" |
| 50 | + serverTitle = "GitHub" |
| 51 | + serverDescription = "Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language." |
| 52 | + repositoryURL = "https://github.com/github/github-mcp-server" |
| 53 | + repositorySource = "github" |
| 54 | + // repositoryID is the github.com repository ID for github/github-mcp-server. |
| 55 | + // It is stable across renames and changes if the repository is recreated. |
| 56 | + repositoryID = "942771284" |
| 57 | +) |
| 58 | + |
| 59 | +// ServerCard is a static metadata document describing a remote MCP server, |
| 60 | +// suitable for pre-connection discovery. It mirrors the ServerCard interface in |
| 61 | +// modelcontextprotocol/experimental-ext-server-card. Server Cards are |
| 62 | +// remote-only and never carry installable packages. |
| 63 | +type ServerCard struct { |
| 64 | + // Schema is the Server Card JSON Schema URI this document conforms to. |
| 65 | + Schema string `json:"$schema"` |
| 66 | + // Name is the server name in reverse-DNS format with exactly one slash. |
| 67 | + Name string `json:"name"` |
| 68 | + // Version is the server version, equivalent to Implementation.version. |
| 69 | + Version string `json:"version"` |
| 70 | + // Description is a short, human-readable explanation of server functionality. |
| 71 | + Description string `json:"description"` |
| 72 | + // Title is an optional human-readable display name. |
| 73 | + Title string `json:"title,omitempty"` |
| 74 | + // WebsiteURL optionally links to the server's homepage or documentation. |
| 75 | + WebsiteURL string `json:"websiteUrl,omitempty"` |
| 76 | + // Repository optionally describes the server's source code for inspection. |
| 77 | + Repository *Repository `json:"repository,omitempty"` |
| 78 | + // Icons optionally lists sized icons a client may render. |
| 79 | + Icons []Icon `json:"icons,omitempty"` |
| 80 | + // Remotes lists the HTTP-based endpoints for connecting to the server. |
| 81 | + Remotes []Remote `json:"remotes,omitempty"` |
| 82 | + // Meta carries vendor-specific metadata using reverse-DNS namespacing. |
| 83 | + Meta map[string]any `json:"_meta,omitempty"` |
| 84 | +} |
| 85 | + |
| 86 | +// Repository describes the MCP server's source code location. |
| 87 | +type Repository struct { |
| 88 | + // URL is the repository URL for browsing source and cloning. |
| 89 | + URL string `json:"url"` |
| 90 | + // Source is the hosting service identifier (e.g. "github"). |
| 91 | + Source string `json:"source"` |
| 92 | + // ID is the optional repository identifier owned by the hosting service. |
| 93 | + ID string `json:"id,omitempty"` |
| 94 | +} |
| 95 | + |
| 96 | +// Remote describes a remote (HTTP-based) MCP server endpoint. |
| 97 | +type Remote struct { |
| 98 | + // Type is the transport type ("streamable-http" or "sse"). |
| 99 | + Type string `json:"type"` |
| 100 | + // URL is the endpoint URL. |
| 101 | + URL string `json:"url"` |
| 102 | + // Headers describes HTTP headers required or accepted when connecting. |
| 103 | + Headers []KeyValueInput `json:"headers,omitempty"` |
| 104 | +} |
| 105 | + |
| 106 | +// Input describes a user-supplied or pre-set value. It is a pragmatic subset of |
| 107 | +// the experimental-ext-server-card Input schema, carrying only the fields the |
| 108 | +// GitHub card emits. |
| 109 | +type Input struct { |
| 110 | + // Description is a human-readable explanation of the input. |
| 111 | + Description string `json:"description,omitempty"` |
| 112 | + // IsRequired indicates the input must be supplied to connect. |
| 113 | + IsRequired bool `json:"isRequired,omitempty"` |
| 114 | + // IsSecret indicates the value is sensitive and must be handled securely. |
| 115 | + IsSecret bool `json:"isSecret,omitempty"` |
| 116 | +} |
| 117 | + |
| 118 | +// KeyValueInput is a named Input used to describe an HTTP header. |
| 119 | +type KeyValueInput struct { |
| 120 | + Input |
| 121 | + // Name is the header name. |
| 122 | + Name string `json:"name"` |
| 123 | +} |
| 124 | + |
| 125 | +// Icon is an optionally-sized icon a client may display. |
| 126 | +type Icon struct { |
| 127 | + // Src is a URI (HTTP(S) or data:) pointing to an icon resource. |
| 128 | + Src string `json:"src"` |
| 129 | + // MimeType optionally overrides the source MIME type. |
| 130 | + MimeType string `json:"mimeType,omitempty"` |
| 131 | + // Sizes optionally lists sizes (e.g. "48x48" or "any") the icon supports. |
| 132 | + Sizes []string `json:"sizes,omitempty"` |
| 133 | + // Theme optionally indicates the theme ("light" or "dark") the icon suits. |
| 134 | + Theme string `json:"theme,omitempty"` |
| 135 | +} |
| 136 | + |
| 137 | +// Config controls how the GitHub MCP Server card is built and served. |
| 138 | +type Config struct { |
| 139 | + // Version is advertised as the card's version and SHOULD match the |
| 140 | + // runtime serverInfo version. When empty, "0.0.0-dev" is used. |
| 141 | + Version string |
| 142 | + |
| 143 | + // RemoteURL is the absolute streamable-HTTP endpoint advertised in the |
| 144 | + // card's single remote. When empty, DefaultRemoteURL is used. The remote |
| 145 | + // repository supplies a per-environment URL here. |
| 146 | + RemoteURL string |
| 147 | + |
| 148 | + // RemoteURLFunc, when set, derives the streamable-HTTP remote URL from the |
| 149 | + // incoming request, taking precedence over RemoteURL whenever it returns a |
| 150 | + // non-empty value. This supports multi-tenant deployments (e.g. proxima) |
| 151 | + // where the absolute URL varies per request (e.g. from X-Forwarded-Host). |
| 152 | + // |
| 153 | + // It is consumed by the Handler when serving a card; NewServerCard ignores |
| 154 | + // it, since the card constructor is not request-aware. |
| 155 | + RemoteURLFunc func(*http.Request) string |
| 156 | +} |
| 157 | + |
| 158 | +// NewServerCard builds the GitHub MCP Server's Server Card from cfg. |
| 159 | +func NewServerCard(cfg Config) *ServerCard { |
| 160 | + version := cfg.Version |
| 161 | + if version == "" { |
| 162 | + version = "0.0.0-dev" |
| 163 | + } |
| 164 | + |
| 165 | + remoteURL := cfg.RemoteURL |
| 166 | + if remoteURL == "" { |
| 167 | + remoteURL = DefaultRemoteURL |
| 168 | + } |
| 169 | + |
| 170 | + // supportedProtocolVersions is intentionally omitted: the go-sdk does not |
| 171 | + // export the list of versions it negotiates, so we cannot advertise it |
| 172 | + // accurately from the runtime. Omitting it is preferable to publishing a |
| 173 | + // hand-maintained list that could drift from what the server actually |
| 174 | + // serves. |
| 175 | + return &ServerCard{ |
| 176 | + Schema: SchemaURL, |
| 177 | + Name: serverName, |
| 178 | + Version: version, |
| 179 | + Description: serverDescription, |
| 180 | + Title: serverTitle, |
| 181 | + WebsiteURL: repositoryURL, |
| 182 | + Icons: githubIcons(), |
| 183 | + Repository: &Repository{ |
| 184 | + URL: repositoryURL, |
| 185 | + Source: repositorySource, |
| 186 | + ID: repositoryID, |
| 187 | + }, |
| 188 | + Remotes: []Remote{ |
| 189 | + { |
| 190 | + Type: "streamable-http", |
| 191 | + URL: remoteURL, |
| 192 | + Headers: []KeyValueInput{ |
| 193 | + { |
| 194 | + Input: Input{ |
| 195 | + Description: "Authorization header with authentication token (PAT or App token)", |
| 196 | + IsRequired: true, |
| 197 | + IsSecret: true, |
| 198 | + }, |
| 199 | + Name: "Authorization", |
| 200 | + }, |
| 201 | + }, |
| 202 | + }, |
| 203 | + }, |
| 204 | + } |
| 205 | +} |
| 206 | + |
| 207 | +// githubIcons returns the light- and dark-theme GitHub mark icons as |
| 208 | +// self-contained data URIs, reusing the embedded Octicons so the card has no |
| 209 | +// external image dependency. The order is fixed so the serialized card — and |
| 210 | +// therefore its ETag — is deterministic. It returns nil if the icons are |
| 211 | +// unavailable. |
| 212 | +func githubIcons() []Icon { |
| 213 | + themes := []struct { |
| 214 | + octicon octicons.Theme |
| 215 | + card string |
| 216 | + }{ |
| 217 | + {octicons.ThemeLight, "light"}, |
| 218 | + {octicons.ThemeDark, "dark"}, |
| 219 | + } |
| 220 | + |
| 221 | + var icons []Icon |
| 222 | + for _, t := range themes { |
| 223 | + if src := octicons.DataURI(iconName, t.octicon); src != "" { |
| 224 | + icons = append(icons, Icon{ |
| 225 | + Src: src, |
| 226 | + MimeType: "image/png", |
| 227 | + Sizes: []string{iconSize}, |
| 228 | + Theme: t.card, |
| 229 | + }) |
| 230 | + } |
| 231 | + } |
| 232 | + return icons |
| 233 | +} |
0 commit comments