Render multi-scope tools as "any of" in generated docs

Author: kelsey-myers

README.md

@@ -875,7 +875,7 @@ The following sets of tools are available:
   - `type`: Type of this issue. Only use if the repository has issue types configured. Use list_issue_types tool to get valid type values for the organization. If the repository doesn't support issue types, omit this parameter. (string, optional)
 
 - **list_issue_types** - List available issue types
-  - **Required OAuth Scopes**: `repo`, `read:org`
+  - **Required OAuth Scopes (any of)**: `repo`, `read:org`
   - **Accepted OAuth Scopes**: `admin:org`, `read:org`, `repo`, `write:org`
   - `owner`: The account owner of the repository or organization. (string, required)
   - `repo`: The name of the repository. When provided, returns issue types for this specific repository. When omitted, returns org-level issue types directly. (string, optional)

cmd/github-mcp-server/generate_docs.go

@@ -221,7 +221,15 @@ func writeToolDoc(buf *strings.Builder, tool inventory.ServerTool) {
 
 	// OAuth scopes if present
 	if len(tool.RequiredScopes) > 0 {
-		fmt.Fprintf(buf, "  - **Required OAuth Scopes**: `%s`\n", strings.Join(tool.RequiredScopes, "`, `"))
+		// Scope filtering uses "any of" semantics (see scopes.HasRequiredScopes),
+		// so when multiple required scopes are listed, render them as alternatives
+		// rather than implying all are required.
+		scopeList := "`" + strings.Join(tool.RequiredScopes, "`, `") + "`"
+		if len(tool.RequiredScopes) > 1 {
+			fmt.Fprintf(buf, "  - **Required OAuth Scopes (any of)**: %s\n", scopeList)
+		} else {
+			fmt.Fprintf(buf, "  - **Required OAuth Scopes**: %s\n", scopeList)
+		}
 
 		// Only show accepted scopes if they differ from required scopes
 		if len(tool.AcceptedScopes) > 0 && !scopesEqual(tool.RequiredScopes, tool.AcceptedScopes) {

docs/feature-flags.md

@@ -95,7 +95,7 @@ runtime behavior (such as output formatting) won't appear here.
   - `type`: Type of this issue. Only use if the repository has issue types configured. Use list_issue_types tool to get valid type values for the organization. If the repository doesn't support issue types, omit this parameter. (string, optional)
 
 - **list_issue_fields** - List issue fields
-  - **Required OAuth Scopes**: `repo`, `read:org`
+  - **Required OAuth Scopes (any of)**: `repo`, `read:org`
   - **Accepted OAuth Scopes**: `admin:org`, `read:org`, `repo`, `write:org`
   - `owner`: The account owner of the repository or organization. The name is not case sensitive. (string, required)
   - `repo`: The name of the repository. When provided, returns fields for this specific repository (inherited from its organization). When omitted, returns org-level fields directly. (string, optional)

docs/insiders-features.md

@@ -89,7 +89,7 @@ The list below is generated from the Go source. It covers tool **inventory and s
   - `type`: Type of this issue. Only use if the repository has issue types configured. Use list_issue_types tool to get valid type values for the organization. If the repository doesn't support issue types, omit this parameter. (string, optional)
 
 - **list_issue_fields** - List issue fields
-  - **Required OAuth Scopes**: `repo`, `read:org`
+  - **Required OAuth Scopes (any of)**: `repo`, `read:org`
   - **Accepted OAuth Scopes**: `admin:org`, `read:org`, `repo`, `write:org`
   - `owner`: The account owner of the repository or organization. The name is not case sensitive. (string, required)
   - `repo`: The name of the repository. When provided, returns fields for this specific repository (inherited from its organization). When omitted, returns org-level fields directly. (string, optional)

pkg/utils/api.go

@@ -94,6 +94,22 @@ func newDotcomHost() (APIHost, error) {
 	}, nil
 }
 
+// DEV-ONLY: mirror newDotcomHost but pointed at the Codespaces monolith on http://*.github.localhost.
+func newLocalDotcomHost() (APIHost, error) {
+	baseRestURL, _ := url.Parse("http://api.github.localhost/")
+	gqlURL, _ := url.Parse("http://api.github.localhost/graphql")
+	uploadURL, _ := url.Parse("http://uploads.github.localhost/")
+	rawURL, _ := url.Parse("http://raw.github.localhost/")
+	authorizationServerURL, _ := url.Parse("http://github.localhost/login/oauth")
+	return APIHost{
+		restURL:                baseRestURL,
+		gqlURL:                 gqlURL,
+		uploadURL:              uploadURL,
+		rawURL:                 rawURL,
+		authorizationServerURL: authorizationServerURL,
+	}, nil
+}
+
 func newGHECHost(hostname string) (APIHost, error) {
 	u, err := url.Parse(hostname)
 	if err != nil {
@@ -235,6 +251,11 @@ func parseAPIHost(s string) (APIHost, error) {
 		return APIHost{}, fmt.Errorf("host must have a scheme (http or https): %s", s)
 	}
 
+	// DEV-ONLY: route github.localhost (Codespaces monolith) to local dotcom-style URLs.
+	if u.Hostname() == "github.localhost" || strings.HasSuffix(u.Hostname(), ".github.localhost") {
+		return newLocalDotcomHost()
+	}
+
 	if u.Hostname() == "github.com" || strings.HasSuffix(u.Hostname(), ".github.com") {
 		return newDotcomHost()
 	}

script/mcp-local

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+go build -C "$REPO_ROOT" -o "$REPO_ROOT/bin/github-mcp-server-local" ./cmd/github-mcp-server
+
+export GITHUB_PERSONAL_ACCESS_TOKEN="${MY_TOKEN:-${GITHUB_TOKEN:-$(gh auth token 2>/dev/null || true)}}"
+
+exec "$REPO_ROOT/bin/github-mcp-server-local" stdio "$@"