feat: Add MCP server, SKILL.md for aria-practices

[karanshah229]

Summary

This PR adds an MCP (Model Context Protocol) server that exposes WAI-ARIA Authoring Practices (APG) pattern documentation as on-demand resources. AI agents and chatbots can query these resources while helping developers build accessible components. A Cursor skill and test fixtures are included for integration and validation.

---

Architecture

Data flow

content/patterns/*/*-pattern.html  (source of truth)
         │
         ▼
    discovery.mjs  ──►  lists pattern IDs, names
         │
         ▼
    parser.mjs  ──►  extracts sections → node-html-markdown → markdown
         │
         ▼
    index.mjs  ──►  MCP Resources API (stdio)
         │
         ▼
    AI client (Cursor, Claude Desktop, etc.)

Pattern HTML is never duplicated. The server reads from the existing content/patterns/ tree and parses it on demand.

Transport and protocol

• Transport: stdio (process spawn). Suits local AI tools like Cursor and Claude Desktop and avoids HTTP.
• Capability: Resources only (no tools or prompts). Pattern specs are read-only reference data.
• URI scheme: apg://pattern/{id} (e.g. apg://pattern/accordion, apg://pattern/dialog-modal).

---

Code Design Decisions

1. Single source of truth

Pattern HTML under content/patterns/ is the only authoritative source. The MCP server parses it at runtime and does not maintain a separate copy. Changes to pattern docs are automatically reflected when the server is used.

2. Modular layout under mcp-server/

File	Responsibility
discovery.mjs	Scans content/patterns/*/*-pattern.html, returns { id, path, name }
parser.mjs	Extracts sections (#about, #examples, #keyboard_interaction, #roles_states_properties), converts to markdown via node-html-markdown
index.mjs	MCP server entry; registers ResourceTemplate, connects stdio transport

Separation makes parsing and discovery easy to test and evolve independently.

3. ESM (.mjs) for MCP server

The MCP SDK is ESM-only. Using .mjs lets us import it without changing the repo "type" or adding a build step.

4. HTML → markdown

node-html-markdown is used instead of a custom converter. It keeps the parser small and robust while still supporting tables, lists, and other structures needed for pattern content.

5. No build step

The server is plain Node.js. There is no transpilation or bundling. Dependencies are installed via the root package.json; the MCP server uses the repo's existing tooling.

6. Minimal changes to existing code

• Added mcp-server/, skill/, src/tests/
• Updated package.json (script + 3 devDependencies)
• Updated eslint.config.mjs and .github/workflows/lint-js.yml for .mjs
• Updated README

No edits to content/, scripts/, or existing test/ setup.

---

File Structure

mcp-server/
├── index.mjs      # MCP server, ResourceTemplate registration, stdio
├── discovery.mjs  # Pattern discovery
└── parser.mjs     # HTML → markdown

skill/
├── README.md
└── wai-aria-apg/
    ├── SKILL.md   # Cursor skill (when to use APG, how to fetch patterns)
    └── README.md

src/tests/         # Manual test fixtures
├── html-landing/  # Plain HTML with accessibility issues
└── react-ts/      # React + TS + Vite app with accessibility issues

---

Dependencies

Package	Purpose
@modelcontextprotocol/sdk	MCP server implementation, stdio transport
zod	Peer dependency of the MCP SDK
node-html-markdown	HTML to markdown conversion

Existing dependencies (cheerio, glob, etc.) are reused where possible.

---

End-User Usage

Running the MCP server

npm install
npm run mcp

The server runs over stdio and waits for MCP client connections.

Cursor setup

1. MCP server (Settings → MCP):

{
  "mcpServers": {
    "wai-aria-apg": {
      "command": "node",
      "args": ["/path/to/aria-practices/mcp-server/index.mjs"]
    }
  }
}

2. Skill (optional): copy skill/wai-aria-apg into .cursor/skills/ so the AI uses APG patterns when working on ARIA components.

Test fixtures

src/tests/html-landing/ and src/tests/react-ts/ contain deliberately inaccessible examples for validating the MCP server and Cursor integration.

# HTML
open src/tests/html-landing/index.html

# React
cd src/tests/react-ts && npm install && npm run dev

---

Testing

• npm run lint:es (and full npm run lint) pass.
• Server startup verified manually; resources can be listed and read via MCP Inspector or a client.
• Existing test suite is unchanged; no Selenium or other test changes for the MCP server.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3416: Add MCP server.

The full IRC log of that discussion

<jugglinmike> Topic: PR 3416: Add MCP server
<jugglinmike> github: https://github.com//pull/3416
<jugglinmike> Matt_King: I didn't know that you could actually put something into the repo that would enable that repo to be an MCP source. This seems super-cool to me on the surface (if I understand the surface correctly)
<jugglinmike> Matt_King: We need some people who have actually done this sort of work to look at this and provide feedback. That wouldn't be me!
<jugglinmike> Matt_King: I would love to use this, and I would love it if a lot of people were using this. That would be great
<jugglinmike> Matt_King: Has anyone here done any work related to developing MCP sources?
<jugglinmike> Matt_King: Hearing none, should we take it to the ARIA working group?
<jugglinmike> Matt_King: Just to get a wider audience of people who could review and test this
<jugglinmike> Daniel: There's no official stance from the W3C on this sort of thing. I do know that some people in WAI have expressed opinions. I've used tools like this myself, but it's one thing to use them and another thing to promote their use.
<jugglinmike> Matt_King: I would assume that the goal is to assist people who are building components--to allow them to instruct their agents to use the guidance from the APG
<jugglinmike> Daniel: In that case, then my comments wouldn't apply as much
<jugglinmike> Matt_King: One of the problems with pointing an agent at the APG right now is that not all of the content in APG is necessarily relevant to building a specific pattern. My understanding is that this would help agents be smarter by focusing their attention on the relevant information. I could be wrong about that!
<jugglinmike> Daniel: I'll take a look at this, and I'll bring it to WAI (just to make sure we're in alignment for this type of change)
<jugglinmike> Matt_King: Sounds good
<jugglinmike> Matt_King: If we can support something that makes APG more useful to agents, I think that would be awesome. But it may be a bigger lift (e.g. maybe it has an impact on the W3 org), so I'm interested in hearing what you and Remi have to say, Daniel