MCP tools

@vispero/cora-mcp gives a coding agent these tools beside the browser_* tools it takes from playwright-mcp. The agent opens a page and works it with the browser tools, then scans it as it is with scan_page, or loads a URL and scans it as it loads with scan_url. Each scan records its run in the state directory, the project’s or, outside a project, the one in the folder cora-mcp was started in, in runs/ (.cora/runs/ by default), where explain_finding reads it, and starts a remediation loop in its loop/ for each issue it finds, which verify_fix checks a fix against. get_fix_guidance gives how to fix a rule’s failures, and the fixes that look right but still fail. Once the fixes are verified, summarize_fixes reports what became of each issue whose loop is open, and ends each loop it reports.

Tool	Does
`scan_page`	Scan the current page
`scan_url`	Load and scan a URL
`list_rules`	List the rules
`explain_finding`	Explain an issue
`get_fix_guidance`	Get a rule’s fix guidance
`verify_fix`	Verify a fix
`summarize_fixes`	Summarize the fixes

Every result is JSON that names its format and version, and a client gets it both as structured content and as text. A result stays short enough for an agent’s context: a scan’s issues are listed most important first until the result is full, and omitted counts the rest, which the run file keeps. explain_finding lists an issue’s combinations by browser, then by viewport. Its findings follow, most important first, and omittedCombinations and omitted count the rest.

A tool that fails returns an error result whose text is JSON: format is cora-mcp-error, with the error’s code, message, hint, docsUrl and nextActions, and, when the message lists problems such as invalid arguments, issues, each with its path and message, as many as the result’s size allows, with omittedIssues counting the rest. The error reference explains each code. Besides the codes each tool lists, any of them can fail with internal.unexpected.

scan_page

Scan the current page

Checks the page the browser shows now with the accessibility rules the project’s config runs on it, or only those the rules selectors name, as the agent left it after navigating, clicking, typing or running script, such as with a dialog open. Scans the current tab, or the tab at tab. Returns the issues found, most severe first, each with an ID that explain_finding and verify_fix take, rules, the IDs of the rules it fails, its fix class and, on an app built with CORA’s source stamps or Angular’s source locations, its source location and how many call sites it has. An issue with a violation of a rule the project’s config sets to report, and no violation CI’s gate checks, has report: true and never fails the gate; an issue that only needs review never has it. Says when the page did not settle before the scan, so another scan of it can find other issues. Records the run in the state directory, the project’s or, outside a project, the one in the folder cora-mcp was started in, in runs/ (.cora/runs/ by default), and each issue’s element as the scan found it in its loop/, for verify_fix. Its issues never fail a gate or change a baseline, since no one can reach the page state again on demand, so none is marked as one the project’s baseline accepts; to check a page as it loads, use scan_url. Automated rules find only some accessibility problems: a scan that finds none does not show the page is accessible.

Arguments:

tab (integer): The index of the tab to scan, as browser_tabs lists it; the current tab when absent.
include (array of strings): CSS selectors in the main document: scan only these elements and their content. A scoped scan records partial coverage. One that matches an element on or inside one the config’s page.exclude leaves out fails with scan.invalid-scope.
exclude (array of strings): CSS selectors in the main document: leave these elements and their content out of the scan. A scoped scan records partial coverage. The config’s page.exclude for the page applies beside them.
rules (array of strings): Rule selectors: run only the rules these name, of those the project’s config runs on the page, each a rule ID such as axe/region, a WCAG success criterion such as 1.4.3, a category such as forms, or an engine’s rules such as axe/*. A narrowed scan never runs a rule the config leaves off, and records a run of its own.

Annotations: readOnlyHint: true, openWorldHint: false

Result: cora-mcp-scan, version 1

Errors: contract.wrong-format, contract.unsupported-version, contract.invalid, contract.unknown-fields, config.invalid, config.ambiguous, config.load-failed, config.invalid-environment, file.unreadable, file.write-failed, scan.invalid-scope, scan.unsupported-page, page.navigated, page.unresponsive, mcp.no-page, mcp.unknown-tab, mcp.invalid-argument, mcp.browser-timeout, mcp.state-unwritable, account.missing, account.invalid, account.expired, service.client-outdated, service.unreachable, service.unavailable

scan_url

Load and scan a URL

Loads a URL in the current tab, as cora scan loads a target, and checks the page as it loads with the accessibility rules the project’s config runs on it, or only those the rules selectors name. A load that fails or answers an HTTP error, a page that keeps navigating or stops answering while it is scanned, and a scan that runs out of time are reported as not scanned, and so is a redirect to another page, such as a sign-in page, whose landing page is scanned in its place when it is on the same host. Returns the issues found, most severe first, each with an ID that explain_finding and verify_fix take, rules, the IDs of the rules it fails, its fix class and, on an app built with CORA’s source stamps or Angular’s source locations, its source location and how many call sites it has. An issue with a violation of a rule the project’s config sets to report, and no violation CI’s gate checks, has report: true and never fails the gate; an issue that only needs review never has it. Says when the page did not settle before the scan, so another scan of it can find other issues. Records the run in the state directory, the project’s or, outside a project, the one in the folder cora-mcp was started in, in runs/ (.cora/runs/ by default), and each issue’s element as the scan found it in its loop/, for verify_fix. An issue the project’s baseline accepts, as cora scan counts it, has accepted: true, so CI’s gate does not fail on it. Automated rules find only some accessibility problems: a scan that finds none does not show the page is accessible.

Arguments:

url (string, required): The page to load: an absolute http or https URL, or a path resolved against the config’s baseUrl.
include (array of strings): CSS selectors in the main document: scan only these elements and their content. A scoped scan records partial coverage. One that matches an element on or inside one the config’s page.exclude leaves out fails with scan.invalid-scope.
exclude (array of strings): CSS selectors in the main document: leave these elements and their content out of the scan. A scoped scan records partial coverage. The config’s page.exclude for the page applies beside them.
rules (array of strings): Rule selectors: run only the rules these name, of those the project’s config runs on the page, each a rule ID such as axe/region, a WCAG success criterion such as 1.4.3, a category such as forms, or an engine’s rules such as axe/*. A narrowed scan never runs a rule the config leaves off, and records a run of its own.

Annotations: readOnlyHint: false, destructiveHint: false, openWorldHint: true

Result: cora-mcp-scan, version 1

Errors: contract.wrong-format, contract.unsupported-version, contract.invalid, contract.unknown-fields, config.invalid, config.ambiguous, config.load-failed, config.invalid-environment, file.unreadable, file.write-failed, target.invalid, scan.invalid-scope, browser.not-installed, browser.launch-failed, signin.storage-state-not-found, signin.setup-failed, mcp.no-page, mcp.invalid-argument, mcp.browser-timeout, mcp.state-unwritable, account.missing, account.invalid, account.expired, service.client-outdated, service.unreachable, service.unavailable

list_rules

List the rules

Lists the accessibility rules scan_page and scan_url run for this project by its config’s rule selection: on the page at url when given, as its route’s selection decides them, and otherwise where no route of the config sets its own; with rules selectors, such as forms or axe/*, only those they name. Each rule gives its ID, what it checks, its WCAG success criteria, its category, whether its findings fail the gate (on) or are only reported (report), decidedBy, the config’s key that decided it, such as rules.standard or routes[0].rules.overrides["axe/region"], and the severity and fix class of the issues it finds.

Arguments:

url (string): The page whose rules to list, as scan_url takes it: an absolute http or https URL, or a path resolved against the config’s baseUrl. Its route’s rule selection decides the rules; without it, the config’s rules where no route sets its own.
rules (array of strings): Rule selectors: list only the rules these name, each a rule ID such as axe/region, a WCAG success criterion such as 1.4.3, a category such as forms, or an engine’s rules such as axe/*.

Annotations: readOnlyHint: true, openWorldHint: false

Result: cora-mcp-rules, version 1

explain_finding

Explain an issue

Explains an issue from a scan’s result: its rule, WCAG success criteria and fix class, report: true when it has a violation of a rule the project’s config sets to report and no violation CI’s gate checks, so it never fails the gate, accepted: true when the project’s baseline accepts it in the run, as cora scan counts it, so CI’s gate does not fail on it, how many call sites it has, the combinations of browser and viewport its findings were seen in, and each of its findings with its page, element, source location, markup and why it failed. Each finding’s reproduce names its page, its url in its browser and viewport, and how to reach it again, setting its viewport with browser_resize, by its kind: load, rescan its url with scan_url; state, reach its named state again, as the test that named it does, then rescan with scan_page; none, open its url and repeat the interaction that reached the page, then rescan with scan_page. Its verify names the rule the rescan must run and the issue ID to look for in the rescan’s result. Without run, the newest run that holds the issue in the state directory, the project’s or, outside a project, the one in the folder cora-mcp was started in, in runs/ (.cora/runs/ by default), is read, so an issue from a cora scan run can be explained too.

Arguments:

issue (string, required): The issue’s ID, as a scan’s result lists it.
run (string): The run that holds the issue, as a scan’s result names it; the newest run that holds it when absent.

Annotations: readOnlyHint: true, openWorldHint: false

Result: cora-mcp-issue, version 1

Errors: contract.wrong-format, contract.unsupported-version, contract.invalid, contract.unknown-fields, config.invalid-environment, file.unreadable, file.write-failed, mcp.unknown-issue, mcp.invalid-argument, account.missing, account.invalid, account.expired, service.client-outdated, service.unreachable, service.unavailable

get_fix_guidance

Get a rule’s fix guidance

Gives how to fix a rule’s failures in any framework: the rule in plain language, who its failures affect, and each situation the rule fails in with its fix, in Markdown, and, where it helps, the markup after the fix, in HTML. Also lists the fixes that silence the rule or look right but still fail people, and why. Takes a rule ID, as list_rules gives it, one of a scan issue’s rules, or explain_finding’s rule.id. With the project’s framework, such as react, its framework adds the rule’s fixes in that framework’s syntax where they differ from those for any framework; it is absent where they do not. Its docsUrl is the rule’s guidance page on CORA’s docs site, to show a person.

Arguments:

rule (string, required): A rule’s ID, as list_rules gives it, one of a scan issue’s rules, or explain_finding’s rule.id, such as axe/image-alt.
framework (“react”): The project’s UI framework, whose fixes the result adds in its syntax where they differ; without it, the result gives the guidance for any framework alone.

Annotations: readOnlyHint: true, openWorldHint: false

Result: cora-mcp-guidance, version 1

Errors: contract.wrong-format, contract.unsupported-version, contract.invalid, contract.unknown-fields, config.invalid-environment, file.unreadable, file.write-failed, mcp.unknown-rule, mcp.invalid-argument, account.missing, account.invalid, account.expired, service.client-outdated, service.unreachable, service.unavailable

verify_fix

Verify a fix

Checks a fix of an issue that scan_page or scan_url found, by its ID, and records the attempt. Rescans the issue’s page in the browser and viewport it was found in: a page reached by navigation is loaded again in the current tab, and one reached by interaction is scanned as the tab shows it, so reach that state again first. Set the viewport with browser_resize first when the tab’s differs. Finds the element by the selector the scan recorded or, on an app with source locations, by where its opening tag starts in the source, so a fix that changes its class or turns a div into a button is still checked. Compares the element’s accessibility-tree entry when the issue was found with its entry now, and returns the verdict: fixed; still-failing, with listedAs, the issue’s ID in the rescan, which an edit can change; suppressed when the fix hid the element from assistive technology, as with aria-hidden, display: none or an empty alt, rather than fixing it; or inconclusive, with its reason, when the rescan did not cover the rule there, the evidence is missing, the element cannot be found (as when the fix moved its tag to other lines or the tag renders several elements), or something besides a fix or hiding, such as a modal dialog over it, keeps it out of the tree. report: true says the issue the rescan still finds under listedAs has a violation of a rule the project’s config sets to report and no violation CI’s gate checks, so it never fails the gate. accepted: true says the project’s baseline accepts the issue under listedAs, so CI’s gate does not fail on it. Its next says what to do: continue fixing the issue, done, or escalate it to a person once 3 attempts have not fixed it. It carries unsettled when the rescan’s page did not settle before it was scanned, so the verdict may judge a page still changing: act on the verdict, and treat the page as unsettled, as a scan’s. A fixed verdict means the rule no longer finds the issue, not that the element is accessible.

Arguments:

issue (string, required): The issue’s ID, as a scan’s result lists it.

Annotations: readOnlyHint: false, destructiveHint: false, openWorldHint: false

Result: cora-mcp-verify, version 1

Errors: contract.wrong-format, contract.unsupported-version, contract.invalid, contract.unknown-fields, config.invalid, config.ambiguous, config.load-failed, config.invalid-environment, file.unreadable, file.write-failed, scan.unsupported-page, page.navigated, page.unresponsive, browser.not-installed, browser.launch-failed, signin.storage-state-not-found, signin.setup-failed, mcp.no-page, mcp.unknown-issue, mcp.loop-changed, mcp.loop-unreadable, mcp.invalid-argument, mcp.browser-timeout, mcp.state-unwritable, account.missing, account.invalid, account.expired, service.client-outdated, service.unreachable, service.unavailable

summarize_fixes

Summarize the fixes

Reports what became of each issue whose remediation loop is open, every issue a scan found whether or not a fix was tried, from the loop records in the state directory, the project’s or, outside a project, the one in the folder cora-mcp was started in, in loop/ (.cora/loop/ by default), and ends each loop it reports: call it last, once each fix is verified with verify_fix. Pass in fixes an entry for each issue you changed, proposed a change for or left for a person: its ID, your account of it, and the test that pins the fix when one does. Each issue gives its rule in plain language, who it affects, its WCAG success criteria or, for a best practice, that it is not a WCAG failure, report: true when it has a violation of a rule the project’s config sets to report and no violation CI’s gate checks, so it never fails the gate, accepted: true when the project’s baseline accepted it in the latest scan that compared it with the baseline, as cora scan counts it, so CI’s gate does not fail on it, its page and element, the issue’s severity, each place in the source its findings sit at and its call sites as the scan found them, your account and the test, the element’s accessibility-tree entry before and after the last fix, and links to each criterion’s Understanding page, the rule’s documentation and its guidance page. Its disposition is fixed when verify_fix last found it fixed, escalated when its loop escalated it to a person, and otherwise proposed, for a person to review the fix you propose or make the one that needs their judgement. An issue left out, for the size of the result or while a verification of it runs, keeps its loop, and omitted counts them: call again for the rest, passing their entries.

Arguments:

fixes (array of objects): An entry for each issue you changed, proposed a change for or left for a person, by any ID it has had: your account of it, and the test that pins the fix when one does.

Annotations: readOnlyHint: true, openWorldHint: false

Result: cora-mcp-summary, version 1

Errors: contract.wrong-format, contract.unsupported-version, contract.invalid, contract.unknown-fields, config.invalid-environment, file.unreadable, file.write-failed, mcp.unknown-issue, mcp.loop-unreadable, mcp.invalid-argument, mcp.state-unwritable, account.missing, account.invalid, account.expired, service.client-outdated, service.unreachable, service.unavailable

cora-mcp’s command line

An MCP entry’s args give cora-mcp these options after its package. Any other stops it with mcp.invalid-argument.

Option	Description
`--version`	print cora-mcp’s version
`--headless`	run the browser without a window, such as on a machine without a display; sets `mcp.headless`