accessibility-mcp

A Model Context Protocol server (built with FastMCP) that exposes WAI-ARIA Authoring Practices Guide (APG) patterns: narrative requirements, keyboard/ARIA guidance as Markdown, official example source (HTML, CSS, JS) from w3c/aria-practices, and RAG via Ollama + LangChain.js (apg_semantic_search; the chunk index is prebuilt in data/rag/chunks.json for releases).

This is APG (widget patterns), not the full WCAG spec. For WCAG success criteria text, use W3C’s WCAG materials separately; APG is the right source for patterns like Carousel and the patterns index.

Codebase documentation: docs/README.md (architecture, data pipeline, MCP tools).

Tests: npm test runs unit tests plus an MCP stdio integration check (src/mcp-stdio.integration.test.ts): builds dist/cli.js, spawns the server with @modelcontextprotocol/sdk, completes the initialize handshake, and callTool(apg_meta) — this matches what Claude Code uses at the protocol level. Manual: npm run mcp:try (see Try tools without Claude).

Claude Code CLI (optional): the real claude -p binary can drive the same server with --mcp-config + --strict-mcp-config (see headless / -p). Uses your normal Claude Code login (same as the REPL)—no ANTHROPIC_API_KEY required unless you use --bare (API-key-only / CI). To smoke-test end-to-end:

CLAUDE_CODE_MCP_SMOKE=1 npm run test:claude-mcp

Exits 0 with a skip message if CLAUDE_CODE_MCP_SMOKE is unset (default in CI).

Data / RAG quality: npm run validate:data (structure checks; no Ollama). npm run eval:rag runs a labeled benchmark and writes reports/rag-eval.html (bar chart of top-1 scores + MRR / Hit@k). There is no training loss curve—embeddings are frozen; see docs/evaluation.md.

Dataset

• npm run ingest — shallow-clones w3c/aria-practices into .cache/, writes:

  • data/manifest.json — compact index (ids, titles, example slugs, bundle paths)

  • data/patterns/<id>.md — pattern doc as Markdown (from *-pattern.html)

  • data/bundles/<id>/<example>.json — referenced HTML/CSS/JS per demo (binary assets listed but omitted)

• npm run rag:index — (after ingest + .env) calls Ollama embeddings and writes data/rag/chunks.json: chunked pattern docs plus one combined text blob per example (HTML/CSS/JS). Maintainers run this before releases; re-run after ingest or when you change OLLAMA_EMBEDDING_MODEL.

• Vendored data/ (including data/rag/chunks.json) is committed and published so end users are not required to ingest or index locally.

Related MCP server: aria-mcp

Usage

npm install
npm run ingest   # refresh from GitHub (re-run when you want newer APG)
npm run rag:index # rebuild RAG index (maintainers / custom models; shipped index in releases)
npm run build
npm start        # stdio MCP server

npx (after publish to npm)

npx -y accessibility-mcp

After the package is on npm, most clients can use command + args with npx / -y / accessibility-mcp instead of a local node path.

Publishing (npm tarball)

The package ships dist/, data/manifest.json, data/patterns/, data/bundles/, and data/rag/chunks.json (see files in package.json). That last file is the precomputed embedding index so installers do not need to run npm run rag:index themselves.

Runtime note: apg_semantic_search still uses Ollama to embed the user query at request time (the index only stores chunk vectors). Point OLLAMA_EMBEDDING_* at the same embedding model the index was built with (see embeddingModel inside chunks.json). Users without Ollama can set OLLAMA_SKIP_PULL=1 and use the non-RAG tools only.

Before npm publish:

1. npm run ingest — refresh APG text and bundles.

2. npm run rag:index — rebuild data/rag/chunks.json (needs Ollama once, on the maintainer machine).

3. npm test (optional but recommended).

4. npm publish — prepack runs npm run build.

Inspect the tarball: npm pack --dry-run.

MCP Inspector (dev)

The MCP Inspector is a dev dependency. After npm run build:

npm run mcp:inspect

Opens a local web UI to exercise tools and resources against node dist/cli.js (Ollama runs on first connect like npm start).

Try tools without Claude (CLI)

npm run mcp:try runs a tiny MCP SDK client that spawns dist/cli.js, completes the handshake, and calls a tool (same mechanism as the integration test).

npm run build
npm run mcp:try -- --list
npm run mcp:try
npm run mcp:try -- apg_list_patterns '{"query":"carousel"}'

See scripts/mcp-client-demo.ts. apg_semantic_search still needs a reachable Ollama embedding endpoint at call time.

Environment (.env)

At startup the server loads .env from the package root (same folder as package.json). Copy .env.example → .env and adjust.

The MCP stdio handshake runs first; Ollama model checks and pulls run after that (async). If Ollama is unreachable, APG list/read tools still work; RAG needs Ollama when invoked.

Without Ollama (no local LLM)

Listing patterns, reading specs, and fetching example sources use only the bundled data/ files—no model and no network at query time.

1. Install Node.js 20+.

2. Run the server from the published package, e.g. npx -y accessibility-mcp (after you publish), or node dist/cli.js from a git checkout after npm install + npm run build.

3. Optionally set OLLAMA_SKIP_PULL=1 so startup never contacts Ollama (otherwise unreachable Ollama only logs a warning by default).

Do not rely on apg_semantic_search without Ollama: it needs a running embedding endpoint at call time. Ignore that tool or expect errors if invoked.

Ollama + LangChain.js helpers (for RAG scripts or future MCP tools):

• loadEnv() — load .env explicitly (also runs via getOllamaConfig() / resolveDataDir()).

• getOllamaConfig() — parsed { baseUrl, chatBaseUrl, embeddingBaseUrl, chatModel, embeddingModel }.

• ensureOllamaModels() — GET /api/tags + POST /api/pull for missing models (same as MCP startup).

• createChatOllama() / createOllamaEmbeddings() — @langchain/ollama instances using those settings.

import { createChatOllama, createOllamaEmbeddings } from "accessibility-mcp";

The apg_semantic_search tool calls Ollama at query time (embed query → cosine similarity vs data/rag/chunks.json). npm run rag:index builds that index with createOllamaEmbeddings().

Sanity check (requires Ollama reachable at OLLAMA_CHAT_BASE_URL or OLLAMA_BASE_URL with OLLAMA_CHAT_MODEL pulled):

cp .env.example .env   # then edit if needed
npm run ollama:smoke

IDE and agent setup

MCP wiring differs by product: some use a top-level mcpServers object; VS Code uses servers inside mcp.json. Below, replace /absolute/path/to/accessibility-mcp with your clone (or use npx once published).

Use an absolute path to dist/cli.js in args (or npx -y accessibility-mcp). A relative path like dist/cli.js is resolved from the client’s workspace and usually fails outside this repo.

Shared snippets

Stdio via local build (mcpServers shape — Cursor, Claude Desktop, Claude Code, Gemini CLI):

{
  "mcpServers": {
    "apg-patterns": {
      "command": "node",
      "args": ["/absolute/path/to/accessibility-mcp/dist/cli.js"]
    }
  }
}

Stdio via npx (after npm publish):

{
  "mcpServers": {
    "apg-patterns": {
      "command": "npx",
      "args": ["-y", "accessibility-mcp"]
    }
  }
}

Custom data directory (any client that supports env on the server process):

{
  "mcpServers": {
    "apg-patterns": {
      "command": "node",
      "args": ["/absolute/path/to/accessibility-mcp/dist/cli.js"],
      "env": {
        "APG_MCP_DATA_DIR": "/absolute/path/to/accessibility-mcp/data"
      }
    }
  }
}

Visual Studio Code (GitHub Copilot agent / MCP)

VS Code stores MCP config in mcp.json using a servers object (not mcpServers). See Add and manage MCP servers in VS Code and the MCP configuration reference.

• Workspace: .vscode/mcp.json

• User: Command Palette → MCP: Open User Configuration

Example (local checkout):

{
  "servers": {
    "apg-patterns": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/accessibility-mcp/dist/cli.js"]
    }
  }
}

Example (npx, after publish):

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

You can also use MCP: Add Server in the Command Palette or install from the Extensions view (@mcp gallery) if this server is listed there.

Cursor

Cursor merges MCP config from:

• Project: .cursor/mcp.json

• Global: ~/.cursor/mcp.json (project entries override global)

Use the mcpServers JSON shape from the shared snippets above. See Model Context Protocol (MCP) | Cursor Docs. Restart Cursor after changes if tools do not appear.

Claude Desktop

Edit the Claude desktop config file and merge under mcpServers:

Use the shared mcpServers snippet. Restart Claude Desktop after saving.

Claude Code

Claude Code supports project .mcp.json, local entries in ~/.claude.json, and user scope; stdio servers use command + args like other clients. See Connect Claude Code to tools via MCP.

Prerequisites: npm install, npm run build, and a .env next to package.json (or pass Ollama settings with repeated --env KEY=value; the server also loads .env from the package root automatically).

Put options (--transport, --scope, --env) before the server name; use -- before the process to spawn (documented ordering).

Local / project (from this repo; records a relative dist/cli.js — only works when that workspace is this package):

cd /absolute/path/to/accessibility-mcp
claude mcp add --transport stdio apg-patterns -- node dist/cli.js

claude mcp add --transport stdio apg-patterns --scope project -- node dist/cli.js

User scope (recommended — works from any folder; use your real path):

claude mcp add --transport stdio apg-patterns --scope user -- node /absolute/path/to/accessibility-mcp/dist/cli.js

After publish to npm:

claude mcp add --transport stdio apg-patterns -- npx -y accessibility-mcp

Then claude mcp list or /mcp in Claude Code to confirm. If the server won’t start, check that args points at the built cli.js. npm test and npm run mcp:try exercise the server without the Claude UI.

Gemini CLI

Configure mcpServers in Gemini CLI settings. User vs project scope:

• User: ~/.gemini/settings.json

• Project: .gemini/settings.json in the repo

Details: MCP servers with the Gemini CLI.

CLI (stdio; user scope — writes ~/.gemini/settings.json):

gemini mcp add --scope user apg-patterns node /absolute/path/to/accessibility-mcp/dist/cli.js

Use --scope project to write .gemini/settings.json instead. Run gemini mcp add --help for flags (-e for env, --trust, etc.).

OpenAI Codex (CLI and IDE extension)

Codex stores MCP servers in config.toml, default ~/.codex/config.toml, or project .codex/config.toml on trusted projects. CLI and IDE share this file. See Model Context Protocol – Codex.

TOML example (stdio):

[mcp_servers.apg-patterns]
command = "node"
args = ["/absolute/path/to/accessibility-mcp/dist/cli.js"]

CLI:

codex mcp add apg-patterns -- node /absolute/path/to/accessibility-mcp/dist/cli.js

Other editors

• Windsurf / JetBrains / etc.: If the product documents MCP stdio support, reuse the same command / args as above; the wrapper key name may differ—check that product’s MCP docs.

• VS Code discovery: With chat.mcp.discovery.enabled, VS Code can pick up MCP definitions from some other apps (e.g. Claude Desktop). See the VS Code MCP article.

Tools

Resources

• apg://manifest — full manifest JSON

• apg://pattern/{patternId} — pattern Markdown

• apg://example/{patternId}/{slug} — example sources as Markdown

License

ISC (this package). APG content is W3C documentation; see W3C document license.