Tactual MCP server
✓ VerifiedMeasures screen-reader navigation cost by calculating the keystrokes required to discover and operate interactive elements on a webpage.
Also known as tactual-dev/tactual
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.2.1
- Last commit
- Jun 28, 2026
- License
- Apache-2.0
What is Tactual MCP?
Tactual measures screen-reader navigation cost by calculating the keystrokes required to discover and operate interactive elements on a webpage.
Summary generated from the project's README
About Tactual MCP server
Developers who need to quantify the accessibility experience of screen-reader users can use Tactual to measure navigation cost. Instead of just checking if ARIA attributes are correct, this tool calculates the exact number of keystrokes required to discover and operate interactive elements like buttons, menus, and form fields. It works by capturing Playwright accessibility snapshots and simulating announcements for specific assistive technology profiles including NVDA, JAWS, and VoiceOver.
You can run Tactual locally via the CLI, integrate it into your CI pipelines, or use it through an MCP server within your editor. It provides deep probing capabilities to explore hidden UI branches such as dialogs, tabs, and disclosures. The tool generates navigation graphs and scores targets based on how efficiently they can be reached. It also supports comparing analysis results between different versions of a site to verify that accessibility improvements actually reduce the effort required for users to complete tasks.
What you can do with it
- 1Simulate screen-reader announcementsPredict exactly what a user would hear when navigating through form fields or landmarks.
- 2Explore complex UI componentsProbe hidden interactive elements like menus and dialogs to ensure they are reachable via keyboard.
Written from the project's README. Every use case is checked against a quote from it.
How to install Tactual MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Tactual MCP in Claude Code
$ claude mcp add tactual -- npx -y tactualInstall Tactual MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"tactual": {
"command": "npx",
"args": [
"-y",
"tactual"
]
}
}
}Install Tactual MCP in VS Code
.vscode/mcp.json
{
"servers": {
"tactual": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"tactual"
]
}
}
}Install Tactual MCP in VS Code CLI
$ code --add-mcp '{"name":"tactual","type":"stdio","command":"npx","args":["-y","tactual"]}'Install Tactual MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"tactual": {
"command": "npx",
"args": [
"-y",
"tactual"
]
}
}
}Install Tactual MCP in Codex
$ codex mcp add tactual -- npx -y tactualInstall Tactual MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.tactual] command = "npx" args = ["-y", "tactual"]
Install Tactual MCP in Gemini CLI
$ gemini mcp add -s user tactual npx -- -y tactualInstall Tactual MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"tactual": {
"command": "npx",
"args": [
"-y",
"tactual"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabletactual-dev/tactual is public and reachablegithub.com/tactual-dev/tactual ↗Pass
- Package names this repository as its sourcetactual names tactual-dev/tactual as sourcenpmjs.com/package/tactual ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-06-28github.com/tactual-dev/tactual ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from tactualPass
- No critical advisory in the package or its dependencies3 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTactual
Screen-reader navigation cost analyzer. Measures how many keystrokes a screen-reader user needs to discover, reach, and operate every interactive target on your page — under a specific AT profile (NVDA, JAWS, VoiceOver).
What it does
Existing accessibility tools check conformance — is the ARIA correct? Is the contrast ratio sufficient?
Tactual measures navigation cost — how many actions does it take a screen-reader user to reach the checkout button? What happens if they overshoot? Can they even discover it exists? Does the menu actually open on Enter, or only on click? Does focus land on the first menuitem or stay stuck on the trigger?
How it works:
- Captures Playwright accessibility snapshots + screen-reader announcement simulation
- Optionally explores hidden branches (menus, dialogs, tabs, disclosures) and probes them with real keyboard events, including APG-style widget contracts and form-error flows
- Builds a navigation graph with entry points (landmarks, headings, linear Tab) and scores every target
- Optionally validates predicted paths against
@guidepup/virtual-screen-readerfor calibration
Tactual is a developer tool for analyzing your own sites and staging environments. Run it locally, in CI, or via the MCP server in your editor. It is not a public scanning service.
How it fits
Tactual complements conformance scanners such as axe-core, Lighthouse, and Pa11y. Those tools are still the right first pass for broad WCAG and ARIA rule coverage. Tactual is aimed at the next question: after a page has valid markup, how expensive is it for an AT user to discover, reach, and operate the important targets?
Use Tactual for screen-reader navigation-cost triage, path tracing, measured keyboard/widget evidence, before/after diffs, CI prioritization, and MCP workflows where an agent needs compact findings with source selectors and remediation candidates. Use real screen readers and manual testing for final validation of critical journeys, timing-sensitive flows, browser/AT settings, and implementation patterns that intentionally differ from a common APG example.
Agent quick path: this README is a product overview plus reference. Agents should start with docs/AGENT-RECIPES.md for task patterns and docs/MCP-TOOLS.md for full MCP schemas, then come back here only for product context, install notes, and release-surface examples.
Install
Requires Node.js 20 or later.
npm install tactual
Tactual installs Playwright as a runtime dependency so one-off npx tactual@latest ... commands work without separately installing Playwright into the npx cache. The MCP SDK also ships as a runtime dependency, so tactual-mcp works from an installed tactual package without a separate SDK install.
Quick start
CLI
# Analyze a URL (default profile: generic-mobile-web-sr-v0)
npx tactual analyze-url https://example.com
# Analyze with a specific AT profile
npx tactual analyze-url https://example.com --profile voiceover-ios-v0
# Explore hidden UI (menus, tabs, dialogs, disclosures)
npx tactual analyze-url https://example.com --explore
# Use a scoring preset for your use case
npx tactual analyze-url https://shop.com --preset ecommerce-checkout
npx tactual analyze-url https://docs.example.com --preset docs-site
# Output as JSON, Markdown, or SARIF
npx tactual analyze-url https://example.com --format json --output report.json
npx tactual analyze-url https://example.com --format sarif --output report.sarif
# Compare two analysis runs
npx tactual diff-results baseline.json candidate.json
npx tactual diff-results baseline.json candidate.json --format json
# Print what NVDA would say as you Tab through the page
npx tactual transcript https://example.com
npx tactual transcript https://example.com --at voiceover
# List available AT profiles and scoring presets
npx tactual profiles
npx tactual presets
# Run benchmark suites
npx tactual benchmark
npx tactual benchmark --suite all
Benchmark fixtures ship with the npm package, so the benchmark command works from a fresh install and does not require cloning the repository fixtures into your current directory.
# Validate predicted paths against a virtual screen reader (reachability + step count)
# Requires optional deps, installed by default with tactual
npx tactual validate-url https://example.com --max-targets 10 --strategy semantic
# Initialize a tactual.json config file
npx tactual init
# Analyze a bot-protected site with stealth + real Chrome
npx tactual analyze-url https://www.npmjs.com/ --stealth --channel chrome
# Deep keyboard probing including revealed widgets and form-error flows
npx tactual analyze-url https://docs.example.com --probe --explore --probe-mode deep
# Focus probing on one opened branch, such as a dialog trigger
npx tactual analyze-url https://app.example.com/settings \
--probe \
--entry-selector "[aria-controls='profile-dialog']" \
--probe-strategy modal-return-focus
# Analyze + inline virtual-SR validation in one command (predicted vs validated steps)
npx tactual analyze-url https://example.com --validate --validate-max-targets 10
Console output includes a compacted path line for each finding showing how a screen-reader user reaches it:
██████░░ 70 link:reference structural
D:47 R:71 O:100 Rec:100
getByRole('link', { name: 'Reference' })
↪ Tab ×2 "v19.2" → K "Learn" → Tab "Reference"
→ Target is not efficiently reachable via heading or landmark navigation
Where Tab = nextItem, H = nextHeading, ; = nextLandmark, K = nextLink, B = nextButton, Enter = activate. Consecutive same-action steps collapse (Tab ×2).
From Audit to Fix
For accessibility work in a local app or preview environment, Tactual supplies evidence for small, reviewable changes:
selector,penalties,suggestedFixes, and evidence summaries on each finding- grouped
issueGroupsand remediation candidates in summarized output analyze_pages.site.repeatedNavigationfor repeated navigation cost across routesdiff-results/diff_resultsfor before-and-after verification
Start with broad triage, then deepen one route before changing code:
# Site-level triage. Redirect JSON for tool consumption.
npx tactual analyze-pages \
https://app.example.com/ \
https://app.example.com/docs \
https://app.example.com/settings \
--profile nvda-desktop-v0 \
--format json > tactual-site.json
# Deepen one route and produce a reviewable markdown report.
npx tactual analyze-url https://app.example.com/docs \
--profile nvda-desktop-v0 \
--explore --probe --probe-mode standard \
--format markdown --output tactual-report.md
# When one branch is the target, open it first and spend probe budget there.
npx tactual analyze-url https://app.example.com/docs \
--profile nvda-desktop-v0 \
--probe \
--entry-selector "[aria-controls='search-panel']" \
--probe-selector "#search-panel" \
--probe-strategy composite-widget \
--format markdown --output tactual-search-panel.md
# Save a baseline before editing, then verify the patch.
npx tactual analyze-url https://app.example.com/docs --explore --probe --format json --output baseline.json
# Edit one root cause in the local repo, rebuild/restart the preview, then re-run:
npx tactual analyze-url https://app.example.com/docs --explore --probe --format json --output candidate.json
npx tactual diff-results baseline.json candidate.json
Use the candidate section as a starting point for repeated root causes such as a shared component, navigation pattern, or widget contract. Confirm the source component and include the route, command, finding evidence, user impact, code change, and verification in whatever issue or PR format the project expects. Score movement is useful supporting evidence, but the change should lead with the accessibility behavior that changed.
MCP clients can consume the same compact output and keep the review loop grounded in routes, selectors, evidence, source changes, and before/after verification.
Library API
import { analyze, getProfile } from "tactual";
import { captureState } from "tactual/playwright";
import { chromium } from "playwright";
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("https://example.com");
const state = await captureState(page);
await browser.close();
const profile = getProfile("generic-mobile-web-sr-v0");
const result = analyze([state], profile);
for (const finding of result.findings) {
console.log(finding.targetId, finding.scores.overall, finding.severity);
}
Screen-reader announcement simulator — predict what NVDA, JAWS, or VoiceOver would announce for every target, with state info (checked, expanded, selected, modal, value, required, invalid, etc.):
import {
simulateScreenReader,
buildAnnouncement,
buildMultiATAnnouncement,
buildTranscript,
} from "tactual/playwright";
const report = await simulateScreenReader(page, state.targets);
for (const a of report.formFields) {
console.log(a.announcement);
// → "Subscribe, check box, checked"
// → "Country, combo box, collapsed"
// → "Email, edit, invalid entry, required, you must use a work address"
}
// Compare across screen readers
const tx = state.targets[5];
buildAnnouncement(tx, "nvda"); // → "Country, combo box, collapsed"
buildAnnouncement(tx, "voiceover"); // → "Country, popup button"
// All three at once
buildMultiATAnnouncement(tx);
// → { nvda: "...", jaws: "...", voiceover: "..." }
// Linear navigation transcript — what an SR user hears Tabbing through
const transcript = buildTranscript(state.targets, "nvda");
// → [{ step: 1, kind: "landmark", announcement: "Main, main landmark" }, ...]
// Multi-target navigation modes (linear, by-heading, by-landmark, by-form-control)
import { buildNavigationTranscript } from "tactual/playwright";
// Heading-only navigation (NVDA: H key)
const headings = buildNavigationTranscript(state.targets, { mode: "by-heading" });
// Navigate from one element to another
const path = buildNavigationTranscript(state.targets, {
from: "link:before-main",
to: "heading:welcome",
mode: "linear",
});
// Demoted landmarks (in DOM but stripped by HTML rules, e.g. <header> in <section>)
for (const d of report.demotedLandmarks) {
console.warn(d.demotionReason);
}
Validation and calibration APIs — compare model output against virtual-SR validation runs or human-observation datasets:
import { validateFindingsInJsdom } from "tactual/validation";
import { runCalibration, formatCalibrationReport } from "tactual/calibration";
// Given a JSDOM instance, PageState, AnalysisResult, and calibration dataset:
const validation = await validateFindingsInJsdom(dom, state, result.findings, {
maxTargets: 10,
strategy: "semantic",
});
const calibration = runCalibration(dataset, new Map([[state.url, result]]));
console.log(validation, formatCalibrationReport(calibration));
Or from the CLI:
npx tactual transcript https://example.com --at voiceover
npx tactual calibration-report my-calibration.json --analysis example-nvda.json
The simulator is heuristic prediction, not real screen-reader output. The simulator itself is fast (pure JavaScript over captured targets — sub-second once targets are in memory), but a full analyze-url run includes browser launch + page capture + scoring and takes seconds on small pages, longer with --probe (~30s+) and --explore (~1–5 min on complex SPAs). Analysis runs in a headless browser by default, so nothing pops up while you work. (Use --no-headless or --channel chrome --stealth for visible/bot-protected sites.)
Data quality. Calibrated against token-level assertions from the W3C ARIA-AT project: 77/77 role/name/state-token assertions pass at 100% across all three ATs (NVDA, JAWS, VoiceOver), covering role/name/state phrasing for 36 single-target patterns (button, toggle button, all menu button variants, disclosure, accordion, checkbox/tri-state, switch, sliders, dialog, alert, links, tabs, comboboxes, radiogroups, spin button, menubar) plus 4 multi-target landmark scenarios. Run npm run calibrate after npm run build to verify against the latest upstream assertions. This is simulator calibration, not proof of full screen-reader fidelity across browse modes, verbosity settings, timing, or every valid widget variant. AT-specific overrides outside the calibrated set are labeled HIGH/MEDIUM/LOW confidence in the source.
MCP Server
Tactual includes an MCP server for AI agent consumption:
# Start the MCP server (stdio transport — default)
npx tactual-mcp
# Start with HTTP transport (for hosted platforms, remote clients)
npx tactual-mcp --http # listens on http://127.0.0.1:8787/mcp
npx tactual-mcp --http --port=3000 # custom port (or set PORT env var)
npx tactual-mcp --http --port 3000 # space-separated form is also supported
npx tactual-mcp --http --host=0.0.0.0 # bind to all interfaces (default: 127.0.0.1)
For network-facing MCP deployments, put the HTTP transport behind an authenticated TLS proxy and keep it scoped to trusted clients. See SECURITY.md for the hosted checklist and threat model.
MCP tools available:
| Tool | Description |
|---|---|
analyze_url |
Analyze a page for SR navigation cost (SARIF default). Supports opt-in exploration, keyboard/widget/form probes, scoped/goal-directed probing, stealth/channel for bot-protected sites, and filtering. |
trace_path |
Step-by-step navigation path to a target with modeled SR announcements. |
validate_url |
Validate predicted paths against @guidepup/virtual-screen-reader. Returns reachable + mean accuracy per strategy (linear/semantic). Closes the predicted-vs-validated loop. |
calibration_report |
Run observed calibration datasets against saved full analysis JSON and return structured scoring signals for tuning/review workflows. |
list_profiles |
List available AT profiles. |
diff_results |
Compare two analysis results — improvements, regressions, severity changes. |
suggest_remediations |
Ranked fix suggestions by impact. |
save_auth |
Authenticate and save session state for analyzing protected content. |
analyze_pages |
Multi-page site triage with aggregated stats and repeated navigation-cost groups across pages. |
Full parameter reference: docs/MCP-TOOLS.md
Setup by AI tool
First install the required packages in your project:
npm install tactual
Claude Code — add to .mcp.json in your project root:
{
"mcpServers": {
"tactual": {
"type": "stdio",
"command": "npx",
"args": ["tactual-mcp"]
}
}
}
GitHub Copilot — add to .copilot/mcp.json or ~/.copilot/mcp-config.json:
{
"mcpServers": {
"tactual": {
"type": "stdio",
"command": "npx",
"args": ["tactual-mcp"]
}
}
}
Cursor / Windsurf / Cline — same format in your editor's MCP config:
{
"mcpServers": {
"tactual": {
"command": "npx",
"args": ["tactual-mcp"]
}
}
}
Direct (global install) — if you prefer not to use npx:
npm install -g tactual
tactual-mcp # starts the MCP server on stdio
GitHub Actions
Use the composite action from the GitHub Actions Marketplace:
jobs:
a11y:
runs-on: ubuntu-latest
permissions:
security-events: write # for SARIF upload
pull-requests: write # for comment-on-pr
steps:
- name: Analyze accessibility
uses: tactual-dev/tactual@v0.5.0
with:
url: https://your-app.com
profile: nvda-desktop-v0
explore: "true"
probe: "true"
probe-mode: standard
fail-below: "70"
comment-on-pr: "true"
The action installs Tactual and Chromium browser binaries, runs the analysis, uploads SARIF to GitHub Code Scanning, and fails the build if the average score is below the threshold. Set comment-on-pr: "true" to post a summary comment on pull requests (updates on re-run). Outputs average-score and result-file for downstream steps. Action version tracks Tactual version — bump the uses: line to pick up patches.
Defaults are conservative: probe is off unless enabled because it sends real keyboard events, and forced-colors icon checks run only for profiles that declare visualModes such as nvda-desktop-v0 and jaws-desktop-v0.
Or use the CLI directly for more control:
- name: Install Tactual
run: npm install tactual
- name: Install browsers
run: npx playwright install chromium --with-deps
- name: Run accessibility analysis
run: npx tactual analyze-url https://your-app.com --format sarif --output results.sarif --threshold 70
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
Regression gate (CI fail on worse-than-baseline)
Pair --baseline with --fail-on-regression to turn Tactual into a strict CI gate: save a baseline from a known-good build, then fail PR checks whenever a change regresses N+ findings vs the baseline. The diff-results command can also be run separately for human-readable before/after reports.
# One-time: snapshot main as the baseline
- name: Snapshot baseline
if: github.ref == 'refs/heads/main'
run: |
npx tactual analyze-url https://preview.your-app.com \
--format json --output tactual-baseline.json
- name: Upload baseline
if: github.ref == 'refs/heads/main'
uses: actions/upload-artifact@v4
with:
name: tactual-baseline
path: tactual-baseline.json
# On PRs: compare against the baseline, fail on regressions
- name: Fetch baseline
uses: actions/download-artifact@v4
with:
name: tactual-baseline
- name: Analyze + gate on regressions
run: |
npx tactual analyze-url https://pr-preview-${{ github.event.number }}.your-app.com \
--format sarif --output results.sarif \
--baseline tactual-baseline.json \
--fail-on-regression 3 # fail if 3+ findings regressed
Or via the action:
- uses: tactual-dev/tactual@v0.5.0
with:
url: https://pr-preview.your-app.com
baseline: tactual-baseline.json
fail-on-regression: "3"
The action mirrors the analyze-url CLI surface for analysis inputs, and a CI-to-CLI contract test keeps those fields aligned. Some workflow controls are Action orchestration rather than direct CLI flags: fail-below wraps CLI --threshold, comment-on-pr controls the PR comment step, and SARIF upload is handled by the workflow. The common inputs you'll set include profile, explore, explore-depth, explore-budget, explore-timeout, probe, probe-mode, probe-strategy, scope-selector, probe-selector, entry-selector, goal-target, goal-pattern, stealth, channel, wait-for-selector, exclude, exclude-selector, focus, min-severity, max-findings, baseline, fail-on-regression, fail-below, validate, storage-state, summary-only. The direct-CLI invocation pattern above is still the recommended path when you want a different Tactual version than the action pins.
| Surface | Naming convention | Example |
|---|---|---|
| CLI | kebab-case flags | --probe-strategy modal-return-focus |
| MCP and library options | camelCase fields | probeStrategy: "modal-return-focus" |
| GitHub Action | kebab-case inputs | probe-strategy: modal-return-focus |
Configuration
Tactual MCP questions
How do I add Tactual MCP to Claude Code?
Run claude mcp add tactual -- npx -y tactual in your terminal. Add --scope user to make it available in every project.
How do I add Tactual MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does Tactual differ from tools like axe-core or Lighthouse?
While tools like axe-core check for ARIA conformance and contrast, Tactual measures navigation cost, such as how many actions it takes a user to reach a specific button.
Does Tactual provide screen-reader announcements?
Yes, it can simulate and predict what NVDA, JAWS, or VoiceOver would announce for every target on a page.
Is Tactual a public scanning service?
No, it is a developer tool intended for use on your own sites and staging environments, which can be run locally, in CI, or via MCP.