mcp-accessibility-scanner 1.0.11 → 1.1.1

package/NOTICE.md

@@ -0,0 +1,21 @@
+# NOTICE
+
+## mcp-accessibility-scanner
+
+Copyright (c) 2024 Justas Monkev
+
+This project is licensed under the MIT License.
+
+## Third-Party Code Attribution
+
+This project includes code adapted from:
+
+### Microsoft Playwright MCP
+- Copyright (c) Microsoft Corporation
+- Licensed under the Apache License, Version 2.0
+- Original source: https://github.com/microsoft/playwright-mcp
+
+Adapted code has been modified to:
+- Convert from ESM to CommonJS module format
+- Integrate with axe-core accessibility scanning
+- Work with existing Playwright instances rather than spawning new ones

package/Readme.md

@@ -1,7 +1,9 @@
-[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/justasmonkev-mcp-accessibility-scanner-badge.png)](https://mseep.ai/app/justasmonkev-mcp-accessibility-scanner)
 
 # MCP Accessibility Scanner 🔍
 
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/justasmonkev-mcp-accessibility-scanner-badge.png)](https://mseep.ai/app/justasmonkev-mcp-accessibility-scanner)
+
+A Model Context Protocol (MCP) server that provides automated web accessibility scanning using Playwright and Axe-core. This server enables LLMs to perform WCAG compliance checks, capture annotated screenshots, and generate detailed accessibility reports.
 A powerful Model Context Protocol (MCP) server that provides automated web accessibility scanning and browser automation using Playwright and Axe-core. This server enables LLMs to perform WCAG compliance checks, interact with web pages, manage persistent browser sessions, and generate detailed accessibility reports with visual annotations.
 
 ## Features
@@ -13,16 +15,18 @@ A powerful Model Context Protocol (MCP) server that provides automated web acces
 🎯 Support for specific violation categories (color contrast, ARIA, forms, keyboard navigation, etc.)  
 
 ### Browser Automation
-🖱️ Click elements by CSS selector or visible text  
-⌨️ Type text into inputs by selector or label  
-🔍 Analyze pages to discover all interactive elements  
-📸 Capture screenshots after each interaction  
-
-### Session Management
-🔄 Create persistent browser sessions for multi-step workflows  
-⏱️ Automatic session cleanup after 3 minutes of inactivity  
-🌐 Navigate between pages while maintaining session state  
-📊 Run accessibility scans within active sessions
+🖱️ Click, hover, and drag elements using accessibility snapshots  
+⌨️ Type text and handle keyboard inputs  
+🔍 Capture page snapshots to discover all interactive elements  
+📸 Take screenshots and save PDFs  
+🎯 Support for both element-based and coordinate-based interactions  
+
+### Advanced Features
+📑 Tab management for multi-page workflows  
+🌐 Monitor console messages and network requests  
+⏱️ Wait for dynamic content to load  
+📁 Handle file uploads and browser dialogs  
+🔄 Navigate through browser history
 
 ## Installation
 
@@ -33,25 +37,6 @@ Using npm:
 npm install -g mcp-accessibility-scanner
 ```
 
-### Docker Installation
-
-The project includes a Dockerfile that sets up all necessary dependencies including Node.js v22 and Python 3.13.
-
-1. Build the Docker image:
-```bash
-docker build -t mcp-server . 
-```
-
-2. Run the container:
-```bash
-docker run -it -e MCP_PROXY_DEBUG=true mcp-server
-```
-
-You can also run it in the background:
-```bash
-docker run -d -p 3000:3000 mcp-server
-```
-
 ### Installation in VS Code
 
 Install the Accessibility Scanner in VS Code using the VS Code CLI:
@@ -83,108 +68,189 @@ Here's the Claude Desktop configuration:
 
 ## Available Tools
 
-The MCP server exposes 18 tools for accessibility scanning and browser automation:
+The MCP server provides comprehensive browser automation and accessibility scanning tools:
 
-### Accessibility Scanning
+### Core Accessibility Tool
 
-#### `accessibility-scan`
-Performs a comprehensive accessibility scan on a webpage.
+#### `scan_page`
+Performs a comprehensive accessibility scan on the current page using Axe-core.
 
 **Parameters:**
-- `url`: The webpage URL to scan (required)
-- `violationsTag`: Array of WCAG/violation tags to check (required)
-- `viewport`: Optional viewport size (default: 1920x1080)
-- `shouldRunInHeadless`: Optional headless mode control (default: true)
+- `violationsTag`: Array of WCAG/violation tags to check
 
 **Supported Violation Tags:**
-- WCAG levels: `wcag2a`, `wcag2aa`, `wcag2aaa`, `wcag21a`, `wcag21aa`, `wcag21aaa`, `wcag22a`, `wcag22aa`, `wcag22aaa`
+- WCAG standards: `wcag2a`, `wcag2aa`, `wcag2aaa`, `wcag21a`, `wcag21aa`, `wcag21aaa`, `wcag22a`, `wcag22aa`, `wcag22aaa`
 - Section 508: `section508`
-- Categories: `cat.color` (contrast), `cat.aria`, `cat.forms`, `cat.keyboard`, `cat.language`, `cat.structure`, etc.
+- Categories: `cat.aria`, `cat.color`, `cat.forms`, `cat.keyboard`, `cat.language`, `cat.name-role-value`, `cat.parsing`, `cat.semantics`, `cat.sensory-and-visual-cues`, `cat.structure`, `cat.tables`, `cat.text-alternatives`, `cat.time-and-media`
 
-### Browser Automation
+### Navigation Tools
+
+#### `browser_navigate`
+Navigate to a URL.
+- Parameters: `url` (string)
+
+#### `browser_navigate_back`
+Go back to the previous page.
+
+#### `browser_navigate_forward`
+Go forward to the next page.
+
+### Page Interaction Tools
+
+#### `browser_snapshot`
+Capture accessibility snapshot of the current page (better than screenshot for analysis).
+
+#### `browser_click`
+Perform click on a web page element.
+- Parameters: `element` (description), `ref` (element reference), `doubleClick` (optional)
+
+#### `browser_type`
+Type text into editable element.
+- Parameters: `element`, `ref`, `text`, `submit` (optional), `slowly` (optional)
+
+#### `browser_hover`
+Hover over element on page.
+- Parameters: `element`, `ref`
+
+#### `browser_drag`
+Perform drag and drop between two elements.
+- Parameters: `startElement`, `startRef`, `endElement`, `endRef`
+
+#### `browser_select_option`
+Select an option in a dropdown.
+- Parameters: `element`, `ref`, `values` (array)
+
+#### `browser_press_key`
+Press a key on the keyboard.
+- Parameters: `key` (e.g., 'ArrowLeft' or 'a')
+
+### Screenshot & Visual Tools
+
+#### `browser_take_screenshot`
+Take a screenshot of the current page.
+- Parameters: `raw` (optional), `filename` (optional), `element` (optional), `ref` (optional)
 
-#### `click-element`
-Clicks an element by CSS selector.
-- Parameters: `url`, `selector`, `viewport`, `shouldRunInHeadless`
+#### `browser_pdf_save`
+Save page as PDF.
+- Parameters: `filename` (optional, defaults to `page-{timestamp}.pdf`)
 
-#### `click-element-by-text`
-Clicks elements by their visible text content.
-- Parameters: `url`, `text`, `elementType` (optional), `viewport`, `shouldRunInHeadless`
+### Browser Management
 
-#### `type-text`
-Types text into an input field by CSS selector.
-- Parameters: `url`, `selector`, `text`, `viewport`, `shouldRunInHeadless`
+#### `browser_close`
+Close the page.
 
-#### `type-text-by-label`
-Types text into input fields by their label text.
-- Parameters: `url`, `labelText`, `text`, `viewport`, `shouldRunInHeadless`
+#### `browser_resize`
+Resize the browser window.
+- Parameters: `width`, `height`
 
-#### `analyze-page`
-Analyzes page to identify all interactive elements.
-- Parameters: `url`, `viewport`, `shouldRunInHeadless`
-- Returns: Lists of all buttons, links, and inputs on the page
+### Tab Management
 
-### Session Management
+#### `browser_tab_list`
+List all open browser tabs.
 
-#### `create-session`
-Creates a persistent browser session for multiple operations.
-- Parameters: `sessionId`, `viewport`, `shouldRunInHeadless`
-- Sessions auto-expire after 3 minutes of inactivity
+#### `browser_tab_new`
+Open a new tab.
+- Parameters: `url` (optional)
 
-#### `navigate-session`
-Navigates to a URL in an existing session.
-- Parameters: `sessionId`, `url`
+#### `browser_tab_select`
+Select a tab by index.
+- Parameters: `index`
 
-#### `click-session` / `click-session-by-text`
-Click elements within a session.
+#### `browser_tab_close`
+Close a tab.
+- Parameters: `index` (optional, closes current tab if not provided)
 
-#### `type-session` / `type-session-by-label`
-Type text within a session.
+### Information & Monitoring Tools
 
-#### `scan-session`
-Run accessibility scan on current page in session.
+#### `browser_console_messages`
+Returns all console messages from the page.
 
-#### `analyze-session`
-Analyze current page in session.
+#### `browser_network_requests`
+Returns all network requests since loading the page.
 
-#### `close-session`
-Close a browser session.
+### Utility Tools
 
-#### `list-sessions`
-List all active browser sessions.
+#### `browser_wait_for`
+Wait for text to appear/disappear or time to pass.
+- Parameters: `time` (optional), `text` (optional), `textGone` (optional)
+
+#### `browser_handle_dialog`
+Handle browser dialogs (alerts, confirms, prompts).
+- Parameters: `accept` (boolean), `promptText` (optional)
+
+#### `browser_file_upload`
+Upload files to the page.
+- Parameters: `paths` (array of absolute file paths)
+
+### Vision Mode Tools (Coordinate-based Interaction)
+
+#### `browser_screen_capture`
+Take a screenshot for coordinate-based interaction.
+
+#### `browser_screen_move_mouse`
+Move mouse to specific coordinates.
+- Parameters: `element`, `x`, `y`
+
+#### `browser_screen_click`
+Click at specific coordinates.
+- Parameters: `element`, `x`, `y`
+
+#### `browser_screen_drag`
+Drag from one coordinate to another.
+- Parameters: `element`, `startX`, `startY`, `endX`, `endY`
+
+#### `browser_screen_type`
+Type text (coordinate-independent).
+- Parameters: `text`, `submit` (optional)
 
 ## Usage Examples
 
 ### Basic Accessibility Scan
 ```
-Could you scan example.com for WCAG 2.1 AA compliance issues?
+1. Navigate to example.com using browser_navigate
+2. Run scan_page with violationsTag: ["wcag21aa"]
 ```
 
 ### Color Contrast Check
 ```
-Please check example.com for color contrast accessibility issues (cat.color).
+1. Use browser_navigate to go to example.com
+2. Run scan_page with violationsTag: ["cat.color"]
 ```
 
-### Multi-step Workflow with Sessions
+### Multi-step Workflow
 ```
-1. Create a session and navigate to example.com
-2. Click the "Sign In" button
-3. Type "user@example.com" into the email field
-4. Run an accessibility scan on the login page
-5. Close the session
+1. Navigate to example.com with browser_navigate
+2. Take a browser_snapshot to see available elements
+3. Click the "Sign In" button using browser_click
+4. Type "user@example.com" using browser_type
+5. Run scan_page on the login page
+6. Take a browser_take_screenshot to capture the final state
 ```
 
 ### Page Analysis
 ```
-Can you analyze example.com and tell me what interactive elements are available?
+1. Navigate to example.com
+2. Use browser_snapshot to capture all interactive elements
+3. Review console messages with browser_console_messages
+4. Check network activity with browser_network_requests
 ```
 
-### Smart Element Interaction
+### Tab Management
 ```
-Navigate to example.com and click the button that says "Get Started"
+1. Open a new tab with browser_tab_new
+2. Navigate to different pages in each tab
+3. Switch between tabs using browser_tab_select
+4. List all tabs with browser_tab_list
 ```
 
-**Note:** All tools automatically save annotated screenshots to your downloads folder, with accessibility violations highlighted in red and numbered badges.
+### Waiting for Dynamic Content
+```
+1. Navigate to a page
+2. Use browser_wait_for to wait for specific text to appear
+3. Interact with the dynamically loaded content
+```
+
+**Note:** Most interaction tools require element references from browser_snapshot. Always capture a snapshot before attempting to interact with page elements.
 
 ## Development
 
@@ -195,42 +261,6 @@ cd mcp-accessibility-scanner
 npm install
 ```
 
-Start the TypeScript compiler in watch mode:
-```bash
-npm run watch
-```
-
-Test the MCP server locally:
-```bash
-npm run inspector
-```
-
-### Docker Development
-
-For development using Docker:
-
-1. Build the development image:
-```bash
-docker build -t mcp-server-dev .
-```
-
-2. Run with volume mounting for live code changes:
-```bash
-docker run -it -v $(pwd):/app -p 3000:3000 -e MCP_PROXY_DEBUG=true mcp-server-dev
-```
-
-## Project Structure
-
-```
-├── src/              # Source code
-│   ├── index.ts     # MCP server setup and tool definitions
-│   └── scanner.ts   # Core scanning functionality
-├── build/           # Compiled JavaScript output
-├── Dockerfile       # Docker configuration for containerized setup
-├── package.json     # Project configuration and dependencies
-└── tsconfig.json    # TypeScript configuration
-```
-
 ## License
 
 MIT

package/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import './lib/program.js';

package/package.json

@@ -1,31 +1,60 @@
 {
 	"name": "mcp-accessibility-scanner",
-	"version": "1.0.11",
+	"version": "1.1.1",
+	"mcpName": "io.github.JustasMonkev/mcp-accessibility-scanner",
 	"description": "A Model Context Protocol (MCP) server for performing automated accessibility scans of web pages using Playwright and Axe-core",
-	"main": "build/index.js",
-	"types": "build/index.d.ts",
+	"type": "module",
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		}
+	},
 	"bin": {
-		"mcp-accessibility-scanner": "build/server.js"
+		"mcp-server-playwright": "cli.js"
 	},
 	"files": [
-		"build/**/*",
+		"lib/**/*",
 		"README.md",
-		"LICENSE"
+		"LICENSE",
+		"NOTICE.md"
 	],
 	"scripts": {
-		"build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755') && require('fs').chmodSync('build/server.js', '755')\"",
-		"prepare": "npm run build",
+		"build": "tsc --project tsconfig.json",
+		"lint": "npm run update-readme && eslint . && tsc --noEmit",
+		"update-readme": "node utils/update-readme.js",
 		"watch": "tsc --watch",
-		"inspector": "npx @modelcontextprotocol/inspector build/index.js"
+		"run-server": "node lib/browserServer.js",
+		"clean": "rm -rf lib",
+		"npm-publish": "npm run clean && npm run build && npm publish"
 	},
 	"dependencies": {
 		"@axe-core/playwright": "^4.10.2",
-		"@modelcontextprotocol/sdk": "^1.13.0",
-		"@playwright/test": "^1.53.1"
+		"@modelcontextprotocol/sdk": "^1.16.0",
+		"commander": "^14.0.0",
+		"debug": "^4.4.1",
+		"mime": "^4.0.7",
+		"playwright": "^1.54.1",
+		"playwright-core": "^1.54.1",
+		"ws": "^8.18.3",
+		"zod-to-json-schema": "^3.24.6"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.0.4",
-		"@types/node": "^24.0.3",
+		"@eslint/eslintrc": "^3.3.1",
+		"@eslint/js": "^9.31.0",
+		"@playwright/test": "^1.54.1",
+		"@stylistic/eslint-plugin": "^5.2.0",
+		"@types/chrome": "^0.1.1",
+		"@types/debug": "^4.1.12",
+		"@types/node": "^24.0.15",
+		"@types/ws": "^8.18.1",
+		"@typescript-eslint/eslint-plugin": "^8.37.0",
+		"@typescript-eslint/parser": "^8.37.0",
+		"@typescript-eslint/utils": "^8.37.0",
+		"eslint": "^9.31.0",
+		"eslint-plugin-import": "^2.32.0",
+		"eslint-plugin-notice": "^1.0.0",
 		"ts-node": "^10.9.2",
 		"typescript": "^5.8.3"
 	},