chore: import upstream snapshot with attribution

2026-07-13 12:37:57 +08:00
commit e30f8ba47c
533 changed files with 115926 additions and 0 deletions
@@ -0,0 +1,136 @@
+# Install GitHub MCP Server in Windsurf
+
+## Prerequisites
+1. Windsurf IDE installed (latest version)
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
+3. For local installation: [Docker](https://www.docker.com/) installed and running
+
+## Remote Server Setup (Recommended)
+
+The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP protocol. Windsurf currently supports PAT authentication only.
+
+### Streamable HTTP Configuration
+Windsurf supports Streamable HTTP servers with a `serverUrl` field:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "serverUrl": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+## Local Server Setup
+
+### Docker Installation (Required)
+**Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
+
+Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-p",
+        "127.0.0.1:8085:8085",
+        "-e",
+        "GITHUB_OAUTH_CALLBACK_PORT",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_OAUTH_CALLBACK_PORT": "8085"
+      }
+    }
+  }
+}
+```
+
+See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.
+
+To authenticate with a Personal Access Token instead (it takes precedence over OAuth):
+
+```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"
+      }
+    }
+  }
+}
+```
+
+## Installation Steps
+
+### Via Plugin Store
+1. Open Windsurf and navigate to Cascade
+2. Click the **Plugins** icon or **hammer icon** (🔨)
+3. Search for "GitHub MCP Server"
+4. Click **Install** and enter your PAT when prompted
+5. Click **Refresh** (🔄)
+
+### Manual Configuration
+1. Click the hammer icon (🔨) in Cascade
+2. Click **Configure** to open `~/.codeium/windsurf/mcp_config.json`
+3. Add your chosen configuration from above
+4. Save the file
+5. Click **Refresh** (🔄) in the MCP toolbar
+
+## Configuration Details
+
+- **File path**: `~/.codeium/windsurf/mcp_config.json`
+- **Scope**: Global configuration only (no per-project support)
+- **Format**: Must be valid JSON (use a linter to verify)
+
+## Verification
+
+After installation:
+1. Look for "1 available MCP server" in the MCP toolbar
+2. Click the hammer icon to see available GitHub tools
+3. Test with: "List my GitHub repositories"
+4. Check for green dot next to the server name
+
+## Troubleshooting
+
+### Remote Server Issues
+- **Authentication failures**: Verify PAT has correct scopes and hasn't expired
+- **Connection errors**: Check firewall/proxy settings for HTTPS connections
+- **Streamable HTTP not working**: Ensure you're using the correct `serverUrl` field format
+
+### Local Server Issues
+- **Docker errors**: Ensure Docker Desktop is running
+- **Image pull failures**: Try `docker logout ghcr.io` then retry
+- **Docker not found**: Install Docker Desktop and ensure it's running
+
+### General Issues
+- **Invalid JSON**: Validate with [jsonlint.com](https://jsonlint.com)
+- **Tools not appearing**: Restart Windsurf completely
+- **Check logs**: `~/.codeium/windsurf/logs/`
+
+## Important Notes
+
+- **Official repository**: [github/github-mcp-server](https://github.com/github/github-mcp-server)
+- **Remote server URL**: `https://api.githubcopilot.com/mcp/`
+- **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported)
+- **npm package**: `@modelcontextprotocol/server-github` (deprecated as of April 2025 - no longer functional)
+- **Windsurf limitations**: No environment variable interpolation, global config only