feat: partition tools by product/feature

Author: SamMorrowDrums

README.md

@@ -96,6 +96,95 @@ If you don't have Docker, you can use `go` to build the binary in the
 command with the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable set to
 your token.
 
+## Tool Configuration
+
+The GitHub MCP Server supports enabling or disabling specific groups of functionalities via the `--toolsets` flag. This allows you to control which GitHub API capabilities are available to your AI tools.
+
+### Available Toolsets
+
+The following sets of tools are available (all are on by default):
+
+| Toolset                 | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| `repos`                 | Repository-related tools (file operations, branches, commits) |
+| `issues`                | Issue-related tools (create, read, update, comment)           |
+| `users `                | Anything relating to GitHub Users                             |
+| `pull_requests`         | Pull request operations (create, merge, review)               |
+| `code_security`         | Code scanning alerts and security features                    |
+| `experiments`           | Experimental features (not considered stable)                 |
+
+#### Specifying Toolsets
+
+To reduce the available tools, you can pass an allow-list in two ways:
+
+1. **Using Command Line Argument**:
+
+   ```bash
+   github-mcp-server --toolsets repos,issues,pull_requests,code_security
+   ```
+
+2. **Using Environment Variable**:
+   ```bash
+   GITHUB_TOOLSETS="repos,issues,pull_requests,code_security" ./github-mcp-server
+   ```
+
+The environment variable `GITHUB_TOOLSETS` takes precedence over the command line argument if both are provided.
+
+Any toolsets you specify will be enabled from the start, including when `--dynamic-toolsets` is on.
+
+You might want to do this if the model is confused about which tools to call and you only require a subset.
+
+
+### Using Toolsets With Docker
+
+When using Docker, you can pass the toolsets as environment variables:
+
+```bash
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
+  -e GITHUB_TOOLSETS="repos,issues,pull_requests,code_security,experiments" \
+  ghcr.io/github/github-mcp-server
+```
+
+### The "all" Toolset
+
+The special toolset `all` can be provided to enable all available toolsets regardless of any other configuration:
+
+```bash
+./github-mcp-server --toolsets all
+```
+
+Or using the environment variable:
+
+```bash
+GITHUB_TOOLSETS="all" ./github-mcp-server
+```
+
+## Dynamic Tool Discovery
+
+Instead of starting with all tools enabled, you can turn on Dynamic Toolset Discovery. 
+This feature provides tools that help the MCP Host application to discover and enable sets of GitHub tools only when needed.
+This helps to avoid situations where models get confused by the shear number of tools available to them, which varies by model.
+
+### Using Dynamic Tool Discovery
+
+When using the binary, you can pass the `--dynamic-toolsets` flag.
+
+```bash
+./github-mcp-server --dynamic-toolsets
+```
+
+When using Docker, you can pass the toolsets as environment variables:
+
+```bash
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
+  -e GITHUB_DYNAMIC_TOOLSETS=1 \
+  ghcr.io/github/github-mcp-server
+```
+
+
+
 ## GitHub Enterprise Server
 
 The flag `--gh-host` and the environment variable `GH_HOST` can be used to set
@@ -317,7 +406,6 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 ### Repositories
 
 - **create_or_update_file** - Create or update a single file in a repository
-
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
   - `path`: File path (string, required)
@@ -327,50 +415,43 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `sha`: File SHA if updating (string, optional)
 
 - **list_branches** - List branches in a GitHub repository
-
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
   - `page`: Page number (number, optional)
   - `perPage`: Results per page (number, optional)
 
 - **push_files** - Push multiple files in a single commit
-
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
   - `branch`: Branch to push to (string, required)
   - `files`: Files to push, each with path and content (array, required)
   - `message`: Commit message (string, required)
 
 - **search_repositories** - Search for GitHub repositories
-
   - `query`: Search query (string, required)
   - `sort`: Sort field (string, optional)
   - `order`: Sort order (string, optional)
   - `page`: Page number (number, optional)
   - `perPage`: Results per page (number, optional)
 
 - **create_repository** - Create a new GitHub repository
-
   - `name`: Repository name (string, required)
   - `description`: Repository description (string, optional)
   - `private`: Whether the repository is private (boolean, optional)
   - `autoInit`: Auto-initialize with README (boolean, optional)
 
 - **get_file_contents** - Get contents of a file or directory
-
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
   - `path`: File path (string, required)
   - `ref`: Git reference (string, optional)
 
 - **fork_repository** - Fork a repository
-
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
   - `organization`: Target organization name (string, optional)
 
 - **create_branch** - Create a new branch
-
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
   - `branch`: New branch name (string, required)
@@ -391,16 +472,15 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `page`: Page number, for files in the commit (number, optional)
   - `perPage`: Results per page, for files in the commit (number, optional)
 
-### Search
-
-- **search_code** - Search for code across GitHub repositories
-
+  - **search_code** - Search for code across GitHub repositories
   - `query`: Search query (string, required)
   - `sort`: Sort field (string, optional)
   - `order`: Sort order (string, optional)
   - `page`: Page number (number, optional)
   - `perPage`: Results per page (number, optional)
 
+### Users
+
 - **search_users** - Search for GitHub users
   - `query`: Search query (string, required)
   - `sort`: Sort field (string, optional)

cmd/github-mcp-server/main.go

@@ -44,12 +44,16 @@ var (
 			if err != nil {
 				stdlog.Fatal("Failed to initialize logger:", err)
 			}
+
+			enabledToolsets := viper.GetStringSlice("toolsets")
+
 			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)
@@ -62,26 +66,30 @@ func init() {
 	cobra.OnInitialize(initConfig)
 
 	// Add global flags that will be shared by all commands
+	rootCmd.PersistentFlags().StringSlice("toolsets", github.DefaultTools, "An optional comma separated list of groups of tools to allow, defaults to enabling all")
+	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")
 	rootCmd.PersistentFlags().Bool("enable-command-logging", false, "When enabled, the server will log all command requests and responses to the log file")
 	rootCmd.PersistentFlags().Bool("export-translations", false, "Save translations to a JSON file")
 	rootCmd.PersistentFlags().String("gh-host", "", "Specify the GitHub hostname (for GitHub Enterprise etc.)")
 
 	// Bind flag to viper
+	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
+	_ = 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"))
 	_ = viper.BindPFlag("enable-command-logging", rootCmd.PersistentFlags().Lookup("enable-command-logging"))
 	_ = viper.BindPFlag("export-translations", rootCmd.PersistentFlags().Lookup("export-translations"))
-	_ = viper.BindPFlag("gh-host", rootCmd.PersistentFlags().Lookup("gh-host"))
+	_ = viper.BindPFlag("host", rootCmd.PersistentFlags().Lookup("gh-host"))
 
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)
 }
 
 func initConfig() {
 	// Initialize Viper configuration
-	viper.SetEnvPrefix("APP")
+	viper.SetEnvPrefix("github")
 	viper.AutomaticEnv()
 }
 
@@ -107,6 +115,7 @@ type runConfig struct {
 	logger             *log.Logger
 	logCommands        bool
 	exportTranslations bool
+	enabledToolsets    []string
 }
 
 func runStdioServer(cfg runConfig) error {
@@ -115,18 +124,14 @@ func runStdioServer(cfg runConfig) error {
 	defer stop()
 
 	// Create GH client
-	token := os.Getenv("GITHUB_PERSONAL_ACCESS_TOKEN")
+	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)
 
-	// Check GH_HOST env var first, then fall back to viper config
-	host := os.Getenv("GH_HOST")
-	if host == "" {
-		host = viper.GetString("gh-host")
-	}
+	host := viper.GetString("host")
 
 	if host != "" {
 		var err error
@@ -149,8 +154,40 @@ func runStdioServer(cfg runConfig) error {
 	hooks := &server.Hooks{
 		OnBeforeInitialize: []server.OnBeforeInitializeFunc{beforeInit},
 	}
-	// Create
-	ghServer := github.NewServer(getClient, version, cfg.readOnly, t, server.WithHooks(hooks))
+	// 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(ghServer, 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)

go.mod

@@ -6,7 +6,7 @@ require (
 	github.com/docker/docker v28.0.4+incompatible
 	github.com/google/go-cmp v0.7.0
 	github.com/google/go-github/v69 v69.2.0
-	github.com/mark3labs/mcp-go v0.18.0
+	github.com/mark3labs/mcp-go v0.20.1
 	github.com/migueleliasweb/go-github-mock v1.1.0
 	github.com/sirupsen/logrus v1.9.3
 	github.com/spf13/cobra v1.9.1

go.sum

@@ -59,6 +59,8 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/mark3labs/mcp-go v0.18.0 h1:YuhgIVjNlTG2ZOwmrkORWyPTp0dz1opPEqvsPtySXao=
 github.com/mark3labs/mcp-go v0.18.0/go.mod h1:KmJndYv7GIgcPVwEKJjNcbhVQ+hJGJhrCCB/9xITzpE=
+github.com/mark3labs/mcp-go v0.20.1 h1:E1Bbx9K8d8kQmDZ1QHblM38c7UU2evQ2LlkANk1U/zw=
+github.com/mark3labs/mcp-go v0.20.1/go.mod h1:KmJndYv7GIgcPVwEKJjNcbhVQ+hJGJhrCCB/9xITzpE=
 github.com/migueleliasweb/go-github-mock v1.1.0 h1:GKaOBPsrPGkAKgtfuWY8MclS1xR6MInkx1SexJucMwE=
 github.com/migueleliasweb/go-github-mock v1.1.0/go.mod h1:pYe/XlGs4BGMfRY4vmeixVsODHnVDDhJ9zoi0qzSMHc=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=

pkg/github/context_tools.go

@@ -0,0 +1,49 @@
+package github
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+// GetMe creates a tool to get details of the authenticated user.
+func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("get_me",
+			mcp.WithDescription(t("TOOL_GET_ME_DESCRIPTION", "Get details of the authenticated GitHub user. Use this when a request include \"me\", \"my\"...")),
+			mcp.WithString("reason",
+				mcp.Description("Optional: reason the session was created"),
+			),
+		),
+		func(ctx context.Context, _ mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+			user, resp, err := client.Users.Get(ctx, "")
+			if err != nil {
+				return nil, fmt.Errorf("failed to get user: %w", err)
+			}
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != http.StatusOK {
+				body, err := io.ReadAll(resp.Body)
+				if err != nil {
+					return nil, fmt.Errorf("failed to read response body: %w", err)
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("failed to get user: %s", string(body))), nil
+			}
+
+			r, err := json.Marshal(user)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal user: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}