Merge main into registry pattern branch (docs only)

SamMorrowDrums · SamMorrowDrums · commit 982b12d84fa5 · 2025-12-16T22:06:13.000+01:00
Preserves registry pattern architecture while incorporating: - Antigravity installation guide - Tool renaming documentation - CONTRIBUTING.md updates - README tool documentation updates Functional changes from main (5a4338c, a48e306, afe34d8) to be ported separately.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -39,6 +39,7 @@ These are one time installations required to be able to test your changes locall
     - Run linter: `script/lint`
     - Update snapshots and run tests: `UPDATE_TOOLSNAPS=true go test ./...`
     - Update readme documentation: `script/generate-docs`
+    - If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](docs/tool-renaming.md))
 6. Push to your fork and [submit a pull request][pr] targeting the `main` branch
 7. Pat yourself on the back and wait for your pull request to be reviewed and merged.
 
diff --git a/README.md b/README.md
@@ -991,7 +991,7 @@ The following sets of tools are available:
      2. get_diff - Get the diff of a pull request.
      3. get_status - Get status of a head commit in a pull request. This reflects status of builds and checks.
      4. get_files - Get the list of files changed in a pull request. Use with pagination parameters to control the number of results returned.
-     5. get_review_comments - Get the review comments on a pull request. They are comments made on a portion of the unified diff during a pull request review. Use with pagination parameters to control the number of results returned.
+     5. get_review_comments - Get review threads on a pull request. Each thread contains logically grouped review comments made on the same code location during pull request reviews. Returns threads with metadata (isResolved, isOutdated, isCollapsed) and their associated comments. Use cursor-based pagination (perPage, after) to control results.
      6. get_reviews - Get the reviews on a pull request. When asked for review comments, use get_review_comments method.
      7. get_comments - Get comments on a pull request. Use this if user doesn't specifically want review comments. Use with pagination parameters to control the number of results returned.
      (string, required)
@@ -1061,7 +1061,7 @@ The following sets of tools are available:
   - `owner`: Repository owner (username or organization) (string, required)
   - `path`: Path where to create/update the file (string, required)
   - `repo`: Repository name (string, required)
-  - `sha`: Required if updating an existing file. The blob SHA of the file being replaced. (string, optional)
+  - `sha`: The blob SHA of the file being replaced. (string, optional)
 
 - **create_repository** - Create repository
   - `autoInit`: Initialize with README (boolean, optional)
@@ -1092,7 +1092,7 @@ The following sets of tools are available:
 
 - **get_file_contents** - Get file or directory contents
   - `owner`: Repository owner (username or organization) (string, required)
-  - `path`: Path to file/directory (directories must end with a slash '/') (string, optional)
+  - `path`: Path to file/directory (string, optional)
   - `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional)
   - `repo`: Repository name (string, required)
   - `sha`: Accepts optional commit SHA. If specified, it will be used instead of ref (string, optional)
diff --git a/docs/installation-guides/README.md b/docs/installation-guides/README.md
@@ -4,6 +4,7 @@ This directory contains detailed installation instructions for the GitHub MCP Se
 
 ## 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
 - **[Cursor](install-cursor.md)** - Installation guide for Cursor IDE
 - **[Google Gemini CLI](install-gemini-cli.md)** - Installation guide for Google Gemini CLI
diff --git a/docs/installation-guides/install-antigravity.md b/docs/installation-guides/install-antigravity.md
@@ -0,0 +1,143 @@
+# Installing GitHub MCP Server in Antigravity
+
+This guide covers setting up the GitHub MCP Server in Google's Antigravity IDE.
+
+## Prerequisites
+
+- Antigravity IDE installed (latest version)
+- GitHub Personal Access Token with appropriate scopes
+
+## Installation Methods
+
+### Option 1: Remote Server (Recommended)
+
+Uses GitHub's hosted server at `https://api.githubcopilot.com/mcp/`.
+
+> [!NOTE]
+> We recommend this manual configuration method because the "official" installation via the Antigravity MCP Store currently has known issues (often resulting in Docker errors). This direct remote connection is more reliable.
+
+#### Step 1: Access MCP Configuration
+
+1. Open Antigravity
+2. Click the "..." (Additional Options) menu in the Agent panel
+3. Select "MCP Servers"
+4. Click "Manage MCP Servers"
+5. Click "View raw config"
+
+This will open your `mcp_config.json` file at:
+- **Windows**: `C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json`
+- **macOS/Linux**: `~/.gemini/antigravity/mcp_config.json`
+
+#### Step 2: Add Configuration
+
+Add the following to your `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "serverUrl": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+**Important**: Note that Antigravity uses `serverUrl` instead of `url` for HTTP-based MCP servers.
+
+#### Step 3: Configure Your Token
+
+Replace `YOUR_GITHUB_PAT` with your actual GitHub Personal Access Token.
+
+Create a token here: https://github.com/settings/tokens
+
+Recommended scopes:
+- `repo` - Full control of private repositories
+- `read:org` - Read org and team membership
+- `read:user` - Read user profile data
+
+#### Step 4: Restart Antigravity
+
+Close and reopen Antigravity for the changes to take effect.
+
+#### Step 5: Verify Installation
+
+1. Open the MCP Servers panel (... menu → MCP Servers)
+2. You should see "github" with a list of available tools
+3. You can now use GitHub tools in your conversations
+
+> [!NOTE]
+> The status indicator in the MCP Servers panel might not immediately turn green in some versions, but the tools will still function if configured correctly.
+
+### Option 2: Local Docker Server
+
+If you prefer running the server locally with Docker:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+**Requirements**:
+- Docker Desktop installed and running
+- Docker must be in your system PATH
+
+## Troubleshooting
+
+### "Error: serverUrl or command must be specified"
+
+Make sure you're using `serverUrl` (not `url`) for the remote server configuration. Antigravity requires `serverUrl` for HTTP-based MCP servers.
+
+### Server not appearing in MCP list
+
+- Verify JSON syntax in your config file
+- Check that your PAT hasn't expired
+- Restart Antigravity completely
+
+### Tools not working
+
+- Ensure your PAT has the correct scopes
+- Check the MCP Servers panel for error messages
+- Verify internet connection for remote server
+
+## Available Tools
+
+Once installed, you'll have access to tools like:
+- `create_repository` - Create new GitHub repositories
+- `push_files` - Push files to repositories
+- `search_repositories` - Search for repositories
+- `create_or_update_file` - Manage file content
+- `get_file_contents` - Read file content
+- And many more...
+
+For a complete list of available tools and features, see the [main README](../../README.md).
+
+## Differences from Other IDEs
+
+- **Configuration key**: Antigravity uses `serverUrl` instead of `url` for HTTP servers
+- **Config location**: `.gemini/antigravity/mcp_config.json` instead of `.cursor/mcp.json`
+- **Tool limits**: Antigravity recommends keeping total enabled tools under 50 for optimal performance
+
+## Next Steps
+
+- Explore the [Server Configuration Guide](../server-configuration.md) for advanced options
+- Check out [toolsets documentation](../../README.md#available-toolsets) to customize available tools
+- See the [Remote Server Documentation](../remote-server.md) for more details
diff --git a/docs/tool-renaming.md b/docs/tool-renaming.md
@@ -0,0 +1,42 @@
+# Tool Renaming Guide
+
+How to safely rename MCP tools without breaking existing user configurations.
+
+## Overview
+
+When tools are renamed, users who have the old tool name in their MCP configuration (for example, in `X-MCP-Tools` headers for the remote MCP server or `--tools` flags for the local MCP server) would normally get errors. 
+The deprecation alias system allows us to maintain backward compatibility by silently resolving old tool names to their new canonical names.
+
+This allows us to rename tools safely, without introducing breaking changes for users that have a hard reference to those tools in their server configuration.
+
+## Quick Steps
+
+1. **Rename the tool** in your code (as usual, this will imply a range of changes like updating the tool registration, the tests and the toolsnaps).
+2. **Add a deprecation alias** in [pkg/github/deprecated_tool_aliases.go](../pkg/github/deprecated_tool_aliases.go):
+   ```go
+   var DeprecatedToolAliases = map[string]string{
+       "old_tool_name": "new_tool_name",
+   }
+   ```
+3. **Update documentation** (README, etc.) to reference the new canonical name
+
+That's it. The server will silently resolve old names to new ones. This will work across both local and remote MCP servers.
+
+## Example
+
+If renaming `get_issue` to `issue_read`:
+
+```go
+var DeprecatedToolAliases = map[string]string{
+    "get_issue": "issue_read",
+}
+```
+
+A user with this configuration:
+```json
+{
+  "--tools": "get_issue,get_file_contents"
+}
+```
+
+Will get `issue_read` and `get_file_contents` tools registered, with no errors.
