Narrow CIMD callback port range to 5 and drop localhost redirect URIs (#189)

* Add public OAuth CIMD and use it as default for mcpc login

Host a Client ID Metadata Document (CIMD) at
https://apify.github.io/mcpc/client-metadata/v1.json so every mcpc
installation presents a consistent client identity on CIMD-capable
authorization servers. This follows the same pattern as VS Code and
Claude Code.

Key changes:
- New docs/client-metadata/v1.json served via GitHub Pages
- mcpc login now defaults to the hosted CIMD; use --no-client-metadata-url
  to opt out or --client-metadata-url <url> to override
- OAuth callback uses fixed port range 13316-13325 to match the CIMD's
  registered redirect_uris (CIMD docs are static, so exact-match ports
  are required by most authorization servers)
- Tightened CIMD URL validation per the spec: reject fragments, embedded
  credentials, and dot path segments
- Added logo_uri, tos_uri, policy_uri to the DCR client metadata getter
  for branding parity with the hosted CIMD

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Use fixed port range 13316–13325 for all OAuth callbacks

Drop the branching between CIMD and non-CIMD port ranges. Using the same
fixed range in all modes (CIMD, DCR, pre-registered --client-id) makes
the callback port predictable for firewalls, docs, and pre-registered
clients, and removes a chunk of conditional logic. Pre-registered
clients can rely on RFC 8252 loopback-any-port semantics or list the
mcpc range in their redirect URIs, same as before.

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Show full default CIMD URL in --client-metadata-url help text

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Shorten default CIMD URL to /mcpc/client.json

Matches the draft-ietf-oauth-client-id-metadata-document spec example
URL (https://example.com/client.json) and trims 13 chars off the
displayed client_id on consent screens.

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Serve GitHub Pages from repo root so / renders the main README

Move client.json from docs/ to the repo root and add a minimal
_config.yml excluding dev dirs, so https://apify.github.io/mcpc/ shows
the project README and https://apify.github.io/mcpc/client.json serves
the OAuth CIMD.

Note: requires changing the GitHub Pages source in repo Settings from
"main / docs" to "main / (root)".

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Fix CIMD metadata URIs: use Pages-hosted paths, drop policy_uri

- logo_uri → client-logo.svg (served via GitHub Pages)
- tos_uri → LICENSE on GitHub Pages (not raw GitHub blob URL)
- Remove policy_uri (no standalone privacy policy page)

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Narrow CIMD callback port range to 5 and drop localhost redirect URIs

- Reduce port range from 10 (13316–13325) to 5 (13316–13320). Matches
  the conservative pattern used by VS Code (1 port) and Claude Code
  (1 port), while leaving headroom for occasional concurrent logins.
- Drop "http://localhost:PORT/callback" entries from the CIMD document
  in favor of "http://127.0.0.1:PORT/callback" only. RFC 8252 §8.3
  explicitly recommends the IP literal over "localhost" to avoid DNS
  resolution ambiguity (a misconfigured /etc/hosts could route
  "localhost" to a non-loopback address). mcpc already binds the
  callback server to 127.0.0.1 only, so the localhost variants were
  dead weight.
- CIMD redirect_uris list shrinks from 20 entries to 5.

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Use 6 non-contiguous OAuth callback ports

Replaces the contiguous range (13316–13320) with an explicit list of
6 spread-out ports: 13163, 13316, 16133, 16313, 31316, 31613. A single
unrelated process squatting on 13316 is now less likely to also hit
the rest of mcpc's callback ports.

findAvailablePort() now takes an explicit `ports` list instead of a
start+range pair.

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Revert port sorting; start list with 13316

Order: 13316, 13163, 31316, 31613, 16133, 16313.

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Add E2E tests for --callback-port and CIMD defaults

Tier 1 (flag-level):
- --callback-port appears in `mcpc login --help`
- --help shows the full default CIMD URL
- --callback-port rejects non-numeric values, 0, values >65535, and
  negatives (validation now in src/cli/index.ts)

Tier 2 (end-to-end port binding):
- Starts `mcpc login --callback-port <port> --no-client-metadata-url`
  against a hanging local HTTP server so the OAuth flow stalls
  during discovery and keeps its callback server bound.
- Polls 127.0.0.1:<port> via bash /dev/tcp probe until it's listening,
  proving --callback-port is honored end-to-end (not just parsed).
- Cleans up both the stall server and the backgrounded mcpc login
  process regardless of outcome.

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

* Serve full docs/ dir via GitHub Pages and clean up _config.yml

List what IS served as a comment (whitelist intent), exclude everything
else. Stop cherry-picking inside docs/ — the full directory is now
published at /mcpc/docs/.

https://claude.ai/code/session_015YnY1wPJF48HUrfdPaFJ1x

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jancurn

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- OAuth callback ports for the hosted CIMD changed from the contiguous range 13316–13325 to 6 non-contiguous ports (13316, 13163, 31316, 31613, 16133, 16313) so one unrelated process is less likely to claim all of them. `localhost` variants dropped from the CIMD's `redirect_uris` in favor of `127.0.0.1` only (per RFC 8252 §8.3, which recommends the IP literal to avoid DNS resolution ambiguity).
 - `restart` success message now notes that previous session state (resource subscriptions, pending notifications, async tasks) was lost, since explicit restart always creates a fresh MCP session
 - `tasks-list` now shows a hint on how to start a new task (`mcpc @session tools-call <name> [args] --task`) when there are no active tasks
 - `mcpc help <command>` now shows a "Did you mean?" suggestion when the command is unknown (e.g., `mcpc help tasks-gfet` → suggests `tasks-get`)

_config.yml

@@ -1,20 +1,27 @@
-title: mcpc
-description: Universal MCP command-line client
+# GitHub Pages configuration for https://apify.github.io/mcpc/
+#
+# Served content (everything else is excluded):
+#   /                    → README.md (project homepage)
+#   /client-metadata.json → OAuth CIMD document
+#   /client-logo.svg     → Client logo for OAuth consent screens
+#   /LICENSE             → Terms of service (referenced by CIMD tos_uri)
+#   /CHANGELOG.md        → Release history
+#   /docs/               → Additional documentation, examples, images
+#
+# Jekyll has no include-only mode, so we exclude everything that
+# shouldn't be published. node_modules/ is excluded by default.
+
 theme: jekyll-theme-cayman
 
-# Dev files and directories not meant for the GitHub Pages site.
-# README.md is rendered at the site root.
 exclude:
   - CLAUDE.md
   - CONTRIBUTING.md
+  - _config.yml
   - bin/
   - dist/
-  - docs/claude-skill/
-  - docs/examples/
   - jest.config.js
-  - node_modules/
-  - package-lock.json
   - package.json
+  - package-lock.json
   - renovate.json
   - scripts/
   - src/

client-metadata.json

@@ -5,25 +5,11 @@
   "tos_uri": "https://apify.github.io/mcpc/LICENSE",
   "redirect_uris": [
     "http://127.0.0.1:13316/callback",
-    "http://127.0.0.1:13317/callback",
-    "http://127.0.0.1:13318/callback",
-    "http://127.0.0.1:13319/callback",
-    "http://127.0.0.1:13320/callback",
-    "http://127.0.0.1:13321/callback",
-    "http://127.0.0.1:13322/callback",
-    "http://127.0.0.1:13323/callback",
-    "http://127.0.0.1:13324/callback",
-    "http://127.0.0.1:13325/callback",
-    "http://localhost:13316/callback",
-    "http://localhost:13317/callback",
-    "http://localhost:13318/callback",
-    "http://localhost:13319/callback",
-    "http://localhost:13320/callback",
-    "http://localhost:13321/callback",
-    "http://localhost:13322/callback",
-    "http://localhost:13323/callback",
-    "http://localhost:13324/callback",
-    "http://localhost:13325/callback"
+    "http://127.0.0.1:13163/callback",
+    "http://127.0.0.1:31316/callback",
+    "http://127.0.0.1:31613/callback",
+    "http://127.0.0.1:16133/callback",
+    "http://127.0.0.1:16313/callback"
   ],
   "grant_types": ["authorization_code", "refresh_token"],
   "response_types": ["code"],

src/cli/index.ts

@@ -616,13 +616,23 @@ ${jsonHelp('Interactive prompts are written to stderr, stdout contains a clean J
           'Missing required argument: server\n\nExample: mcpc login mcp.apify.com'
         );
       }
+      let callbackPort: number | undefined;
+      if (opts.callbackPort) {
+        const parsed = parseInt(opts.callbackPort as string, 10);
+        if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+          throw new ClientError(
+            `Invalid --callback-port value: "${opts.callbackPort as string}". Must be an integer between 1 and 65535.`
+          );
+        }
+        callbackPort = parsed;
+      }
       await auth.login(server, {
         profile: opts.profile,
         scope: opts.scope,
         clientId: opts.clientId,
         clientSecret: opts.clientSecret,
         clientMetadataUrl: opts.clientMetadataUrl,
-        ...(opts.callbackPort ? { callbackPort: parseInt(opts.callbackPort as string, 10) } : {}),
+        ...(callbackPort !== undefined ? { callbackPort } : {}),
         ...getOptionsFromCommand(command),
       });
     });

src/lib/auth/oauth-flow.ts

@@ -15,11 +15,7 @@ import { ClientError } from '../errors.js';
 import { createLogger } from '../logger.js';
 import { removeKeychainOAuthClientInfo, storeKeychainOAuthClientInfo } from './keychain.js';
 import type { AuthProfile } from '../types.js';
-import {
-  MCPC_OAUTH_CALLBACK_PORT,
-  MCPC_OAUTH_CALLBACK_PORT_RANGE,
-  validateClientMetadataUrl,
-} from './oauth-utils.js';
+import { MCPC_OAUTH_CALLBACK_PORTS, validateClientMetadataUrl } from './oauth-utils.js';
 
 const logger = createLogger('oauth-flow');
 
@@ -257,11 +253,11 @@ function startCallbackServer(port: number): {
 
 /**
  * Find an available port for the OAuth callback server.
- * Tries `range` consecutive ports starting at `startPort` and returns the
- * first free one. Throws if all ports in the range are occupied.
+ * Tries each port in `ports` in order and returns the first free one.
+ * Throws if all ports are occupied.
  */
-async function findAvailablePort(startPort: number, range: number): Promise<number> {
-  for (let port = startPort; port < startPort + range; port++) {
+async function findAvailablePort(ports: readonly number[]): Promise<number> {
+  for (const port of ports) {
     try {
       await new Promise<void>((resolve, reject) => {
         const testServer = createServer();
@@ -277,7 +273,7 @@ async function findAvailablePort(startPort: number, range: number): Promise<numb
     }
   }
   throw new ClientError(
-    `Could not find available port for OAuth callback server (tried ports ${startPort}–${startPort + range - 1}). ` +
+    `Could not find available port for OAuth callback server (tried ports ${ports.join(', ')}). ` +
       'Another mcpc login may be in progress — wait for it to finish and try again.'
   );
 }
@@ -434,10 +430,8 @@ export async function performOAuthFlow(
   }
 
   // When --callback-port is set, use that exact port. Otherwise try the
-  // fixed mcpc range (13316–13325) that matches the hosted CIMD's redirect_uris.
-  const port = callbackPort
-    ? await findAvailablePort(callbackPort, 1)
-    : await findAvailablePort(MCPC_OAUTH_CALLBACK_PORT, MCPC_OAUTH_CALLBACK_PORT_RANGE);
+  // fixed mcpc port list that matches the hosted CIMD's redirect_uris.
+  const port = await findAvailablePort(callbackPort ? [callbackPort] : MCPC_OAUTH_CALLBACK_PORTS);
   const redirectUrl = `http://127.0.0.1:${port}/callback`;
 
   logger.debug(`Using redirect URL: ${redirectUrl}`);

src/lib/auth/oauth-utils.ts

@@ -13,8 +13,15 @@ export const DEFAULT_AUTH_PROFILE = 'default';
 
 export const DEFAULT_CLIENT_METADATA_URL = 'https://apify.github.io/mcpc/client-metadata.json';
 
-export const MCPC_OAUTH_CALLBACK_PORT = 13316;
-export const MCPC_OAUTH_CALLBACK_PORT_RANGE = 10;
+/**
+ * Loopback ports used by mcpc's OAuth callback server. Matches the
+ * `redirect_uris` registered in the hosted CIMD document. Tried in order;
+ * the first available port is used. Non-contiguous values to reduce the
+ * chance that a single unrelated process claims all of them.
+ */
+export const MCPC_OAUTH_CALLBACK_PORTS: readonly number[] = [
+  13316, 13163, 31316, 31613, 16133, 16313,
+] as const;
 
 /**
  * OAuth token endpoint response (per OAuth 2.0 spec - uses snake_case)

test/e2e/suites/basic/auth-errors.test.sh

@@ -158,4 +158,101 @@ assert_contains "$STDOUT" "--no-client-metadata-url"
 assert_contains "$STDOUT" "apify.github.io"
 test_pass
 
+test_case "login --help documents --callback-port"
+run_mcpc help login
+assert_success
+assert_contains "$STDOUT" "--callback-port"
+test_pass
+
+test_case "login --help shows full default CIMD URL"
+run_mcpc help login
+assert_success
+assert_contains "$STDOUT" "https://apify.github.io/mcpc/client-metadata.json"
+test_pass
+
+test_case "login --callback-port with non-numeric value is rejected"
+run_xmcpc login mcp.example.com --callback-port abc --no-client-metadata-url
+assert_failure
+assert_contains "$STDERR" "--callback-port"
+test_pass
+
+test_case "login --callback-port with 0 is rejected"
+run_xmcpc login mcp.example.com --callback-port 0 --no-client-metadata-url
+assert_failure
+assert_contains "$STDERR" "--callback-port"
+test_pass
+
+test_case "login --callback-port above 65535 is rejected"
+run_xmcpc login mcp.example.com --callback-port 65536 --no-client-metadata-url
+assert_failure
+assert_contains "$STDERR" "--callback-port"
+test_pass
+
+test_case "login --callback-port negative is rejected"
+run_xmcpc login mcp.example.com --callback-port -1 --no-client-metadata-url
+assert_failure
+assert_contains "$STDERR" "--callback-port"
+test_pass
+
+# =============================================================================
+# Test: Tier 2 - end-to-end callback port binding
+#
+# Starts `mcpc login` in the background with --callback-port set, pointing at
+# a local HTTP server that accepts connections but never responds. This keeps
+# mcpc in the OAuth-discovery phase, so its callback server stays bound long
+# enough to observe. We then verify the expected loopback port is listening.
+# This proves --callback-port is honored end-to-end, not just parsed.
+# =============================================================================
+
+# Pick a likely-free high port outside mcpc's default list for the callback
+TEST_CALLBACK_PORT=47317
+
+test_case "login --callback-port binds the requested port on 127.0.0.1"
+
+# Start a hanging HTTP server on a random local port. mcpc will hit this while
+# trying to discover OAuth metadata and block indefinitely, which is what we
+# want so we can observe the callback server.
+STALL_PORT=47318
+node -e "require('http').createServer(()=>{}).listen(${STALL_PORT}, '127.0.0.1')" &
+STALL_PID=$!
+
+# Wait for the stall server to be ready
+for _ in $(seq 1 20); do
+  if (echo >/dev/tcp/127.0.0.1/$STALL_PORT) >/dev/null 2>&1; then
+    break
+  fi
+  sleep 0.1
+done
+
+# Start mcpc login in the background. --no-client-metadata-url skips CIMD
+# so mcpc goes straight to DCR against the stall server (which hangs).
+$MCPC login http://127.0.0.1:$STALL_PORT \
+  --callback-port "$TEST_CALLBACK_PORT" \
+  --no-client-metadata-url \
+  </dev/null >/dev/null 2>&1 &
+LOGIN_PID=$!
+
+# Poll for the callback port to be bound (up to 10 seconds)
+bound=false
+for _ in $(seq 1 100); do
+  if (echo >/dev/tcp/127.0.0.1/$TEST_CALLBACK_PORT) >/dev/null 2>&1; then
+    bound=true
+    break
+  fi
+  sleep 0.1
+done
+
+# Clean up background processes regardless of outcome
+_kill_tree "$LOGIN_PID"
+wait "$LOGIN_PID" 2>/dev/null || true
+_kill_tree "$STALL_PID"
+wait "$STALL_PID" 2>/dev/null || true
+
+if [[ "$bound" == "true" ]]; then
+  test_pass
+else
+  test_fail "Port $TEST_CALLBACK_PORT was not bound within 10s"
+  exit 1
+fi
+
 test_done