MCP reference | a11ied

Startup

Starting the server

npx -y a11ied mcp

Configure your client to run that command over stdio. The server opens no network port and takes no options.

{
  "mcpServers": {
    "a11ied": {
      "command": "npx",
      "args": ["-y", "a11ied", "mcp"]
    }
  }
}

For a source checkout, build the workspace and copy the root mcp.example.json entry into your client's configuration. Set the client's working directory to the repository root, or use an absolute path to packages/cli/dist/cli.js.

Defaults

Every tool that takes version defaults to 2.2. The other supported value is 2.1.

Tools

MCP tools

The wcag_* tools look up the Web Content Accessibility Guidelines (WCAG), the standard most accessibility requirements come from, by success criterion. run_axe runs axe-core (axe), an open-source rules engine that checks a page against a set of automated accessibility rules. tree and audit read the page too, and the sr_* tools drive a screen reader session.

doctorReturn the a11ied, Node, and browser details and the setup state of each screen reader. Same as a1 doctor.

wcag_showReturn one criterion with its techniques, failures, test method (the testMethod object), and strategy. Set includeUnderstanding for the full Understanding document text. A technique or failure id also returns its body. Same as a1 wcag show and a1 wcag understanding.

wcag_criteriaList criteria, filtered by level or summarized. Same as a1 wcag criteria.

searchSearch the WCAG corpus and the ARIA Authoring Practices Guide together, ranked, each row labeled by kind. Same as a1 search.

wcag_ruleMap an axe-core rule id to its criteria and fix guidance. Same as a1 wcag rule.

pattern_showOne ARIA pattern from the Authoring Practices Guide, with the guide's own text for it and its examples, or one example with its keyboard and attribute tables. Omit name to list every pattern. Same as a1 pattern.

pattern_findThe examples the APG files under one ARIA role or attribute. Same as a1 pattern role and a1 pattern attribute.

run_axeRun axe-core against a target. Same as a1 axe.

treePrint the accessibility tree for a target. Same as a1 tree.

auditRun axe, the tree summary, and applicability together. Same as a1 audit.

sr_sessionStart, open, stop, or check the one active screen reader session. Same as a1 sr start, open, stop, status.

sr_actionRun one action against the active session. Covers every other a1 sr subcommand except expect, list, batch, and walk.

sr_listList the named commands sr_action's perform action runs. Same as a1 sr list.

sr_expectCheck that the session announced a phrase. Same as a1 sr expect.

sr_transcriptPrint the session transcript, or write it to a file. Same as a1 sr transcript.

a1 sr batch and a1 sr walk have no matching tool. batch reads a file of actions for shell scripting. Call sr_action once per step instead. walk composes sr_session (action start) with sr_action (action read-all) and sr_transcript. Call those three tools in that order.

Standards

wcag_show, wcag_criteria, wcag_rule, search

wcag_showcriterion required, an id such as 1.4.3, a slug such as contrast-minimum, or a technique id such as G18. Always returns the testMethod and strategy objects alongside the criterion. Set includeUnderstanding: true for the full Understanding document text and its source, the primary reference for fixing a violation.

wcag_criterialevel optional: A, AA, or AAA. Omit it to list every criterion. Set summary: true for the count of automated, hybrid, and manual criteria per level instead of the list.

searchquery required. kind scopes it to one corpus. limit defaults to 10 and caps at 50.

wcag_ruleruleId required, an axe-core rule id such as color-contrast. Returns the criteria it covers and axe's help text and help URL.

All four read bundled data. They make no network request and start no browser, so they are safe for an agent to call freely.

Page checks

run_axe, tree, audit

targetAn http(s) URL or a local file path.

htmlInline HTML markup to load instead of target.

All three take one page target, exactly like the CLI's positional <target> and --html. run_axe also takes criterion, level, or ruleIds to narrow the run, and rejects more than one of them. Omit all three, and run_axe runs every mapped rule, matching a1 axe with no filter.

audit takes level to select cumulative A, AA, or AAA coverage, and resultsFile to read the current run's manual evidence. Use the same evidence path on record_result and pattern_record calls. Supply runFile and provenance to validate the run, scoped check, states, actor, actions, and artifacts. A note alone stays unverified. For APG rows, pass the observed subjectHash and widget pointer. Keyboard rows require typed action evidence; attribute rows require scoped observations. pattern_pending requires the same run, pointer, and hash to count judgments across all queued states.

Provenance and non-image artifact envelopes include attempt from the claimed check's attempts. Evidence from another attempt is rejected.

tree takes role and name to keep only matching nodes and their ancestors. run_axe and tree take click, a selector for the one element to click after the page loads, which reaches a dialog or a menu the page renders only after a click.

run_axe and audit each return a verdict object and an exitCode. exitCode is 4, the CLI's assertion exit code, when a violation at or above failOn (default minor) is not covered by baseline, and 0 otherwise.

Pass baseline as { acceptedFindings: [...] } to accept known findings, the same list the CLI reads from a --baseline file.

audit_assessment

This tool uses the same validated coordinator as the CLI assessment commands. action selects start, state, journey, queue, next, status, resume, evaluate, block, or finalize. It sends no UI input. The host agent executes procedures and supplies observed evidence and judgments.

startRequires a structured target and observed environment. Accepts profile, scope, file, runId, inventoryPath, and actionPolicy. Defaults are WCAG 2.2 AA and site scope for web targets or app scope for desktop app targets.

state, journey, queueRequire file and the corresponding structured object. Return the saved identity and revision separately from status pagination. Invented procedures, obsolete versions, invalid scopes, and unknown APG rows are rejected before persistence.

nextRequires file. Returns one check, procedure, environment, journey, and bounded state context. Read additional status state pages by ID when needed. Concurrent claims or changed claim generations are rejected.

statusRequires file. Accepts offset and limit; defaults are 0 and 20, with a maximum of 100. Each list returns items, total, and an optional nextOffset.

evaluate, blockRequire file and checkId. Evaluate requires outcome and saved evidenceIds. Block requires a recovery reason.

resume, finalizeResume keeps interrupted checks blocked; retryCheckIds requests explicit safe retries. Finalize rejects incomplete coverage unless allowPartial is true, which preserves an active run.

{"action":"status","file":".a11ied/fireside/run.json","offset":0,"limit":20}

record_result saves validated evidence before evaluate. report_build remains separate and consumes discovery and page artifacts. A lifecycle receipt alone does not establish native reader or complete installed-audit verification.

Screen reader

sr_session and sr_action

sr_session

actionstart, open, stop, or status. Required.

target(start only) voiceover, nvda, or virtual.

allowVirtual(start only) Set to true to accept the simulated reader when a real one is available.

url(start and open) The page to load. Virtual loads it directly. VoiceOver and NVDA open it in a system browser and refocus it.

app(start only) A native app that is already open, to read instead of a page.

nativeInput(start only) Defaults to guarded: commands check the observed foreground target. Inspect returned state and speech after actions. require-binding refuses unavailable native binding; development bypasses target checks.

One session is active at a time, and start stops any session already active. The start response includes session, which has sessionId, target, and targetType. Pass sessionId to stop to retry a recovery owner named in an error, even when active-session metadata could not be published. targetType is real for VoiceOver and NVDA, and simulated for virtual. status returns { noSession: true } instead of throwing when no session is active.

sr_action

Takes the same action and payload shapes the CLI's driver runtime takes, one action per call. The portable verbs need no payload and work on every target: next, previous, interact, stop-interacting, activate, top, bottom, escape, read, transcript, and title.

next and previous take an optional payload to jump by kind: heading, link, landmark (a named region such as banner, navigation, or main), control, button, table, list, graphic, region, or form-field.

pressPayload { keys }, one chord per entry, pressed in order, such as ["Tab", "Tab"].

typePayload { text }.

checkpointPayload { label }, a named point in the transcript for the since parameter for expectations and waits.

performPayload { command, commandSet? }. Runs a named screen reader command. Call sr_list for the names.

focusPayload with one of appName, bundleId, processName, pid, or windowTitle.

findPayload { text }. Moves to the next place the text appears.

tablePayload { move }: next-cell, row-header, and the other table moves.

elementsPayload { kind, max? }. The rotor for one kind, from the top of the page.

read-allPayload { max? }. Say-all as a transcript from the cursor.

gotoPayload { role?, name?, max? }. Steps forward until the item matches.

waitPayload { for?, since?, ms?, timeoutMs? }. Polls the transcript for a phrase.

screenshotPayload { path }. VoiceOver cursor only.

find, goto, and wait add exitCode to the result: 4 when the search or wait did not match, matching a1 sr find, goto, and wait, and 0 otherwise.

Every response's state includes the timestamped transcript so far. A VoiceOver session's state also includes axFocusedElement: the accessibility role, subrole, title, description, value, and enabled state of the element system keyboard focus is on.

Checks

sr_list, sr_expect, sr_transcript

sr_listquery, sr, and commandSet all optional. Start with query. The unfiltered list is over 400 entries.

sr_expectpattern required, text (case-insensitive) or /regex/flags. since limits the check to phrases after a checkpoint. not passes when the phrase was NOT announced.

sr_transcriptsince, tail, afterIndex, limit, out, and format are optional. Index paging defaults to 200 entries. transcript.window reports omitted entries and the next index. out also writes the transcript to a .json or .md path.

sr_expect returns exitCode 4 (the CLI assertion exit code) and a message when the phrase did not match, and 0 when it did.

Assertion pattern

Move the session with sr_action, then call sr_expect to check what was announced. This is the same pattern the agent skill's screen reader recipe uses.

Resources

Read-only resource URIs

a11ied://targetsThe supported target list.

a11ied://wcag/criteria/2.2The criteria index for a version.

a11ied://wcag/levels/2.2Level to criteria lists for a version.

a11ied://wcag/test-methods/2.2The test method (method) and mapped rule ids for every criterion in a version.

The three versioned resources are registered for both 2.1 and 2.2, which makes seven resources in total. All return application/json.

Side effects

Side effects by tool

wcag_show, wcag_criteria, wcag_rule, search, pattern_show, pattern_find

Read local files. wcag_rule also reads the installed axe-core package for help text.

run_axe, tree, audit

Open the target in browser automation.

doctorReads prerequisites for the requested task. Reader checks inspect settings; recording checks run only when requested.

The sr_* tools change the state of the machine. A real session puts VoiceOver or NVDA under automation control until the client calls sr_session with action: "stop".