Merge branch 'main' into feature/reply-to-review-comments

Author: lossyrob

README.md

@@ -345,6 +345,38 @@ To specify toolsets you want available to the LLM, you can pass an allow-list in
 
 The environment variable `GITHUB_TOOLSETS` takes precedence over the command line argument if both are provided.
 
+#### Specifying Individual Tools
+
+You can also configure specific tools using the `--tools` flag. Tools can be used independently or combined with toolsets and dynamic toolsets discovery for fine-grained control.
+
+1. **Using Command Line Argument**:
+
+   ```bash
+   github-mcp-server --tools get_file_contents,issue_read,create_pull_request
+   ```
+
+2. **Using Environment Variable**:
+   ```bash
+   GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" ./github-mcp-server
+   ```
+
+3. **Combining with Toolsets** (additive):
+   ```bash
+   github-mcp-server --toolsets repos,issues --tools get_gist
+   ```
+   This registers all tools from `repos` and `issues` toolsets, plus `get_gist`.
+
+4. **Combining with Dynamic Toolsets** (additive):
+   ```bash
+   github-mcp-server --tools get_file_contents --dynamic-toolsets
+   ```
+   This registers `get_file_contents` plus the dynamic toolset tools (`enable_toolset`, `list_available_toolsets`, `get_toolset_tools`).
+
+**Important Notes:**
+- Tools, toolsets, and dynamic toolsets can all be used together
+- Read-only mode takes priority: write tools are skipped if `--read-only` is set, even if explicitly requested via `--tools`
+- Tool names must match exactly (e.g., `get_file_contents`, not `getFileContents`). Invalid tool names will cause the server to fail at startup with an error message
+
 ### Using Toolsets With Docker
 
 When using Docker, you can pass the toolsets as environment variables:
@@ -356,6 +388,25 @@ docker run -i --rm \
   ghcr.io/github/github-mcp-server
 ```
 
+### Using Tools With Docker
+
+When using Docker, you can pass specific tools as environment variables. You can also combine tools with toolsets:
+
+```bash
+# Tools only
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
+  -e GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" \
+  ghcr.io/github/github-mcp-server
+
+# Tools combined with toolsets (additive)
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
+  -e GITHUB_TOOLSETS="repos,issues" \
+  -e GITHUB_TOOLS="get_gist" \
+  ghcr.io/github/github-mcp-server
+```
+
 ### Special toolsets
 
 #### "all" toolset

cmd/github-mcp-server/main.go

@@ -46,8 +46,14 @@ var (
 				return fmt.Errorf("failed to unmarshal toolsets: %w", err)
 			}
 
-			// No passed toolsets configuration means we enable the default toolset
-			if len(enabledToolsets) == 0 {
+			// Parse tools (similar to toolsets)
+			var enabledTools []string
+			if err := viper.UnmarshalKey("tools", &enabledTools); err != nil {
+				return fmt.Errorf("failed to unmarshal tools: %w", err)
+			}
+
+			// If neither toolset config nor tools config is passed we enable the default toolset
+			if len(enabledToolsets) == 0 && len(enabledTools) == 0 {
 				enabledToolsets = []string{github.ToolsetMetadataDefault.ID}
 			}
 
@@ -57,6 +63,7 @@ var (
 				Host:                 viper.GetString("host"),
 				Token:                token,
 				EnabledToolsets:      enabledToolsets,
+				EnabledTools:         enabledTools,
 				DynamicToolsets:      viper.GetBool("dynamic_toolsets"),
 				ReadOnly:             viper.GetBool("read-only"),
 				ExportTranslations:   viper.GetBool("export-translations"),
@@ -79,6 +86,7 @@ func init() {
 
 	// Add global flags that will be shared by all commands
 	rootCmd.PersistentFlags().StringSlice("toolsets", nil, github.GenerateToolsetsHelp())
+	rootCmd.PersistentFlags().StringSlice("tools", nil, "Comma-separated list of specific tools to enable")
 	rootCmd.PersistentFlags().Bool("dynamic-toolsets", false, "Enable dynamic toolsets")
 	rootCmd.PersistentFlags().Bool("read-only", false, "Restrict the server to read-only operations")
 	rootCmd.PersistentFlags().String("log-file", "", "Path to log file")
@@ -91,6 +99,7 @@ func init() {
 
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
+	_ = viper.BindPFlag("tools", rootCmd.PersistentFlags().Lookup("tools"))
 	_ = viper.BindPFlag("dynamic_toolsets", rootCmd.PersistentFlags().Lookup("dynamic-toolsets"))
 	_ = viper.BindPFlag("read-only", rootCmd.PersistentFlags().Lookup("read-only"))
 	_ = viper.BindPFlag("log-file", rootCmd.PersistentFlags().Lookup("log-file"))

internal/ghmcp/server.go

@@ -40,6 +40,10 @@ type MCPServerConfig struct {
 	// See: https://github.com/github/github-mcp-server?tab=readme-ov-file#tool-configuration
 	EnabledToolsets []string
 
+	// EnabledTools is a list of specific tools to enable (additive to toolsets)
+	// When specified, these tools are registered in addition to any specified toolset tools
+	EnabledTools []string
+
 	// Whether to enable dynamic toolsets
 	// See: https://github.com/github/github-mcp-server?tab=readme-ov-file#dynamic-tool-discovery
 	DynamicToolsets bool
@@ -62,7 +66,7 @@ type MCPServerConfig struct {
 
 const stdioServerLogPrefix = "stdioserver"
 
-func NewMCPServer(cfg MCPServerConfig) (*server.MCPServer, error) {
+func NewMCPServer(cfg MCPServerConfig, logger *slog.Logger) (*server.MCPServer, error) {
 	apiHost, err := parseAPIHost(cfg.Host)
 	if err != nil {
 		return nil, fmt.Errorf("failed to parse API host: %w", err)
@@ -88,6 +92,9 @@ func NewMCPServer(cfg MCPServerConfig) (*server.MCPServer, error) {
 	if cfg.RepoAccessTTL != nil {
 		repoAccessOpts = append(repoAccessOpts, lockdown.WithTTL(*cfg.RepoAccessTTL))
 	}
+
+	repoAccessLogger := logger.With("component", "lockdown")
+	repoAccessOpts = append(repoAccessOpts, lockdown.WithLogger(repoAccessLogger))
 	var repoAccessCache *lockdown.RepoAccessCache
 	if cfg.LockdownMode {
 		repoAccessCache = lockdown.GetInstance(gqlClient, repoAccessOpts...)
@@ -179,15 +186,32 @@ func NewMCPServer(cfg MCPServerConfig) (*server.MCPServer, error) {
 		github.FeatureFlags{LockdownMode: cfg.LockdownMode},
 		repoAccessCache,
 	)
-	err = tsg.EnableToolsets(enabledToolsets, nil)
 
-	if err != nil {
-		return nil, fmt.Errorf("failed to enable toolsets: %w", err)
+	// Enable and register toolsets if configured
+	// This always happens if toolsets are specified, regardless of whether tools are also specified
+	if len(enabledToolsets) > 0 {
+		err = tsg.EnableToolsets(enabledToolsets, nil)
+		if err != nil {
+			return nil, fmt.Errorf("failed to enable toolsets: %w", err)
+		}
+
+		// Register all mcp functionality with the server
+		tsg.RegisterAll(ghServer)
 	}
 
-	// Register all mcp functionality with the server
-	tsg.RegisterAll(ghServer)
+	// Register specific tools if configured
+	if len(cfg.EnabledTools) > 0 {
+		// Clean and validate tool names
+		enabledTools := github.CleanTools(cfg.EnabledTools)
 
+		// Register the specified tools (additive to any toolsets already enabled)
+		err = tsg.RegisterSpecificTools(ghServer, enabledTools, cfg.ReadOnly)
+		if err != nil {
+			return nil, fmt.Errorf("failed to register tools: %w", err)
+		}
+	}
+
+	// Register dynamic toolsets if configured (additive to toolsets and tools)
 	if cfg.DynamicToolsets {
 		dynamic := github.InitDynamicToolset(ghServer, tsg, cfg.Translator)
 		dynamic.RegisterTools(ghServer)
@@ -210,6 +234,10 @@ type StdioServerConfig struct {
 	// See: https://github.com/github/github-mcp-server?tab=readme-ov-file#tool-configuration
 	EnabledToolsets []string
 
+	// EnabledTools is a list of specific tools to enable (additive to toolsets)
+	// When specified, these tools are registered in addition to any specified toolset tools
+	EnabledTools []string
+
 	// Whether to enable dynamic toolsets
 	// See: https://github.com/github/github-mcp-server?tab=readme-ov-file#dynamic-tool-discovery
 	DynamicToolsets bool
@@ -267,13 +295,14 @@ func RunStdioServer(cfg StdioServerConfig) error {
 		Host:              cfg.Host,
 		Token:             cfg.Token,
 		EnabledToolsets:   cfg.EnabledToolsets,
+		EnabledTools:      cfg.EnabledTools,
 		DynamicToolsets:   cfg.DynamicToolsets,
 		ReadOnly:          cfg.ReadOnly,
 		Translator:        t,
 		ContentWindowSize: cfg.ContentWindowSize,
 		LockdownMode:      cfg.LockdownMode,
 		RepoAccessTTL:     cfg.RepoAccessCacheTTL,
-	})
+	}, logger)
 	if err != nil {
 		return fmt.Errorf("failed to create MCP server: %w", err)
 	}

pkg/github/tools.go

@@ -525,3 +525,24 @@ func ContainsToolset(tools []string, toCheck string) bool {
 	}
 	return false
 }
+
+// CleanTools cleans tool names by removing duplicates and trimming whitespace.
+// Validation of tool existence is done during registration.
+func CleanTools(toolNames []string) []string {
+	seen := make(map[string]bool)
+	result := make([]string, 0, len(toolNames))
+
+	// Remove duplicates and trim whitespace
+	for _, tool := range toolNames {
+		trimmed := strings.TrimSpace(tool)
+		if trimmed == "" {
+			continue
+		}
+		if !seen[trimmed] {
+			seen[trimmed] = true
+			result = append(result, trimmed)
+		}
+	}
+
+	return result
+}

pkg/lockdown/lockdown.go

@@ -15,11 +15,12 @@ import (
 // RepoAccessCache caches repository metadata related to lockdown checks so that
 // multiple tools can reuse the same access information safely across goroutines.
 type RepoAccessCache struct {
-	client *githubv4.Client
-	mu     sync.Mutex
-	cache  *cache2go.CacheTable
-	ttl    time.Duration
-	logger *slog.Logger
+	client           *githubv4.Client
+	mu               sync.Mutex
+	cache            *cache2go.CacheTable
+	ttl              time.Duration
+	logger           *slog.Logger
+	trustedBotLogins map[string]struct{}
 }
 
 type repoAccessCacheEntry struct {
@@ -85,6 +86,9 @@ func GetInstance(client *githubv4.Client, opts ...RepoAccessOption) *RepoAccessC
 			client: client,
 			cache:  cache2go.Cache(defaultRepoAccessCacheKey),
 			ttl:    defaultRepoAccessTTL,
+			trustedBotLogins: map[string]struct{}{
+				"copilot": {},
+			},
 		}
 		for _, opt := range opts {
 			if opt != nil {
@@ -109,13 +113,22 @@ type CacheStats struct {
 	Evictions int64
 }
 
+// IsSafeContent determines if the specified user can safely access the requested repository content.
+// Safe access applies when any of the following is true:
+// - the content was created by a trusted bot;
+// - the author currently has push access to the repository;
+// - the repository is private;
+// - the content was created by the viewer.
 func (c *RepoAccessCache) IsSafeContent(ctx context.Context, username, owner, repo string) (bool, error) {
 	repoInfo, err := c.getRepoAccessInfo(ctx, username, owner, repo)
 	if err != nil {
-		c.logDebug("error checking repo access info for content filtering", "owner", owner, "repo", repo, "user", username, "error", err)
 		return false, err
 	}
-	if repoInfo.IsPrivate || repoInfo.ViewerLogin == username {
+
+	c.logDebug(ctx, fmt.Sprintf("evaluated repo access for user %s to %s/%s for content filtering, result: hasPushAccess=%t, isPrivate=%t",
+		username, owner, repo, repoInfo.HasPushAccess, repoInfo.IsPrivate))
+
+	if c.isTrustedBot(username) || repoInfo.IsPrivate || repoInfo.ViewerLogin == strings.ToLower(username) {
 		return true, nil
 	}
 	return repoInfo.HasPushAccess, nil
@@ -136,30 +149,34 @@ func (c *RepoAccessCache) getRepoAccessInfo(ctx context.Context, username, owner
 	if err == nil {
 		entry := cacheItem.Data().(*repoAccessCacheEntry)
 		if cachedHasPush, known := entry.knownUsers[userKey]; known {
-			c.logDebug("repo access cache hit", "owner", owner, "repo", repo, "user", username)
+			c.logDebug(ctx, fmt.Sprintf("repo access cache hit for user %s to %s/%s", username, owner, repo))
 			return RepoAccessInfo{
 				IsPrivate:     entry.isPrivate,
 				HasPushAccess: cachedHasPush,
 				ViewerLogin:   entry.viewerLogin,
 			}, nil
 		}
-		c.logDebug("known users cache miss", "owner", owner, "repo", repo, "user", username)
+
+		c.logDebug(ctx, "known users cache miss, fetching from graphql API")
+
 		info, queryErr := c.queryRepoAccessInfo(ctx, username, owner, repo)
 		if queryErr != nil {
 			return RepoAccessInfo{}, queryErr
 		}
+
 		entry.knownUsers[userKey] = info.HasPushAccess
 		entry.viewerLogin = info.ViewerLogin
 		entry.isPrivate = info.IsPrivate
 		c.cache.Add(key, c.ttl, entry)
+
 		return RepoAccessInfo{
 			IsPrivate:     entry.isPrivate,
 			HasPushAccess: entry.knownUsers[userKey],
 			ViewerLogin:   entry.viewerLogin,
 		}, nil
 	}
 
-	c.logDebug("repo access cache miss", "owner", owner, "repo", repo, "user", username)
+	c.logDebug(ctx, fmt.Sprintf("repo access cache miss for user %s to %s/%s", username, owner, repo))
 
 	info, queryErr := c.queryRepoAccessInfo(ctx, username, owner, repo)
 	if queryErr != nil {
@@ -223,19 +240,35 @@ func (c *RepoAccessCache) queryRepoAccessInfo(ctx context.Context, username, own
 		}
 	}
 
+	c.logDebug(ctx, fmt.Sprintf("queried repo access info for user %s to %s/%s: isPrivate=%t, hasPushAccess=%t, viewerLogin=%s",
+		username, owner, repo, bool(query.Repository.IsPrivate), hasPush, query.Viewer.Login))
+
 	return RepoAccessInfo{
 		IsPrivate:     bool(query.Repository.IsPrivate),
 		HasPushAccess: hasPush,
 		ViewerLogin:   string(query.Viewer.Login),
 	}, nil
 }
 
-func cacheKey(owner, repo string) string {
-	return fmt.Sprintf("%s/%s", strings.ToLower(owner), strings.ToLower(repo))
+func (c *RepoAccessCache) log(ctx context.Context, level slog.Level, msg string, attrs ...slog.Attr) {
+	if c == nil || c.logger == nil {
+		return
+	}
+	if !c.logger.Enabled(ctx, level) {
+		return
+	}
+	c.logger.LogAttrs(ctx, level, msg, attrs...)
 }
 
-func (c *RepoAccessCache) logDebug(msg string, args ...any) {
-	if c != nil && c.logger != nil {
-		c.logger.Debug(msg, args...)
-	}
+func (c *RepoAccessCache) logDebug(ctx context.Context, msg string, attrs ...slog.Attr) {
+	c.log(ctx, slog.LevelDebug, msg, attrs...)
+}
+
+func (c *RepoAccessCache) isTrustedBot(username string) bool {
+	_, ok := c.trustedBotLogins[strings.ToLower(username)]
+	return ok
+}
+
+func cacheKey(owner, repo string) string {
+	return fmt.Sprintf("%s/%s", strings.ToLower(owner), strings.ToLower(repo))
 }