genat-mcp 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# GenAT MCP
+
+MCP server that exposes a **GenAT** tool: generate accessibility tests for a URL based on your project folder. It detects framework (TypeScript/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).
+
+## Install
+
+**If the package is published to npm** (otherwise you get 404):
+
+```bash
+# Global (binary on PATH)
+npm install -g genat-mcp
+
+# Or local / project
+npm install genat-mcp
+```
+
+**Until published, or for development**, install from the repo:
+
+```bash
+# From this repo root
+cd mcp-genat && npm install
+# Then in Cursor MCP use: node with args ["/path/to/n8n_playwright_tests/mcp-genat/index.js"]
+
+# Or from another project (local path)
+npm install /path/to/n8n_playwright_tests/mcp-genat
+# Then use npx genat-mcp or node node_modules/genat-mcp/index.js
+```
+
+## Environment
+
+| Variable           | Required | Default | Description |
+|--------------------|----------|---------|-------------|
+| **N8N_WEBHOOK_URL** | No       | `http://localhost:5678/webhook-test/webhook-genat` | n8n GenAT webhook URL. Set this if your n8n instance is elsewhere (e.g. `https://your-n8n-host/webhook-test/webhook-genat`). |
+
+## Cursor MCP config
+
+**Using npx (local install):**
+
+```json
+{
+  "mcpServers": {
+    "GenAT": {
+      "command": "npx",
+      "args": ["genat-mcp"]
+    }
+  }
+}
+```
+
+**Using global install:**
+
+```json
+{
+  "mcpServers": {
+    "GenAT": {
+      "command": "genat-mcp"
+    }
+  }
+}
+```
+
+If the global binary is not on PATH, use the full path, e.g. `node $(npm root -g)/genat-mcp/index.js`.
+
+## Requirements
+
+- **Node.js** 20+
+- **n8n** with the [GenAT workflow](../workflows/genat-accessibility-tests.json) imported and activated (webhook path `webhook-test/webhook-genat`)
+- **DOM Analyzer** and **Accessibility Analyzer** services running (see main README: `npm run services` from repo root)
+
+## Tool: GenAT
+
+- **url** (string): Page URL to analyze for accessibility.
+- **parentProjectFolder** (string): Path to the project root (TypeScript or Python Playwright).
+- **writeToProject** (boolean, optional): If `true`, write generated files under `tests/accessibility/` in the project folder.
+
+Returns JSON with `testCode`, `featureFile`, `stepDefCode`, `pageObjectCode` (and `_written` paths when writing).
+
+## Publishing to npm
+
+Until the package is published, `npm install genat-mcp` returns 404. To publish:
+
+1. Replace `your-username` in `package.json` (`repository`, `homepage`, `bugs`) and in `server.json` if you use the MCP Registry.
+2. **npm requires 2FA or a granular access token with "bypass 2FA" enabled** to publish. Enable 2FA on your npm account (Account → "Require two-factor authentication for writes"), or create an [Automation / granular token](https://docs.npmjs.com/creating-and-viewing-access-tokens) with "bypass 2FA for publish" and use it: `npm login` (paste token as password) or set `NPM_CONFIG_//registry.npmjs.org/:_authToken=your-token`.
+3. From this directory: `npm publish` (or `npm publish --access public` for a scoped package).
+
+After publishing, the "Install from npm" instructions above work.
+
+## Publishing to the MCP Registry
+
+To list this server on the [MCP Registry](https://registry.modelcontextprotocol.io): use your GitHub identity in `package.json` and `server.json`, publish to npm (see above), install [mcp-publisher](https://github.com/modelcontextprotocol/registry/releases), run `mcp-publisher login github` and `mcp-publisher publish`.

package/detect-framework.js

@@ -0,0 +1,134 @@
+/**
+ * Detect project framework from parent folder: language, BDD framework, Page Object pattern.
+ * Used by GenAT MCP before calling n8n.
+ */
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+
+const ALLOWED_BDD = ['cucumber', 'pytest-bdd', 'behave', 'none'];
+
+/**
+ * @param {string} parentProjectFolder - absolute or relative path to project root
+ * @returns {{ scriptType: 'typescript'|'python', bddFramework: string, pageObject: boolean, projectSummary: string }}
+ */
+export function detectFramework(parentProjectFolder) {
+  const root = resolve(parentProjectFolder);
+  if (!existsSync(root) || !readdirSync(root).length) {
+    return {
+      scriptType: 'typescript',
+      bddFramework: 'none',
+      pageObject: false,
+      projectSummary: 'Folder not found or empty; using defaults.',
+    };
+  }
+
+  let scriptType = 'typescript';
+  let bddFramework = 'none';
+  let pageObject = false;
+  const summaryParts = [];
+
+  // Language: package.json + ts/spec vs requirements.txt / py
+  const hasPackageJson = existsSync(join(root, 'package.json'));
+  const hasTsConfig = existsSync(join(root, 'tsconfig.json'));
+  const hasRequirements = existsSync(join(root, 'requirements.txt'));
+  const hasPyproject = existsSync(join(root, 'pyproject.toml'));
+
+  function hasExtension(dir, ext) {
+    try {
+      const files = walk(root, (f) => f.endsWith(ext));
+      return files.length > 0;
+    } catch {
+      return false;
+    }
+  }
+  const hasTs = hasExtension(root, '.ts') || hasExtension(root, '.spec.ts');
+  const hasPy = hasExtension(root, '.py') || hasExtension(root, '_test.py');
+
+  if (hasPy && (hasRequirements || hasPyproject || hasPy)) {
+    scriptType = 'python';
+    summaryParts.push('Language: Python');
+  } else if (hasPackageJson || hasTsConfig || hasTs) {
+    scriptType = 'typescript';
+    summaryParts.push('Language: TypeScript/JavaScript');
+  }
+
+  // BDD: Cucumber (package.json), pytest-bdd, Behave
+  if (scriptType === 'typescript' && hasPackageJson) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      if (deps['@cucumber/cucumber'] || deps['cucumber']) {
+        bddFramework = 'cucumber';
+        summaryParts.push('BDD: Cucumber');
+      }
+    } catch (_) {}
+  }
+  const hasFeatureFiles = hasExtension(root, '.feature');
+  if (scriptType === 'python') {
+    try {
+      if (hasRequirements) {
+        const req = readFileSync(join(root, 'requirements.txt'), 'utf8');
+        if (/pytest-bdd/i.test(req)) {
+          bddFramework = 'pytest-bdd';
+          summaryParts.push('BDD: pytest-bdd');
+        } else if (/behave/i.test(req)) {
+          bddFramework = 'behave';
+          summaryParts.push('BDD: Behave');
+        }
+      }
+      if (bddFramework === 'none' && existsSync(join(root, 'features'))) {
+        bddFramework = 'behave';
+        summaryParts.push('BDD: Behave (features/ present)');
+      }
+      if (bddFramework === 'none' && hasFeatureFiles) summaryParts.push('Found .feature files');
+    } catch (_) {}
+  }
+  if (scriptType === 'typescript' && hasFeatureFiles && bddFramework === 'none') {
+    summaryParts.push('Found .feature files (consider Cucumber)');
+  }
+
+  // Page Object: pages/ or *Page.ts / *_page.py
+  try {
+    if (existsSync(join(root, 'pages'))) {
+      pageObject = true;
+      summaryParts.push('Page Object: pages/ directory');
+    } else {
+      const pageTs = walk(root, (f) => f.endsWith('Page.ts') || f.endsWith('Page.tsx'));
+      const pagePy = walk(root, (f) => f.endsWith('_page.py') || f.endsWith('Page.py'));
+      if (pageTs.length || pagePy.length) {
+        pageObject = true;
+        summaryParts.push('Page Object: *Page.ts / *_page.py files');
+      }
+    }
+  } catch (_) {}
+
+  const projectSummary = summaryParts.length ? summaryParts.join('; ') : 'No framework hints detected.';
+
+  return {
+    scriptType,
+    bddFramework: ALLOWED_BDD.includes(bddFramework) ? bddFramework : 'none',
+    pageObject,
+    projectSummary,
+  };
+}
+
+/**
+ * @param {string} dir
+ * @param {(f: string) => boolean} predicate
+ * @param {string[]} [acc]
+ * @returns {string[]}
+ */
+function walk(dir, predicate, acc = []) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name !== 'node_modules' && e.name !== '.git' && e.name !== '__pycache__' && e.name !== '.venv' && e.name !== 'venv') {
+        walk(full, predicate, acc);
+      }
+    } else if (predicate(e.name)) {
+      acc.push(e.name);
+    }
+  }
+  return acc;
+}

package/index.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * GenAT MCP server: tool "GenAT" to generate accessibility tests via n8n.
+ * Inputs: url, parentProjectFolder (path to TS or Python Playwright project).
+ * Detects framework (language, BDD, Page Object), POSTs to n8n webhook, returns generated files.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { detectFramework } from './detect-framework.js';
+import { writeGeneratedFiles } from './write-files.js';
+
+const N8N_WEBHOOK_URL = process.env.N8N_WEBHOOK_URL || 'http://localhost:5678/webhook-test/webhook-genat';
+
+const server = new McpServer(
+  {
+    name: 'GenAT',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.registerTool(
+  'GenAT',
+  {
+    description:
+      'Generate accessibility tests for a URL based on the project folder. Analyzes the page (DOM + a11y), detects project framework (TypeScript/Python, BDD, Page Object), and returns generated test files (feature, spec/step defs, page objects). Optionally write files to the project folder.',
+    inputSchema: {
+      url: z.string().describe('Page URL to analyze for accessibility (e.g. https://example.com)'),
+      parentProjectFolder: z
+        .string()
+        .describe('Absolute or relative path to the project root containing TypeScript or Python Playwright code'),
+      writeToProject: z
+        .boolean()
+        .optional()
+        .describe('If true, write generated files into the project folder (e.g. tests/accessibility/)'),
+    },
+  },
+  async ({ url, parentProjectFolder, writeToProject }) => {
+    if (!url || typeof url !== 'string') {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ error: 'Missing or invalid "url"' }) }],
+        isError: true,
+      };
+    }
+
+    let framework;
+    try {
+      framework = detectFramework(parentProjectFolder || '.');
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              error: 'Framework detection failed',
+              message: err instanceof Error ? err.message : String(err),
+              fallback: { scriptType: 'typescript', bddFramework: 'none', pageObject: false },
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const body = {
+      url,
+      scriptType: framework.scriptType,
+      bddFramework: framework.bddFramework,
+      pageObject: framework.pageObject,
+      projectSummary: framework.projectSummary,
+    };
+
+    let response;
+    try {
+      response = await fetch(N8N_WEBHOOK_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              error: 'Failed to call n8n webhook',
+              message: err instanceof Error ? err.message : String(err),
+              hint: 'Set N8N_WEBHOOK_URL to your n8n webhook URL (e.g. https://your-n8n/webhook-test/webhook-genat)',
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    if (!response.ok) {
+      const text = await response.text();
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              error: `n8n returned ${response.status}`,
+              body: text.slice(0, 1000),
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      return {
+        content: [{ type: 'text', text: 'n8n response was not JSON' }],
+        isError: true,
+      };
+    }
+
+    if (writeToProject && parentProjectFolder && data) {
+      try {
+        const written = writeGeneratedFiles(parentProjectFolder, data);
+        data._written = written;
+      } catch (err) {
+        data._writeError = err instanceof Error ? err.message : String(err);
+      }
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(data, null, 2),
+        },
+      ],
+    };
+  }
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error('GenAT MCP server error:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "genat-mcp",
+  "version": "1.0.0",
+  "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", "write-files.js"],
+  "keywords": ["mcp", "accessibility", "playwright", "n8n", "model-context-protocol", "a11y", "testing"],
+  "repository": {
+    "type": "git",
+    "url": "https://git-m1.shr.oclc.org/scm/automation/n8n_playwright_tests.git"
+  },
+  "homepage": "https://git-m1.shr.oclc.org/scm/automation/n8n_playwright_tests#readme",
+  "bugs": { "url": "https://git-m1.shr.oclc.org/scm/automation/n8n_playwright_tests/issues" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.25.0"
+  }
+}

package/write-files.js

@@ -0,0 +1,55 @@
+/**
+ * Write generated accessibility test files into the project folder.
+ * Uses suggested paths from the workflow response when present.
+ */
+import { writeFile, mkdir } from 'fs/promises';
+import { join, resolve } from 'path';
+
+const DEFAULT_DIR = 'tests/accessibility';
+
+/**
+ * @param {string} parentProjectFolder - project root path
+ * @param {{ testCode?: string, scriptType?: string, featureFile?: string, stepDefCode?: string, pageObjectCode?: string, suggestedPaths?: Record<string, string> }} data - workflow response
+ * @returns {string[]} list of written file paths
+ */
+export async function writeGeneratedFiles(parentProjectFolder, data) {
+  const root = resolve(parentProjectFolder);
+  const baseDir = join(root, DEFAULT_DIR);
+  await mkdir(baseDir, { recursive: true });
+
+  const written = [];
+  const scriptType = (data.scriptType || 'typescript').toLowerCase();
+
+  const defaultNames = {
+    typescript: { spec: 'accessibility.spec.ts', steps: 'steps.ts', page: 'AccessibilityPage.ts' },
+    python: { spec: 'accessibility_test.py', steps: 'step_definitions.py', page: 'accessibility_page.py' },
+  };
+  const names = defaultNames[scriptType] || defaultNames.typescript;
+  const suggested = data.suggestedPaths || {};
+
+  if (data.testCode) {
+    const relPath = suggested.spec || join(DEFAULT_DIR, names.spec);
+    await writeFile(join(root, relPath), data.testCode, 'utf8');
+    written.push(relPath);
+  }
+
+  if (data.featureFile) {
+    const relPath = suggested.feature || join(DEFAULT_DIR, 'accessibility.feature');
+    await writeFile(join(root, relPath), data.featureFile, 'utf8');
+    written.push(relPath);
+  }
+
+  if (data.stepDefCode) {
+    const relPath = suggested.stepDef || join(DEFAULT_DIR, names.steps);
+    await writeFile(join(root, relPath), data.stepDefCode, 'utf8');
+    written.push(relPath);
+  }
+
+  if (data.pageObjectCode) {
+    const relPath = suggested.pageObject || join(DEFAULT_DIR, names.page);
+    await writeFile(join(root, relPath), data.pageObjectCode, 'utf8');
+    written.push(relPath);
+  }
+
+  return written;
+}