arc-templated-issues-mcp 1.0.0

package/README.md

@@ -0,0 +1,101 @@
+# arc-templated-issues-mcp
+
+ARC accessibility issue templates as an MCP server. Converts AxeCore violations into formatted issue templates and provides access to web and native accessibility issue templates.
+
+## Usage
+
+Add to your Claude Desktop / Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "arc-issues": {
+      "command": "npx",
+      "args": ["-y", "arc-templated-issues-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_issue_templates` | Lists available accessibility issue template files (web and native). |
+| `get_issue_template` | Returns the full content of a template by name (`web-issue-templates.md` or `native-issue-templates.md`). |
+| `format_violations` | Converts one or more AxeCore violations into formatted markdown or JSON issue templates. |
+| `validate_issue` | Validates that a formatted issue contains all required sections. |
+
+### `format_violations`
+
+Accepts standard AxeCore violation objects and returns structured issue templates ready for filing.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `violations` | object or array | Yes | Single AxeCore violation or array of violations |
+| `context` | object | No | Page context: `url`, `browser`, `operatingSystem`, `buildVersion`, `stepsToReproduce` |
+| `outputFormat` | `"markdown"` \| `"json"` | No | Defaults to `"markdown"` |
+
+**Example input:**
+```json
+{
+  "violations": [{
+    "id": "button-name",
+    "impact": "critical",
+    "tags": ["wcag412", "wcag244"],
+    "description": "Ensures buttons have discernible text",
+    "help": "Buttons must have discernible text",
+    "helpUrl": "https://dequeuniversity.com/rules/axe/4.10/button-name",
+    "nodes": [{
+      "html": "<button></button>",
+      "target": [".cta-button"],
+      "failureSummary": "Element does not have inner text that is visible to screen readers"
+    }]
+  }],
+  "context": { "url": "https://example.com/checkout" }
+}
+```
+
+## Templates
+
+Templates are sourced from the [`arc-templated-issues`](https://gitlab.com/tmobile/arc/arc-templated-issues) npm package.
+
+| Template | Platform | Contents |
+|----------|----------|----------|
+| `web-issue-templates.md` | Web | Control labeling, heading structure, images, keyboard access, link text, contrast, focus management, semantic HTML |
+| `native-issue-templates.md` | Native (iOS/Android) | Button labels, focus order, heading traits, decorative images, grouping, state communication |
+
+## Project Structure
+
+```
+src/
+  index.js              MCP server (stdio transport)
+  tools.js              Tool definitions and handlers
+data/
+  template-index.json   Routing — maps template names to paths within arc-templated-issues
+```
+
+## Development
+
+```bash
+git clone <repo-url>
+npm install
+npm start
+```
+
+## npm scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm start` | Start the MCP server |
+| `npm run release:patch` | Bump patch version and publish to npm |
+| `npm run release:minor` | Bump minor version and publish to npm |
+| `npm run release:major` | Bump major version and publish to npm |
+
+## Learn More
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [ARC Accessibility Issue Templates](https://gitlab.com/tmobile/arc/arc-templated-issues)

package/data/template-index.json

@@ -0,0 +1,20 @@
+{
+  "version": "1.0.0",
+  "description": "Routes accessibility issue template requests to markdown source files",
+  "packageName": "arc-templated-issues",
+  "templates": [
+    {
+      "name": "web-issue-templates.md",
+      "platform": "web",
+      "path": "public/web-issue-templates.md",
+      "description": "Web accessibility issue templates (AxeCore-compatible)"
+    },
+    {
+      "name": "native-issue-templates.md",
+      "platform": "native",
+      "path": "public/native-issue-templates.md",
+      "description": "Native iOS/Android accessibility issue templates"
+    }
+  ],
+  "defaultTemplate": "web-issue-templates.md"
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "arc-templated-issues-mcp",
+  "version": "1.0.0",
+  "description": "ARC accessibility issue templates MCP server",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "arc-templated-issues-mcp": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "data/template-index.json"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node src/index.js",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "arc-templated-issues": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { tools } from './tools.js';
+
+/**
+ * Create and configure the MCP server for local (stdio) use
+ */
+const server = new Server(
+  {
+    name: 'arc-templated-issues-mcp',
+    version: '1.0.0',
+    description: 'ARC accessibility issue templates MCP server — formats AxeCore violations and provides web/native issue templates',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+/**
+ * Handler for listing available tools
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: tools.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema
+    }))
+  };
+});
+
+/**
+ * Handler for calling tools
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const tool = tools.find(t => t.name === request.params.name);
+  
+  if (!tool) {
+    throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+  
+  // Execute tool handler
+  return await tool.handler(request.params.arguments);
+});
+
+/**
+ * Start the server with stdio transport
+ */
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('arc-templated-issues-mcp MCP server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Fatal error in main():', error);
+  process.exit(1);
+});

package/src/tools.js

@@ -0,0 +1,342 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = resolve(__dirname, '../data');
+const require = createRequire(import.meta.url);
+
+async function loadIndex() {
+  const raw = await readFile(resolve(DATA_DIR, 'template-index.json'), 'utf8');
+  return JSON.parse(raw);
+}
+
+function resolvePackageDir(packageName) {
+  const pkgJson = require.resolve(`${packageName}/package.json`);
+  return dirname(pkgJson);
+}
+
+async function readTemplate(entry, packageName) {
+  const pkgDir = resolvePackageDir(packageName);
+  return readFile(resolve(pkgDir, entry.path), 'utf8');
+}
+
+function textResponse(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+// AxeCore impact → severity/priority
+const IMPACT_MAP = {
+  critical: { severity: '1-Critical', priority: 'Blocker' },
+  serious:  { severity: '2-Severe',   priority: 'High' },
+  moderate: { severity: '3-Average',  priority: 'Medium' },
+  minor:    { severity: '4-Low',      priority: 'Low' },
+};
+
+// AxeCore WCAG tag strings → human-readable criteria
+const WCAG_TAGS = {
+  wcag111: '1.1.1 (Level A)',
+  wcag121: '1.2.1 (Level A)',
+  wcag122: '1.2.2 (Level A)',
+  wcag123: '1.2.3 (Level A)',
+  wcag124: '1.2.4 (Level AA)',
+  wcag125: '1.2.5 (Level AA)',
+  wcag131: '1.3.1 (Level A)',
+  wcag132: '1.3.2 (Level A)',
+  wcag133: '1.3.3 (Level A)',
+  wcag134: '1.3.4 (Level AA)',
+  wcag135: '1.3.5 (Level AA)',
+  wcag141: '1.4.1 (Level A)',
+  wcag142: '1.4.2 (Level A)',
+  wcag143: '1.4.3 (Level AA)',
+  wcag144: '1.4.4 (Level AA)',
+  wcag145: '1.4.5 (Level AA)',
+  wcag1410: '1.4.10 (Level AA)',
+  wcag1411: '1.4.11 (Level AA)',
+  wcag1412: '1.4.12 (Level AA)',
+  wcag1413: '1.4.13 (Level AA)',
+  wcag211: '2.1.1 (Level A)',
+  wcag212: '2.1.2 (Level A)',
+  wcag214: '2.1.4 (Level A)',
+  wcag221: '2.2.1 (Level A)',
+  wcag222: '2.2.2 (Level A)',
+  wcag231: '2.3.1 (Level A)',
+  wcag241: '2.4.1 (Level A)',
+  wcag242: '2.4.2 (Level A)',
+  wcag243: '2.4.3 (Level A)',
+  wcag244: '2.4.4 (Level A)',
+  wcag245: '2.4.5 (Level AA)',
+  wcag246: '2.4.6 (Level AA)',
+  wcag247: '2.4.7 (Level AA)',
+  wcag248: '2.4.8 (Level AAA)',
+  wcag249: '2.4.9 (Level AAA)',
+  wcag251: '2.5.1 (Level A)',
+  wcag252: '2.5.2 (Level A)',
+  wcag253: '2.5.3 (Level A)',
+  wcag254: '2.5.4 (Level A)',
+  wcag311: '3.1.1 (Level A)',
+  wcag312: '3.1.2 (Level AA)',
+  wcag321: '3.2.1 (Level A)',
+  wcag322: '3.2.2 (Level A)',
+  wcag323: '3.2.3 (Level AA)',
+  wcag324: '3.2.4 (Level AA)',
+  wcag331: '3.3.1 (Level A)',
+  wcag332: '3.3.2 (Level A)',
+  wcag333: '3.3.3 (Level AA)',
+  wcag334: '3.3.4 (Level AA)',
+  wcag411: '4.1.1 (Level A)',
+  wcag412: '4.1.2 (Level A)',
+  wcag413: '4.1.3 (Level AA)',
+};
+
+function parseWcagTags(tags) {
+  return tags
+    .filter(t => t.startsWith('wcag') && /\d/.test(t))
+    .map(t => WCAG_TAGS[t])
+    .filter(Boolean);
+}
+
+function extractElementType(html) {
+  const match = html && html.match(/^<([a-z][a-z0-9-]*)/i);
+  return match ? match[1].toLowerCase() : 'unknown';
+}
+
+function formatViolationAsMarkdown(violation, node, context) {
+  const impact = (violation.impact || 'moderate').toLowerCase();
+  const { severity, priority } = IMPACT_MAP[impact] || IMPACT_MAP.moderate;
+  const wcagCriteria = parseWcagTags(violation.tags || []);
+  const elementType = extractElementType(node.html);
+  const selector = Array.isArray(node.target) ? node.target.join(', ') : (node.target || '');
+
+  const lines = [
+    `## ${violation.help || violation.description}`,
+    '',
+    `**Severity:** ${severity}  `,
+    `**Priority:** ${priority}`,
+    '',
+    '### Problem Statement',
+    violation.description || '',
+    '',
+    '### Element',
+    `- **Type:** \`${elementType}\``,
+    `- **Selector:** \`${selector}\``,
+    '',
+    '### Code Reference',
+    '```html',
+    node.html || '',
+    '```',
+    '',
+    '### Failure Summary',
+    node.failureSummary || '',
+    '',
+  ];
+
+  if (wcagCriteria.length > 0) {
+    lines.push('### WCAG Criteria');
+    wcagCriteria.forEach(c => lines.push(`- ${c}`));
+    lines.push('');
+  }
+
+  if (violation.helpUrl) {
+    lines.push(`### Resources`);
+    lines.push(`- [Axe Rule: ${violation.id}](${violation.helpUrl})`);
+    lines.push('');
+  }
+
+  if (context) {
+    lines.push('### Environment');
+    if (context.url) lines.push(`- **URL:** ${context.url}`);
+    if (context.browser) lines.push(`- **Browser:** ${context.browser}`);
+    if (context.operatingSystem) lines.push(`- **OS:** ${context.operatingSystem}`);
+    if (context.buildVersion) lines.push(`- **Build:** ${context.buildVersion}`);
+    if (context.stepsToReproduce) {
+      lines.push('');
+      lines.push('**Steps to Reproduce:**');
+      lines.push(context.stepsToReproduce);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatViolationAsJSON(violation, node, context) {
+  const impact = (violation.impact || 'moderate').toLowerCase();
+  const { severity, priority } = IMPACT_MAP[impact] || IMPACT_MAP.moderate;
+  const wcagCriteria = parseWcagTags(violation.tags || []);
+  const elementType = extractElementType(node.html);
+  const selector = Array.isArray(node.target) ? node.target.join(', ') : (node.target || '');
+
+  return {
+    ruleId: violation.id,
+    severity,
+    priority,
+    wcagCriteria,
+    problemStatement: violation.description || '',
+    impact: violation.impact,
+    element: {
+      type: elementType,
+      selector,
+      html: node.html || '',
+    },
+    failureSummary: node.failureSummary || '',
+    helpUrl: violation.helpUrl || '',
+    ...(context ? { context } : {}),
+  };
+}
+
+export const tools = [
+  {
+    name: 'list_issue_templates',
+    description: 'Lists all available accessibility issue template files (web and native).',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+    handler: async () => {
+      const index = await loadIndex();
+      const lines = index.templates.map(
+        t => `- **${t.name}** (${t.platform}): ${t.description}`
+      );
+      return textResponse(`Available templates:\n\n${lines.join('\n')}`);
+    },
+  },
+
+  {
+    name: 'get_issue_template',
+    description: 'Retrieves the full content of an accessibility issue template by name.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        templateName: {
+          type: 'string',
+          description: 'Template filename, e.g. "web-issue-templates.md" or "native-issue-templates.md"',
+        },
+      },
+      required: ['templateName'],
+    },
+    handler: async (args) => {
+      const index = await loadIndex();
+      const entry = index.templates.find(t => t.name === args.templateName);
+      if (!entry) {
+        const names = index.templates.map(t => t.name).join(', ');
+        return textResponse(`Template "${args.templateName}" not found. Available: ${names}`);
+      }
+      const content = await readTemplate(entry, index.packageName);
+      return textResponse(content);
+    },
+  },
+
+  {
+    name: 'format_violations',
+    description:
+      'Converts one or more AxeCore accessibility violations into formatted issue templates.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        violations: {
+          description:
+            'A single AxeCore violation object or an array of them.',
+          oneOf: [
+            { type: 'object' },
+            { type: 'array', items: { type: 'object' } },
+          ],
+        },
+        context: {
+          type: 'object',
+          description: 'Optional context about the page/environment.',
+          properties: {
+            url: { type: 'string' },
+            browser: { type: 'string' },
+            operatingSystem: { type: 'string' },
+            buildVersion: { type: 'string' },
+            stepsToReproduce: { type: 'string' },
+          },
+        },
+        outputFormat: {
+          type: 'string',
+          enum: ['markdown', 'json'],
+          description: 'Output format. Defaults to "markdown".',
+        },
+      },
+      required: ['violations'],
+    },
+    handler: async (args) => {
+      const violations = Array.isArray(args.violations)
+        ? args.violations
+        : [args.violations];
+      const context = args.context || null;
+      const format = args.outputFormat === 'json' ? 'json' : 'markdown';
+
+      const results = [];
+      for (const violation of violations) {
+        const nodes = violation.nodes || [{}];
+        for (const node of nodes) {
+          if (format === 'json') {
+            results.push(formatViolationAsJSON(violation, node, context));
+          } else {
+            results.push(formatViolationAsMarkdown(violation, node, context));
+          }
+        }
+      }
+
+      if (format === 'json') {
+        return textResponse(JSON.stringify(results, null, 2));
+      }
+      return textResponse(results.join('\n---\n\n'));
+    },
+  },
+
+  {
+    name: 'validate_issue',
+    description: 'Validates that a formatted accessibility issue contains all required sections.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        issueContent: {
+          type: 'string',
+          description: 'The formatted issue content (markdown string) to validate.',
+        },
+      },
+      required: ['issueContent'],
+    },
+    handler: async (args) => {
+      const content = args.issueContent || '';
+
+      const checks = [
+        {
+          label: 'Severity',
+          pass: /\*\*Severity\*\*\s*:/i.test(content) || /severity/i.test(content),
+        },
+        {
+          label: 'Priority',
+          pass: /\*\*Priority\*\*\s*:/i.test(content) || /priority/i.test(content),
+        },
+        {
+          label: 'Element or selector reference',
+          pass: /selector|element|`[^`]+`/i.test(content),
+        },
+        {
+          label: 'Code block',
+          pass: /```/.test(content),
+        },
+        {
+          label: 'Failure or problem description',
+          pass: /failure|problem|issue|description/i.test(content),
+        },
+      ];
+
+      const failures = checks.filter(c => !c.pass).map(c => c.label);
+      const passed = failures.length === 0;
+
+      if (passed) {
+        return textResponse('Validation passed: issue contains all required sections.');
+      }
+      return textResponse(
+        `Validation failed. Missing sections:\n${failures.map(f => `- ${f}`).join('\n')}`
+      );
+    },
+  },
+];