Merge branch 'main' into issue-350

Author: aryasoni98

.dockerignore

@@ -0,0 +1,11 @@
+.github
+.vscode
+script
+third-party
+.dockerignore
+.gitignore
+**/*.yml
+**/*.yaml
+**/*.md
+**/*_test.go
+LICENSE

Dockerfile

@@ -1,27 +1,26 @@
+FROM golang:1.24.2-alpine AS build
 ARG VERSION="dev"
 
-FROM golang:1.24.2 AS build
-# allow this step access to build arg
-ARG VERSION
 # Set the working directory
 WORKDIR /build
 
-RUN go env -w GOMODCACHE=/root/.cache/go-build
+# Install git
+RUN --mount=type=cache,target=/var/cache/apk \
+    apk add git
 
-# Install dependencies
-COPY go.mod go.sum ./
-RUN --mount=type=cache,target=/root/.cache/go-build go mod download
-
-COPY . ./
 # Build the server
-RUN --mount=type=cache,target=/root/.cache/go-build CGO_ENABLED=0 go build -ldflags="-s -w -X main.version=${VERSION} -X main.commit=$(git rev-parse HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-    -o github-mcp-server cmd/github-mcp-server/main.go
+# go build automatically download required module dependencies to /go/pkg/mod
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/root/.cache/go-build \
+    --mount=type=bind,target=. \
+    CGO_ENABLED=0 go build -ldflags="-s -w -X main.version=${VERSION} -X main.commit=$(git rev-parse HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    -o /bin/github-mcp-server cmd/github-mcp-server/main.go
 
 # Make a stage to run the app
 FROM gcr.io/distroless/base-debian12
 # Set the working directory
 WORKDIR /server
 # Copy the binary from the build stage
-COPY --from=build /build/github-mcp-server .
+COPY --from=build /bin/github-mcp-server .
 # Command to run the server
 CMD ["./github-mcp-server", "stdio"]

README.md

@@ -260,7 +260,7 @@ GITHUB_TOOLSETS="all" ./github-mcp-server
 
 **Note**: This feature is currently in beta and may not be available in all environments. Please test it out and let us know if you encounter any issues.
 
-Instead of starting with all tools enabled, you can turn on dynamic toolset discovery. Dynamic toolsets allow the MCP host to list and enable toolsets in response to a user prompt. This should help to avoid situations where the model gets confused by the shear number of tools available.
+Instead of starting with all tools enabled, you can turn on dynamic toolset discovery. Dynamic toolsets allow the MCP host to list and enable toolsets in response to a user prompt. This should help to avoid situations where the model gets confused by the sheer number of tools available.
 
 ### Using Dynamic Tool Discovery
 
@@ -283,6 +283,27 @@ docker run -i --rm \
 
 The flag `--gh-host` and the environment variable `GITHUB_HOST` can be used to set
 the GitHub Enterprise Server hostname.
+Prefix the hostname with the `https://` URI scheme, as it otherwise defaults to `http://` which GitHub Enterprise Server does not support.
+
+``` json
+"github": {
+    "command": "docker",
+    "args": [
+    "run",
+    "-i",
+    "--rm",
+    "-e",
+    "GITHUB_PERSONAL_ACCESS_TOKEN",
+    "-e",
+    "GITHUB_HOST",
+    "ghcr.io/github/github-mcp-server"
+    ],
+    "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
+        "GITHUB_HOST": "https://<your GHES domain name>"
+    }
+}
+```
 
 ## i18n / Overriding Descriptions
 

cmd/github-mcp-server/main.go

@@ -1,25 +1,17 @@
 package main
 
 import (
-	"context"
+	"errors"
 	"fmt"
-	"io"
-	stdlog "log"
 	"os"
-	"os/signal"
-	"syscall"
 
+	"github.com/github/github-mcp-server/internal/ghmcp"
 	"github.com/github/github-mcp-server/pkg/github"
-	iolog "github.com/github/github-mcp-server/pkg/log"
-	"github.com/github/github-mcp-server/pkg/translations"
-	gogithub "github.com/google/go-github/v69/github"
-	"github.com/mark3labs/mcp-go/mcp"
-	"github.com/mark3labs/mcp-go/server"
-	log "github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 )
 
+// These variables are set by the build process using ldflags.
 var version = "version"
 var commit = "commit"
 var date = "date"
@@ -36,36 +28,34 @@ var (
 		Use:   "stdio",
 		Short: "Start stdio server",
 		Long:  `Start a server that communicates via standard input/output streams using JSON-RPC messages.`,
-		Run: func(_ *cobra.Command, _ []string) {
-			logFile := viper.GetString("log-file")
-			readOnly := viper.GetBool("read-only")
-			exportTranslations := viper.GetBool("export-translations")
-			logger, err := initLogger(logFile)
-			if err != nil {
-				stdlog.Fatal("Failed to initialize logger:", err)
+		RunE: func(_ *cobra.Command, _ []string) error {
+			token := viper.GetString("personal_access_token")
+			if token == "" {
+				return errors.New("GITHUB_PERSONAL_ACCESS_TOKEN not set")
 			}
 
 			// If you're wondering why we're not using viper.GetStringSlice("toolsets"),
 			// it's because viper doesn't handle comma-separated values correctly for env
 			// vars when using GetStringSlice.
 			// https://github.com/spf13/viper/issues/380
 			var enabledToolsets []string
-			err = viper.UnmarshalKey("toolsets", &enabledToolsets)
-			if err != nil {
-				stdlog.Fatal("Failed to unmarshal toolsets:", err)
+			if err := viper.UnmarshalKey("toolsets", &enabledToolsets); err != nil {
+				return fmt.Errorf("failed to unmarshal toolsets: %w", err)
 			}
 
-			logCommands := viper.GetBool("enable-command-logging")
-			cfg := runConfig{
-				readOnly:           readOnly,
-				logger:             logger,
-				logCommands:        logCommands,
-				exportTranslations: exportTranslations,
-				enabledToolsets:    enabledToolsets,
-			}
-			if err := runStdioServer(cfg); err != nil {
-				stdlog.Fatal("failed to run stdio server:", err)
+			stdioServerConfig := ghmcp.StdioServerConfig{
+				Version:              version,
+				Host:                 viper.GetString("host"),
+				Token:                token,
+				EnabledToolsets:      enabledToolsets,
+				DynamicToolsets:      viper.GetBool("dynamic_toolsets"),
+				ReadOnly:             viper.GetBool("read-only"),
+				ExportTranslations:   viper.GetBool("export-translations"),
+				EnableCommandLogging: viper.GetBool("enable-command-logging"),
+				LogFilePath:          viper.GetString("log-file"),
 			}
+
+			return ghmcp.RunStdioServer(stdioServerConfig)
 		},
 	}
 )
@@ -103,143 +93,9 @@ func initConfig() {
 	viper.AutomaticEnv()
 }
 
-func initLogger(outPath string) (*log.Logger, error) {
-	if outPath == "" {
-		return log.New(), nil
-	}
-
-	file, err := os.OpenFile(outPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
-	if err != nil {
-		return nil, fmt.Errorf("failed to open log file: %w", err)
-	}
-
-	logger := log.New()
-	logger.SetLevel(log.DebugLevel)
-	logger.SetOutput(file)
-
-	return logger, nil
-}
-
-type runConfig struct {
-	readOnly           bool
-	logger             *log.Logger
-	logCommands        bool
-	exportTranslations bool
-	enabledToolsets    []string
-}
-
-func runStdioServer(cfg runConfig) error {
-	// Create app context
-	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
-	defer stop()
-
-	// Create GH client
-	token := viper.GetString("personal_access_token")
-	if token == "" {
-		cfg.logger.Fatal("GITHUB_PERSONAL_ACCESS_TOKEN not set")
-	}
-	ghClient := gogithub.NewClient(nil).WithAuthToken(token)
-	ghClient.UserAgent = fmt.Sprintf("github-mcp-server/%s", version)
-
-	host := viper.GetString("host")
-
-	if host != "" {
-		var err error
-		ghClient, err = ghClient.WithEnterpriseURLs(host, host)
-		if err != nil {
-			return fmt.Errorf("failed to create GitHub client with host: %w", err)
-		}
-	}
-
-	t, dumpTranslations := translations.TranslationHelper()
-
-	beforeInit := func(_ context.Context, _ any, message *mcp.InitializeRequest) {
-		ghClient.UserAgent = fmt.Sprintf("github-mcp-server/%s (%s/%s)", version, message.Params.ClientInfo.Name, message.Params.ClientInfo.Version)
-	}
-
-	getClient := func(_ context.Context) (*gogithub.Client, error) {
-		return ghClient, nil // closing over client
-	}
-
-	hooks := &server.Hooks{
-		OnBeforeInitialize: []server.OnBeforeInitializeFunc{beforeInit},
-	}
-	// Create server
-	ghServer := github.NewServer(version, server.WithHooks(hooks))
-
-	enabled := cfg.enabledToolsets
-	dynamic := viper.GetBool("dynamic_toolsets")
-	if dynamic {
-		// filter "all" from the enabled toolsets
-		enabled = make([]string, 0, len(cfg.enabledToolsets))
-		for _, toolset := range cfg.enabledToolsets {
-			if toolset != "all" {
-				enabled = append(enabled, toolset)
-			}
-		}
-	}
-
-	// Create default toolsets
-	toolsets, err := github.InitToolsets(enabled, cfg.readOnly, getClient, t)
-	context := github.InitContextToolset(getClient, t)
-
-	if err != nil {
-		stdlog.Fatal("Failed to initialize toolsets:", err)
-	}
-
-	// Register resources with the server
-	github.RegisterResources(ghServer, getClient, t)
-	// Register the tools with the server
-	toolsets.RegisterTools(ghServer)
-	context.RegisterTools(ghServer)
-
-	if dynamic {
-		dynamic := github.InitDynamicToolset(ghServer, toolsets, t)
-		dynamic.RegisterTools(ghServer)
-	}
-
-	stdioServer := server.NewStdioServer(ghServer)
-
-	stdLogger := stdlog.New(cfg.logger.Writer(), "stdioserver", 0)
-	stdioServer.SetErrorLogger(stdLogger)
-
-	if cfg.exportTranslations {
-		// Once server is initialized, all translations are loaded
-		dumpTranslations()
-	}
-
-	// Start listening for messages
-	errC := make(chan error, 1)
-	go func() {
-		in, out := io.Reader(os.Stdin), io.Writer(os.Stdout)
-
-		if cfg.logCommands {
-			loggedIO := iolog.NewIOLogger(in, out, cfg.logger)
-			in, out = loggedIO, loggedIO
-		}
-
-		errC <- stdioServer.Listen(ctx, in, out)
-	}()
-
-	// Output github-mcp-server string
-	_, _ = fmt.Fprintf(os.Stderr, "GitHub MCP Server running on stdio\n")
-
-	// Wait for shutdown signal
-	select {
-	case <-ctx.Done():
-		cfg.logger.Infof("shutting down server...")
-	case err := <-errC:
-		if err != nil {
-			return fmt.Errorf("error running server: %w", err)
-		}
-	}
-
-	return nil
-}
-
 func main() {
 	if err := rootCmd.Execute(); err != nil {
-		fmt.Println(err)
+		fmt.Fprintf(os.Stderr, "%v\n", err)
 		os.Exit(1)
 	}
 }

cmd/mcpcurl/README.md

@@ -17,7 +17,7 @@ be executed against the configured MCP server.
 
 ## Usage
 
-```bash
+```console
 mcpcurl --stdio-server-cmd="<command to start MCP server>" <command> [flags]
 ```
 
@@ -33,7 +33,7 @@ The `--stdio-server-cmd` flag is required for all commands and specifies the com
 
 List available tools in Anthropic's MCP server:
 
-```bash
+```console
 % ./mcpcurl --stdio-server-cmd "docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN mcp/github" tools --help
 Contains all dynamically generated tool commands from the schema
 
@@ -72,7 +72,7 @@ Use "mcpcurl tools [command] --help" for more information about a command.
 
 Get help for a specific tool:
 
-```bash
+```console
  % ./mcpcurl --stdio-server-cmd "docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN mcp/github" tools get_issue --help
 Get details of a specific issue in a GitHub repository
 
@@ -93,7 +93,7 @@ Global Flags:
 
 Use one of the tools:
 
-```bash
+```console
  % ./mcpcurl --stdio-server-cmd "docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN mcp/github" tools get_issue --owner golang --repo go --issue_number 1
 {
   "active_lock_reason": null,

e2e/README.md

@@ -77,8 +77,16 @@ FAIL    github.com/github/github-mcp-server/e2e 1.433s
 FAIL
 ```
 
+## Debugging the Tests
+
+It is possible to provide `GITHUB_MCP_SERVER_E2E_DEBUG=true` to run the e2e tests with an in-process version of the MCP server. This has slightly reduced coverage as it doesn't integrate with Docker, or make use of the cobra/viper configuration parsing. However, it allows for placing breakpoints in the MCP Server internals, supporting much better debugging flows than the fully black-box tests.
+
+One might argue that the lack of visibility into failures for the black box tests also indicates a product need, but this solves for the immediate pain point felt as a maintainer.
+
 ## Limitations
 
 The current test suite is intentionally very limited in scope. This is because the maintenance costs on e2e tests tend to increase significantly over time. To read about some challenges with GitHub integration tests, see [go-github integration tests README](https://github.com/google/go-github/blob/5b75aa86dba5cf4af2923afa0938774f37fa0a67/test/README.md). We will expand this suite circumspectly!
 
-Currently, visibility into failures is not particularly good.
+The tests are quite repetitive and verbose. This is intentional as we want to see them develop more before committing to abstractions.
+
+Currently, visibility into failures is not particularly good. We're hoping that we can pull apart the mcp-go client and have it hook into streams representing stdio without requiring an exec. This way we can get breakpoints in the debugger easily.