com.overlayqa由 overlayqa.com 发布官方发布者v0.7.0更新于 Oct 30, 2026
Run accessibility, contrast, and design token audits and file QA issues from your AI coding tool.
OverlayQA MCP 让 AI 编程助手对公开网址做无障碍、对比度和设计令牌审计，并在 OverlayQA 项目中创建、讨论和验证 QA 问题。
Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。
把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体，或 SourceWeft 对话中。智能体会读取该服务器的安装指南，先向你展示发布者、端点和登录方式，经你同意后再把它添加到你的客户端。密钥不会写进任何命令。
阅读 https://sourceweft.com/mcp/com.overlayqa%2Fmcp/install.md，并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前，先告诉我它的发布者、端点和登录方式，等我确认。不要把 API 密钥写进命令或我会提交的文件；问我密钥应从哪里获取。把它添加到你客户端的 mcpServers 配置中。 客户端会在首次连接时完成 OAuth 登录。
{
"mcpServers": {
"overlayqa": {
"type": "http",
"url": "https://api.overlayqa.com/mcp"
}
}
}[Install in Cursor] [Install in VS Code] [npm] [license] [MCP]
OverlayQA MCP is a Model Context Protocol server that gives your AI coding agent accessibility and design-QA superpowers. Ask Claude Code, Cursor, or Windsurf to audit any URL for WCAG and color-contrast issues, then read, assign, discuss, label and resolve issues in your OverlayQA projects without leaving your editor.
One click:
Or add it to your editor's MCP config manually:
Claude Code (.mcp.json in your project root) / Cursor (~/.cursor/mcp.json) / Windsurf (~/.codeium/windsurf/mcp_config.json):
Any MCP-compatible client works the same way. On first run a browser tab opens to connect your OverlayQA account (free, no card): pick the workspace, allow access, and the connection lasts 30 days. Credentials cache at ~/.overlayqa/auth.json; the access token is short-lived and refreshes in the background. Disconnect an editor at any time from Connected AI apps in the dashboard (app.overlayqa.com/mcp/connect).
Tools your agent can call. Each is written so the model picks the right one from natural language.
Audit
File and manage issues
AI review workflows
Both start tools require projectId, a public url, and a new UUID requestId. They return a jobId immediately. Read it with get_review_result until complete or failed. Reuse the same request ID and inputs after a lost response; do not start another review just to read its result. Reviews use your scan allowance and do not automatically file issues. Visual comparison captures at the design’s authored width and returns AI findings, not a deterministic pixel-difference CI verdict.
Every tool also accepts an optional context argument: one sentence on why the agent is calling it. OverlayQA records that sentence, the tool name, your account, project and issue ids, counts and scores, the URL a scan runs on, and your editor's name and version (from the MCP handshake) as product analytics. The sentence is capped and stripped of email addresses and credential-like strings before it is stored. Nothing else travels: not your conversation, not your code, not the tool's replies. Full detail: overlayqa.com/privacy.
Which editors does it work with? Claude Code, Cursor, Windsurf, and any MCP-compatible client (it speaks standard stdio MCP).
Is it free? Yes to start: 3 accessibility/contrast scans per day with no card. A 14-day trial raises that to 30 scans per day and unlocks issue and project creation. After that, creating issues and projects needs a paid plan (Pro has unlimited scans).
What does it actually scan? Any public URL. Accessibility uses axe-core mapped to WCAG success criteria; contrast checks foreground/background ratios and returns the failing element pairs.
Do I need an account? Yes, a free OverlayQA account. On first run a browser tab opens to connect it; the connection lasts 30 days and can be disconnected from the dashboard at any time.
Does it work with the OverlayQA Chrome extension? Yes. The MCP server and the extension share the same projects and issues, so anything you file from your editor shows up in the extension and the dashboard, and vice versa.
The MCP server is one way into OverlayQA. The Chrome extension is the other: click any element on a live page and it captures a screenshot plus the CSS, DOM, and metadata into a dev-ready issue in seconds, and runs AI accessibility and design-system audits right on the page. Same projects, same issues, shared with this server.
MIT
Use list_labels with a project UUID to see that workspace's labels and your permissions. create_label creates a reusable label; set_issue_label applies or removes it from one issue without changing its other labels or text. Workspace owners and admins can use rename_label and delete_label; deletion removes the label's assignments, not its issues. list_issues accepts labelIds (match any), including unlabeled. Shared reports preserve the names present when shared.
Local verification can set OVERLAYQA_API_BASE and an isolated OVERLAYQA_AUTH_FILE; neither changes the default production endpoint or normal saved login.
Requires the matching issue-parity API deployment. Existing scans and status updates remain compatible with 0.2.0.
For mentions, use @[userId] in the text and include the same ID in mentionedUserIds. Comment creation requires a UUID requestId: reuse it when retrying that same submission after a lost response, so a retry does not post twice. Attachments are base64 bytes with filename and MIME type, up to ten PNG/JPG/PDF files and 10 MiB total per comment.
list_issues defaults to all states for compatibility. Use state: "active" for open/in-progress issues that are not ignored. finished includes resolved/verified/closed issues that are not ignored; ignored selects the independent ignore flag. All supplied filters intersect. Pages start at 1 and contain up to 100 issues; an empty filtered page is not a complete-project result unless hasMore is false.
To poll for new feedback, pass createdAfter with the createdAt of the newest issue you have already seen (an ISO-8601 time with a zone, such as 2026-10-05T22:00:00Z); only issues created after it come back. pageUrl narrows the list to one page and ignores the query string. Each listed issue carries source (client means a reviewer filed it on a share link), commentCount, lastCommentAt and lastCommentBy (reviewer or team), so an issue still needs a reply when source is client and commentCount is 0, or lastCommentBy is reviewer. If the server has not been updated for a filter yet, the tool answers FILTER_NOT_SUPPORTED instead of an unfiltered list.
The label tools listed above were included in 0.3.0. The later review workflows, client review tools and scheduled reviews are described below and require their matching server updates. Saved-design discovery is not included.
Run npm test and npm run build. The live journey drives the built client over the real stdio protocol against a local API or production using designated fixture accounts; it creates and removes its own projects and produces JSON and HTML evidence.
Release order: deploy and verify the server endpoints, then publish npm 0.3.0 and update the MCP registry. A local build or version bump is not a publication.
verify_issue({ issueId, requestId }) runs the same fix-verification engine as the dashboard on the issue’s saved public URL. The issue must be resolved, verified, or closed, have original screenshot evidence, and have a verifiable type (General and Improvement cannot be checked). Use a new UUID for each check; reuse that UUID only when retrying the same request after a lost response. Verification uses the workspace’s existing permissions and verification allowance and follows the server rollout setting.
The result contains a saved check ID, verdict, explanation, confidence, after-screenshot URL, capture context, and timestamps. A check can pass, pass with a caveat, fail, be inconclusive, or report an error. It never updates issue status. Inspect the evidence before deciding whether to change status with update_issue. Private or localhost pages require the browser extension’s signed-in capture.
get_issue_verifications({ issueId }) reads the latest 50 saved checks, newest first, without running another check. get_issue also includes latestVerification, or null when none exists. On an older server, an absent field means this capability has not been deployed; it does not mean the issue has never been checked.
list_issues accepts notDetected: true for issues flagged “No longer detected”, or false for issues without that flag (including issues never checked). It combines with status, state, page and other filters before pagination. The returned notDetectedAt and lastDetectedAt timestamps describe scan detection, not proof of a fix. A server that ignores this filter is refused as FILTER_NOT_SUPPORTED.
These additions need the matching server deployment before the client release. Both local and hosted MCP offer verification and saved history; hosted verification needs scan and write permission. This change does not enable verification in production.
These tools require the matching server deployment before publishing this client. The guest-options database migration must be applied before deploying that server. They are available on local and hosted MCP connections and use the app's project permissions.
Creating a public link requires the user's intent to share. Adding email addresses requires their intent to invite those people. A new address may receive an invitation and automatic day 3/7/10 reminders. Read invitationsEnabled and the returned per-address invites: when delivery is off, addresses are saved with sent: false, skipped: true and may be invited after it is enabled. One failed invitation does not undo the link or successful invitations.
The list returns doneReviewers and clients with email, invitedAt, inviteFailed, lastReminderAt, done, commented, and unsubscribed. Done reviewing means a client finished giving feedback; it does not certify fixes or mean everyone is done. Only the client can perform that gesture. Reminder timing and stop conditions remain owned by the existing scheduler; there is no MCP send-now tool.
After an uncertain recipient-update response, retry the same complete list and reopen it; retained addresses are not invited twice. Creating a review does not have a retry key: after a lost response, use list_client_reviews to check for the saved link before creating another. Project viewers and read-only hosted connections can read progress but cannot change links or invite people.
These tools require the matching server update. create_review_issues shares the Auto Review/visual-comparison rollout gate.
Exports support Jira, Linear, Asana, Trello, Notion, ClickUp, GitHub and Basecamp through the product's existing adapters. Destination fields are required; the client never chooses the first project or list. Notion lists the database retained at connection, without arbitrary database search. An already-exported issue keeps its original destination. Images, discussion, and supported field synchronization follow the same provider limits as the app; a stored sync timestamp is not proof of a fresh round trip.
Example: call list_export_destinations with { "provider": "trello" }, then list boards and lists for the chosen board. Pass both boardId and listId in export_issues.destination. Scheduling future scans and sharing issues require the user's request. After uncertain results, read saved state before starting new work.
来源：README.md，提交 9470d4f
File selected findings from your completed MCP Auto Review or visual comparison in its original project. Preserves saved images, page, captured context and fix guidance without scanning again. Repeating the same job and indexes recovers existing issues; inspect every finding outcome for partial completion. Old jobs without retained page provenance cannot be filed.
jobId必填contextfindingIndexes必填List readable scheduled reviews in this workspace, including cadence, pause state, next run and latest saved result summary. Does not scan or send email.
contextCreate a recurring public-page review with the same plan limits and cadence as the dashboard. Enables future scans and review emails. A lost response can be recovered by listing schedules; the same project, page and scan type cannot have duplicate schedules.
url必填cadence必填contextscanType必填projectId必填confirmLoginPagePause, resume, or change a scheduled review cadence. Supply exactly one of action or cadence. Resuming enables future scans and review emails; plan and project permissions still apply. Pausing keeps previous results.
actioncadencecontextscheduleId必填Delete a scheduled review and stop its future scans and emails. Does not delete filed project issues.
contextscheduleId必填Run an active scheduled review now using its existing settings and the dashboard run-now path. Uses scan resources; Run now does not send email. Request IDs and run results are retained for 24 hours. Reuse requestId after a lost response; poll the saved run with the same scheduleId and requestId. Does not resume paused schedules.
contextrequestId必填scheduleId必填Read the latest retained scheduled-review findings and evidence without rescanning, or poll a specific run by requestId. An empty result before the first successful run is not a clean scan. No longer detected, ignored and already filed are not proof that an issue was fixed.
contextrequestIdscheduleId必填List your connected issue trackers and reconnect requirements without exposing credentials. A connection does not prove export delivery or working two-way sync. Connect or reconnect in OverlayQA first.
contextDiscover and read destination choices for a connected tracker. Omit collection to learn its available collections and required parameters. Read choices before exporting; use schema collections for required destination fields. Does not create tasks or connect accounts.
cloudIdcontextparentIdprovider必填accountIdcollectionissueTypeIdExport existing issues with their captured evidence and discussion to an explicitly chosen connected tracker destination. Uses the same product export and retry handlers. Inspect every result: pending or partial attachment delivery is not success. Read the saved export status after uncertain outcomes before retrying.
contextissueIds必填metadataprovider必填destination必填Read persisted export destinations, attachment delivery and the latest recorded sync success/error for an issue. Does not contact trackers or force a sync. Missing or stale sync evidence is not proof of a current round trip; unsupported fields are reported.
contextissueId必填Run an accessibility audit on a URL. Returns WCAG violations with severity, descriptions, and an overall score. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
url必填contextprojectIdRun a color contrast audit on a URL. Returns elements failing WCAG contrast ratios with severity and details. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
url必填contextRun an accessibility scan on a URL and automatically create issues in the given project for each violation at or above the minimum severity. Returns scan summary + issue IDs created. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
url必填contextprojectId必填minSeverityStart AI visual comparison of a public page against a Figma frame, saved design or uploaded image. Supply reference, or both figmaFileKey and figmaNodeId. Captures at the design’s authored width. Optional measureSpacing adds supported element measurements and tolerances. Uses your scan allowance and returns a persistent job ID; results include individual differences and screenshot evidence. Does not create issues or provide a deterministic pixel-difference build gate.
url必填contextprojectId必填referencerequestId必填figmaNodeIdfigmaFileKeymeasureSpacingStart Auto Review of a public page in a readable project. Uses your scan allowance and the project’s review settings, ignored findings and already-filed issues. Returns a persistent job ID; results include findings, scores, AI status and screenshot evidence. Does not create issues. Login-required pages need the browser extension.
url必填contextviewportprojectId必填requestId必填breakpointLabelRead a previously started review without starting or charging for another run. Returns running progress, failed details, or the complete Auto Review or visual-comparison findings and evidence. Results are retained for 24 hours by default and require access to the original project and workspace.
jobId必填contextAudit a live URL's design-system token usage. Returns a 0-100 token-health score plus findings (inconsistent font sizes, text colors, spacing, font families, border radii) with severity and evidence. Audits the live page only; the figmaFileKey argument is accepted but Figma comparison is not yet available via MCP.
url必填contextfigmaFileKeyCreate an issue in an OverlayQA project. Title is required; severity, type, and description default to medium / general / empty. Assignee defaults to you; pass null for Unassigned.
typetitle必填contextseverityprojectId必填assigneeIddescriptionList project issues with labels, description, ownership and ignored state. notDetectedAt records when a scan stopped detecting the issue; lastDetectedAt records a detection. Neither proves a fix. Use notDetected to filter the flag. Filter by status, severity, type, labels, assignee, creator, page (pageUrl), or active/finished/ignored state, and use createdAfter to ask only for issues newer than the last one seen. Each issue carries source (client means a reviewer filed it on a share link), commentCount, lastCommentAt and lastCommentBy (reviewer or team): an issue still needs a reply when source is client and commentCount is 0, or lastCommentBy is reviewer. Returns page, pageSize, total and hasMore; continue to the next page while hasMore is true. Use get_issue for full capture evidence and the discussion.
pagetypestatestatuscontextpageUrllabelIdspageSizeseverityprojectId必填assigneeIdcreatedById另有 2 个Update issue status, title, description, severity, type, assignee, or ignored state. Only supplied fields change. Use null to unassign and ignored=false to restore. Accepts UUID or display id. Status verified does not run a verification scan. Use verify_issue to check a deployed fix, then inspect its evidence before deciding whether to change status.
typetitlestatuscontextignoredissueId必填severityassigneeIddescriptionRead a complete issue by UUID or display id: description, labels, assignee, ignored state, screenshot URLs, captured element/CSS and viewport evidence, its comments (the same discussion list_comments returns), and latestVerification (the newest saved check, or null). Read get_issue_verifications for history; issue status and notDetectedAt alone do not prove a fix.
contextissueId必填List workspace teammates for a readable project. Use their userId for assignment and comment mentions. Returns the signed-in userId too.
contextprojectId必填Move an issue into another project in the same workspace, preserving its identity, comments and evidence. Requires write access to both projects. Returns its new display id; use that id afterward.
contextissueId必填targetProjectId必填Check whether a resolved, verified, or closed issue is fixed on its public page. Uses the existing capture and verification engine and your verification allowance. Requires an original screenshot and a verifiable issue type. Returns the saved verdict, explanation, confidence, and after-screenshot evidence; passed_with_caveat, failed, inconclusive, and error are not an unconditional pass. Does not change issue status. Login-required and localhost pages need the browser extension. Reuse requestId only when retrying the same check after a lost response. Availability follows the verification rollout.
contextissueId必填requestId必填Read the latest 50 saved verification results for an issue, newest first. Includes verdicts, explanations, confidence, after-screenshot URLs, capture context, and timestamps. This does not run a new check. An issue status of verified or a no-longer-detected flag alone is not a verification pass.
contextissueId必填Read an issue discussion, including comment authors, audience, mentions and attachment metadata. Returns native and linked comments; edit/delete accept native comment IDs only.
contextissueId必填Post a comment with explicit audience (Team only or Team and clients), optional teammate mentions and PNG/JPG/PDF files. Reuse requestId when retrying the same submission after a lost response.
content必填contextissueId必填requestId必填visibility必填attachmentsmentionedUserIdsEdit your own native comment text and mention list. Audience and attached files stay unchanged. Supply the complete mention list, including retained mentions.
content必填contextissueId必填commentId必填mentionedUserIds必填Delete your own native comment and its attached files. This also removes it from client-visible discussions when its audience was public.
contextissueId必填commentId必填Read a native comment attachment as filename and base64 bytes. Uses the same issue permissions as reading comments. Attachment IDs come from list_comments.
contextissueId必填commentId必填attachmentId必填List the workspace label library and your write/manage permissions. Optionally include an issue UUID to see its assigned labels.
contextissueIdprojectId必填Create a reusable workspace label. Editors can create labels; retries and case-insensitive duplicate names return the existing label. Apply it with set_issue_label.
name必填contextprojectId必填Rename a label throughout its workspace. Requires workspace owner or admin permission. Assignments are preserved; existing shared reports keep their original names.
name必填contextlabelId必填projectId必填Delete a label from the workspace and all its issues. Requires workspace owner or admin permission. Issues themselves are retained.
contextlabelId必填projectId必填Apply (applied=true) or remove (applied=false) one workspace label on an issue. Other labels and issue text remain unchanged. Safe to retry.
applied必填contextissueId必填labelId必填List all OverlayQA projects in the authenticated user's team.
contextCreate a new OverlayQA project. Returns the project id, name, slug, displayPrefix, and url.
urlname必填contextList a project’s client review links, share URLs, titles, capture status, expiry, visits, comments, doneReviewers and clients. Each client includes invitedAt, inviteFailed, lastReminderAt, done, commented and unsubscribed. Done reviewing means that reviewer finished giving feedback, not that issues are fixed or that every client is done. invitationsEnabled reports the delivery switch; reminders follow the existing automatic schedule.
contextprojectId必填Create a public client review link for a website in a writable project, optionally with a title, client emails, welcome note and private guest comments. Snapshot mode starts asynchronous capture; read list_client_reviews for readiness. New client emails may receive an invitation and automatic day 3/7/10 reminders. Requires explicit intent to share and, when emails are supplied, invite those people. If invitationsEnabled is false, addresses are saved but not sent and may be invited when delivery is enabled. Inspect invites for per-address sent/skipped results. After a lost response, list links before creating again to avoid duplicates.
mode必填titlecontextpageUrl必填expiresAtprojectId必填welcomeNoteclientEmailsviewportWidthviewportHeightprivateCommentsallowResponsiveViewsChange a client review link’s expiry or responsive previews, or revoke/restore access. Supply only fields to change. Revoked or expired links stop scheduled reminders. This does not mark a reviewer done or change issue status.
revokecontextreviewId必填expiresAtallowResponsiveViewsReplace a client review link’s COMPLETE client email list. Requires explicit intent to invite or remove these people. New addresses may receive an invitation and automatic day 3/7/10 reminders; retained addresses keep their history and are not invited again. Removed addresses stop reminders; an empty list removes all recipients but leaves the public link working. If invitationsEnabled is false, addresses are saved for later delivery. Read clients and invites for actual per-address state. Reminders stop after that address comments, marks done, unsubscribes, or the link expires/is revoked.
emails必填contextreviewId必填已满足适用检查项的 100%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
You: Scan staging.acme.com for accessibility issues, then open issues for the criticals.Agent: scan_accessibility → 7 violations (2 critical, 3 high), score 71/100. scan_and_create_issues → created 2 issues in "Acme Web": - Buttons missing accessible names (WCAG 4.1.2): critical - Insufficient text contrast on .cta (WCAG 1.4.3): highYou: List the open criticals.Agent: list_issues(status=open, severity=critical) → 2 issues.{ "mcpServers": { "overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] } }}MCP_PARITY_API=http://127.0.0.1:3241 MCP_SERVER_ENV=/path/to/server/.env npm run test:issues-liveMCP_PARITY_API=https://api.overlayqa.com npm run test:issues-live