Content
# ATAG MCP
An MCP (Model Context Protocol) server that provides guidance on [ATAG 2.0](https://www.w3.org/TR/ATAG20/) — 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
| Tool | Description |
|---|---|
| `get-server-info` | Dataset statistics and attribution |
| `explain-atag` | Overview of ATAG, how it differs from WCAG, and its two-part structure |
| `list-parts` | Part A and Part B summaries |
| `list-principles` | All 8 principles, filterable by part |
| `list-guidelines` | All 24 guidelines, filterable by part or principle |
| `list-success-criteria` | All 63 success criteria, filterable by part, principle, guideline, or level |
| `get-criterion` | Full details for a specific SC (e.g. `B.2.3.1`) |
| `get-guideline` | Full guideline details with all child success criteria |
| `get-criteria-by-level` | All criteria at Level A, AA, or AAA |
| `search-atag` | Keyword search across all ATAG content |
| `list-glossary-terms` | All ATAG glossary terms |
| `get-glossary-term` | Definition of a specific ATAG term |
| `get-guidance` | **Key tool** — describe a feature you're building and get the most relevant ATAG criteria |
## 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):
```json
{
"mcpServers": {
"atag-mcp": {
"command": "npx",
"args": ["-y", "atag-mcp"]
}
}
}
```
### VS Code (Claude extension)
```json
{
"mcp": {
"servers": {
"atag-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "atag-mcp"]
}
}
}
}
```
### Local development install
```bash
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
```bash
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](https://nvie.com/posts/a-successful-git-branching-model/) with [Conventional Commits](https://www.conventionalcommits.org/):
- `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.
```bash
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](https://registry.modelcontextprotocol.io) validates them against the published npm package. After the npm publish succeeds, refresh the registry listing with:
```bash
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
