Add tool search CLI

Author: JoannaaKL

README.md

@@ -80,6 +80,7 @@ Alternatively, to manually configure VS Code, choose the appropriate JSON block
 </table>
 
 ### Install in other MCP hosts
+
 - **[GitHub Copilot in other IDEs](/docs/installation-guides/install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
 - **[Claude Applications](/docs/installation-guides/install-claude.md)** - Installation guide for Claude Desktop and Claude Code CLI
 - **[Codex](/docs/installation-guides/install-codex.md)** - Installation guide for Open AI Codex
@@ -104,6 +105,7 @@ When no toolsets are specified, [default toolsets](#default-toolset) are used.
 GitHub Enterprise Cloud can also make use of the remote server.
 
 Example for `https://octocorp.ghe.com` with GitHub PAT token:
+
 ```
 {
     ...
@@ -140,24 +142,30 @@ The MCP server can use many of the GitHub APIs, so enable the permissions that y
 <details><summary><b>Handling PATs Securely</b></summary>
 
 ### Environment Variables (Recommended)
+
 To keep your GitHub PAT secure and reusable across different MCP hosts:
 
 1. **Store your PAT in environment variables**
+
    ```bash
    export GITHUB_PAT=your_token_here
    ```
+
    Or create a `.env` file:
+
    ```env
    GITHUB_PAT=your_token_here
    ```
 
 2. **Protect your `.env` file**
+
    ```bash
    # Add to .gitignore to prevent accidental commits
    echo ".env" >> .gitignore
    ```
 
 3. **Reference the token in configurations**
+
    ```bash
    # CLI usage
    claude mcp update github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT
@@ -180,6 +188,7 @@ To keep your GitHub PAT secure and reusable across different MCP hosts:
 - **Regular rotation**: Update tokens periodically
 - **Never commit**: Keep tokens out of version control
 - **File permissions**: Restrict access to config files containing tokens
+
   ```bash
   chmod 600 ~/.your-app/config.json
   ```
@@ -193,6 +202,7 @@ the hostname for GitHub Enterprise Server or GitHub Enterprise Cloud with data r
 
 - For GitHub Enterprise Server, prefix the hostname with the `https://` URI scheme, as it otherwise defaults to `http://`, which GitHub Enterprise Server does not support.
 - For GitHub Enterprise Cloud with data residency, use `https://YOURSUBDOMAIN.ghe.com` as the hostname.
+
 ``` json
 "github": {
     "command": "docker",
@@ -328,6 +338,20 @@ If you don't have Docker, you can use `go build` to build the binary in the
 }
 ```
 
+### CLI utilities
+
+The `github-mcp-server` binary includes a few CLI subcommands that are helpful for debugging and exploring the server.
+
+- `github-mcp-server tool-search "<query>"` searches tools by name, description, and input parameter names.
+- Use `--max-results` to return more matches.
+- Output is colorized when writing to a TTY (and typically not colorized when piped).
+
+Example:
+
+```bash
+github-mcp-server tool-search "owner" --max-results 5
+```
+
 ## 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. Enabling only the toolsets that you need can help the LLM with tool choice and reduce the context size.
@@ -349,6 +373,7 @@ To specify toolsets you want available to the LLM, you can pass an allow-list in
    ```
 
 2. **Using Environment Variable**:
+
    ```bash
    GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server
    ```
@@ -366,23 +391,29 @@ You can also configure specific tools using the `--tools` flag. Tools can be use
    ```
 
 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
@@ -435,9 +466,11 @@ GITHUB_TOOLSETS="all" ./github-mcp-server
 ```
 
 #### "default" toolset
+
 The default toolset `default` is the configuration that gets passed to the server if no toolsets are specified.
 
 The default configuration is:
+
 - context
 - repos
 - issues
@@ -1371,32 +1404,34 @@ The following sets of tools are available:
 
 <summary>Copilot</summary>
 
--   **create_pull_request_with_copilot** - Perform task with GitHub Copilot coding agent
-    -   `owner`: Repository owner. You can guess the owner, but confirm it with the user before proceeding. (string, required)
-    -   `repo`: Repository name. You can guess the repository name, but confirm it with the user before proceeding. (string, required)
-    -   `problem_statement`: Detailed description of the task to be performed (e.g., 'Implement a feature that does X', 'Fix bug Y', etc.) (string, required)
-    -   `title`: Title for the pull request that will be created (string, required)
-    -   `base_ref`: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional)
+- **create_pull_request_with_copilot** - Perform task with GitHub Copilot coding agent
+  - `owner`: Repository owner. You can guess the owner, but confirm it with the user before proceeding. (string, required)
+  - `repo`: Repository name. You can guess the repository name, but confirm it with the user before proceeding. (string, required)
+  - `problem_statement`: Detailed description of the task to be performed (e.g., 'Implement a feature that does X', 'Fix bug Y', etc.) (string, required)
+  - `title`: Title for the pull request that will be created (string, required)
+  - `base_ref`: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional)
 
 </details>
 
 <details>
 
 <summary>Copilot Spaces</summary>
 
--   **get_copilot_space** - Get Copilot Space
-    -   `owner`: The owner of the space. (string, required)
-    -   `name`: The name of the space. (string, required)
+- **get_copilot_space** - Get Copilot Space
+  - `owner`: The owner of the space. (string, required)
+  - `name`: The name of the space. (string, required)
+
+- **list_copilot_spaces** - List Copilot Spaces
 
--   **list_copilot_spaces** - List Copilot Spaces
 </details>
 
 <details>
 
 <summary>GitHub Support Docs Search</summary>
 
--   **github_support_docs_search** - Retrieve documentation relevant to answer GitHub product and support questions. Support topics include: GitHub Actions Workflows, Authentication, GitHub Support Inquiries, Pull Request Practices, Repository Maintenance, GitHub Pages, GitHub Packages, GitHub Discussions, Copilot Spaces
-    -   `query`: Input from the user about the question they need answered. This is the latest raw unedited user message. You should ALWAYS leave the user message as it is, you should never modify it. (string, required)
+- **github_support_docs_search** - Retrieve documentation relevant to answer GitHub product and support questions. Support topics include: GitHub Actions Workflows, Authentication, GitHub Support Inquiries, Pull Request Practices, Repository Maintenance, GitHub Pages, GitHub Packages, GitHub Discussions, Copilot Spaces
+  - `query`: Input from the user about the question they need answered. This is the latest raw unedited user message. You should ALWAYS leave the user message as it is, you should never modify it. (string, required)
+
 </details>
 
 ## Dynamic Tool Discovery

cmd/github-mcp-server/main.go

@@ -136,7 +136,6 @@ func initConfig() {
 	viper.SetEnvPrefix("github")
 	viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_"))
 	viper.AutomaticEnv()
-
 }
 
 func main() {

docs/installation-guides/README.md

@@ -3,6 +3,7 @@
 This directory contains detailed installation instructions for the GitHub MCP Server across different host applications and IDEs. Choose the guide that matches your development environment.
 
 ## Installation Guides by Host Application
+
 - **[GitHub Copilot in other IDEs](install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
 - **[Antigravity](install-antigravity.md)** - Installation for Google Antigravity IDE
 - **[Claude Applications](install-claude.md)** - Installation guide for Claude Web, Claude Desktop and Claude Code CLI
@@ -28,32 +29,36 @@ This directory contains detailed installation instructions for the GitHub MCP Se
 | Copilot in Eclipse | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: Eclipse Plug-in for Copilot 0.10.0+ | Easy |
 
 **Legend:**
+
 - ✅ = Fully supported
 - ❌ = Not yet supported
 
-**Note:** Remote MCP support requires host applications to register a GitHub App or OAuth app for OAuth flow support – even if the new OAuth spec is supported by that host app. Currently, only VS Code has full remote GitHub server support. 
+**Note:** Remote MCP support requires host applications to register a GitHub App or OAuth app for OAuth flow support – even if the new OAuth spec is supported by that host app. Currently, only VS Code has full remote GitHub server support.
 
 ## Installation Methods
 
 The GitHub MCP Server can be installed using several methods. **Docker is the most popular and recommended approach** for most users, but alternatives are available depending on your needs:
 
 ### 🐳 Docker (Most Common & Recommended)
+
 - **Pros**: No local build required, consistent environment, easy updates, works across all platforms
 - **Cons**: Requires Docker installed and running
 - **Best for**: Most users, especially those already using Docker or wanting the simplest setup
 - **Used by**: Claude Desktop, Copilot in VS Code, Cursor, Windsurf, etc.
 
 ### 📦 Pre-built Binary (Lightweight Alternative)
+
 - **Pros**: No Docker required, direct execution via stdio, minimal setup
 - **Cons**: Need to manually download and manage updates, platform-specific binaries
 - **Best for**: Minimal environments, users who prefer not to use Docker
 - **Used by**: Claude Code CLI, lightweight setups
 
 ### 🔨 Build from Source (Advanced Users)
+
 - **Pros**: Latest features, full customization, no external dependencies
 - **Cons**: Requires Go development environment, more complex setup
 - **Prerequisites**: [Go 1.24+](https://go.dev/doc/install)
-- **Build command**: `go build -o github-mcp-server cmd/github-mcp-server/main.go`
+- **Build command**: `go build -o github-mcp-server ./cmd/github-mcp-server`
 - **Best for**: Developers who want the latest features or need custom modifications
 
 ### Important Notes on the GitHub MCP Server
@@ -65,9 +70,11 @@ The GitHub MCP Server can be installed using several methods. **Docker is the mo
 ## General Prerequisites
 
 All installations with Personal Access Tokens (PAT) require:
+
 - **GitHub Personal Access Token (PAT)**: [Create one here](https://github.com/settings/personal-access-tokens/new)
 
 Optional (depending on installation method):
+
 - **Docker** (for Docker-based installations): [Download Docker](https://www.docker.com/)
 - **Go 1.24+** (for building from source): [Install Go](https://go.dev/doc/install)
 
@@ -84,6 +91,7 @@ Regardless of which installation method you choose, follow these security guidel
 ## Getting Help
 
 If you encounter issues:
+
 1. Check the troubleshooting section in your specific installation guide
 2. Verify your GitHub PAT has the required permissions
 3. Ensure Docker is running (for local installations)
@@ -93,8 +101,8 @@ If you encounter issues:
 ## Configuration Options
 
 After installation, you may want to explore:
+
 - **Toolsets**: Enable/disable specific GitHub API capabilities
 - **Read-Only Mode**: Restrict to read-only operations
 - **Dynamic Tool Discovery**: Enable tools on-demand
 - **Lockdown Mode**: Hide public issue details created by users without push access
-

go.mod

@@ -3,6 +3,7 @@ module github.com/github/github-mcp-server
 go 1.24.0
 
 require (
+	github.com/fatih/color v1.18.0
 	github.com/google/go-github/v79 v79.0.0
 	github.com/google/jsonschema-go v0.4.2
 	github.com/josephburnett/jd v1.9.2
@@ -20,6 +21,8 @@ require (
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/yudai/golcs v0.0.0-20170316035057-ecda9a501e82 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
@@ -34,6 +37,7 @@ require (
 	github.com/go-viper/mapstructure/v2 v2.4.0
 	github.com/google/go-querystring v1.1.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/lithammer/fuzzysearch v1.1.8
 	github.com/modelcontextprotocol/go-sdk v1.2.0
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect