@letsrunit/mcp-server 0.9.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letsrunit/mcp-server",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "MCP server for letsrunit — AI-agent browser test generation and execution",
   "keywords": [
     "testing",
@@ -46,12 +46,13 @@
   },
   "packageManager": "yarn@4.10.3",
   "dependencies": {
-    "@letsrunit/controller": "0.9.1",
-    "@letsrunit/gherkin": "0.9.1",
-    "@letsrunit/journal": "0.9.1",
-    "@letsrunit/playwright": "0.9.1",
-    "@letsrunit/store": "0.9.1",
-    "@letsrunit/utils": "0.9.1",
+    "@cucumber/cucumber": "^12.7.0",
+    "@letsrunit/controller": "0.11.0",
+    "@letsrunit/gherkin": "0.11.0",
+    "@letsrunit/journal": "0.11.0",
+    "@letsrunit/playwright": "0.11.0",
+    "@letsrunit/store": "0.11.0",
+    "@letsrunit/utils": "0.11.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@playwright/test": "^1.57.0",
     "zod": "^4.3.5"

package/src/index.ts

@@ -6,6 +6,7 @@ import { SessionManager } from './sessions';
 const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
 import {
   registerDebug,
+  registerDiagnostics,
   registerDiff,
   registerListSteps,
   registerListSessions,
@@ -33,6 +34,9 @@ registerSessionClose(server, sessions);
 registerListSteps(server, sessions);
 registerListSessions(server, sessions);
 registerDiff(server, sessions);
+if (process.env.LETSRUNIT_MCP_DIAGNOSTICS === 'enabled') {
+  registerDiagnostics(server);
+}
 
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/src/tools/diagnostics.ts

@@ -0,0 +1,22 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { collectSupportDiagnostics } from '../utility/support';
+import { err, text } from '../utility/response';
+
+export function registerDiagnostics(server: McpServer): void {
+  server.registerTool(
+    'letsrunit_diagnostics',
+    {
+      description:
+        'Return runtime diagnostics for MCP support-file loading (cwd resolution, cucumber config path, support entries). Available only when LETSRUNIT_MCP_DIAGNOSTICS=enabled.',
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        const diagnostics = await collectSupportDiagnostics();
+        return text(JSON.stringify(diagnostics));
+      } catch (e) {
+        return err(`Diagnostics failed: ${(e as Error).message}`);
+      }
+    },
+  );
+}

package/src/tools/diff.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { unifiedHtmlDiff } from '@letsrunit/playwright';
-import { openStore, findLastRun, findArtifacts } from '@letsrunit/store';
+import { openStore, findLastTest, findArtifacts } from '@letsrunit/store';
 import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -28,17 +28,17 @@ export function registerDiff(server: McpServer, sessions: SessionManager): void
     'letsrunit_diff',
     {
       description:
-        'Diff the current live page against the HTML snapshot from the last passing run of a scenario. ' +
+        'Diff the current live page against the HTML snapshot from the last passing test of a scenario. ' +
         'Pass the scenarioId returned by letsrunit_run. ' +
         'Returns a unified HTML diff and paths to baseline screenshots. ' +
-        'By default only considers baseline runs from the current git ancestry (gitTreeOnly: true).',
+        'By default only considers baseline tests from the current git ancestry (gitTreeOnly: true).',
       inputSchema: {
         sessionId: z.string().describe('Session ID returned by letsrunit_session_start'),
         scenarioId: z.string().describe('Scenario UUID returned by letsrunit_run'),
         gitTreeOnly: z
           .boolean()
           .optional()
-          .describe('Restrict baseline to runs from the current git ancestry (default: true)'),
+          .describe('Restrict baseline to tests from the current git ancestry (default: true)'),
       },
     },
     async (input) => {
@@ -55,20 +55,20 @@ export function registerDiff(server: McpServer, sessions: SessionManager): void
 
         const allowedCommits = (input.gitTreeOnly ?? true) ? resolveAllowedCommits() : undefined;
 
-        const run = findLastRun(db, input.scenarioId, 'passed', allowedCommits ?? undefined);
-        if (!run) {
+        const test = findLastTest(db, input.scenarioId, 'passed', allowedCommits ?? undefined);
+        if (!test) {
           return err(
             allowedCommits
-              ? 'No passing run found for this scenario in the current git ancestry. Try gitTreeOnly: false or run cucumber first.'
-              : 'No passing run found for this scenario.',
+              ? 'No passing test found for this scenario in the current git ancestry. Try gitTreeOnly: false or run cucumber first.'
+              : 'No passing test found for this scenario.',
           );
         }
 
-        const artifacts = findArtifacts(db, run.id);
+        const artifacts = findArtifacts(db, test.id);
 
         const htmlArtifact = [...artifacts].reverse().find((a) => a.filename.endsWith('.html'));
         if (!htmlArtifact) {
-          return err('No HTML snapshot found in the baseline run. Ensure the store formatter is configured.');
+          return err('No HTML snapshot found in the baseline test. Ensure the store formatter is configured.');
         }
 
         const storedHtml = readFileSync(join(artifactDir, htmlArtifact.filename), 'utf-8');
@@ -86,8 +86,8 @@ export function registerDiff(server: McpServer, sessions: SessionManager): void
           JSON.stringify({
             diff,
             baseline: {
-              runId: run.id,
-              commit: run.gitCommit,
+              testId: test.id,
+              commit: test.gitCommit,
               screenshots,
             },
           }),

package/src/tools/index.ts

@@ -1,4 +1,5 @@
 export { registerDebug } from './debug';
+export { registerDiagnostics } from './diagnostics';
 export { registerDiff } from './diff';
 export { registerListSteps } from './list-steps';
 export { registerListSessions } from './list-sessions';

package/src/tools/run.ts

@@ -1,17 +1,10 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { parseFeature } from '@letsrunit/gherkin';
-import { computeStepId, computeScenarioId } from '@letsrunit/store';
+import { scenarioIdFromGherkin } from '@letsrunit/gherkin';
 import type { SessionManager } from '../sessions';
 import { normalizeGherkin } from '../utility/gherkin';
 import { err, text } from '../utility/response';
 
-function scenarioIdFromGherkin(gherkin: string): string {
-  const { steps } = parseFeature(gherkin);
-  const stepIds = steps.map((s) => computeStepId(s));
-  return computeScenarioId(stepIds);
-}
-
 export function registerRun(server: McpServer, sessions: SessionManager): void {
   server.registerTool(
     'letsrunit_run',

package/src/tools/session-start.ts

@@ -2,6 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { SessionManager } from '../sessions';
 import { err, text } from '../utility/response';
+import { loadSupportFiles } from '../utility/support';
 
 export function registerSessionStart(server: McpServer, sessions: SessionManager): void {
   server.registerTool(
@@ -19,6 +20,8 @@ export function registerSessionStart(server: McpServer, sessions: SessionManager
     },
     async (input) => {
       try {
+        await loadSupportFiles();
+
         const viewport =
           input.viewportWidth || input.viewportHeight
             ? { width: input.viewportWidth ?? 1280, height: input.viewportHeight ?? 720 }

package/src/utility/support.ts

@@ -0,0 +1,238 @@
+import { createRequire } from 'node:module';
+import { loadConfiguration } from '@cucumber/cucumber/api';
+import { registry } from '@letsrunit/bdd';
+import { existsSync } from 'node:fs';
+import { glob } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+type CucumberConfig = {
+  require?: unknown;
+  import?: unknown;
+  letsrunit?: {
+    ignore?: unknown;
+  };
+};
+
+type SupportEntry =
+  | { kind: 'path'; value: string }
+  | { kind: 'module'; value: string };
+
+const CUCUMBER_CONFIG_FILES = [
+  'cucumber.js',
+  'cucumber.mjs',
+  'cucumber.cjs',
+  'cucumber.ts',
+  'cucumber.mts',
+  'cucumber.cts',
+];
+
+const loadedProjectRoots = new Set<string>();
+const loadedSupportEntries = new Set<string>();
+
+export type SupportDiagnostics = {
+  envProjectCwd: string | null;
+  processCwd: string;
+  inputCwd: string | null;
+  effectiveCwd: string;
+  projectRoot: string;
+  cucumberConfigPath: string | null;
+  supportPatterns: string[];
+  ignorePatterns: string[];
+  ignoredPaths: string[];
+  supportEntries: SupportEntry[];
+  loadedProjectRoots: string[];
+  loadedSupportEntries: string[];
+  moduleResolution: {
+    serverBddPath: string | null;
+    projectBddPath: string | null;
+    sameModule: boolean;
+  };
+  registry: {
+    total: number;
+    byType: {
+      Given: number;
+      When: number;
+      Then: number;
+    };
+    definitions: Array<{
+      type: 'Given' | 'When' | 'Then';
+      source: string;
+      comment?: string;
+    }>;
+  };
+};
+
+function toStrings(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === 'string');
+}
+
+function hasGlobMagic(input: string): boolean {
+  return /[*?[\]{}]/.test(input);
+}
+
+function isPathLike(input: string): boolean {
+  return input.startsWith('.') || input.startsWith('/') || /^[A-Za-z]:[\\/]/.test(input);
+}
+
+function toAbsolutePath(baseDir: string, input: string): string {
+  return isAbsolute(input) ? resolve(input) : resolve(baseDir, input);
+}
+
+function normalizeMatch(baseDir: string, match: string): string {
+  return isAbsolute(match) ? resolve(match) : resolve(baseDir, match);
+}
+
+async function expandPathPatterns(baseDir: string, patterns: string[]): Promise<Set<string>> {
+  const files = new Set<string>();
+
+  for (const pattern of patterns) {
+    if (hasGlobMagic(pattern)) {
+      for await (const match of glob(pattern, { cwd: baseDir, absolute: true, withFileTypes: false })) {
+        files.add(normalizeMatch(baseDir, match));
+      }
+      continue;
+    }
+
+    files.add(toAbsolutePath(baseDir, pattern));
+  }
+
+  return files;
+}
+
+async function resolveSupportEntries(baseDir: string, entries: string[]): Promise<SupportEntry[]> {
+  const resolved: SupportEntry[] = [];
+
+  for (const entry of entries) {
+    if (hasGlobMagic(entry)) {
+      for await (const match of glob(entry, { cwd: baseDir, absolute: true, withFileTypes: false })) {
+        resolved.push({ kind: 'path', value: normalizeMatch(baseDir, match) });
+      }
+      continue;
+    }
+
+    if (!isPathLike(entry)) {
+      resolved.push({ kind: 'module', value: entry });
+      continue;
+    }
+
+    resolved.push({ kind: 'path', value: toAbsolutePath(baseDir, entry) });
+  }
+
+  return resolved;
+}
+
+function findCucumberConfig(cwd: string): string | null {
+  for (const filename of CUCUMBER_CONFIG_FILES) {
+    const path = resolve(cwd, filename);
+    if (existsSync(path)) return path;
+  }
+
+  return null;
+}
+
+async function loadLetsrunitIgnorePatterns(cwd: string): Promise<string[]> {
+  const configPath = findCucumberConfig(cwd);
+  if (!configPath) return [];
+
+  const configModule = await import(pathToFileURL(configPath).href);
+  const config = (configModule.default ?? configModule) as CucumberConfig;
+
+  return toStrings(config.letsrunit?.ignore);
+}
+
+function resolveEffectiveCwd(cwd?: string): string {
+  return cwd ?? process.env.LETSRUNIT_PROJECT_CWD ?? process.cwd();
+}
+
+function resolveFrom(moduleId: string, fromPath: string): string | null {
+  try {
+    const req = createRequire(fromPath);
+    return req.resolve(moduleId);
+  } catch {
+    return null;
+  }
+}
+
+export async function collectSupportDiagnostics(cwd?: string): Promise<SupportDiagnostics> {
+  const effectiveCwd = resolveEffectiveCwd(cwd);
+  const projectRoot = resolve(effectiveCwd);
+  const cucumberConfigPath = findCucumberConfig(projectRoot);
+  const { useConfiguration } = await loadConfiguration({}, { cwd: projectRoot });
+  const supportPatterns = [...toStrings(useConfiguration.require), ...toStrings(useConfiguration.import)];
+  const ignorePatterns = await loadLetsrunitIgnorePatterns(projectRoot);
+  const ignoredPaths = await expandPathPatterns(projectRoot, ignorePatterns);
+  const supportEntries = await resolveSupportEntries(projectRoot, supportPatterns);
+  const serverBddPath = resolveFrom('@letsrunit/bdd', import.meta.url);
+  const projectBddPath = resolveFrom('@letsrunit/bdd', resolve(projectRoot, 'package.json'));
+  const registryDefinitions = registry.defs.map((def) => ({
+    type: def.type,
+    source: def.source,
+    comment: def.comment,
+  }));
+
+  return {
+    envProjectCwd: process.env.LETSRUNIT_PROJECT_CWD ?? null,
+    processCwd: process.cwd(),
+    inputCwd: cwd ?? null,
+    effectiveCwd,
+    projectRoot,
+    cucumberConfigPath,
+    supportPatterns,
+    ignorePatterns,
+    ignoredPaths: [...ignoredPaths].sort(),
+    supportEntries,
+    loadedProjectRoots: [...loadedProjectRoots].sort(),
+    loadedSupportEntries: [...loadedSupportEntries].sort(),
+    moduleResolution: {
+      serverBddPath,
+      projectBddPath,
+      sameModule: !!serverBddPath && !!projectBddPath && serverBddPath === projectBddPath,
+    },
+    registry: {
+      total: registryDefinitions.length,
+      byType: {
+        Given: registryDefinitions.filter((d) => d.type === 'Given').length,
+        When: registryDefinitions.filter((d) => d.type === 'When').length,
+        Then: registryDefinitions.filter((d) => d.type === 'Then').length,
+      },
+      definitions: registryDefinitions,
+    },
+  };
+}
+
+export async function loadSupportFiles(cwd?: string): Promise<void> {
+  const projectRoot = resolve(resolveEffectiveCwd(cwd));
+  if (loadedProjectRoots.has(projectRoot)) return;
+
+  const { useConfiguration } = await loadConfiguration({}, { cwd: projectRoot });
+  const supportPatterns = [...toStrings(useConfiguration.require), ...toStrings(useConfiguration.import)];
+  if (supportPatterns.length === 0) {
+    loadedProjectRoots.add(projectRoot);
+    return;
+  }
+
+  const ignorePatterns = await loadLetsrunitIgnorePatterns(projectRoot);
+  const ignoredPaths = await expandPathPatterns(projectRoot, ignorePatterns);
+  const supportEntries = await resolveSupportEntries(projectRoot, supportPatterns);
+
+  for (const entry of supportEntries) {
+    if (entry.kind === 'path' && ignoredPaths.has(entry.value)) {
+      continue;
+    }
+
+    const key = `${entry.kind}:${entry.value}`;
+    if (loadedSupportEntries.has(key)) continue;
+
+    if (entry.kind === 'path') {
+      await import(pathToFileURL(entry.value).href);
+    } else {
+      await import(entry.value);
+    }
+
+    loadedSupportEntries.add(key);
+  }
+
+  loadedProjectRoots.add(projectRoot);
+}