Merge branch 'main' into add-issue-dependencies

Author: eshaffer321

.vscode/launch.json

@@ -23,6 +23,16 @@
             "program": "cmd/github-mcp-server/main.go",
             "args": ["stdio", "--read-only"],
             "console": "integratedTerminal",
+        },
+        {
+            "name": "Launch http server",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "cwd": "${workspaceFolder}",
+            "program": "cmd/github-mcp-server/main.go",
+            "args": ["http", "--port", "8082"],
+            "console": "integratedTerminal",
         }
     ]
 }

Dockerfile

@@ -26,6 +26,8 @@ LABEL io.modelcontextprotocol.server.name="io.github.github/github-mcp-server"
 WORKDIR /server
 # Copy the binary from the build stage
 COPY --from=build /bin/github-mcp-server .
+# Expose the default port
+EXPOSE 8082
 # Set the entrypoint to the server binary
 ENTRYPOINT ["/server/github-mcp-server"]
 # Default arguments for ENTRYPOINT

cmd/github-mcp-server/main.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/ghmcp"
 	"github.com/github/github-mcp-server/pkg/github"
+	ghhttp "github.com/github/github-mcp-server/pkg/http"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 	"github.com/spf13/viper"
@@ -89,6 +90,31 @@ var (
 			return ghmcp.RunStdioServer(stdioServerConfig)
 		},
 	}
+
+	httpCmd = &cobra.Command{
+		Use:   "http",
+		Short: "Start HTTP server",
+		Long:  `Start an HTTP server that listens for MCP requests over HTTP.`,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			ttl := viper.GetDuration("repo-access-cache-ttl")
+			httpConfig := ghhttp.ServerConfig{
+				Version:              version,
+				Host:                 viper.GetString("host"),
+				Port:                 viper.GetInt("port"),
+				BaseURL:              viper.GetString("base-url"),
+				ResourcePath:         viper.GetString("base-path"),
+				ExportTranslations:   viper.GetBool("export-translations"),
+				EnableCommandLogging: viper.GetBool("enable-command-logging"),
+				LogFilePath:          viper.GetString("log-file"),
+				ContentWindowSize:    viper.GetInt("content-window-size"),
+				LockdownMode:         viper.GetBool("lockdown-mode"),
+				RepoAccessCacheTTL:   &ttl,
+				ScopeChallenge:       viper.GetBool("scope-challenge"),
+			}
+
+			return ghhttp.RunHTTPServer(httpConfig)
+		},
+	}
 )
 
 func init() {
@@ -112,6 +138,12 @@ func init() {
 	rootCmd.PersistentFlags().Bool("insiders", false, "Enable insiders features")
 	rootCmd.PersistentFlags().Duration("repo-access-cache-ttl", 5*time.Minute, "Override the repo access cache TTL (e.g. 1m, 0s to disable)")
 
+	// HTTP-specific flags
+	httpCmd.Flags().Int("port", 8082, "HTTP server port")
+	httpCmd.Flags().String("base-url", "", "Base URL where this server is publicly accessible (for OAuth resource metadata)")
+	httpCmd.Flags().String("base-path", "", "Externally visible base path for the HTTP server (for OAuth resource metadata)")
+	httpCmd.Flags().Bool("scope-challenge", false, "Enable OAuth scope challenge responses")
+
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
 	_ = viper.BindPFlag("tools", rootCmd.PersistentFlags().Lookup("tools"))
@@ -126,9 +158,13 @@ func init() {
 	_ = viper.BindPFlag("lockdown-mode", rootCmd.PersistentFlags().Lookup("lockdown-mode"))
 	_ = viper.BindPFlag("insiders", rootCmd.PersistentFlags().Lookup("insiders"))
 	_ = viper.BindPFlag("repo-access-cache-ttl", rootCmd.PersistentFlags().Lookup("repo-access-cache-ttl"))
-
+	_ = viper.BindPFlag("port", httpCmd.Flags().Lookup("port"))
+	_ = viper.BindPFlag("base-url", httpCmd.Flags().Lookup("base-url"))
+	_ = viper.BindPFlag("base-path", httpCmd.Flags().Lookup("base-path"))
+	_ = viper.BindPFlag("scope-challenge", httpCmd.Flags().Lookup("scope-challenge"))
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)
+	rootCmd.AddCommand(httpCmd)
 }
 
 func initConfig() {

docs/remote-server.md

@@ -121,13 +121,15 @@ The Remote GitHub MCP server supports the following URL path patterns:
 - `/` - Default toolset (see ["default" toolset](../README.md#default-toolset))
 - `/readonly` - Default toolset in read-only mode
 - `/insiders` - Default toolset with insiders mode enabled
-- `/insiders/readonly` - Default toolset with insiders mode in read-only mode
+- `/readonly/insiders` - Default toolset in read-only mode with insiders mode enabled
 - `/x/all` - All available toolsets
 - `/x/all/readonly` - All available toolsets in read-only mode
 - `/x/all/insiders` - All available toolsets with insiders mode enabled
+- `/x/all/readonly/insiders` - All available toolsets in read-only mode with insiders mode enabled
 - `/x/{toolset}` - Single specific toolset
 - `/x/{toolset}/readonly` - Single specific toolset in read-only mode
 - `/x/{toolset}/insiders` - Single specific toolset with insiders mode enabled
+- `/x/{toolset}/readonly/insiders` - Single specific toolset in read-only mode with insiders mode enabled
 
 Note: `{toolset}` can only be a single toolset, not a comma-separated list. To combine multiple toolsets, use the `X-MCP-Toolsets` header instead. Path modifiers like `/readonly` and `/insiders` can be combined with the `X-MCP-Insiders` or `X-MCP-Readonly` headers.
 

docs/streamable-http.md

@@ -0,0 +1,93 @@
+# Streamable HTTP Server
+
+The Streamable HTTP mode enables the GitHub MCP Server to run as an HTTP service, allowing clients to connect via standard HTTP protocols. This mode is ideal for deployment scenarios where stdio transport isn't suitable, such as reverse proxy setups, containerized environments, or distributed architectures.
+
+## Features
+
+- **Streamable HTTP Transport** — Full HTTP server with streaming support for real-time tool responses
+- **OAuth Metadata Endpoints** — Standard `.well-known/oauth-protected-resource` discovery for OAuth clients
+- **Scope Challenge Support** — Automatic scope validation with proper HTTP 403 responses and `WWW-Authenticate` headers
+- **Scope Filtering** — Restrict available tools based on authenticated credentials and permissions
+- **Custom Base Paths** — Support for reverse proxy deployments with customizable base URLs
+
+## Running the Server
+
+### Basic HTTP Server
+
+Start the server on the default port (8082):
+
+```bash
+github-mcp-server http
+```
+
+The server will be available at `http://localhost:8082`.
+
+### With Scope Challenge
+
+Enable scope validation to enforce GitHub permission checks:
+
+```bash
+github-mcp-server http --scope-challenge
+```
+
+When `--scope-challenge` is enabled, requests with insufficient scopes receive a `403 Forbidden` response with a `WWW-Authenticate` header indicating the required scopes.
+
+### With OAuth Metadata Discovery
+
+For use behind reverse proxies or with custom domains, expose OAuth metadata endpoints:
+
+```bash
+github-mcp-server http --scope-challenge --base-url https://myserver.com --base-path /mcp
+```
+
+The OAuth protected resource metadata's `resource` attribute will be populated with the full URL to the server's protected resource endpoint:
+
+```json
+{
+  "resource_name": "GitHub MCP Server",
+  "resource": "https://myserver.com/mcp",
+  "authorization_servers": [
+    "https://github.com/login/oauth"
+  ],
+  "scopes_supported": [
+    "repo",
+    ...
+  ],
+  ...
+}
+```
+
+This allows OAuth clients to discover authentication requirements and endpoint information automatically.
+
+## Client Configuration
+
+### Using OAuth Authentication
+
+If your IDE or client has GitHub credentials configured (i.e. VS Code), simply reference the HTTP server:
+
+```json
+{
+  "type": "http",
+  "url": "http://localhost:8082"
+}
+```
+
+The server will use the client's existing GitHub authentication.
+
+### Using Bearer Tokens or Custom Headers
+
+To provide PAT credentials, or to customize server behavior preferences, you can include additional headers in the client configuration:
+
+```json
+{
+  "type": "http",
+  "url": "http://localhost:8082",
+  "headers": {
+    "Authorization": "Bearer ghp_yourtokenhere",
+    "X-MCP-Toolsets": "default",
+    "X-MCP-Readonly": "true"
+  }
+}
+```
+
+See [Remote Server](./remote-server.md) documentation for more details on client configuration options.

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/go-chi/chi/v5 v5.2.3
 	github.com/go-openapi/jsonpointer v0.19.5 // indirect
 	github.com/go-openapi/swag v0.21.1 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0

go.sum

@@ -10,6 +10,8 @@ github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHk
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/go-chi/chi/v5 v5.2.3 h1:WQIt9uxdsAbgIYgid+BpYc+liqQZGMHRaUwp0JUcvdE=
+github.com/go-chi/chi/v5 v5.2.3/go.mod h1:L2yAIGWB3H+phAw1NxKwWM+7eUH/lU8pOMm5hHcoops=
 github.com/go-openapi/jsonpointer v0.19.5 h1:gZr+CIYByUqjcgeLXnQu2gHYQC9o73G2XUeOFYEICuY=
 github.com/go-openapi/jsonpointer v0.19.5/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
 github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk=