Skip to content

chore: update readme for tool parititioning #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 17, 2025
Merged

chore: update readme for tool parititioning #274

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f1c9a71
chore: update readme for tool paritioning
SamMorrowDrums Apr 14, 2025
5ca6aed
Update README.md
SamMorrowDrums Apr 14, 2025
e6e1c6b
docs: update toolset copy
toby Apr 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 92 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,95 @@ If you don't have Docker, you can use `go build` to build the binary in the
}
```

## 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
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The env version of this may have changed in main, double check and update docs if required.

Expand Down Expand Up @@ -331,7 +420,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)
Expand All @@ -341,50 +429,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)
Expand All @@ -405,16 +486,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)
Expand Down