Contributing Overview

Thank you for your interest in contributing to AccessibilityHub! This guide will help you get started with development.

Quick Links

Project Structure

Detailed explanation of the codebase organization

Creating Tools

Guide for creating new accessibility tools

GitHub Repository

View the source code and open issues

Report Issues

Report bugs or request features

Requirements

Node.js ≥ 20

Check version in .nvmrc

node --version

pnpm

Package manager (v10.26.2+)

npm install -g pnpm

Chrome/Chromium

Automatically downloaded by Puppeteer

Getting Started

Clone and install

git clone https://github.com/drzkn/A-I-ccesibility.git
cd A-I-ccesibility
pnpm install

Build the project

pnpm build

This compiles TypeScript to the dist/ folder using tsup.

Run the server

pnpm start

This starts the MCP server. Use with an MCP client to test.

Development mode

pnpm dev

Watch mode - automatically rebuilds on file changes.

Available Scripts

Script	Description
`pnpm build`	Build the project with tsup
`pnpm dev`	Watch mode - rebuilds on file changes
`pnpm start`	Run the compiled MCP server
`pnpm typecheck`	Run TypeScript type checking
`pnpm clean`	Remove the dist folder
`pnpm format`	Format code with Prettier
`pnpm format:check`	Check code formatting
`pnpm test`	Run tests once
`pnpm test:watch`	Run tests in watch mode
`pnpm test:coverage`	Run tests with coverage report
`pnpm inspect`	Build and open MCP Inspector for debugging

Development Workflow

Create a feature branch

git checkout -b feature/your-feature-name

Use descriptive branch names:

feature/add-wcag-3-support
fix/contrast-calculation-bug
docs/improve-setup-guide

Make your changes

Follow the project conventions:

Use TypeScript strict mode
Follow existing code style
Add tests for new functionality
Update documentation

Test your changes

pnpm typecheck        # Type checking
pnpm format:check     # Code formatting
pnpm test             # Run tests
pnpm build            # Verify build

Debug with MCP Inspector

pnpm inspect

This opens the MCP Inspector connected to your local server for interactive testing.

Commit your changes

git add .
git commit -m "feat: add WCAG 3.0 APCA support"

Use Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation
refactor: Code refactoring
test: Tests
chore: Build/tooling

Push and create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub with:

Clear description of changes
Link to related issue (if any)
Screenshots/examples if applicable

Code Style

TypeScript

// Use explicit types
export interface AnalysisResult {
  issueCount: number;
  issues: Issue[];
  summary: Summary;
}

// Use async/await
export async function analyzeUrl(url: string): Promise<AnalysisResult> {
  const result = await adapter.analyze(url);
  return normalizeResult(result);
}

Naming Conventions

Folders

Tool folders: PascalCase (Axe, Pa11y, AnalyzeMixed)
Subfolders: lowercase (adapters, normalizers, types, utils)

Files

Use kebab-case or toolname.category.ts pattern
Examples: main.ts, index.ts, pa11y.adapter.ts, axe.types.ts
Each subfolder must have index.ts that re-exports
JSON files: kebab-case (wcag-criteria.json)

Variables and Functions

Variables/functions: camelCase (analyzeUrl, issueCount)
Constants: UPPER_SNAKE_CASE (DEFAULT_TIMEOUT, MAX_RETRIES)
Interfaces/Types: PascalCase (AnalysisResult, ToolConfig)
Enums: PascalCase for name, PascalCase for values

Formatting

Prettier handles formatting automatically:

pnpm format          # Format all files
pnpm format:check    # Check formatting

Prettier config:

2 spaces indentation
Single quotes
Trailing commas
Semicolons

Testing

Tests are located in tests/, mirroring the src/ structure.

Running Tests

pnpm test              # Run all tests
pnpm test:watch        # Watch mode
pnpm test:coverage     # With coverage report

Writing Tests

// tests/tools/Axe/axe.test.ts
import { describe, it, expect } from 'vitest';
import { analyzeWithAxeTool } from '../../../src/tools/Axe';
import { createMockServer } from '../../helpers/mock-server';

describe('Axe Tool', () => {
  it('should analyze URL and return issues', async () => {
    const server = createMockServer();
    const result = await analyzeWithAxeTool.handler({
      url: 'https://example.com',
      options: { wcagLevel: 'AA' }
    });
    
    expect(result.success).toBe(true);
    expect(result.issues).toBeInstanceOf(Array);
  });
});

Test Helpers

Helper	Location	Purpose
`mock-server.ts`	`tests/helpers/`	Mock MCP server for tool testing
`mock-prompt-server.ts`	`tests/helpers/`	Mock server for prompt testing
`mock-resource-server.ts`	`tests/helpers/`	Mock server for resource testing
`html-fixtures.ts`	`tests/fixtures/`	HTML fixtures for testing
`axe-fixtures.ts`	`tests/fixtures/`	Mock axe-core results

Debugging with MCP Inspector

The MCP Inspector is a powerful tool for testing your changes:

Start inspector

pnpm inspect

This builds the project and opens the inspector in your browser.

Test tools

In the inspector:

Select a tool from the dropdown
Fill in the parameters (url, options, etc.)
Click “Call Tool”
View the response

Test prompts

Select a prompt from the dropdown
Fill in the arguments
Click “Get Prompt”
View the generated prompt text

Test resources

Enter a resource URI (e.g., wcag://criteria/1.1.1)
Click “Read Resource”
View the resource data

The MCP Inspector automatically reloads when you run pnpm build, making it easy to iterate on changes.

Pull Request Guidelines

Before Submitting

Run all checks

pnpm format:check     # Verify formatting
pnpm typecheck        # Check types
pnpm test             # Run tests
pnpm build            # Verify build

Update documentation

If adding new features:

Update relevant docs in docs/
Add JSDoc comments to public APIs
Update CHANGELOG.md if applicable

Add tests

Add tests for new functionality
Ensure coverage doesn’t decrease
Test edge cases and error conditions

PR Description Template

## Description

Brief description of changes

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing

Describe how you tested your changes:
- [ ] Unit tests pass
- [ ] Manual testing with MCP Inspector
- [ ] Tested with Claude Desktop/Cursor/etc.

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

## Related Issues

Fixes #(issue number)

Review Process

Automated checks run on PR creation (build, tests, linting)
Code review by maintainers
Testing by maintainers with MCP Inspector
Merge once approved and checks pass

Project Structure

For detailed information about the codebase organization, see:

Project Structure

Comprehensive guide to the project’s architecture and organization

Creating New Tools

For step-by-step instructions on creating new accessibility tools:

Creating Tools

Guide for creating new tools following the project conventions

Questions?

If you have questions or need help:

Open an Issue

Ask questions or report problems

Discussions

Join the community discussion

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Key principles:

Be respectful and inclusive
Welcome newcomers
Accept constructive criticism gracefully
Focus on what is best for the community

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Get Started

Core Concepts

Guides

Contributing

Quick Links

Project Structure

Creating Tools

GitHub Repository

Report Issues

Requirements

Node.js ≥ 20

pnpm

Chrome/Chromium

Getting Started

Available Scripts

Development Workflow

Code Style

TypeScript

Naming Conventions

Formatting

Testing

Running Tests

Writing Tests

Test Helpers

Debugging with MCP Inspector

Pull Request Guidelines

Before Submitting

PR Description Template

Review Process

Project Structure

Project Structure

Creating New Tools

Creating Tools

Questions?

Open an Issue

Discussions

Code of Conduct

License

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Contributing

​Quick Links

Project Structure

Creating Tools

GitHub Repository

Report Issues

​Requirements

Node.js ≥ 20

pnpm

Chrome/Chromium

​Getting Started

​Available Scripts

​Development Workflow

​Code Style

​TypeScript

​Naming Conventions

​Formatting

​Testing

​Running Tests

​Writing Tests

​Test Helpers

​Debugging with MCP Inspector

​Pull Request Guidelines

​Before Submitting

​PR Description Template

​Review Process

​Project Structure

Project Structure

​Creating New Tools

Creating Tools

​Questions?

Open an Issue

Discussions

​Code of Conduct

​License

Build docs developers (and LLMs) love

Quick Links

Requirements

Getting Started

Available Scripts

Development Workflow

Code Style

TypeScript

Naming Conventions

Formatting

Testing

Running Tests

Writing Tests

Test Helpers

Debugging with MCP Inspector

Pull Request Guidelines

Before Submitting

PR Description Template

Review Process

Project Structure

Creating New Tools

Questions?

Code of Conduct

License