# aria-mcp
A Model Context Protocol (MCP) server providing comprehensive access to the W3C WAI-ARIA specification. Designed for accessibility professionals, developers, and AI agents to query ARIA roles, states, properties, and accessibility requirements.
## Quick Start
Add to your MCP client configuration:
```json
{
"mcpServers": {
"aria": {
"command": "npx",
"args": ["-y", "aria-mcp"]
}
}
}
```
That's it! No cloning, no building - just add the config and start querying ARIA.
## Features
- **Complete ARIA 1.3 Specification Data**: Roles, states, properties, and their relationships
- **Role Validation**: Check attribute validity for specific roles
- **Accessibility Guidance**: Name requirements, landmarks, live regions
- **Smart Suggestions**: Get role recommendations based on UI component descriptions
- **Works Locally & Remotely**: stdio transport for local use, Netlify Functions for remote deployment
## Available Tools
| Tool | Description |
|------|-------------|
| **Role Information** | |
| `get-role` | Get detailed information about a specific ARIA role |
| `list-roles` | List all ARIA roles, optionally filtered by category |
| `search-roles` | Search for roles by keyword in name or description |
| `get-role-hierarchy` | Get the inheritance hierarchy for a role |
| **States & Properties** | |
| `get-attribute` | Get details about an ARIA state or property |
| `list-states` | List all ARIA states with descriptions |
| `list-properties` | List all ARIA properties, optionally global only |
| `get-global-attributes` | List all global ARIA states and properties |
| **Validation** | |
| `validate-role-attributes` | Validate if attributes are allowed for a role |
| `get-required-attributes` | Get required attributes for a role |
| `get-prohibited-attributes` | Get prohibited attributes for a role |
| **Role Relationships** | |
| `get-required-context` | Get required parent context for a role |
| `get-required-owned` | Get required child elements for a role |
| **Accessible Name** | |
| `check-name-requirements` | Check accessible name requirements for a role |
| `get-roles-requiring-name` | List all roles that require an accessible name |
| **Specialized Queries** | |
| `list-landmarks` | List all ARIA landmark roles with usage guidance |
| `list-widget-roles` | List interactive widget roles |
| `list-live-regions` | List live region roles with politeness levels |
| **Guidance** | |
| `suggest-role` | Get role suggestions based on UI component description |
| `get-aria-version` | Get ARIA specification version and statistics |
| `get-server-info` | Get information about this MCP server |
## Installation
```bash
npm install
```
### Configure Claude Desktop
Add this to your Claude Desktop MCP settings (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"aria-mcp": {
"command": "node",
"args": ["/path/to/aria-mcp/src/index.js"]
}
}
}
```
### Configure Cursor
Add to your Cursor MCP settings:
```json
{
"mcpServers": {
"aria-mcp": {
"command": "node",
"args": ["/path/to/aria-mcp/src/index.js"]
}
}
}
```
## Usage Examples
### Query a Role
```
get-role button
```
Returns complete information about the button role including:
- Description and purpose
- Category (widget, landmark, etc.)
- Required/supported/prohibited attributes
- Name requirements
- Parent/child role requirements
### Validate Attributes
```
validate-role-attributes role=button attributes=["aria-pressed","aria-expanded","aria-label"]
```
Checks if each attribute is valid, required, or prohibited for the role.
### Get Role Suggestions
```
suggest-role "dropdown menu with autocomplete"
```
Returns suggested roles (combobox, listbox) with usage guidance.
### List Landmarks
```
list-landmarks
```
Lists all ARIA landmark roles with best practices for page structure.
## Data Source
This MCP server uses data parsed directly from the [W3C ARIA repository](https://github.com/w3c/aria), which is included as a Git submodule.
### Updating the Data
To update to the latest ARIA specification:
```bash
npm run update-submodule
```
This will:
1. Pull the latest changes from the W3C ARIA repository
2. Re-parse the specification to regenerate `data/aria-data.json`
### Manual Parsing
To regenerate the data without updating the submodule:
```bash
npm run parse
```
## Project Structure
```
aria-mcp/
├── src/
│ ├── index.js # MCP server with stdio transport
│ └── tools.js # Tool definitions and handlers
├── scripts/
│ └── parse-aria-spec.js # Parser for W3C ARIA HTML specs
├── data/
│ ├── aria/ # W3C ARIA repo (Git submodule)
│ └── aria-data.json # Parsed specification data
├── netlify/
│ └── functions/
│ └── api.js # Netlify Function for remote use
└── netlify.toml # Netlify configuration
```
## Deployment to Netlify
This project is configured for Netlify deployment.
### Deploy via GitHub
1. Push this repository to GitHub
2. Connect to Netlify via the dashboard
3. Netlify will automatically build and deploy
### Using the Remote Server
Once deployed, configure your MCP client:
```json
{
"mcpServers": {
"aria-mcp": {
"command": "npx",
"args": ["mcp-remote@next", "https://your-site.netlify.app/mcp"]
}
}
}
```
## Use Cases
### For Accessibility Professionals
- **Quick Reference**: Look up role requirements without leaving your IDE
- **Validation**: Verify ARIA usage in code reviews
- **Training**: Help team members understand ARIA semantics
### For Developers
- **Real-time Guidance**: Get role suggestions while building components
- **Attribute Validation**: Catch invalid ARIA usage early
- **Documentation**: Access spec details without browser context switching
### For AI Agents
- **Code Generation**: Generate accessible components with correct ARIA
- **Code Review**: Validate ARIA usage in pull requests
- **Accessibility Audits**: Check for missing or incorrect attributes
## ARIA Specification Coverage
- **100 Roles**: All roles from WAI-ARIA 1.3
- **10 States**: Dynamic values that change with user interaction
- **43 Properties**: Static or rarely-changing characteristics
- **Role Categories**: widget, composite, document, landmark, liveRegion, window, abstract
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `npm run parse` if modifying the parser
5. Submit a pull request
## License
MIT
## Resources
- [WAI-ARIA Specification](https://w3c.github.io/aria/)
- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
