@letsrunit/mcp-server 0.0.1 → 0.2.6

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Controller } from '@letsrunit/controller';
+import { MemorySink, Journal } from '@letsrunit/journal';
+import { join } from 'path';
+import { z } from 'zod';
+import { scrubHtml, screenshotElement, screenshot } from '@letsrunit/playwright';
+import { mkdir, writeFile } from 'fs/promises';
+
+var SESSION_TIMEOUT_MS = 30 * 60 * 1e3;
+var BASE_ARTIFACT_DIR = process.env.LETSRUNIT_ARTIFACT_DIR ?? join(process.env.HOME ?? "/tmp", ".letsrunit", "artifacts");
+function sessionId() {
+  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
+}
+var SessionManager = class {
+  sessions = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  async create(options = {}) {
+    const id = sessionId();
+    const artifactDir = join(BASE_ARTIFACT_DIR, id);
+    const sink = new MemorySink(artifactDir);
+    const journal = new Journal(sink);
+    const controller = await Controller.launch({ ...options, journal });
+    const session = {
+      id,
+      controller,
+      sink,
+      journal,
+      artifactDir,
+      createdAt: Date.now(),
+      lastActivity: Date.now(),
+      stepCount: 0
+    };
+    this.sessions.set(id, session);
+    this.resetTimer(id);
+    return session;
+  }
+  get(id) {
+    const session = this.sessions.get(id);
+    if (!session) throw new Error(`Session not found: ${id}`);
+    return session;
+  }
+  has(id) {
+    return this.sessions.has(id);
+  }
+  touch(id) {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.lastActivity = Date.now();
+      this.resetTimer(id);
+    }
+  }
+  list() {
+    return Array.from(this.sessions.values());
+  }
+  async close(id) {
+    const session = this.sessions.get(id);
+    if (!session) return;
+    clearTimeout(this.timers.get(id));
+    this.timers.delete(id);
+    this.sessions.delete(id);
+    await session.controller.close();
+  }
+  resetTimer(id) {
+    clearTimeout(this.timers.get(id));
+    const timer = setTimeout(() => this.close(id), SESSION_TIMEOUT_MS);
+    if (typeof timer === "object" && "unref" in timer) timer.unref();
+    this.timers.set(id, timer);
+  }
+};
+
+// src/utility/response.ts
+function text(content) {
+  return { content: [{ type: "text", text: content }] };
+}
+function err(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+// src/tools/debug.ts
+function registerDebug(server2, sessions2) {
+  server2.registerTool(
+    "letsrunit_debug",
+    {
+      description: "Evaluate JavaScript on the current page via Playwright page.evaluate(). Use for debugging \u2014 not for test logic.",
+      inputSchema: {
+        sessionId: z.string().describe("Session ID"),
+        script: z.string().describe("JavaScript expression or function body to evaluate in the page context")
+      }
+    },
+    async (input) => {
+      try {
+        const session = sessions2.get(input.sessionId);
+        sessions2.touch(input.sessionId);
+        const result = await session.controller.page.evaluate(input.script);
+        return text(JSON.stringify({ result }));
+      } catch (e) {
+        return text(JSON.stringify({ result: null, error: e.message }));
+      }
+    }
+  );
+}
+
+// src/tools/list-sessions.ts
+function registerListSessions(server2, sessions2) {
+  server2.registerTool(
+    "letsrunit_list_sessions",
+    {
+      description: "List all active browser sessions.",
+      inputSchema: {}
+    },
+    async () => {
+      const list = sessions2.list().map((s) => ({
+        sessionId: s.id,
+        createdAt: s.createdAt,
+        lastActivity: s.lastActivity,
+        stepCount: s.stepCount,
+        artifactDir: s.artifactDir
+      }));
+      return text(JSON.stringify({ sessions: list }));
+    }
+  );
+}
+
+// src/utility/gherkin.ts
+function normalizeGherkin(input) {
+  const trimmed = input.trim();
+  if (/^(Feature|Scenario|Background):/im.test(trimmed)) {
+    return trimmed;
+  }
+  return `Feature: MCP
+
+Scenario: Steps
+  ${trimmed.split("\n").join("\n  ")}`;
+}
+
+// src/tools/run.ts
+function registerRun(server2, sessions2) {
+  server2.registerTool(
+    "letsrunit_run",
+    {
+      description: "Execute Gherkin steps or a complete feature in the browser. Accepts a single step line, multiple step lines, a full Scenario, or a full Feature. Returns status, steps, reason on failure, and journal entries. Does not return a page snapshot \u2014 call letsrunit_snapshot explicitly if you need the DOM.",
+      inputSchema: {
+        sessionId: z.string().describe("Session ID returned by letsrunit_session_start"),
+        input: z.string().describe(
+          'Gherkin text to execute: one or more step lines (e.g. "Given I am on \\"https://example.com\\""), a Scenario block, or a full Feature block.'
+        )
+      }
+    },
+    async (input) => {
+      try {
+        const session = sessions2.get(input.sessionId);
+        sessions2.touch(input.sessionId);
+        const feature = normalizeGherkin(input.input);
+        session.sink.clear();
+        const result = await session.controller.run(feature);
+        session.stepCount += result.steps.length;
+        return text(
+          JSON.stringify({
+            status: result.status,
+            steps: result.steps,
+            reason: result.reason?.message,
+            journal: session.sink.getEntries()
+          })
+        );
+      } catch (e) {
+        return err(`Run failed: ${e.message}`);
+      }
+    }
+  );
+}
+function registerScreenshot(server2, sessions2) {
+  server2.registerTool(
+    "letsrunit_screenshot",
+    {
+      description: "Take a screenshot of the current page. Optionally crop to a specific element (selector) or highlight elements before capturing (mask).",
+      inputSchema: {
+        sessionId: z.string().describe("Session ID"),
+        selector: z.string().optional().describe("CSS selector \u2014 crop screenshot to the bounding box of this element"),
+        mask: z.array(z.string()).optional().describe("CSS selectors whose matching elements are highlighted (dark overlay, element spotlighted)"),
+        fullPage: z.boolean().optional().describe("Capture the full scrollable page (default: false)")
+      }
+    },
+    async (input) => {
+      try {
+        const session = sessions2.get(input.sessionId);
+        sessions2.touch(input.sessionId);
+        const page = session.controller.page;
+        let file;
+        if (input.selector) {
+          file = await screenshotElement(page, input.selector);
+        } else {
+          const masks = input.mask?.map((sel) => page.locator(sel)) ?? [];
+          file = await screenshot(page, {
+            fullPage: input.fullPage ?? false,
+            ...masks.length ? { mask: masks } : {}
+          });
+        }
+        await mkdir(session.artifactDir, { recursive: true });
+        const path = join(session.artifactDir, file.name);
+        await writeFile(path, await file.bytes());
+        return text(JSON.stringify({ path, mimeType: "image/png" }));
+      } catch (e) {
+        return err(`Screenshot failed: ${e.message}`);
+      }
+    }
+  );
+}
+function registerSessionClose(server2, sessions2) {
+  server2.registerTool(
+    "letsrunit_session_close",
+    {
+      description: "Close a browser session and release its resources.",
+      inputSchema: {
+        sessionId: z.string().describe("Session ID to close")
+      }
+    },
+    async (input) => {
+      try {
+        await sessions2.close(input.sessionId);
+        return text(JSON.stringify({ closed: true }));
+      } catch (e) {
+        return err(`Failed to close session: ${e.message}`);
+      }
+    }
+  );
+}
+function registerSessionStart(server2, sessions2) {
+  server2.registerTool(
+    "letsrunit_session_start",
+    {
+      description: "Launch a new browser session. Does not navigate anywhere \u2014 use letsrunit_run with a Given step to navigate.",
+      inputSchema: {
+        language: z.string().optional().describe("Browser language code, e.g. 'en', 'fr'"),
+        headless: z.boolean().optional().describe("Run browser in headless mode (default: true)"),
+        viewportWidth: z.number().int().optional().describe("Viewport width in pixels (default: 1280)"),
+        viewportHeight: z.number().int().optional().describe("Viewport height in pixels (default: 720)")
+      }
+    },
+    async (input) => {
+      try {
+        const viewport = input.viewportWidth || input.viewportHeight ? { width: input.viewportWidth ?? 1280, height: input.viewportHeight ?? 720 } : void 0;
+        const session = await sessions2.create({
+          headless: input.headless ?? true,
+          locale: input.language,
+          viewport
+        });
+        return text(JSON.stringify({ sessionId: session.id }));
+      } catch (e) {
+        return err(`Failed to start session: ${e.message}`);
+      }
+    }
+  );
+}
+function registerSnapshot(server2, sessions2) {
+  server2.registerTool(
+    "letsrunit_snapshot",
+    {
+      description: "Get the current page HTML, scrubbed for LLM consumption. Use selector to scope to a DOM subtree.",
+      inputSchema: {
+        sessionId: z.string().describe("Session ID"),
+        selector: z.string().optional().describe("CSS selector \u2014 return only the matching element's outer HTML instead of the full page"),
+        dropHidden: z.boolean().optional().describe("Remove hidden/inert nodes (default: true)"),
+        dropHead: z.boolean().optional().describe("Remove the <head> element (default: true)"),
+        pickMain: z.boolean().optional().describe("Keep only the <main> element (default: auto)"),
+        stripAttributes: z.union([z.literal(0), z.literal(1), z.literal(2)]).optional().describe("Attribute allowlist level: 0=none, 1=semantic (default), 2=aggressive")
+      }
+    },
+    async (input) => {
+      try {
+        const session = sessions2.get(input.sessionId);
+        sessions2.touch(input.sessionId);
+        const page = session.controller.page;
+        const url = page.url();
+        const opts = {
+          dropHidden: input.dropHidden,
+          dropHead: input.dropHead,
+          pickMain: input.pickMain,
+          stripAttributes: input.stripAttributes
+        };
+        let html;
+        if (input.selector) {
+          const rawHtml = await page.locator(input.selector).first().evaluate((el) => el.outerHTML);
+          html = await scrubHtml({ html: rawHtml, url }, opts);
+        } else {
+          html = await scrubHtml(page, opts);
+        }
+        return text(JSON.stringify({ url, html }));
+      } catch (e) {
+        return err(`Snapshot failed: ${e.message}`);
+      }
+    }
+  );
+}
+
+// src/index.ts
+var sessions = new SessionManager();
+var server = new McpServer({
+  name: "letsrunit",
+  version: "0.1.0",
+  websiteUrl: "https://letsrunit.ai"
+});
+registerSessionStart(server, sessions);
+registerRun(server, sessions);
+registerSnapshot(server, sessions);
+registerScreenshot(server, sessions);
+registerDebug(server, sessions);
+registerSessionClose(server, sessions);
+registerListSessions(server, sessions);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sessions.ts","../src/utility/response.ts","../src/tools/debug.ts","../src/tools/list-sessions.ts","../src/utility/gherkin.ts","../src/tools/run.ts","../src/tools/screenshot.ts","../src/tools/session-close.ts","../src/tools/session-start.ts","../src/tools/snapshot.ts","../src/index.ts"],"names":["server","sessions","z","join"],"mappings":"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","file":"index.js","sourcesContent":["import { Controller, type ControllerOptions } from '@letsrunit/controller';\nimport { Journal, MemorySink } from '@letsrunit/journal';\nimport { join } from 'node:path';\n\nconst SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes\n\nexport interface Session {\n  id: string;\n  controller: Controller;\n  sink: MemorySink;\n  journal: Journal<MemorySink>;\n  artifactDir: string;\n  createdAt: number;\n  lastActivity: number;\n  stepCount: number;\n}\n\nconst BASE_ARTIFACT_DIR = process.env.LETSRUNIT_ARTIFACT_DIR ?? join(process.env.HOME ?? '/tmp', '.letsrunit', 'artifacts');\n\nfunction sessionId(): string {\n  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);\n}\n\nexport class SessionManager {\n  private readonly sessions = new Map<string, Session>();\n  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();\n\n  async create(options: ControllerOptions = {}): Promise<Session> {\n    const id = sessionId();\n    const artifactDir = join(BASE_ARTIFACT_DIR, id);\n\n    const sink = new MemorySink(artifactDir);\n    const journal = new Journal(sink);\n\n    const controller = await Controller.launch({ ...options, journal });\n\n    const session: Session = {\n      id,\n      controller,\n      sink,\n      journal,\n      artifactDir,\n      createdAt: Date.now(),\n      lastActivity: Date.now(),\n      stepCount: 0,\n    };\n\n    this.sessions.set(id, session);\n    this.resetTimer(id);\n\n    return session;\n  }\n\n  get(id: string): Session {\n    const session = this.sessions.get(id);\n    if (!session) throw new Error(`Session not found: ${id}`);\n    return session;\n  }\n\n  has(id: string): boolean {\n    return this.sessions.has(id);\n  }\n\n  touch(id: string): void {\n    const session = this.sessions.get(id);\n    if (session) {\n      session.lastActivity = Date.now();\n      this.resetTimer(id);\n    }\n  }\n\n  list(): Session[] {\n    return Array.from(this.sessions.values());\n  }\n\n  async close(id: string): Promise<void> {\n    const session = this.sessions.get(id);\n    if (!session) return;\n\n    clearTimeout(this.timers.get(id));\n    this.timers.delete(id);\n    this.sessions.delete(id);\n\n    await session.controller.close();\n  }\n\n  private resetTimer(id: string): void {\n    clearTimeout(this.timers.get(id));\n    const timer = setTimeout(() => this.close(id), SESSION_TIMEOUT_MS);\n    // Allow Node.js to exit even if a timer is pending\n    if (typeof timer === 'object' && 'unref' in timer) timer.unref();\n    this.timers.set(id, timer);\n  }\n}\n","export function text(content: string) {\n  return { content: [{ type: 'text' as const, text: content }] };\n}\n\nexport function err(message: string) {\n  return { content: [{ type: 'text' as const, text: message }], isError: true };\n}\n","import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\nimport { type SessionManager } from '../sessions';\nimport { text } from '../utility/response';\n\nexport function registerDebug(server: McpServer, sessions: SessionManager): void {\n  server.registerTool(\n    'letsrunit_debug',\n    {\n      description:\n        'Evaluate JavaScript on the current page via Playwright page.evaluate(). Use for debugging — not for test logic.',\n      inputSchema: {\n        sessionId: z.string().describe('Session ID'),\n        script: z.string().describe('JavaScript expression or function body to evaluate in the page context'),\n      },\n    },\n    async (input) => {\n      try {\n        const session = sessions.get(input.sessionId);\n        sessions.touch(input.sessionId);\n\n        const result = await session.controller.page.evaluate(input.script);\n        return text(JSON.stringify({ result }));\n      } catch (e) {\n        return text(JSON.stringify({ result: null, error: (e as Error).message }));\n      }\n    },\n  );\n}\n","import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { type SessionManager } from '../sessions';\nimport { text } from '../utility/response';\n\nexport function registerListSessions(server: McpServer, sessions: SessionManager): void {\n  server.registerTool(\n    'letsrunit_list_sessions',\n    {\n      description: 'List all active browser sessions.',\n      inputSchema: {},\n    },\n    async () => {\n      const list = sessions.list().map((s) => ({\n        sessionId: s.id,\n        createdAt: s.createdAt,\n        lastActivity: s.lastActivity,\n        stepCount: s.stepCount,\n        artifactDir: s.artifactDir,\n      }));\n\n      return text(JSON.stringify({ sessions: list }));\n    },\n  );\n}\n","export function normalizeGherkin(input: string): string {\n  const trimmed = input.trim();\n\n  if (/^(Feature|Scenario|Background):/im.test(trimmed)) {\n    return trimmed;\n  }\n\n  return `Feature: MCP\\n\\nScenario: Steps\\n  ${trimmed.split('\\n').join('\\n  ')}`;\n}\n","import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\nimport type { SessionManager } from '../sessions';\nimport { normalizeGherkin } from '../utility/gherkin';\nimport { err, text } from '../utility/response';\n\nexport function registerRun(server: McpServer, sessions: SessionManager): void {\n  server.registerTool(\n    'letsrunit_run',\n    {\n      description:\n        'Execute Gherkin steps or a complete feature in the browser. ' +\n        'Accepts a single step line, multiple step lines, a full Scenario, or a full Feature. ' +\n        'Returns status, steps, reason on failure, and journal entries. Does not return a page snapshot — call letsrunit_snapshot explicitly if you need the DOM.',\n      inputSchema: {\n        sessionId: z.string().describe('Session ID returned by letsrunit_session_start'),\n        input: z\n          .string()\n          .describe(\n            'Gherkin text to execute: one or more step lines (e.g. \"Given I am on \\\\\"https://example.com\\\\\"\"), a Scenario block, or a full Feature block.',\n          ),\n      },\n    },\n    async (input) => {\n      try {\n        const session = sessions.get(input.sessionId);\n        sessions.touch(input.sessionId);\n\n        const feature = normalizeGherkin(input.input);\n\n        session.sink.clear();\n        const result = await session.controller.run(feature);\n        session.stepCount += result.steps.length;\n\n        return text(\n          JSON.stringify({\n            status: result.status,\n            steps: result.steps,\n            reason: result.reason?.message,\n            journal: session.sink.getEntries(),\n          }),\n        );\n      } catch (e) {\n        return err(`Run failed: ${(e as Error).message}`);\n      }\n    },\n  );\n}\n","import { screenshot, screenshotElement } from '@letsrunit/playwright';\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { mkdir, writeFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport { z } from 'zod';\nimport { type SessionManager } from '../sessions';\nimport { err, text } from '../utility/response';\n\nexport function registerScreenshot(server: McpServer, sessions: SessionManager): void {\n  server.registerTool(\n    'letsrunit_screenshot',\n    {\n      description:\n        'Take a screenshot of the current page. Optionally crop to a specific element (selector) or highlight elements before capturing (mask).',\n      inputSchema: {\n        sessionId: z.string().describe('Session ID'),\n        selector: z\n          .string()\n          .optional()\n          .describe('CSS selector — crop screenshot to the bounding box of this element'),\n        mask: z\n          .array(z.string())\n          .optional()\n          .describe('CSS selectors whose matching elements are highlighted (dark overlay, element spotlighted)'),\n        fullPage: z.boolean().optional().describe('Capture the full scrollable page (default: false)'),\n      },\n    },\n    async (input) => {\n      try {\n        const session = sessions.get(input.sessionId);\n        sessions.touch(input.sessionId);\n\n        const page = session.controller.page;\n\n        let file: File;\n\n        if (input.selector) {\n          file = await screenshotElement(page, input.selector);\n        } else {\n          const masks = input.mask?.map((sel) => page.locator(sel)) ?? [];\n          file = await screenshot(page, {\n            fullPage: input.fullPage ?? false,\n            ...(masks.length ? { mask: masks } : {}),\n          });\n        }\n\n        await mkdir(session.artifactDir, { recursive: true });\n        const path = join(session.artifactDir, file.name);\n        await writeFile(path, await file.bytes());\n\n        return text(JSON.stringify({ path, mimeType: 'image/png' }));\n      } catch (e) {\n        return err(`Screenshot failed: ${(e as Error).message}`);\n      }\n    },\n  );\n}\n","import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\nimport type { SessionManager } from '../sessions';\nimport { err, text } from '../utility/response';\n\nexport function registerSessionClose(server: McpServer, sessions: SessionManager): void {\n  server.registerTool(\n    'letsrunit_session_close',\n    {\n      description: 'Close a browser session and release its resources.',\n      inputSchema: {\n        sessionId: z.string().describe('Session ID to close'),\n      },\n    },\n    async (input) => {\n      try {\n        await sessions.close(input.sessionId);\n        return text(JSON.stringify({ closed: true }));\n      } catch (e) {\n        return err(`Failed to close session: ${(e as Error).message}`);\n      }\n    },\n  );\n}\n","import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\nimport type { SessionManager } from '../sessions';\nimport { err, text } from '../utility/response';\n\nexport function registerSessionStart(server: McpServer, sessions: SessionManager): void {\n  server.registerTool(\n    'letsrunit_session_start',\n    {\n      description:\n        'Launch a new browser session. Does not navigate anywhere — use letsrunit_run with a Given step to navigate.',\n      inputSchema: {\n        language: z.string().optional().describe(\"Browser language code, e.g. 'en', 'fr'\"),\n        headless: z.boolean().optional().describe('Run browser in headless mode (default: true)'),\n        viewportWidth: z.number().int().optional().describe('Viewport width in pixels (default: 1280)'),\n        viewportHeight: z.number().int().optional().describe('Viewport height in pixels (default: 720)'),\n      },\n    },\n    async (input) => {\n      try {\n        const viewport =\n          input.viewportWidth || input.viewportHeight\n            ? { width: input.viewportWidth ?? 1280, height: input.viewportHeight ?? 720 }\n            : undefined;\n\n        const session = await sessions.create({\n          headless: input.headless ?? true,\n          locale: input.language,\n          viewport,\n        });\n\n        return text(JSON.stringify({ sessionId: session.id }));\n      } catch (e) {\n        return err(`Failed to start session: ${(e as Error).message}`);\n      }\n    },\n  );\n}\n","import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { scrubHtml } from '@letsrunit/playwright';\nimport { z } from 'zod';\nimport { type SessionManager } from '../sessions';\nimport { err, text } from '../utility/response';\n\nexport function registerSnapshot(server: McpServer, sessions: SessionManager): void {\n  server.registerTool(\n    'letsrunit_snapshot',\n    {\n      description:\n        'Get the current page HTML, scrubbed for LLM consumption. Use selector to scope to a DOM subtree.',\n      inputSchema: {\n        sessionId: z.string().describe('Session ID'),\n        selector: z\n          .string()\n          .optional()\n          .describe(\"CSS selector — return only the matching element's outer HTML instead of the full page\"),\n        dropHidden: z.boolean().optional().describe('Remove hidden/inert nodes (default: true)'),\n        dropHead: z.boolean().optional().describe('Remove the <head> element (default: true)'),\n        pickMain: z.boolean().optional().describe('Keep only the <main> element (default: auto)'),\n        stripAttributes: z\n          .union([z.literal(0), z.literal(1), z.literal(2)])\n          .optional()\n          .describe('Attribute allowlist level: 0=none, 1=semantic (default), 2=aggressive'),\n      },\n    },\n    async (input) => {\n      try {\n        const session = sessions.get(input.sessionId);\n        sessions.touch(input.sessionId);\n\n        const page = session.controller.page;\n        const url = page.url();\n\n        const opts = {\n          dropHidden: input.dropHidden,\n          dropHead: input.dropHead,\n          pickMain: input.pickMain,\n          stripAttributes: input.stripAttributes,\n        };\n\n        let html: string;\n\n        if (input.selector) {\n          const rawHtml = await page\n            .locator(input.selector)\n            .first()\n            .evaluate((el: Element) => el.outerHTML);\n          html = await scrubHtml({ html: rawHtml, url }, opts);\n        } else {\n          html = await scrubHtml(page, opts);\n        }\n\n        return text(JSON.stringify({ url, html }));\n      } catch (e) {\n        return err(`Snapshot failed: ${(e as Error).message}`);\n      }\n    },\n  );\n}\n","import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { SessionManager } from './sessions';\nimport {\n  registerDebug,\n  registerListSessions,\n  registerRun,\n  registerScreenshot,\n  registerSessionClose,\n  registerSessionStart,\n  registerSnapshot,\n} from './tools';\n\nconst sessions = new SessionManager();\n\nconst server = new McpServer({\n  name: 'letsrunit',\n  version: '0.1.0',\n  websiteUrl: 'https://letsrunit.ai',\n});\n\nregisterSessionStart(server, sessions);\nregisterRun(server, sessions);\nregisterSnapshot(server, sessions);\nregisterScreenshot(server, sessions);\nregisterDebug(server, sessions);\nregisterSessionClose(server, sessions);\nregisterListSessions(server, sessions);\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n"]}

package/package.json

@@ -1,4 +1,74 @@
 {
   "name": "@letsrunit/mcp-server",
-  "version": "0.0.1"
-}
+  "version": "0.2.6",
+  "description": "MCP server for letsrunit — AI-agent browser test generation and execution",
+  "keywords": [
+    "testing",
+    "automation",
+    "mcp",
+    "playwright",
+    "letsrunit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/letsrunit-hq/letsrunit.git",
+    "directory": "packages/mcp-server"
+  },
+  "bugs": "https://github.com/letsrunit-hq/letsrunit/issues",
+  "homepage": "https://github.com/letsrunit-hq/letsrunit#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "letsrunit-mcp": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsup",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "packageManager": "yarn@4.10.3",
+  "dependencies": {
+    "@letsrunit/controller": "0.2.6",
+    "@letsrunit/journal": "0.2.6",
+    "@letsrunit/playwright": "0.2.6",
+    "@letsrunit/utils": "0.2.6",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@playwright/test": "^1.57.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "@vitest/coverage-v8": "4.0.17",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SessionManager } from './sessions';
+import {
+  registerDebug,
+  registerListSessions,
+  registerRun,
+  registerScreenshot,
+  registerSessionClose,
+  registerSessionStart,
+  registerSnapshot,
+} from './tools';
+
+const sessions = new SessionManager();
+
+const server = new McpServer({
+  name: 'letsrunit',
+  version: '0.1.0',
+  websiteUrl: 'https://letsrunit.ai',
+});
+
+registerSessionStart(server, sessions);
+registerRun(server, sessions);
+registerSnapshot(server, sessions);
+registerScreenshot(server, sessions);
+registerDebug(server, sessions);
+registerSessionClose(server, sessions);
+registerListSessions(server, sessions);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/sessions.ts

@@ -0,0 +1,94 @@
+import { Controller, type ControllerOptions } from '@letsrunit/controller';
+import { Journal, MemorySink } from '@letsrunit/journal';
+import { join } from 'node:path';
+
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+
+export interface Session {
+  id: string;
+  controller: Controller;
+  sink: MemorySink;
+  journal: Journal<MemorySink>;
+  artifactDir: string;
+  createdAt: number;
+  lastActivity: number;
+  stepCount: number;
+}
+
+const BASE_ARTIFACT_DIR = process.env.LETSRUNIT_ARTIFACT_DIR ?? join(process.env.HOME ?? '/tmp', '.letsrunit', 'artifacts');
+
+function sessionId(): string {
+  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
+}
+
+export class SessionManager {
+  private readonly sessions = new Map<string, Session>();
+  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  async create(options: ControllerOptions = {}): Promise<Session> {
+    const id = sessionId();
+    const artifactDir = join(BASE_ARTIFACT_DIR, id);
+
+    const sink = new MemorySink(artifactDir);
+    const journal = new Journal(sink);
+
+    const controller = await Controller.launch({ ...options, journal });
+
+    const session: Session = {
+      id,
+      controller,
+      sink,
+      journal,
+      artifactDir,
+      createdAt: Date.now(),
+      lastActivity: Date.now(),
+      stepCount: 0,
+    };
+
+    this.sessions.set(id, session);
+    this.resetTimer(id);
+
+    return session;
+  }
+
+  get(id: string): Session {
+    const session = this.sessions.get(id);
+    if (!session) throw new Error(`Session not found: ${id}`);
+    return session;
+  }
+
+  has(id: string): boolean {
+    return this.sessions.has(id);
+  }
+
+  touch(id: string): void {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.lastActivity = Date.now();
+      this.resetTimer(id);
+    }
+  }
+
+  list(): Session[] {
+    return Array.from(this.sessions.values());
+  }
+
+  async close(id: string): Promise<void> {
+    const session = this.sessions.get(id);
+    if (!session) return;
+
+    clearTimeout(this.timers.get(id));
+    this.timers.delete(id);
+    this.sessions.delete(id);
+
+    await session.controller.close();
+  }
+
+  private resetTimer(id: string): void {
+    clearTimeout(this.timers.get(id));
+    const timer = setTimeout(() => this.close(id), SESSION_TIMEOUT_MS);
+    // Allow Node.js to exit even if a timer is pending
+    if (typeof timer === 'object' && 'unref' in timer) timer.unref();
+    this.timers.set(id, timer);
+  }
+}

package/src/tools/debug.ts

@@ -0,0 +1,29 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { type SessionManager } from '../sessions';
+import { text } from '../utility/response';
+
+export function registerDebug(server: McpServer, sessions: SessionManager): void {
+  server.registerTool(
+    'letsrunit_debug',
+    {
+      description:
+        'Evaluate JavaScript on the current page via Playwright page.evaluate(). Use for debugging — not for test logic.',
+      inputSchema: {
+        sessionId: z.string().describe('Session ID'),
+        script: z.string().describe('JavaScript expression or function body to evaluate in the page context'),
+      },
+    },
+    async (input) => {
+      try {
+        const session = sessions.get(input.sessionId);
+        sessions.touch(input.sessionId);
+
+        const result = await session.controller.page.evaluate(input.script);
+        return text(JSON.stringify({ result }));
+      } catch (e) {
+        return text(JSON.stringify({ result: null, error: (e as Error).message }));
+      }
+    },
+  );
+}

package/src/tools/index.ts

@@ -0,0 +1,7 @@
+export { registerDebug } from './debug';
+export { registerListSessions } from './list-sessions';
+export { registerRun } from './run';
+export { registerScreenshot } from './screenshot';
+export { registerSessionClose } from './session-close';
+export { registerSessionStart } from './session-start';
+export { registerSnapshot } from './snapshot';

package/src/tools/list-sessions.ts

@@ -0,0 +1,24 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type SessionManager } from '../sessions';
+import { text } from '../utility/response';
+
+export function registerListSessions(server: McpServer, sessions: SessionManager): void {
+  server.registerTool(
+    'letsrunit_list_sessions',
+    {
+      description: 'List all active browser sessions.',
+      inputSchema: {},
+    },
+    async () => {
+      const list = sessions.list().map((s) => ({
+        sessionId: s.id,
+        createdAt: s.createdAt,
+        lastActivity: s.lastActivity,
+        stepCount: s.stepCount,
+        artifactDir: s.artifactDir,
+      }));
+
+      return text(JSON.stringify({ sessions: list }));
+    },
+  );
+}

package/src/tools/run.ts

@@ -0,0 +1,48 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { SessionManager } from '../sessions';
+import { normalizeGherkin } from '../utility/gherkin';
+import { err, text } from '../utility/response';
+
+export function registerRun(server: McpServer, sessions: SessionManager): void {
+  server.registerTool(
+    'letsrunit_run',
+    {
+      description:
+        'Execute Gherkin steps or a complete feature in the browser. ' +
+        'Accepts a single step line, multiple step lines, a full Scenario, or a full Feature. ' +
+        'Returns status, steps, reason on failure, and journal entries. Does not return a page snapshot — call letsrunit_snapshot explicitly if you need the DOM.',
+      inputSchema: {
+        sessionId: z.string().describe('Session ID returned by letsrunit_session_start'),
+        input: z
+          .string()
+          .describe(
+            'Gherkin text to execute: one or more step lines (e.g. "Given I am on \\"https://example.com\\""), a Scenario block, or a full Feature block.',
+          ),
+      },
+    },
+    async (input) => {
+      try {
+        const session = sessions.get(input.sessionId);
+        sessions.touch(input.sessionId);
+
+        const feature = normalizeGherkin(input.input);
+
+        session.sink.clear();
+        const result = await session.controller.run(feature);
+        session.stepCount += result.steps.length;
+
+        return text(
+          JSON.stringify({
+            status: result.status,
+            steps: result.steps,
+            reason: result.reason?.message,
+            journal: session.sink.getEntries(),
+          }),
+        );
+      } catch (e) {
+        return err(`Run failed: ${(e as Error).message}`);
+      }
+    },
+  );
+}

package/src/tools/screenshot.ts

@@ -0,0 +1,57 @@
+import { screenshot, screenshotElement } from '@letsrunit/playwright';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { type SessionManager } from '../sessions';
+import { err, text } from '../utility/response';
+
+export function registerScreenshot(server: McpServer, sessions: SessionManager): void {
+  server.registerTool(
+    'letsrunit_screenshot',
+    {
+      description:
+        'Take a screenshot of the current page. Optionally crop to a specific element (selector) or highlight elements before capturing (mask).',
+      inputSchema: {
+        sessionId: z.string().describe('Session ID'),
+        selector: z
+          .string()
+          .optional()
+          .describe('CSS selector — crop screenshot to the bounding box of this element'),
+        mask: z
+          .array(z.string())
+          .optional()
+          .describe('CSS selectors whose matching elements are highlighted (dark overlay, element spotlighted)'),
+        fullPage: z.boolean().optional().describe('Capture the full scrollable page (default: false)'),
+      },
+    },
+    async (input) => {
+      try {
+        const session = sessions.get(input.sessionId);
+        sessions.touch(input.sessionId);
+
+        const page = session.controller.page;
+
+        let file: File;
+
+        if (input.selector) {
+          file = await screenshotElement(page, input.selector);
+        } else {
+          const masks = input.mask?.map((sel) => page.locator(sel)) ?? [];
+          file = await screenshot(page, {
+            fullPage: input.fullPage ?? false,
+            ...(masks.length ? { mask: masks } : {}),
+          });
+        }
+
+        await mkdir(session.artifactDir, { recursive: true });
+        const path = join(session.artifactDir, file.name);
+        await writeFile(path, await file.bytes());
+
+        return text(JSON.stringify({ path, mimeType: 'image/png' }));
+      } catch (e) {
+        return err(`Screenshot failed: ${(e as Error).message}`);
+      }
+    },
+  );
+}

package/src/tools/session-close.ts

@@ -0,0 +1,24 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { SessionManager } from '../sessions';
+import { err, text } from '../utility/response';
+
+export function registerSessionClose(server: McpServer, sessions: SessionManager): void {
+  server.registerTool(
+    'letsrunit_session_close',
+    {
+      description: 'Close a browser session and release its resources.',
+      inputSchema: {
+        sessionId: z.string().describe('Session ID to close'),
+      },
+    },
+    async (input) => {
+      try {
+        await sessions.close(input.sessionId);
+        return text(JSON.stringify({ closed: true }));
+      } catch (e) {
+        return err(`Failed to close session: ${(e as Error).message}`);
+      }
+    },
+  );
+}

package/src/tools/session-start.ts

@@ -0,0 +1,38 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { SessionManager } from '../sessions';
+import { err, text } from '../utility/response';
+
+export function registerSessionStart(server: McpServer, sessions: SessionManager): void {
+  server.registerTool(
+    'letsrunit_session_start',
+    {
+      description:
+        'Launch a new browser session. Does not navigate anywhere — use letsrunit_run with a Given step to navigate.',
+      inputSchema: {
+        language: z.string().optional().describe("Browser language code, e.g. 'en', 'fr'"),
+        headless: z.boolean().optional().describe('Run browser in headless mode (default: true)'),
+        viewportWidth: z.number().int().optional().describe('Viewport width in pixels (default: 1280)'),
+        viewportHeight: z.number().int().optional().describe('Viewport height in pixels (default: 720)'),
+      },
+    },
+    async (input) => {
+      try {
+        const viewport =
+          input.viewportWidth || input.viewportHeight
+            ? { width: input.viewportWidth ?? 1280, height: input.viewportHeight ?? 720 }
+            : undefined;
+
+        const session = await sessions.create({
+          headless: input.headless ?? true,
+          locale: input.language,
+          viewport,
+        });
+
+        return text(JSON.stringify({ sessionId: session.id }));
+      } catch (e) {
+        return err(`Failed to start session: ${(e as Error).message}`);
+      }
+    },
+  );
+}

package/src/tools/snapshot.ts

@@ -0,0 +1,61 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { scrubHtml } from '@letsrunit/playwright';
+import { z } from 'zod';
+import { type SessionManager } from '../sessions';
+import { err, text } from '../utility/response';
+
+export function registerSnapshot(server: McpServer, sessions: SessionManager): void {
+  server.registerTool(
+    'letsrunit_snapshot',
+    {
+      description:
+        'Get the current page HTML, scrubbed for LLM consumption. Use selector to scope to a DOM subtree.',
+      inputSchema: {
+        sessionId: z.string().describe('Session ID'),
+        selector: z
+          .string()
+          .optional()
+          .describe("CSS selector — return only the matching element's outer HTML instead of the full page"),
+        dropHidden: z.boolean().optional().describe('Remove hidden/inert nodes (default: true)'),
+        dropHead: z.boolean().optional().describe('Remove the <head> element (default: true)'),
+        pickMain: z.boolean().optional().describe('Keep only the <main> element (default: auto)'),
+        stripAttributes: z
+          .union([z.literal(0), z.literal(1), z.literal(2)])
+          .optional()
+          .describe('Attribute allowlist level: 0=none, 1=semantic (default), 2=aggressive'),
+      },
+    },
+    async (input) => {
+      try {
+        const session = sessions.get(input.sessionId);
+        sessions.touch(input.sessionId);
+
+        const page = session.controller.page;
+        const url = page.url();
+
+        const opts = {
+          dropHidden: input.dropHidden,
+          dropHead: input.dropHead,
+          pickMain: input.pickMain,
+          stripAttributes: input.stripAttributes,
+        };
+
+        let html: string;
+
+        if (input.selector) {
+          const rawHtml = await page
+            .locator(input.selector)
+            .first()
+            .evaluate((el: Element) => el.outerHTML);
+          html = await scrubHtml({ html: rawHtml, url }, opts);
+        } else {
+          html = await scrubHtml(page, opts);
+        }
+
+        return text(JSON.stringify({ url, html }));
+      } catch (e) {
+        return err(`Snapshot failed: ${(e as Error).message}`);
+      }
+    },
+  );
+}

package/src/utility/gherkin.ts

@@ -0,0 +1,9 @@
+export function normalizeGherkin(input: string): string {
+  const trimmed = input.trim();
+
+  if (/^(Feature|Scenario|Background):/im.test(trimmed)) {
+    return trimmed;
+  }
+
+  return `Feature: MCP\n\nScenario: Steps\n  ${trimmed.split('\n').join('\n  ')}`;
+}

package/src/utility/response.ts

@@ -0,0 +1,7 @@
+export function text(content: string) {
+  return { content: [{ type: 'text' as const, text: content }] };
+}
+
+export function err(message: string) {
+  return { content: [{ type: 'text' as const, text: message }], isError: true };
+}