@community-access/accessibility-agents-mcp

v7.1.0

Published

6 days ago

Server-based MCP server for the A11y Agent Team. Provides accessibility scanning tools over stdio and over the Streamable HTTP transport. Works with any MCP client.

0High
0Medium
0Low

jeffbis

mcp accessibility a11y wcag axe-core model-context-protocol claude copilot

A11y Agent Team MCP Server

MCP (Model Context Protocol) server that provides 39 accessibility scanning tools over Streamable HTTP or stdio. Works with Claude Code, Claude Desktop, VS Code, the Copilot CLI and any MCP-compatible client. It is built on @modelcontextprotocol/sdk 1.32.2 and implements what that SDK provides (protocol revisions up to 2025-11-25); see the MCP standards page for where it stands against 2026-07-28.

In this repository, the MCP server lives in the top-level mcp-server/ directory. The main entry points are server.js (HTTP) and stdio.js (stdio).

What Works Out Of The Box

The MCP server is the executable part of document scanning. The skills (for PDF, pdf-accessibility and pdf-scan-config under skills/) tell the model when to scan; this server provides the actual scan_pdf_document tool.

| What you install | What you get | PDF scanning works? | |------------------|--------------|---------------------| | Skills only | PDF scanning instructions in chat | No | | Skills + MCP server | Working scan_pdf_document tool | Yes | | Skills + MCP server + veraPDF | Baseline scan + deep PDF/UA validation | Yes |

A plugin install launches dist/stdio.mjs, a single esbuild bundle of the stdio server and its dependencies, so it starts with no npm install (mcp.json, and mcpServers in .claude-plugin/plugin.json). Playwright, @axe-core/playwright and pdf-lib are left out of the bundle and stay optional; the tools that need them say how to install them. Run npm install in this folder only for the HTTP server (server.js) or to work on the source.

If you change the server's source, run npm run build here and commit the rebuilt dist/stdio.mjs: the bundle gate in npm run verify fails when the committed bundle differs from a fresh build.

Architecture

The server supports two transport modes:

| Mode | Entry Point | Transport | Use Case | |------|-------------|-----------|----------| | HTTP | server.js | Streamable HTTP (stateful with a GET event stream by default; stateless with A11Y_MCP_STATELESS=1). The legacy HTTP+SSE transport is not offered | Remote clients, shared servers, CI/CD | | stdio | stdio.js (bundled as dist/stdio.mjs) | stdin/stdout | Claude Desktop, plugin installs, local use |

Both modes share the same tool implementations via server-core.js.

Quick Start

Before you start, make sure node --version reports a supported Node.js LTS line (26, 24 or 22) and that npm is available. The repository installer does not install Node.js; get it from https://nodejs.org/en/download.

# stdio, from the bundle: no install needed
node mcp-server/dist/stdio.mjs

# HTTP mode needs the dependencies
cd mcp-server
npm install
npm start
# -> http://127.0.0.1:3100/mcp

From npm, with no checkout (from 7.1.0, once published as @community-access/accessibility-agents-mcp; also listed in the MCP Registry as io.github.Community-Access/accessibility-agents):

npx -y @community-access/accessibility-agents-mcp
claude mcp add accessibility-agents -- npx -y @community-access/accessibility-agents-mcp

The npm package is the stdio bundle alone. The browser and PDF form tools need their optional packages in the same node_modules, so for those install the server into a folder with them and run it from there: npm install @community-access/accessibility-agents-mcp playwright @axe-core/playwright pdf-lib, npx playwright install chromium, then npx accessibility-agents-mcp.

For a PDF-only walkthrough, see PDF-QUICKSTART.md.

Prerequisite Matrix

Each class, with requirement, needed for and required.

| Class | Requirement | Needed For | Required? | |------|-------------|------------|-----------| | Runtime | Node.js LTS (26, 24 or 22) | Running the MCP server | Yes | | Runtime | none for the stdio bundle | dist/stdio.mjs carries @modelcontextprotocol/sdk and zod inside it | No | | HTTP or development | npm, then npm install in this folder (@modelcontextprotocol/sdk, zod, express) | The HTTP server (server.js), running the unbundled source and the tests | Only for those | | Client | MCP-compatible client | Calling the server tools | Yes | | Optional feature | Java 11+ + verapdf | Deep PDF validation with run_verapdf_scan | No | | Optional feature | playwright, @axe-core/playwright, Chromium | Browser-based scanning tools | No | | Optional feature | pdf-lib | convert_pdf_form_to_html | No | | Installer-only | git | Cloning the repository | No |

Python is not required to run the MCP server or to install the package.

Local Vs Shared Server

You can run this MCP server either locally on your own machine or as a shared HTTP service.

| Mode | Where it runs | Best for | |------|---------------|----------| | Local stdio | Your machine, started by the client | Claude Desktop and local-only use | | Local HTTP | Your machine on 127.0.0.1 | VS Code Copilot, local testing, debugging | | Shared HTTP | A server or container | Team use, CI/CD, remote clients |

For most users, start locally first. The default HTTP binding is 127.0.0.1, so it is not exposed to the network unless you deliberately change the host.

Configuration

Each environment variable, with its default and description.

| Environment Variable | Default | Description | |---------------------|---------|-------------| | PORT | 3100 | HTTP server port | | A11Y_MCP_HOST | 127.0.0.1 | Bind address | | A11Y_MCP_STATELESS | (unset) | Set to 1 for stateless mode | | GLOW_API_BASE_URL | https://letitglow.app/mcp | Endpoint the GLOW bridge tools call |

Stateful vs Stateless

Stateful (default): Sessions persist across requests (Mcp-Session-Id), and a GET request opens a server-sent event stream for that session. Best for interactive use. The 2026-07-28 MCP revision removes sessions and the GET endpoint; this mode follows the SDK.
Stateless: Each request creates a fresh server instance. No sessions, POST only. Best for CI/CD and serverless deployments.

Client Configuration

Claude Desktop (`claude_desktop_config.json`)

Claude Desktop starts local servers from claude_desktop_config.json (Settings, Developer, Edit Config), using stdio:

{
  "mcpServers": {
    "a11y-agent-team": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/stdio.mjs"]
    }
  }
}

Remote HTTP servers are added in Claude Desktop as custom connectors rather than in this file; see https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp.

Claude Code

The plugin registers the server for you. Without the plugin:

claude mcp add --transport stdio a11y-agent-team -- node /path/to/mcp-server/dist/stdio.mjs

VS Code (`.vscode/mcp.json`)

{
  "servers": {
    "a11y-agent-team": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}

Using GLOW Bridge Tools

The GLOW bridge tools are part of this MCP server. You do not register a second MCP server for GLOW.

Default behavior

The bridge targets https://letitglow.app/mcp by default.
You can call glow_health_check immediately after starting this server.

Use a different GLOW endpoint

Option 1: set server environment variable before startup:

# Linux/macOS
export GLOW_API_BASE_URL="https://letitglow.app/mcp"
npm start

# Windows PowerShell
$env:GLOW_API_BASE_URL = "https://letitglow.app/mcp"
npm start

Option 2: pass baseUrl per tool call (for one-off testing):

glow_health_check with baseUrl
glow_audit_document with baseUrl
glow_fix_document with baseUrl
glow_convert_document with baseUrl
glow_generate_report with baseUrl

Example prompts after connection

Run glow_health_check
Audit ./docs/sample.md with glow_audit_document using format markdown
Convert ./docs/sample.md from markdown to html with glow_convert_document
Generate an html report for ./docs/sample.md with glow_generate_report

PDF-Only Quick Start

If your immediate goal is only PDF accessibility scanning, this is the smallest working path:

Install a Node.js LTS release (26, 24 or 22).
Open this folder: mcp-server/
Run npm install
Start the server with npm start
Point your MCP client at http://127.0.0.1:3100/mcp
Install the skills (see Getting started) if you want the guided PDF workflow in chat

Minimum files for the MCP side:

package.json
server.js
server-core.js
stdio.js
tools/

If you also want the chat workflow layer, add:

the pdf-accessibility and pdf-scan-config skills (skills/pdf-accessibility/, skills/pdf-scan-config/), installed with the rest of the package
templates/pdf-config-moderate.json copied to your project as .a11y-pdf-config.json (optional)