feat: Implement session step recording, history lifecycle by Winify · Pull Request #36 · webdriverio/mcp

Winify · 2026-03-16T15:17:54Z

Proposed changes

Session history is exposed via MCP resources (wdio://sessions, wdio://session/current/steps) so clients can inspect recorded steps without tool calls.
The index resource will advertise available URI templates to make session
navigation fully discoverable.
Generated WebdriverIO JS code will branch on session type (browser | ios | android) to emit platform-correct commands, and preserve all recorded params to avoid silent data loss on playback.
Error steps will be wrapped in try/catch rather than commented out, keeping replayed scripts structurally faithful to the original session.

Types of changes

Polish (an improvement for an existing feature)
Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update (improvements to the project's docs)
Specification changes (updates to WebDriver command specifications)
Internal updates (everything related to internal scripts, governance documentation and CI files)

Checklist

I have squashed commits that belong together
I have tested with Claude Desktop (or another MCP-compatible client)
I have read the CONTRIBUTING doc
I have added the necessary documentation for new/changed tools (if appropriate)
I have added proper type definitions for new commands (if appropriate)

Further comments

Reviewers: @webdriverio/project-committers

…verIO code generation - Added `RecordedStep` and `SessionHistory` types for session tracking. - Introduced `withRecording` HOF and `appendStep` for step logging. - Extended browser and app session management to initialize and maintain session histories, including transition sentinels and lifecycle markers. - Developed WebdriverIO JavaScript code generator from recorded steps. - Registered MCP resources for session indexing and step inspection. - Added corresponding tests and updated design documentation.

…tool inputs - Preferring headless browsers

…ort details - Added documentation for session step recording, MCP resources, and generated WebdriverIO JS scripts. - Updated file structure and descriptions to include recording, code generation, and MCP resource components. - Highlighted session recording as a feature in the README.

mccmrunal · 2026-03-17T13:17:34Z

+      };
+      return `const browser = await remote(${indentJson(config)});`;
+    }
+    case 'navigate':


@Winify I see you have added multiple actions here still lot of them are missing are those going to be added in future?

I did not want to capture every tool calling, just driver/browser interactions that induce change

What actions d you think could be good candidates?

You are right, I added the sessions after the initial commit, and it became jumbled, will take a look

mccmrunal · 2026-03-17T13:20:32Z

+  return textContent ? (textContent as any).text : 'Unknown error';
+}
+
+export function withRecording(toolName: string, callback: ToolCallback): ToolCallback {


All existing tools return errors like "Error closing session: ..." or "Error: ...", so this works today, but it is a brittle string-prefix check that will silently miss errors from any future tool that uses a different format (e.g. "Failed to...", "Unable to find...").

Suggestion: Use the MCP SDK's isError field if available, or introduce a convention: tools should set result.isError = true when returning errors, as the SDK supports this.

I will take a look at this

I wanted to refactor the tools' response data for a while now, but somehow always fell short

mccmrunal · 2026-03-17T13:23:42Z

Please take a look at these below points too

The start_browser and start_app_session tools are not wrapped with withRecording() in server.ts
SessionHistory is never cleared ( might lead to memory leak)

Winify · 2026-03-17T16:17:24Z

Please take a look at these below points too

The start_browser and start_app_session tools are not wrapped with withRecording() in server.ts

SessionHistory is never cleared ( might lead to memory leak)

SessionHistory is always appended to existing sessions, start_browser and start_app_session tools are what creating these sessions, so I did not find it useful to describe the sessionHistory of the tool that creates said history
The mcp state is ephemeral, if the server restarts then it just cleans itself

Do you think there will be long-lived sessions where it could pose a problem? I do not think it should be dangerous even with a couple sessions with couple hundred steps

…etection and handling throughout the codebase

…tart_browser tools - Correctly capture the capabilities of the sessions

…) in Resources

Winify · 2026-03-17T17:32:50Z

@mccmrunal I have added some fixes

mccmrunal · 2026-03-18T03:42:02Z

@mccmrunal I have added some fixes

Great updates @Winify! Pulled the latest and went through all the changes , most of the concerns are resolved. I think we can move ahead for now . You can merge this.

Base automatically changed from feature/attach-emulate-tools to main March 17, 2026 07:22

Winify marked this pull request as ready for review March 17, 2026 07:24

Winify added 3 commits March 17, 2026 08:58

chore: Infer session capabilities from start_app_session and browser …

24e4fdb

…tool inputs - Preferring headless browsers

fix: Use browser.$() for element instead of $()

630201b

Winify force-pushed the feature/session-recording branch from abcf3a4 to 630201b Compare March 17, 2026 07:58

wdio-bot and others added 2 commits March 17, 2026 08:01

chore: release v2.4.1

f18a945

mccmrunal reviewed Mar 17, 2026

View reviewed changes

Winify added 3 commits March 17, 2026 17:25

refactor: Mark tool errors with isError flag for consistent error d…

186a03a

…etection and handling throughout the codebase

fix: Use correct abstraction for attach_browser, start_app_session, s…

9cebdbd

…tart_browser tools - Correctly capture the capabilities of the sessions

refactor: Separate session steps (in JSON) and code generation (in JS…

ad7ff03

…) in Resources

Winify merged commit 222e9c3 into main Mar 18, 2026
2 checks passed

Winify deleted the feature/session-recording branch March 19, 2026 17:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Implement session step recording, history lifecycle#36

feat: Implement session step recording, history lifecycle#36
Winify merged 8 commits intomainfrom
feature/session-recording

Winify commented Mar 16, 2026 •

edited

Loading

Uh oh!

mccmrunal Mar 17, 2026

Uh oh!

Winify Mar 17, 2026

Uh oh!

Winify Mar 17, 2026 •

edited

Loading

Uh oh!

mccmrunal Mar 17, 2026

Uh oh!

Winify Mar 17, 2026

Uh oh!

mccmrunal commented Mar 17, 2026 •

edited

Loading

Uh oh!

Winify commented Mar 17, 2026

Uh oh!

Winify commented Mar 17, 2026

Uh oh!

mccmrunal commented Mar 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Winify commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Types of changes

Checklist

Further comments

Reviewers: @webdriverio/project-committers

Uh oh!

mccmrunal Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

Winify Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

Winify Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mccmrunal Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

Winify Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

mccmrunal commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Winify commented Mar 17, 2026

Uh oh!

Winify commented Mar 17, 2026

Uh oh!

mccmrunal commented Mar 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Winify commented Mar 16, 2026 •

edited

Loading

Winify Mar 17, 2026 •

edited

Loading

mccmrunal commented Mar 17, 2026 •

edited

Loading