Accessibility Agents

A11y Agent Team MCP サーバー

Streamable HTTP または stdio 経由で、39 個のアクセシビリティスキャンツールを提供する MCP（Model Context Protocol）サーバーです。Claude Code、Claude Desktop、VS Code、Copilot CLI、および MCP 対応クライアントで動作します。@modelcontextprotocol/sdk 1.32.2 を基盤としており、この SDK が提供する機能（2025-11-25 までのプロトコル改訂）を実装しています。2026-07-28 時点での状況については、MCP standards page をご覧ください。

このリポジトリでは、MCP サーバーはトップレベルの mcp-server/ ディレクトリにあります。主なエントリーポイントは server.js（HTTP）と stdio.js（stdio）です。

初期状態で利用できる機能

MCP サーバーは、ドキュメントスキャンを実行する部分です（PDF 用の pdf-accessibility と pdf-scan-config は skills/ にあります）。スキルはスキャンを行うタイミングをモデルに伝え、このサーバーは実際の scan_pdf_document ツールを提供します。

インストールするもの	得られるもの	PDF スキャンは機能しますか？
スキルのみ	チャット内の PDF スキャン手順	いいえ
スキル + MCP サーバー	動作する scan_pdf_document ツール	はい
スキル + MCP サーバー + veraPDF	ベースラインスキャン + 詳細な PDF/UA 検証	はい

プラグインをインストールすると、stdio サーバーとその依存関係を単一の esbuild バンドルにまとめた dist/stdio.mjs が起動するため、npm install は不要です（mcp.json および .claude-plugin/plugin.json の mcpServers）。Playwright、@axe-core/playwright、pdf-lib はバンドルから除外され、任意の依存関係として扱われます。これらを必要とするツールには、インストール方法が記載されています。このフォルダーで npm install を実行するのは、HTTP サーバー（server.js）を使う場合、またはソースを編集する場合のみです。

サーバーのソースを変更した場合は、ここで npm run build を実行し、再ビルドした dist/stdio.mjs をコミットしてください。コミット済みのバンドルが新しいビルドと異なると、npm run verify の bundle ゲートで失敗します。

アーキテクチャ

サーバーは 2 つのトランスポートモードをサポートしています。

モード	エントリーポイント	トランスポート	用途
HTTP	server.js	Streamable HTTP（デフォルトでは GET イベントストリームを使うステートフルモード。A11Y_MCP_STATELESS=1 を指定するとステートレスモード）。従来の HTTP+SSE トランスポートは提供していません	リモートクライアント、共有サーバー、CI/CD
stdio	stdio.js（dist/stdio.mjs としてバンドル）	stdin/stdout	Claude Desktop、プラグインのインストール、ローカルでの使用

どちらのモードも、server-core.js を介して同じツール実装を共有します。

クイックスタート

開始する前に、node --version がサポート対象の Node.js LTS 系列（26、24、22 のいずれか）を示し、npm が利用可能であることを確認してください。リポジトリのインストーラーは Node.js をインストールしません。https://nodejs.org/en/download から入手してください。

# stdio, from the bundle: no install needed
node mcp-server/dist/stdio.mjs

# HTTP mode needs the dependencies
cd mcp-server
npm install
npm start
# -> http://127.0.0.1:3100/mcp

チェックアウトせずに npm から利用する場合（7.1.0 から。@community-access/accessibility-agents-mcp として公開後に利用可能。MCP Registry では io.github.Community-Access/accessibility-agents としても掲載されています）。

npx -y @community-access/accessibility-agents-mcp
claude mcp add accessibility-agents -- npx -y @community-access/accessibility-agents-mcp

npm パッケージに含まれるのは stdio バンドルのみです。ブラウザーおよび PDF フォームのツールを使うには、オプションのパッケージを同じ node_modules にインストールする必要があります。その場合は、それらのパッケージと一緒にサーバーをフォルダーへインストールし、そのフォルダーから実行してください。 npm install @community-access/accessibility-agents-mcp playwright @axe-core/playwright pdf-lib を実行し、続いて npx playwright install chromium、その後 npx accessibility-agents-mcp を実行します。

PDF のみを扱う手順については、PDF-QUICKSTART.md をご覧ください。

前提条件マトリクス

各項目の要件、用途、必須かどうかを示します。

項目	要件	用途	必須？
ランタイム	Node.js LTS（26、24、または22）	MCP サーバーの実行	はい
ランタイム	stdio バンドルでは不要	dist/stdio.mjs に @modelcontextprotocol/sdk と zod が含まれています	いいえ
HTTP または開発	npm。その後、このフォルダーで npm install（@modelcontextprotocol/sdk、zod、express）を実行	HTTP サーバー（server.js）、バンドルされていないソースの実行、テスト	これらの場合のみ
クライアント	MCP 対応クライアント	サーバーのツールの呼び出し	はい
オプション機能	Java 11 以降 + verapdf	run_verapdf_scan による詳細な PDF 検証	いいえ
オプション機能	playwright、@axe-core/playwright、Chromium	ブラウザーベースのスキャンツール	いいえ
オプション機能	pdf-lib	convert_pdf_form_to_html	いいえ
インストール時のみ	git	リポジトリのクローン	いいえ

MCP サーバーの実行にも、パッケージのインストールにも、Python は必要ありません。

ローカルサーバーと共有サーバー

この MCP サーバーは、ご自身のマシンでローカルに実行することも、共有 HTTP サービスとして実行することもできます。

モード	実行場所	最適な用途
ローカル stdio	クライアントによって起動される、ご自身のマシン	Claude Desktop とローカル限定の利用
ローカル HTTP	127.0.0.1 上のご自身のマシン	VS Code Copilot、ローカルテスト、デバッグ
共有 HTTP	サーバーまたはコンテナー	チームでの利用、CI/CD、リモートクライアント

ほとんどのユーザーは、まずローカルで起動してください。HTTP のデフォルトのバインド先は 127.0.0.1 なので、ホストを意図的に変更しない限り、ネットワークには公開されません。

設定

各環境変数のデフォルト値と説明を示します。

環境変数	デフォルト	説明
PORT	3100	HTTP サーバーのポート
A11Y_MCP_HOST	127.0.0.1	バインドアドレス
A11Y_MCP_STATELESS	（未設定）	ステートレスモードにするには 1 を設定します
GLOW_API_BASE_URL	https://letitglow.app/mcp	GLOW ブリッジツールが呼び出すエンドポイント

ステートフルモードとステートレスモード

• ステートフル（デフォルト）：セッションはリクエストをまたいで保持され（Mcp-Session-Id）、GET リクエストを行うと、そのセッション用のサーバー送信イベントストリームが開きます。対話的な利用に最適です。2026-07-28 の MCP リビジョンではセッションと GET エンドポイントが削除されており、このモードは SDK に従います。
• ステートレス：リクエストごとに新しいサーバーインスタンスが作成されます。セッションはなく、POST のみです。CI/CD とサーバーレス環境へのデプロイに最適です。

クライアントの設定

Claude Desktop（claude_desktop_config.json）

Claude Desktop は、stdio を使用して claude_desktop_config.json（Settings、Developer、Edit Config）からローカルサーバーを起動します。

{
  "mcpServers": {
    "a11y-agent-team": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/stdio.mjs"]
    }
  }
}

リモート HTTP サーバーはこのファイルではなく、カスタムコネクターとして Claude Desktop に追加します。詳しくは https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp をご覧ください。

Claude Code

プラグインがサーバーを登録します。プラグインを使用しない場合：

claude mcp add --transport stdio a11y-agent-team -- node /path/to/mcp-server/dist/stdio.mjs

VS Code（.vscode/mcp.json）

{
  "servers": {
    "a11y-agent-team": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}

GLOW ブリッジツールの使用

GLOW ブリッジツールはこの MCP サーバーの一部です。GLOW 用に別の MCP サーバーを登録する必要はありません。

デフォルトの動作

• ブリッジはデフォルトで https://letitglow.app/mcp を対象とします。
• このサーバーの起動後すぐに glow_health_check を呼び出せます。

別の GLOW エンドポイントを使用する

オプション 1：起動前にサーバーの環境変数を設定します。

# Linux/macOS
export GLOW_API_BASE_URL="https://letitglow.app/mcp"
npm start

# Windows PowerShell
$env:GLOW_API_BASE_URL = "https://letitglow.app/mcp"
npm start

オプション 2：ツール呼び出しごとに baseUrl を渡します（単発のテスト用）。

• baseUrl を指定して glow_health_check
• baseUrl を指定して glow_audit_document
• baseUrl を指定して glow_fix_document
• baseUrl を指定して glow_convert_document
• baseUrl を指定して glow_generate_report

接続後のプロンプト例

• Run glow_health_check
• Audit ./docs/sample.md with glow_audit_document using format markdown
• Convert ./docs/sample.md from markdown to html with glow_convert_document
• Generate an html report for ./docs/sample.md with glow_generate_report

PDF 専用クイックスタート

PDF のアクセシビリティスキャンだけがすぐに必要な場合は、次の最小構成で動作します。

1. Node.js の LTS リリース（26、24、または 22）をインストールします。
2. このフォルダーを開きます：mcp-server/
3. npm install を実行します。
4. npm start でサーバーを起動します。
5. MCP クライアントを http://127.0.0.1:3100/mcp に接続します。
6. チャットでガイド付き PDF ワークフローを使う場合は、スキルをインストールします（はじめにを参照）。

MCP 側で必要な最小限のファイル：

• package.json
• server.js
• server-core.js
• stdio.js
• tools/

チャットワークフローレイヤーも使用する場合は、次を追加します。

• pdf-accessibility と pdf-scan-config のスキル（skills/pdf-accessibility/、skills/pdf-scan-config/）。パッケージのほかのファイルと一緒にインストールされます。
• templates/pdf-config-moderate.json をプロジェクトに .a11y-pdf-config.json としてコピーします（任意）。

利用可能なツール

コアツール

各ツールとその説明です。

ツール	説明
check_contrast	2 色間の WCAG コントラスト比を計算します
get_accessibility_guidelines	コンポーネントの種類に応じた WCAG AA ガイドラインを取得します
check_heading_structure	HTML の見出し階層を分析します
check_link_text	あいまいなリンクテキスト、または欠落したリンクテキストを検出します
check_form_labels	フォーム入力にアクセシブルなラベルが設定されているか確認します

ドキュメントツール

各ツールとその説明です。

ツール	説明
scan_office_document	.docx/.xlsx/.pptx のアクセシビリティの問題をスキャンします
scan_pdf_document	PDF/UA チェックを使用して PDF をスキャンします
scan_epub_document	.epub ファイルが EPUB Accessibility 1.1 に準拠しているかスキャンします
extract_document_metadata	アクセシビリティに関係するメタデータを抽出します
batch_scan_documents	1 回の呼び出しで複数のドキュメントをスキャンします
fix_document_metadata	ドキュメントのメタデータ（タイトル、言語、作成者）を修正します
fix_document_headings	ドキュメントの見出し構造を修正します

GLOW ブリッジツール

各ツールとその説明です。

ツール	説明
glow_health_check	GLOW エンドポイントの状態を確認します（デフォルト：https://letitglow.app/mcp）
glow_audit_document	Markdown/HTML/DOCX ファイルを GLOW にアップロードし、/audit を実行します
glow_fix_document	Markdown/HTML/DOCX ファイルを GLOW にアップロードし、/fix を実行します
glow_convert_document	Markdown/HTML/DOCX ファイルを GLOW にアップロードし、/convert を実行します
glow_generate_report	Markdown/HTML/DOCX ファイルを GLOW にアップロードし、/report を実行します

高度なツール（オプションの依存関係）

各ツール、その必要条件、および説明です。

ツール	必要条件	説明
run_axe_scan	playwright, @axe-core/playwright	ライブ URL に対して axe-core を実行します
run_playwright_a11y_tree	playwright	アクセシビリティツリーを取得します
run_playwright_keyboard_scan	playwright	キーボードナビゲーションをテストします
run_playwright_contrast_scan	playwright	視覚的なコントラストを分析します
run_playwright_viewport_scan	playwright	複数の幅でリフローをテストします
run_verapdf_scan	veraPDF CLI	flavour で選択した PDF/UA-1（デフォルト）、PDF/UA-2、または PDF/A の検証を行います（SARIF 出力）
convert_pdf_form_to_html	pdf-lib	PDF フォームをアクセシブルな HTML に変換します

Markdown ツール

各ツールとその説明です。

ツール	説明
scan_markdown_document	Markdown ファイルのアクセシビリティの問題（リンク、代替テキスト、見出し、テーブル、絵文字）をスキャンします

キャッシュツール

各ツールとその説明です。

ツール	説明
check_audit_cache	ファイルの監査結果がキャッシュにあるか確認します
update_audit_cache	監査結果をキャッシュに保存、または更新します

オプションの依存関係のインストール

# Playwright + axe-core (for web scanning)
npm install playwright @axe-core/playwright
npx playwright install chromium

# pdf-lib (for PDF form conversion)
npm install pdf-lib

# veraPDF (external CLI)
# Download from https://verapdf.org/software/

veraPDF の実用的なセットアップ

veraPDF は任意です。組み込みの scan_pdf_document ツールは、veraPDF がなくても動作します。組み込みのヒューリスティックスキャンよりも詳細な PDF/UA 検証が必要な場合は、veraPDF をインストールしてください。

veraPDF の用途

• 内蔵スキャナーより詳細に PDF/UA 準拠を検証します
• 専用の PDF 検証ツールを使用して、構造やメタデータの問題を確認します
• 基本スキャン後の二次チェックとして使用します

veraPDF の用途ではないもの

• 基本的な PDF スキャンに必須ではありません
• このリポジトリにおける主要な修正ワークフローではありません
• verapdf --fix がここでサポートされているワークフローの一部だと想定しないでください

veraPDF をインストールする

veraPDF には Java 11 以降が必要です。

Windows

まだインストールされていない場合は、先に Java をインストールしてください。

winget install --exact --id EclipseAdoptium.Temurin.21.JRE

次に、利用可能な場合は Chocolatey を使用して veraPDF をインストールします。

choco install verapdf

Chocolatey が環境に含まれていない場合は、https://docs.verapdf.org/install/ から手動インストーラーを使用してください。

macOS

brew install verapdf

手動ダウンロード

https://docs.verapdf.org/install/ からダウンロードし、verapdf が PATH から利用できることを確認してください。

veraPDF を確認する

verapdf --version

Windows では、Java または veraPDF のインストール後にターミナルまたはエディターを再起動し、更新された PATH が反映されるようにしてください。

veraPDF を直接使用する

verapdf --flavour ua1 --format text path/to/file.pdf

この MCP サーバー経由で veraPDF を使用する

サーバーが実行中で、同じマシンに veraPDF がインストールされていれば、MCP クライアントから run_verapdf_scan を呼び出せます。

自然言語によるリクエストの例：

• veraPDFを使用してreport.pdfの詳細なPDF/UAスキャンを実行
• veraPDFでbrochure.pdfを検証し、不合格項目を要約

verapdf がインストールされていない場合、ツールはインストール方法を案内します。

詳しくは、veraPDF 連携を参照してください。

ヘルスチェック

curl http://127.0.0.1:3100/health
# {"status":"ok","name":"a11y-agent-team","version":"7.1.0","mode":"stateful"}

MCP プロンプト

アクセシビリティのワークフローをモデルに案内する、事前構築済みのプロンプトテンプレートです。

プロンプト	引数	説明
audit-page	url（必須）、level（任意：A/AA/AAA）	WCAG 監査の手順を体系的に示します。axe-core、見出し、リンク、フォーム、キーボード、コントラストの各スキャンを順に実行します
check-component	component（必須）	内蔵ガイドラインを使用したコンポーネント固有のレビュー（モーダル、タブ、アコーディオン、コンボボックス、カルーセル、フォーム、ライブリージョン、ナビゲーション、一般）
explain-wcag	criterion（必須）	WCAG の達成基準を、実践的な例、よくある違反、テスト方法の案内とともに説明します

MCP リソース

アクセシビリティの参考資料を提供する読み取り専用のデータエンドポイントです。{...} パラメーターを含む 2 つはリソーステンプレートです。クライアントはこれらを一覧表示または補完し、a11y://guidelines/modal のような具体的なアドレスを読み取ります。

リソース URI	説明
a11y://guidelines/{component}	コンポーネントのアクセシビリティガイドラインを Markdown 形式で提供します（モーダル、タブ、アコーディオン、コンボボックス、カルーセル、フォーム、ライブリージョン、ナビゲーション、一般）
a11y://tools	登録済みのすべてのツールと説明の自動生成リスト
a11y://config/{profile}	JSON 形式のスキャン設定テンプレート（strict、moderate、minimal）

セキュリティ

• パストラバーサルの防止：ファイル操作では、ホームディレクトリと CWD の境界に照らしてパスを検証します（CWE-22）
• シンボリックリンクの解決：書き込み操作では、シンボリックリンクを解決して範囲外への逸脱を防ぎます（CWE-59）
• SSRF 対策：URL ベースのツールではスキームを検証します（http/https のみ）
• コマンドインジェクションの防止：外部コマンドには引数配列を指定した execFile（exec ではなく）を使用します
• ファイルサイズの制限：ドキュメントは 100 MB、バッチ処理は 50 ファイルまでです
• ローカルへのバインド：サーバーはデフォルトで 127.0.0.1 にバインドされます（ネットワークには公開されません）

デプロイ

Docker

FROM node:24-slim
WORKDIR /app
COPY package.json .
RUN npm install
COPY . .
EXPOSE 3100
CMD ["node", "server.js"]

Systemd

[Unit]
Description=A11y Agent Team MCP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node /opt/a11y-mcp/server.js
Environment=PORT=3100
Restart=on-failure

[Install]
WantedBy=multi-user.target

ライセンス

MIT です。リポジトリのルートにある LICENSE を参照してください。