Merge pull request #36 from webdriverio/feature/session-recording

feat: Implement session step recording, history lifecycle

- Using `Resources` for session information
- Code and JSON Steps separately
- Use `isError` for faulty tool calling

Author: Winify

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [2.4.1](https://github.com/webdriverio/mcp/compare/v2.4.0...v2.4.1) (2026-03-17)
+
+### Features
+
+* implement session step recording, history lifecycle, and WebdriverIO code generation ([6c41763](https://github.com/webdriverio/mcp/commit/6c417632fe05414659119e8531bab7394d81318d))
+
+### Bug Fixes
+
+* Use browser.$() for element instead of $() ([630201b](https://github.com/webdriverio/mcp/commit/630201b140b3f6d399ef452796c3a71feca8011a))
+
 ## [2.4.0](https://github.com/webdriverio/mcp/compare/v2.3.1...v2.4.0) (2026-03-17)
 
 ### Features

CLAUDE.md

@@ -15,14 +15,18 @@ npm start         # Run built server from lib/server.js
 
 ```
 src/
-├── server.ts                    # MCP server entry, registers all tools
+├── server.ts                    # MCP server entry, registers all tools + MCP resources
 ├── tools/
 │   ├── browser.tool.ts          # Session state + start_browser + getBrowser()
 │   ├── app-session.tool.ts      # start_app_session (iOS/Android via Appium)
 │   ├── navigate.tool.ts         # URL navigation
 │   ├── get-visible-elements.tool.ts  # Element detection (web + mobile)
-│   ├── click-element.tool.ts    # Click/tap actions
+│   ├── click.tool.ts            # Click/tap actions
 │   └── ...                      # Other tools follow same pattern
+├── recording/
+│   ├── step-recorder.ts         # withRecording HOF, appendStep, session history access
+│   ├── code-generator.ts        # SessionHistory → WebdriverIO JS code
+│   └── resources.ts             # MCP resource builders (sessions index, step log)
 ├── scripts/
 │   └── get-interactable-browser-elements.ts  # Browser-context script
 ├── locators/
@@ -32,7 +36,8 @@ src/
 ├── config/
 │   └── appium.config.ts         # iOS/Android capability builders
 └── types/
-    └── tool.ts                  # ToolDefinition interface
+    ├── tool.ts                  # ToolDefinition interface
+    └── recording.ts             # RecordedStep, SessionHistory interfaces
 ```
 
 ### Session State
@@ -80,6 +85,14 @@ export const myTool: ToolCallback = async ({ param }: { param: string }) => {
 server.tool(myToolDefinition.name, myToolDefinition.description, myToolDefinition.inputSchema, myTool);
 ```
 
+### Recording
+
+All tools are wrapped with `withRecording()` in `server.ts`. Steps accumulate in `state.sessionHistory` (keyed by sessionId).
+MCP resources expose history without tool calls:
+- `wdio://sessions` — index of all sessions (fixed URI, discoverable via ListResources)
+- `wdio://session/current/steps` — current session step log + generated JS (fixed URI)
+- `wdio://session/{sessionId}/steps` — any session by ID (URI template, NOT listed by ListResources — see `docs/architecture/mcp-resources-notes.md`)
+
 ### Build
 
 - **tsup** bundles `src/server.ts` → `lib/server.js` (ESM)
@@ -95,6 +108,9 @@ server.tool(myToolDefinition.name, myToolDefinition.description, myToolDefinitio
 | `src/tools/app-session.tool.ts`                    | Appium session creation                       |
 | `src/scripts/get-interactable-browser-elements.ts` | Browser-context element detection             |
 | `src/locators/`                                    | Mobile element detection + locator generation |
+| `src/recording/step-recorder.ts`                   | `withRecording(toolName, cb)` HOF — wraps every tool for step logging |
+| `src/recording/code-generator.ts`                  | Generates runnable WebdriverIO JS from `SessionHistory` |
+| `src/recording/resources.ts`                       | Builds text for `wdio://sessions` and `wdio://session/*/steps` resources |
 | `tsup.config.ts`                                   | Build configuration                           |
 
 ## Gotchas

README.md

@@ -85,6 +85,7 @@ appium
 - **Scrolling**: Smooth scrolling with configurable distances
 - **Attach to running Chrome**: Connect to an existing Chrome window via `--remote-debugging-port` — ideal for testing authenticated or pre-configured sessions
 - **Device emulation**: Apply mobile/tablet presets (iPhone 15, Pixel 7, etc.) to simulate responsive layouts without a physical device
+- **Session Recording**: All tool calls are automatically recorded and exportable as runnable WebdriverIO JS
 
 ### Mobile App Automation (iOS/Android)
 
@@ -458,6 +459,16 @@ This eliminates the need to manually handle permission popups during automated t
 - **Data Format:** TOON (Token-Oriented Object Notation) for efficient LLM communication
 - **Element Detection:** XML-based page source parsing with intelligent filtering and multi-strategy locator generation
 
+### Session Recording & Code Export
+
+Every tool call is automatically recorded to a session history. You can inspect sessions and export runnable code via MCP resources — no extra tool calls needed:
+
+- `wdio://sessions` — lists all recorded sessions with type, timestamps, and step count
+- `wdio://session/current/steps` — step log for the active session, plus a generated WebdriverIO JS script ready to run with `webdriverio`
+- `wdio://session/{sessionId}/steps` — same for any past session by ID
+
+The generated script reconstructs the full session — including capabilities, navigation, clicks, and inputs — as a standalone `import { remote } from 'webdriverio'` file.
+
 ## Troubleshooting
 
 **Browser automation not working?**

package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "git://github.com/webdriverio/mcp.git"
   },
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)",
   "main": "./lib/server.js",
   "module": "./lib/server.js",

src/config/appium.config.ts

@@ -97,7 +97,7 @@ export function buildIOSCapabilities(
   // Add any additional custom options
   for (const [key, value] of Object.entries(options)) {
     if (
-      !['deviceName', 'platformVersion', 'automationName', 'autoAcceptAlerts', 'autoDismissAlerts', 'udid', 'noReset', 'fullReset', 'newCommandTimeout'].includes(
+      !['deviceName', 'platformVersion', 'automationName', 'autoGrantPermissions', 'autoAcceptAlerts', 'autoDismissAlerts', 'udid', 'noReset', 'fullReset', 'newCommandTimeout'].includes(
         key,
       )
     ) {
@@ -156,7 +156,7 @@ export function buildAndroidCapabilities(
   // Add any additional custom options
   for (const [key, value] of Object.entries(options)) {
     if (
-      !['deviceName', 'platformVersion', 'automationName', 'autoGrantPermissions', 'appWaitActivity', 'noReset', 'fullReset', 'newCommandTimeout'].includes(
+      !['deviceName', 'platformVersion', 'automationName', 'autoGrantPermissions', 'autoAcceptAlerts', 'autoDismissAlerts', 'appWaitActivity', 'noReset', 'fullReset', 'newCommandTimeout'].includes(
         key,
       )
     ) {

src/recording/code-generator.ts

@@ -0,0 +1,82 @@
+// src/recording/code-generator.ts
+import type { RecordedStep, SessionHistory } from '../types/recording';
+
+/** Escape single quotes so generated JS string literals are valid. */
+function escapeStr(value: unknown): string {
+  return String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+function formatParams(params: Record<string, unknown>): string {
+  return Object.entries(params)
+    .map(([k, v]) => `${k}="${v}"`)
+    .join(' ');
+}
+
+function indentJson(value: unknown): string {
+  return JSON.stringify(value, null, 2)
+    .split('\n')
+    .map((line, i) => (i > 0 ? `  ${line}` : line))
+    .join('\n');
+}
+
+function generateStep(step: RecordedStep, history: SessionHistory): string {
+  if (step.tool === '__session_transition__') {
+    const newId = (step.params.newSessionId as string) ?? 'unknown';
+    return `// --- new session: ${newId} started at ${step.timestamp} ---`;
+  }
+
+  if (step.status === 'error') {
+    return `// [error] ${step.tool}: ${formatParams(step.params)} — ${step.error ?? 'unknown error'}`;
+  }
+
+  const p = step.params;
+  switch (step.tool) {
+    case 'start_browser': {
+      const nav = p.navigationUrl ? `\nawait browser.url('${escapeStr(p.navigationUrl)}');` : '';
+      return `const browser = await remote({\n  capabilities: ${indentJson(history.capabilities)}\n});${nav}`;
+    }
+    case 'start_app_session': {
+      const config: Record<string, unknown> = {
+        protocol: 'http',
+        hostname: history.appiumConfig?.hostname ?? 'localhost',
+        port: history.appiumConfig?.port ?? 4723,
+        path: history.appiumConfig?.path ?? '/',
+        capabilities: history.capabilities,
+      };
+      return `const browser = await remote(${indentJson(config)});`;
+    }
+    case 'attach_browser': {
+      const nav = p.navigationUrl ? `\nawait browser.url('${escapeStr(p.navigationUrl)}');` : '';
+      return `const browser = await remote({\n  capabilities: ${indentJson(history.capabilities)}\n});${nav}`;
+    }
+    case 'navigate':
+      return `await browser.url('${escapeStr(p.url)}');`;
+    case 'click_element':
+      return `await browser.$('${escapeStr(p.selector)}').click();`;
+    case 'set_value':
+      return `await browser.$('${escapeStr(p.selector)}').setValue('${escapeStr(p.value)}');`;
+    case 'scroll': {
+      const scrollAmount = (p.direction as string) === 'down' ? (p.pixels as number) : -(p.pixels as number);
+      return `await browser.execute(() => window.scrollBy(0, ${scrollAmount}));`;
+    }
+    case 'tap_element':
+      if (p.selector !== undefined) {
+        return `await browser.$('${escapeStr(p.selector)}').click();`;
+      }
+      return `await browser.tap({ x: ${p.x}, y: ${p.y} });`;
+    case 'swipe':
+      return `await browser.execute('mobile: swipe', { direction: '${escapeStr(p.direction)}' });`;
+    case 'drag_and_drop':
+      if (p.targetSelector !== undefined) {
+        return `await browser.$('${escapeStr(p.sourceSelector)}').dragAndDrop(browser.$('${escapeStr(p.targetSelector)}'));`;
+      }
+      return `await browser.$('${escapeStr(p.sourceSelector)}').dragAndDrop({ x: ${p.x}, y: ${p.y} });`;
+    default:
+      return `// [unknown tool] ${step.tool}`;
+  }
+}
+
+export function generateCode(history: SessionHistory): string {
+  const steps = history.steps.map(step => generateStep(step, history)).join('\n');
+  return `import { remote } from 'webdriverio';\n\n${steps}\n\nawait browser.deleteSession();`;
+}

src/recording/resources.ts

@@ -0,0 +1,55 @@
+// src/recording/resources.ts
+import type { SessionHistory } from '../types/recording';
+import { generateCode } from './code-generator';
+import { getSessionHistory } from './step-recorder';
+import { getBrowser } from '../tools/browser.tool';
+
+function getCurrentSessionId(): string | null {
+  return (getBrowser as any).__state?.currentSession ?? null;
+}
+
+export interface SessionStepsPayload {
+  stepsJson: string;
+  generatedJs: string;
+}
+
+export function buildSessionsIndex(): string {
+  const histories = getSessionHistory();
+  const currentId = getCurrentSessionId();
+  const sessions = Array.from(histories.values()).map((h) => ({
+    sessionId: h.sessionId,
+    type: h.type,
+    startedAt: h.startedAt,
+    ...(h.endedAt ? { endedAt: h.endedAt } : {}),
+    stepCount: h.steps.length,
+    isCurrent: h.sessionId === currentId,
+  }));
+  return JSON.stringify({ sessions });
+}
+
+export function buildCurrentSessionSteps(): SessionStepsPayload | null {
+  const currentId = getCurrentSessionId();
+  if (!currentId) return null;
+
+  return buildSessionStepsById(currentId);
+}
+
+export function buildSessionStepsById(sessionId: string): SessionStepsPayload | null {
+  const history = getSessionHistory().get(sessionId);
+  if (!history) return null;
+
+  return buildSessionPayload(history);
+}
+
+function buildSessionPayload(history: SessionHistory): SessionStepsPayload {
+  const stepsJson = JSON.stringify({
+    sessionId: history.sessionId,
+    type: history.type,
+    startedAt: history.startedAt,
+    ...(history.endedAt ? { endedAt: history.endedAt } : {}),
+    stepCount: history.steps.length,
+    steps: history.steps,
+  });
+
+  return { stepsJson, generatedJs: generateCode(history) };
+}

src/recording/step-recorder.ts

@@ -0,0 +1,62 @@
+// src/recording/step-recorder.ts
+import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp';
+import type { RecordedStep, SessionHistory } from '../types/recording';
+import { getBrowser } from '../tools/browser.tool';
+
+function getState() {
+  return (getBrowser as any).__state as {
+    currentSession: string | null;
+    sessionHistory: Map<string, SessionHistory>;
+  };
+}
+
+export function appendStep(
+  toolName: string,
+  params: Record<string, unknown>,
+  status: 'ok' | 'error',
+  durationMs: number,
+  error?: string,
+): void {
+  const state = getState();
+  const sessionId = state.currentSession;
+  if (!sessionId) return;
+
+  const history = state.sessionHistory.get(sessionId);
+  if (!history) return;
+
+  const step: RecordedStep = {
+    index: history.steps.length + 1,
+    tool: toolName,
+    params,
+    status,
+    durationMs,
+    timestamp: new Date().toISOString(),
+    ...(error !== undefined && { error }),
+  };
+  history.steps.push(step);
+}
+
+export function getSessionHistory(): Map<string, SessionHistory> {
+  return getState().sessionHistory;
+}
+
+function extractErrorText(result: Awaited<ReturnType<ToolCallback>>): string {
+  const textContent = result.content.find((c: any) => c.type === 'text');
+  return textContent ? (textContent as any).text : 'Unknown error';
+}
+
+export function withRecording(toolName: string, callback: ToolCallback): ToolCallback {
+  return async (params, extra) => {
+    const start = Date.now();
+    const result = await callback(params, extra);
+    const isError = (result as any).isError === true;
+    appendStep(
+      toolName,
+      params as Record<string, unknown>,
+      isError ? 'error' : 'ok',
+      Date.now() - start,
+      isError ? extractErrorText(result) : undefined,
+    );
+    return result;
+  };
+}