[Aaryan430]

Stack: #527 → #541 (this, based on #527) → #553. GitHub moves this PR to main once #527 merges. The scan-logs call added here now uses the account's region (#489).

Why

The MCP daily report for 2 Nov put accessibility stability at 55.4%. Most of that was one account probing the scanner, but even without it the accessibility tools sat at 67–80% all week. This PR fixes the failures that need only an MCP change. The others (central-scanner's "user info missing", the External API add-on, report links that need accessibility changes) are tracked separately.

What changed

A scan that outlasts the 5-minute wait is handed back, not reported as failed

• Before, the wait rejected with "Scan timed out after 5 minutes" and the tool answered Failed to start accessibility scan: … as an error, with no scan id or run id. The scan kept running and finished. In an isolated test the agent then told the user no scan existed.
• Now the wait ends with a ScanTimeoutError and the tool returns a normal result:
  • the scan is still running and was not cancelled;
  • the scan id, run id and dashboard link;
  • call fetchAccessibilityIssues with those ids once it has finished, and don't start the scan again.
• A cancelled run now ends the wait instead of waiting out the 5 minutes, and the 5-minute timer is cleared once a scan finishes.

Local URLs through a BrowserStack Local tunnel the user started (localIdentifier)

• The hosted MCP runs on BrowserStack's servers, so it cannot start a tunnel on the user's machine, and it refused every local URL.
• The scan API already takes localTestingInfo with any tunnel id. startAccessibilityScan now takes an optional localIdentifier. With it, MCP sends the scan through that tunnel and does not start or kill any tunnel of its own.
• This also covers USE_OWN_LOCAL_BINARY_PROCESS, which refused local URLs, and internal hosts that are not localhost.
• Without it, the hosted refusal now says how to start a tunnel: the Local app, or BrowserStackLocal --key <your access key> --local-identifier <a name>, then pass that name as localIdentifier.

A taken scan name no longer fails the scan

• Scan names are unique per account, so an agent re-scanning a page under the same name was refused.
• MCP now retries once as <name> YYYY-MM-DD HH:MM:SS UTC. Only a 422 that says "already exists", or gives no reason, counts as a taken name; a 422 about a setting is passed on unchanged.
• The timestamp uses only characters central-scanner allows in a name, and the name is shortened to stay within its 255 characters. The result opens with the name the scan was started under.

Scan names the API would refuse are cleaned instead of failing the scan

• central-scanner allows only letters, digits, spaces and _ : * . @ ! $ ' { } [ ] ( - in a scan name, and never --. Agents name scans after page titles and paths, so 21 scans in a week failed on "Scan name is invalid".
• MCP now replaces any other character before creating the scan. Accents are dropped (Café → Cafe), parentheses become square brackets (the API takes ( but not )), and a run of replaced characters becomes -, or - between words. A name with nothing usable left, such as one in another script, falls back to the page's host.
• The result opens with The name "…" has characters scan names can't contain, so this scan was started as "…". A cleaned name that is also taken gets the timestamp below, and the note says both.

A failed scan says why

• It used to say only "The dashboard says why", which left an agent nothing to tell the user (19 failed scans in a week).
• The result now gives the run's own reason, taken from the scans list (lastScanDetails.error, only when that is this run). It also lists each page that did not scan, with its reason from the run's scan logs (e.g. [HTTP 403] Forbidden, Failed to start the test), up to 10 pages and then a count.
• If neither read gives anything, it still points to the dashboard. Both reads are best-effort, so a failed read doesn't add an error on top of the failed scan.

Saying why advanced or experimental rules came back off

• On a public-API scan, a plan without advanced or experimental rules turns them off and runs the scan anyway, without saying so. A customer reported this through submitFeedback.
• When those rules were asked for, or left at their default (on), and the run reports them off, the settings line now adds that the account's plan most likely doesn't include them, and that the issues don't cover them.
• The two rule parameters say "off if the plan lacks them".

Connections that never open (apiClient)

• On the hosted server, calls failed within 0.5–1.5 s with connect ETIMEDOUT <IPv4>; connect ENETUNREACH <IPv6>: 17 calls across 7 tools in a week.
• Node gives each of a host's addresses 250 ms by default. On a slow route the IPv4 attempt is dropped that early, and IPv6 fails where there is no route. Likely cause; not confirmed on the hosted pod.
• The default HTTPS agent now gives each address 2 s (autoSelectFamilyAttemptTimeout). I checked that the agent option reaches the socket on Node 22.
• A request whose connection never opened within 5 s is tried once more. Nothing was sent, so this is safe for POSTs too. A request that got a response, failed after connecting, or failed only after every address timed out (the host is down) is not repeated.
• The retry and the 2 s per-address connect timeout apply to every tool's calls through apiClient, not only accessibility. A host that is really down now fails after roughly 2–5 s instead of under 1 s.

Verified

• npm run build steps: lint, prettier, tsc and vitest all pass (130 files, 1876 tests). New tests cover each item above.
• Live, in isolated claude -p sessions with a strict MCP config (only this server, no built-in tools), against a real account:
  • Taken name: asked to scan under an existing name, the scan started as zz-5m-timeout-test 2026-11-03 09:51:04 UTC (scan 4300475) and the result opened with the rename note. The agent told the user.
  • Own tunnel: with BrowserStack Local started separately under zz-mcp-9a-test and a test page on localhost:8765, the agent passed localIdentifier itself. The scan reached the page through the tunnel and found the 8 planted issues (scan 4300483). The tunnel was still running afterwards.
  • Name cleaned: asked to name a scan Pricing / Plans | Q4 (draft), v2, the scan started as Pricing - Plans - Q4 [draft] - v2, and the result opened with the rename note.
  • Failed scan: a scan of a domain that does not resolve (scan 4300543) returned Why: The requested page is not reachable. Please ensure the domain is accessible. and the page with Failed to start the test.
  • 5-minute wait: with a test-only copy of this build that sends the page plus 10 more URLs (so the scan takes over 5 minutes), the tool returned the still-running result with scan 4300473 / run 2420007 instead of Failed to start. The agent then called fetchAccessibilityIssues with those ids itself and told the user the scan was still finishing. On 2.4.1 the same test ended with the agent saying no scan existed.
• Not tested live: the plan note (the test account's plan includes advanced rules) and the connect retry (the failure can't be reproduced locally). Both are covered by unit tests.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Central YAML (base), Organization UI (inherited), Workspace UI (inherited); Enforced overrides: Organization
• Review profile: ASSERTIVE
• Plan: Enterprise
• Run ID: 497d66f1-4e3e-4574-98f7-d219b2bd3e61

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[sarve-shreyas]

Reviewed 6abd4a4..cbe1c17 (this PR on top of #527). npm run build passes locally on this head: 142 files, 2,104 tests.

No blocking findings from me. Checked and fine:

• ScanTimeoutError hands the ids back, the timer is cleared on finish/error, and cancelled ends the wait.
• An own localIdentifier skips both start and kill, and sends localTestingInfo for public URLs too.
• Taken-name retry only fires on a 422 that says "already exists" or gives no reason; the timestamp stays inside the allowed character set and 255 chars.
• cleanScanName collapses runs so -- can't appear, and falls back to the host.
• failureDetails is best-effort (errors swallowed) and only takes lastScanDetails.error when it is this run.
• planDowngradeNote only fires when the rules were asked for or left at their default.

One non-blocking note inline on apiClient.

[sarve-shreyas]

Non-blocking: this retry and the new directAgent apply to every tool that uses apiClient, not just accessibility. I'm fine with that, since a connect failure sent nothing. But it's worth a line in the PR description so reviewers of other tools know about it.

Also, a host that really is down now takes up to (2 s × addresses) × 2 before failing, where it used to fail in under a second. The default case is fine, but tools that loop over many calls (scan-list walks, polling) could stall much longer when an upstream is down. Maybe skip the retry when the first attempt already spent its full per-address budget, or cap the total.

[sarve-shreyas]

Re-reviewed cbe1c17..dd1edcd (dd1edcd plus the merge of #527). npm run build passes locally: 142 files, 2,104 tests.

Resolved:

• The connect retry now only fires when the failure came within 5 s (CONNECT_RETRY_WINDOW_MS). A host that's really down waits out the OS connect timeout on its last address, goes past the window, and isn't retried. The fast ETIMEDOUT/ENETUNREACH case this PR targets still is.

No open findings from me on this PR. Small ask: a line in the description noting that the retry and directAgent apply to every tool, not just accessibility.

[sarve-shreyas]

Approved at dd1edcd. The connect retry now only fires on a fast failure. Build passes locally, 2,104 tests. Small ask, not blocking: note in the description that the apiClient retry and agent apply to every tool.