MCP Server Architecture

Defines the package boundary, responsibilities, and security model for the A11YSmith MCP (Model Context Protocol) server.

Package Boundary

The MCP server lives in packages/mcp-server/ as a standalone package (@a11ysmith/mcp-server).

packages/mcp-server/
  src/
    server.ts              # createServer() — configured MCP server
    bin.ts                 # CLI entry point (stdio transport)
    index.ts               # Package exports
    tools/
      index.ts             # registerAllTools() barrel
      lookup-standard.ts
      lookup-rule.ts
      list-agents.ts
      check-contrast.ts
      get-crosswalk.ts
      lookup-knowledge.ts
      lookup-context-pack.ts
      verify-sources.ts
      get-remediation.ts
    __tests__/
      server.test.ts
      integration.test.ts
      get-remediation.test.ts
  package.json
  tsconfig.json

Dependencies: @a11ysmith/schemas, @a11ysmith/core, @a11ysmith/standards, @a11ysmith/agents, @a11ysmith/web-auditor, @a11ysmith/android-auditor, @a11ysmith/ios-auditor

The MCP server is a consumer of the other packages, not a dependency of them.

Responsibilities

The MCP server exposes A11YSmith capabilities as MCP tools that AI assistants can invoke:

Current Tools (9 tools)

Maintained MCP tools
Tool	Purpose	Delegates to
`lookup_standard`	Look up a TAS or WCAG standard by ID, category, or platform	`@a11ysmith/standards` catalog
`lookup_rule`	Look up audit rules by ID or list all (web, Android, iOS — 59 total)	`@a11ysmith/web-auditor`, `@a11ysmith/android-auditor`, `@a11ysmith/ios-auditor`
`list_agents`	List agents by team, or get agent details	`@a11ysmith/agents` manifest
`check_contrast`	Calculate WCAG contrast ratio between two hex colors	`@a11ysmith/agents` contrast knowledge module
`get_crosswalk`	Get TAS-WCAG crosswalk mapping	`@a11ysmith/standards` crosswalk engine
`lookup_knowledge_module`	Look up knowledge module by domain/topic (web, document, markdown, android, ios)	`@a11ysmith/agents` knowledge registries
`lookup_context_pack`	Look up context pack by ID	`@a11ysmith/agents` context pack registry
`verify_sources`	Run governance verification on knowledge sources	`@a11ysmith/agents` governance engine
`get_remediation`	Get cross-platform remediation guidance for a finding by rule ID	`@a11ysmith/core` finding adapter, `@a11ysmith/agents` technique catalogs

Wrapper-Only Tools (generated, not in maintained package)

Generated wrapper tools
Tool	Purpose	Why not in maintained package
`audit_web`	Run a web accessibility audit on a URL	Requires Playwright browser runtime
`audit_document`	Run document accessibility audit	Requires document parser libraries

Design Principles

No logic duplication. Every tool delegates to an existing package export. The contrast tool uses contrastRatioRgb() from the agents package, not a reimplemented formula.
createServer() as the API. Consumers call createServer() to get a fully configured McpServer. The bin entry point adds stdio transport on top.
Tools are individually registrable. Each tool exports a registerXxx(server) function. Consumers can cherry-pick tools if needed.
All inputs validated by Zod schemas. The MCP SDK handles schema enforcement before handlers execute.

Ownership Boundary

Ownership boundaries
Concern	Owner	Why
Knowledge, lookup, and remediation tools (9 tools)	`@a11ysmith/mcp-server`	Canonical, tested, version-controlled
Local transport (stdio)	Generated wrapper	Platform-specific
Path validation (CWE-22/CWE-59)	Generated wrapper	Environment-specific
CLI-delegation tools (`audit_web`, `audit_document`)	Generated wrapper	Require local `a11ysmith` binary, not portable as library code

Rule for contributors: If a tool operates purely on in-memory data structures, it belongs in @a11ysmith/mcp-server. If it requires local filesystem access, process spawning, or environment-specific configuration, it belongs in the generated wrapper.

Relationship to Generators

The Claude Desktop generator (packages/agents/src/generators/claude-desktop/) produces a thin wrapper that imports createServer() from @a11ysmith/mcp-server and adds two CLI-delegation tools on top:

The maintained package provides the canonical 9-tool implementation
The wrapper adds audit_web and audit_document (CLI delegation)
The wrapper handles transport, path validation, and environment wiring

Usage

As a CLI

# Direct invocation
npx @a11ysmith/mcp-server

# Or via the bin alias
a11ysmith-mcp

As a library

import { createServer } from '@a11ysmith/mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createServer({ name: 'my-a11y-server', version: '1.0.0' });
await server.connect(new StdioServerTransport());

Claude Desktop configuration

{
  "mcpServers": {
    "a11ysmith": {
      "command": "npx",
      "args": ["@a11ysmith/mcp-server"]
    }
  }
}

Scope

In scope: Read-only lookups, calculations, and remediation guidance that delegate to existing package data. All 9 tools operate on in-memory data structures — no file I/O, no browser automation, no network calls.

Intentionally out of scope for the maintained package:

audit_web — Requires Playwright browser runtime. Available in the generated wrapper via CLI delegation.
audit_document — Requires document parser libraries (adm-zip, pdf-parse). Available in the generated wrapper via CLI delegation.
Mobile backward-compat modules — The structured reference data in knowledge/mobile/ (React Native props, iOS traits, Android attrs) are not KnowledgeModule instances and are not exposed via MCP. They exist for direct agent consumption only. Migration to first-class KnowledgeModule instances is planned for Phase 4.

Security Requirements

MCP server must not expose file system paths outside the project directory
MCP server must not transmit audit artifacts containing PII without sanitization
MCP server must validate all tool inputs before processing
MCP server must use the report sanitizer for any output that may contain sensitive data
MCP server must not store credentials or tokens

Current Status

Phase 3: Complete. The @a11ysmith/mcp-server package is a maintained package with 9 tools, 68 tests (data layer + integration + remediation), cross-platform rule coverage (26 web, 15 Android, 18 iOS — 59 total), full 5-domain knowledge coverage (web, document, markdown, android, ios), and full delegation to existing packages. The get_remediation tool provides TAS-first remediation with WCAG fallback, AT-specific validation steps, and cross-platform technique resolution via the finding adapter in @a11ysmith/core. The Claude Desktop generator produces a thin wrapper that imports from this package and adds 2 CLI-delegation tools (audit_web, audit_document).