genat-mcp 2.2.8 → 2.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server that exposes a **GenAT** tool: generate accessibility tests for a URL based on your project folder. It detects framework (TypeScript, JavaScript, or Python, BDD, Page Object), calls an n8n GenAT workflow, and returns (or writes) generated test files.
 
-Full setup (n8n workflow, services, usage) is in the [project README](../README.md).
+Full setup (n8n workflow, services, usage) is in the [project README](../README.md). GenAT workflows also instruct the AI to align with **OCLC internal Confluence** pages ([Accessibility Guidelines and Resources](https://confluence.oclc.org/spaces/UAD/pages/103062358/Accessibility+Guidelines+and+Resources), [OCLC Accessibility Release Blockers](https://confluence.oclc.org/spaces/UXUI/pages/119232333/OCLC+Accessibility+Release+Blockers)); the MCP sends optional extra context from [oclc-accessibility-confluence-context.md](oclc-accessibility-confluence-context.md) or `GENAT_OCLC_ACCESSIBILITY_CONTEXT`.
 
 **For teams:** See [GENAT_OVERVIEW.md](GENAT_OVERVIEW.md) for a concise, presentation-ready overview. Suitable as a source for NotebookLM or other AI tools to create slide decks.
 
@@ -42,6 +42,7 @@ npm install /path/to/n8n_playwright_tests/mcp-genat
 | **N8N_ANALYZE_STATES** | No       | (off)   | Set to `1`, `true`, or `yes` to analyze dropdown/combobox expanded states and include state-specific violations in generated tests. Used as default when the tool is invoked without `analyzeStates`; also used by run-genat.mjs. Increases analysis time. |
 | **GENAT_PROJECT_ROOT** | No       | (cwd)   | Base path for resolving `parentProjectFolder`. When set, `parentProjectFolder` is resolved relative to this path. Use when your project is outside the MCP's working directory. Example: if your pytest project is at `/Users/me/projects/ill_tests`, set `GENAT_PROJECT_ROOT=/Users/me/projects` and use `parentProjectFolder ill_tests` in the prompt. |
 | **GENAT_FETCH_TIMEOUT_MS** | No       | 600000 (10 min) | Max time in milliseconds to wait for the n8n webhook response. Increase if GenAT times out before the workflow completes (e.g. complex pages with JIRA + AI Agent). Set in MCP env, e.g. `GENAT_FETCH_TIMEOUT_MS=900000` for 15 minutes. |
+| **GENAT_OCLC_ACCESSIBILITY_CONTEXT** | No       | (bundled file) | Optional multiline text sent as `oclcAccessibilityContext` in the webhook body. Overrides the default [oclc-accessibility-confluence-context.md](oclc-accessibility-confluence-context.md) (OCLC UAD guidelines + UXUI release blockers links and notes). Use to paste updated Confluence excerpts without republishing the package. |
 
 ## Framework detection and auto-discovery
 

package/index.js

@@ -12,6 +12,7 @@ import { z } from 'zod';
 import { detectFramework } from './detect-framework.js';
 import { detectLogin } from './detect-login.js';
 import { writeGeneratedFiles } from './write-files.js';
+import { loadOclcAccessibilityContext } from './oclc-context.js';
 
 const N8N_WEBHOOK_URL = process.env.N8N_WEBHOOK_URL || 'http://localhost:5678/webhook-test/webhook-genat-login';
 const SERVICE_BASE_URL = process.env.SERVICE_BASE_URL || null;
@@ -55,7 +56,7 @@ function insecureHttpsFetch(url, { method = 'GET', headers = {}, body, signal })
 const server = new McpServer(
   {
     name: 'GenAT',
-    version: '2.2.8',
+    version: '2.3.1',
   },
   {
     capabilities: {
@@ -102,13 +103,38 @@ server.registerTool(
         .string()
         .optional()
         .describe('Login page URL if different from target URL'),
+      requiresAuth: z
+        .boolean()
+        .optional()
+        .describe(
+          'v2 workflow only: if true, after the first unauthenticated fetch, retry with login when credentials exist (protected pages when DOM/URL heuristics miss). Omit on public pages.'
+        ),
+      forceLogin: z
+        .boolean()
+        .optional()
+        .describe(
+          'v2 workflow only: same behavior as requiresAuth when true (optional alternate flag for tooling).'
+        ),
       jiraNumber: z
         .string()
         .optional()
         .describe('JIRA issue key (e.g. PROJ-123, RB-40039). Extract from prompts like "JIRA RB-40039" or "JIRA ticket PROJ-123". Pass only the key (e.g. RB-40039), not "JIRA RB-40039".'),
     },
   },
-  async ({ url, parentProjectFolder, writeToProject, maxAssertions, scopeToRegions, analyzeStates, loginUsername, loginPassword, loginUrl, jiraNumber }) => {
+  async ({
+    url,
+    parentProjectFolder,
+    writeToProject,
+    maxAssertions,
+    scopeToRegions,
+    analyzeStates,
+    loginUsername,
+    loginPassword,
+    loginUrl,
+    requiresAuth,
+    forceLogin,
+    jiraNumber,
+  }) => {
     if (!url || typeof url !== 'string') {
       return {
         content: [{ type: 'text', text: JSON.stringify({ error: 'Missing or invalid "url"' }) }],
@@ -151,6 +177,7 @@ server.registerTool(
     const maxAssertionsResolved = maxAssertions ?? (process.env.N8N_MAX_ASSERTIONS ? parseInt(process.env.N8N_MAX_ASSERTIONS, 10) : null);
     const scopeToRegionsResolved = scopeToRegions?.length ? scopeToRegions : (process.env.N8N_SCOPE_TO_REGIONS ? process.env.N8N_SCOPE_TO_REGIONS.split(',').map((s) => s.trim()).filter(Boolean) : null);
     const analyzeStatesResolved = analyzeStates || /^1|true|yes$/i.test(process.env.N8N_ANALYZE_STATES || '');
+    const oclcAccessibilityContext = loadOclcAccessibilityContext();
 
     const body = {
       url,
@@ -159,6 +186,7 @@ server.registerTool(
       pageObject: framework.pageObject,
       projectSummary: framework.projectSummary,
       ...(framework.projectLayoutHints && { projectLayoutHints: framework.projectLayoutHints }),
+      ...(oclcAccessibilityContext && { oclcAccessibilityContext }),
       ...(SERVICE_BASE_URL && { serviceBaseUrl: SERVICE_BASE_URL }),
       ...(maxAssertionsResolved != null && !isNaN(maxAssertionsResolved) && { maxAssertions: maxAssertionsResolved }),
       ...(scopeToRegionsResolved?.length && { scopeToRegions: scopeToRegionsResolved }),
@@ -171,6 +199,8 @@ server.registerTool(
         ...(login.passwordSelector && { loginPasswordSelector: login.passwordSelector }),
         ...(login.submitSelector && { loginSubmitSelector: login.submitSelector }),
       }),
+      ...(requiresAuth === true && { requiresAuth: true }),
+      ...(forceLogin === true && { forceLogin: true }),
       ...(jiraNumber && jiraNumber.trim() && { jiraNumber: jiraNumber.trim() }),
     };
 

package/oclc-accessibility-confluence-context.md

@@ -0,0 +1,51 @@
+# OCLC internal accessibility sources (GenAT)
+
+GenAT injects this file into the n8n workflow as **oclcAccessibilityContext** so generated tests align with internal guidance, in addition to WCAG 2.1 AA and related standards from the accessibility analyzer.
+
+Source URLs (canonical):
+
+- **UAD — Accessibility Guidelines and Resources:** https://confluence.oclc.org/spaces/UAD/pages/103062358/Accessibility+Guidelines+and+Resources
+- **UXUI — OCLC Accessibility Release Blockers:** https://confluence.oclc.org/spaces/UXUI/pages/119232333/OCLC+Accessibility+Release+Blockers
+
+---
+
+## Summary: UAD Accessibility Guidelines and Resources
+
+**Policy / Definition of done:** Net-new applications (new UI stack, e.g. React/Angular with Material UI) are expected to be accessible and internationalized. Interfaces must be usable and inclusive.
+
+**Principles:** Follow **POUR** — Perceivable, Operable, Understandable, Robust. Accessibility is broader than screen-reader-only compliance.
+
+**Build (high level):**
+
+- Use Storybook with accessibility tooling where applicable.
+- Valid, well-structured HTML; landmark regions; semantic elements (`main`, `nav`, headings, etc.) over generic `div`/`span` when defining structure.
+- Relative sizing (**rem**/**em**), sensible line-height; avoid locking users out of zoom.
+- Prefer **native** HTML controls (`button`, `a`, `input`, `select`, `form`) over custom reimplementations.
+- Use `<a>` for navigation (with real `href`); use `<button>` for actions (style as link if needed).
+- All images need appropriate **alt** text.
+- Use **ARIA** correctly; incorrect ARIA can harm more than help.
+- **Keyboard:** no traps; focus management after dynamic changes; follow WAI-ARIA authoring practices for composite widgets.
+- Tab order: interactive controls in a logical sequence; avoid `tabindex` on non-interactive elements except focus management (`tabindex="-1"` when appropriate).
+- Treat a11y issues in code review similarly to i18n/hardcoded strings.
+
+**Verify:** Target **WCAG 2.1 AA** plus real-world usability. Combine automated checks (e.g. axe, Pa11y), linting (e.g. eslint-plugin-jsx-a11y), integration/unit tests for behaviors (e.g. modal focus trap), browser tools, and **manual** testing including screen readers (VoiceOver, NVDA) with realistic navigation patterns.
+
+---
+
+## Summary: OCLC Accessibility Release Blockers
+
+**Intent:** Distinguish **critical failures** that must block a release vs. issues that can be fixed post-release.
+
+**The three release blockers** (minimum for OCLC interfaces):
+
+1. **Keyboard operable** — Everything operable without a mouse; no keyboard traps. Primary WCAG tie-in: **2.1.1 Keyboard**. Related: meaningful sequence, no keyboard trap, bypass blocks, focus order, focus visible.
+2. **High contrast** — Text **4.5:1**; non-text UI (icons, borders) **3:1** vs. background. Check hover/focus/selected states. Primary: **1.4.3 Contrast (Minimum)**. Related: use of color, non-text contrast.
+3. **Clearly labeled** — Text alternatives for non-text content; forms and controls have clear, distinguishable names/labels. Primary: **1.1.1 Non-text Content**. Related: info/relationships, link purpose, headings/labels, labels/instructions, name/role/value.
+
+OCLC aims for **WCAG 2.2 A and AA** broadly; prioritize **site-wide** issues (login, headers/footers, navigation, reusable components, contrast) when triaging.
+
+**For GenAT:** Generated tests should explicitly exercise these three themes (keyboard paths, contrast-relevant assertions where feasible, labels/roles/names) in addition to axe rule coverage.
+
+---
+
+Teams may override this file via env **`GENAT_OCLC_ACCESSIBILITY_CONTEXT`** to paste updated Confluence excerpts without republishing the package.

package/oclc-context.js

@@ -0,0 +1,24 @@
+/**
+ * Optional OCLC Confluence text appended to the n8n webhook body as oclcAccessibilityContext.
+ * Env GENAT_OCLC_ACCESSIBILITY_CONTEXT overrides the default file.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_FILE = join(__dirname, 'oclc-accessibility-confluence-context.md');
+const MAX_LEN = 120000;
+
+export function loadOclcAccessibilityContext() {
+  const fromEnv = process.env.GENAT_OCLC_ACCESSIBILITY_CONTEXT?.trim();
+  if (fromEnv) return fromEnv.slice(0, MAX_LEN);
+  if (existsSync(DEFAULT_FILE)) {
+    try {
+      return readFileSync(DEFAULT_FILE, 'utf8').trim().slice(0, MAX_LEN);
+    } catch {
+      return '';
+    }
+  }
+  return '';
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "genat-mcp",
-  "version": "2.2.8",
+  "version": "2.3.1",
   "mcpName": "io.github.asokans@oclc.org/genat",
   "description": "MCP server GenAT: generate accessibility tests via n8n workflow (url + project folder)",
   "type": "module",
   "main": "index.js",
   "bin": { "genat-mcp": "index.js" },
   "engines": { "node": ">=20" },
-  "files": ["index.js", "detect-framework.js", "detect-login.js", "write-files.js", "run-genat.mjs", "rules/genat-mcp.mdc"],
+  "files": ["index.js", "detect-framework.js", "detect-login.js", "write-files.js", "strip-gherkin-from-python-steps.js", "oclc-context.js", "oclc-accessibility-confluence-context.md", "run-genat.mjs", "rules/genat-mcp.mdc"],
   "keywords": ["mcp", "accessibility", "playwright", "n8n", "model-context-protocol", "a11y", "testing"],
   "repository": {
     "type": "git",

package/run-genat.mjs

@@ -13,12 +13,15 @@
  *   N8N_MAX_ASSERTIONS - override assertion count (e.g. 25)
  *   N8N_SCOPE_TO_REGIONS - comma-separated regions (e.g. header,main,table)
  *   N8N_ANALYZE_STATES - set to 1 to analyze dropdown/combobox expanded states
+ *   GENAT_OCLC_ACCESSIBILITY_CONTEXT - optional; overrides bundled oclc-accessibility-confluence-context.md for the workflow prompt
+ *   GENAT_REQUIRES_AUTH / GENAT_FORCE_LOGIN - set to 1/true for v2 workflow: request login retry when credentials exist (after first unauthenticated fetch)
  */
 import https from 'node:https';
 import { resolve } from 'node:path';
 import { detectFramework } from './detect-framework.js';
 import { detectLogin } from './detect-login.js';
 import { writeGeneratedFiles } from './write-files.js';
+import { loadOclcAccessibilityContext } from './oclc-context.js';
 
 const DEFAULT_WEBHOOK = 'http://localhost:5678/webhook-test/webhook-genat-login';
 const N8N_WEBHOOK_URL = process.env.N8N_WEBHOOK_URL || DEFAULT_WEBHOOK;
@@ -85,6 +88,9 @@ async function main() {
     ? process.env.N8N_SCOPE_TO_REGIONS.split(',').map((s) => s.trim()).filter(Boolean)
     : null;
   const analyzeStates = /^1|true|yes$/i.test(process.env.N8N_ANALYZE_STATES || '');
+  const requiresAuth = /^1|true|yes$/i.test(process.env.GENAT_REQUIRES_AUTH || '');
+  const forceLogin = /^1|true|yes$/i.test(process.env.GENAT_FORCE_LOGIN || '');
+  const oclcAccessibilityContext = loadOclcAccessibilityContext();
 
   const body = {
     url,
@@ -93,6 +99,7 @@ async function main() {
     pageObject: framework.pageObject,
     projectSummary: framework.projectSummary,
     ...(framework.projectLayoutHints && { projectLayoutHints: framework.projectLayoutHints }),
+    ...(oclcAccessibilityContext && { oclcAccessibilityContext }),
     ...(maxAssertions != null && !isNaN(maxAssertions) && { maxAssertions }),
     ...(scopeToRegions?.length && { scopeToRegions }),
     ...(analyzeStates && { analyzeStates: true }),
@@ -102,6 +109,8 @@ async function main() {
     ...(login.usernameSelector && { loginUsernameSelector: login.usernameSelector }),
     ...(login.passwordSelector && { loginPasswordSelector: login.passwordSelector }),
     ...(login.submitSelector && { loginSubmitSelector: login.submitSelector }),
+    ...(requiresAuth && { requiresAuth: true }),
+    ...(forceLogin && { forceLogin: true }),
   };
 
   const fetchOpts = {

package/strip-gherkin-from-python-steps.js

@@ -0,0 +1,30 @@
+/**
+ * Remove accidental leading Gherkin (.feature text) from pytest-bdd step file content
+ * when the model duplicates the feature inside ```steps```.
+ * @param {string} s
+ * @returns {string}
+ */
+export function stripLeadingGherkinFromPythonSteps(s) {
+  if (!s || typeof s !== 'string') return s;
+  const lines = s.split('\n');
+  const firstImport = lines.findIndex((l) => /^\s*(import |from )/.test(l));
+  if (firstImport > 0) {
+    const head = lines.slice(0, firstImport).join('\n');
+    if (
+      /Feature\s*:|Scenario(\s+Outline)?\s*:|^\s*(Given|When|Then|And|But)\s*:|^\s*Background\s*:/im.test(head)
+    ) {
+      return lines.slice(firstImport).join('\n').trim();
+    }
+  }
+  const firstStep = lines.findIndex((l) => {
+    const t = l.trim();
+    return /^@(given|when|then|step|pytest|fixture)/i.test(t) || /^def /.test(t);
+  });
+  if (firstStep > 0) {
+    const head = lines.slice(0, firstStep).join('\n');
+    if (/Feature\s*:|Scenario(\s+Outline)?\s*:/im.test(head)) {
+      return lines.slice(firstStep).join('\n').trim();
+    }
+  }
+  return s.trim();
+}

package/write-files.js

@@ -5,6 +5,7 @@
 import { existsSync } from 'fs';
 import { writeFile, mkdir } from 'fs/promises';
 import { dirname, join, resolve } from 'path';
+import { stripLeadingGherkinFromPythonSteps } from './strip-gherkin-from-python-steps.js';
 
 const DEFAULT_DIR = 'tests/accessibility';
 
@@ -54,10 +55,14 @@ export async function writeGeneratedFiles(parentProjectFolder, data) {
 
   if (usePytestBddLayout) {
     const pb = resolvePytestBddPaths(root);
+    const stepDefStripped = data.stepDefCode
+      ? stripLeadingGherkinFromPythonSteps(data.stepDefCode)
+      : '';
+    const testStripped = data.testCode ? stripLeadingGherkinFromPythonSteps(data.testCode) : '';
     const dup =
-      data.testCode &&
-      data.stepDefCode &&
-      data.testCode.trim() === data.stepDefCode.trim();
+      testStripped &&
+      stepDefStripped &&
+      testStripped.trim() === stepDefStripped.trim();
 
     if (data.featureFile) {
       const relPath = suggested.feature || pb.featureRel;
@@ -71,14 +76,14 @@ export async function writeGeneratedFiles(parentProjectFolder, data) {
       const relPath = suggested.stepDef || pb.stepRel;
       const abs = join(root, relPath);
       await mkdir(dirname(abs), { recursive: true });
-      await writeFile(abs, data.stepDefCode || data.testCode || '', 'utf8');
+      await writeFile(abs, stepDefStripped || testStripped || '', 'utf8');
       written.push(relPath);
     } else {
       if (data.stepDefCode) {
         const relPath = suggested.stepDef || pb.stepRel;
         const abs = join(root, relPath);
         await mkdir(dirname(abs), { recursive: true });
-        await writeFile(abs, data.stepDefCode, 'utf8');
+        await writeFile(abs, stepDefStripped, 'utf8');
         written.push(relPath);
       }
       if (data.testCode) {
@@ -86,13 +91,13 @@ export async function writeGeneratedFiles(parentProjectFolder, data) {
           const relPath = suggested.spec || pb.specRel;
           const abs = join(root, relPath);
           await mkdir(dirname(abs), { recursive: true });
-          await writeFile(abs, data.testCode, 'utf8');
+          await writeFile(abs, testStripped, 'utf8');
           written.push(relPath);
         } else {
           const relPath = suggested.stepDef || pb.stepRel;
           const abs = join(root, relPath);
           await mkdir(dirname(abs), { recursive: true });
-          await writeFile(abs, data.testCode, 'utf8');
+          await writeFile(abs, testStripped, 'utf8');
           written.push(relPath);
         }
       }