io.github.MMasey/atag-mcp

ATAG MCP

An MCP (Model Context Protocol) server that provides guidance on ATAG 2.0 — the W3C Authoring Tool Accessibility Guidelines — to help authoring tool developers build more accessible software.

What is ATAG?

ATAG 2.0 defines how authoring tools (rich-text editors, CMSes, IDEs, website builders, etc.) should:

• Part A — Be accessible to authors with disabilities (the tool's own UI)
• Part B — Help authors produce accessible web content (alt text prompts, accessibility checkers, accessible templates, etc.)

Why this exists

ATAG 2.0 has been a W3C Recommendation since 2015, but adoption among authoring tools remains limited — partly because the guidance is easy to overlook at the moment design and implementation decisions are actually made. With more authoring tool features now being built with the help of AI coding assistants, this server puts the full spec within the assistant's reach: describe the feature you're working on (an image upload dialog, a rich-text toolbar, a template picker) and get back the actual success criteria that apply, rather than a half-remembered summary. The aim is to lower the cost of considering ATAG at all — the first step towards tools that support it.

The data is a static, hand-checked copy of the ATAG 2.0 spec — not fetched or generated at runtime — so answers stay faithful to the W3C source. A weekly workflow checks for upstream spec changes.

Tools

Setup

No local install required — add the config below and your MCP client will fetch the package automatically via npx.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

VS Code (Claude extension)

{
  "mcp": {
    "servers": {
      "atag-mcp": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "atag-mcp"]
      }
    }
  }
}

Local development install

npm install
npm run build
# then point your config to dist/index.js directly

Usage examples

Ask Claude:

• "What ATAG criteria apply to an image insertion dialog?" → uses get-guidance
• "Show me all Level A criteria from Part B" → uses get-criteria-by-level
• "Explain guideline B.3.1" → uses get-guideline
• "What does 'editing-view' mean in ATAG?" → uses get-glossary-term
• "Search ATAG for keyboard access" → uses search-atag

Development

npm run dev          # Run server directly with tsx (no compile step)
npm test             # Run all tests
npm run test:watch   # Watch mode
npm run validate-data  # Validate data/atag.json structure
npm run check-updates  # Check if W3C spec has changed

Branching and commits

This project follows git flow with Conventional Commits:

• main — released code only; every merge to main is tagged and published
• develop — integration branch; day-to-day work lands here
• feature/<name> — branched from and merged back to develop
• release/<version> — branched from develop, merged to main (tagged) and back to develop
• hotfix/<name> — branched from main for urgent fixes, merged to both main and develop

Commit messages use conventional prefixes: feat:, fix:, docs:, test:, ci:, chore:, refactor: (with ! or a BREAKING CHANGE: footer for breaking changes).

Releasing

Versioning uses standard npm version bumps. Pushing a v* tag triggers the GitHub Actions publish workflow, which runs tests and publishes to npm automatically.

npm version patch   # bug fixes:    1.0.0 → 1.0.1
npm version minor   # new features: 1.0.0 → 1.1.0
npm version major   # breaking:     1.0.0 → 2.0.0

git push && git push --tags

When bumping the version, also update the version fields in server.json to match — the MCP Registry validates them against the published npm package. After the npm publish succeeds, refresh the registry listing with:

mcp-publisher login github
mcp-publisher publish

Publishing requires the NPM_TOKEN repository secret (a granular npm access token with write access to atag-mcp). If the token expires or is rotated, add the new one under the same secret name, then run the manual Check npm token workflow (Actions tab) to verify it authenticates before tagging a release.

Keeping data current

The ATAG 2.0 spec is captured in data/atag.json. The GitHub Actions workflow (.github/workflows/update-atag.yml) runs weekly and opens an issue if the W3C spec content changes.

To update manually:

1. Review changes at https://www.w3.org/TR/ATAG20/
2. Edit data/atag.json with the changes
3. Run npm run validate-data to check structure
4. Run npm run check-updates -- --save to update the stored hash

Data

• Version: ATAG 2.0
• Specification: https://www.w3.org/TR/ATAG20/
• Parts: 2 (Part A + Part B)
• Principles: 8
• Guidelines: 24
• Success Criteria: 63
• Glossary Terms: 18

License

MIT