feat(mcp): open a session without a config by naming the engine
e2e mcp only worked next to an e2e.config.ts. A coding agent in a fresh directory got CONFIG_NOT_FOUND and had to set a project up before it could look at an app. Now open_session can name the engine instead.
Fixes ENG-1191.
open_session {engine: "@e2e-dev/web", app: {url: "http://localhost:3000"}}
open_session {
engine: {package: "@e2e-dev/mobile", options: {
platform: "ios",
device: {package: "@e2e-dev/limrun", export: "limrun", options: {region: "eu"}}
}},
app: {bundleId: "com.example.app"}
}
engineis a package name, or the factory call a config would write as{package, export?, options?}. The second call above ismobile({ platform: 'ios', device: limrun({ region: 'eu' }) }).- An option value with only those keys is called first and replaced by its result. That is how an engine gets a device or browser provider, which JSON can't carry.
exportnames any export, so providers already on npm work without a release. apptakesurl,bundleId, andappPathonly.- Plain
open_sessionwith no config still fails. The error now shows both shapes, which is how an agent finds the option. engineis refused where a config exists, and together withtarget,config, ortest.@e2e-dev/weband@e2e-dev/mobiledefault-export their factory.mobile()without a platform now says which platforms it takes.
Where a package comes from
flowchart LR
A[package name] --> B{in the project?}
B -- yes --> L[load it]
B -- no --> C{beside e2e?}
C -- yes --> L
C -- no --> D{in ~/.e2e/engines?}
D -- yes --> L
D -- no --> E[ENGINE_NOT_INSTALLED<br/>names the npm command]
- The server installs nothing. The agent runs the command the error prints, in its own shell.
- An engine that brings its own copy of
e2eworks. Only the handle's brand and contract version cross. - Core still names no engine:
packages/e2e/src/mcp/default-engine.tsimports a resolved file, never a specifier.
Security
- This is the first MCP argument that makes the server load code the agent named.
docs/reference/security.mdxsays so. - Only installed packages load. A path, a URL, a
..segment, and a Node builtin name are refused withINVALID_ARGUMENT. - A
__proto__key inoptionsstays an own property.
Open for a decision
- A nested factory call is recognized by shape:
packageplus nothing butexportandoptions. A third-party engine option that looks like that would be read as a call. No shipped engine or provider has one. The fresh-context reviewer suggested a reserved key such as{$call: {...}}. I kept the plain shape, made the options object itself never a call, and made the not-installed error say how the value was read.
Verified
Ran it locally: yes
Surface: the built e2e mcp server in directories with no config.
Final build, driven over stdio (limrun here is the repo's, with #1663):
>>> open_session {}
CONFIG_NOT_FOUND: no e2e.config.ts, e2e.config.mts, e2e.config.js, or e2e.config.mjs found in <project> or its parent directories; run e2e init to create one, or pass engine to open_session to open a session without one: {engine: "@e2e-dev/web", app: {url: "<app URL>"}}, or {engine: {package: "@e2e-dev/mobile", options: {platform: "ios"}}, app: {bundleId: "<app>"}}
>>> open_session {"engine":"util"}
INVALID_ARGUMENT: open_session: engine names an installed package such as "@e2e-dev/web", got "util"
>>> open_session {"engine":"@e2e-dev/mobile","app":{"bundleId":"com.apple.mobilesafari"}}
INVALID_CONFIG: mobile() needs platform: 'ios' or 'android', got no platform
>>> open_session {"engine":{"package":"@e2e-dev/mobile","options":{"platform":"ios","device":{"package":"@e2e-dev/absent-cloud"}}},"app":{"bundleId":"com.apple.mobilesafari"}}
ENGINE_NOT_INSTALLED: an option value with only package, export, and options keys is read as a factory call, and package @e2e-dev/absent-cloud is not installed in <project>, beside e2e, or in ~/.e2e/engines. Install it once for every project with: npm install --prefix "~/.e2e/engines" @e2e-dev/absent-cloud; then call open_session again
>>> open_session {"engine":{"package":"@e2e-dev/mobile","options":{"platform":"ios","device":{"package":"@e2e-dev/limrun","export":"limrun","options":{"hardTimeout":"15m"}}}},"app":{"bundleId":"com.apple.mobilesafari"}}
Session 01a1c478-7df0-770e-ab87-b38dcb0a1590 open on target "ios" (platform ios, engine mobile 0.12.6), headless; no config file: one target on @e2e-dev/mobile, every other setting at its default. run_tests and open_session {test} need an e2e.config.ts (npx e2e init writes one).
App: com.apple.mobilesafari, launched fresh.
>>> close_session {}
Session 01a1c478-7df0-770e-ab87-b38dcb0a1590 closed (closed by the agent); 1 tool calls ran.
Real clients calling the tools, on earlier builds of this branch:
- Codex, GPT-6.1 Sol (before the last review-fix commit). The server was added with
codex mcp add. Codex showed the modelengine?: string | { package, export?, options? }. Sol opened e2e.com with the string form, tapped[ docs ], readtest_lines, then opened/docs/quickstartwith the object form. Every step passed. - Claude Code (string form). A fresh session with the server registered by
claude mcp addopened e2e.com, went to the docs, and returned a four-line draft test. - Two copies of
e2e. The runner alone in one tree,@e2e-dev/webinstalled with the printed command into a separate~/.e2e/engines: a session opened,run_codepassed a tap and an assertion. - iOS simulator (string form).
@e2e-dev/mobiledrove Safari on a local simulator to e2e.com and the docs.
| Web session, docs page | Limrun device, nested provider |
|---|---|
Not verified: Android, and an engine installed with pnpm or Bun into ~/.e2e/engines.
Review
- Fresh-context review, seven findings. Fixed:
import-only packages failed to load, an installed package with no built entry was reported as not installed,engine: "@e2e-dev/mobile"failed with a rawTypeError, a Node builtin name became a file import, two untested hunks, a stale comment. Kept with changes: the shape rule above. - Bot review on the PR, eight findings. Fixed six: a skill example with no
app.urlvalue, a__proto__test that would pass if the key were dropped, "no e2e.config.ts" where any config name counts, one debugging-table row covering two error codes, the string shorthand missing from AGENTS.md, and a security sentence that read as covering more thanengine. Declined two: offeringenginewhen a lookalike config file exists (that branch predates this PR and names the rename as the fix), and wildcard subpaths ofimport-only packages (the import fallback is deliberately narrow and fails with an explicit error). - Reviewed with sol-loop: 2 rounds with gpt-6.1-sol. Sol verdict: approved. That was before the review-fix commits.
Docs pass: docs/mcp-server.mdx 199 to 212 lines, 1065 to 1105 prose words. docs/writing-an-engine.mdx 306 to 326 lines, 1606 to 1665 words. Both gain one short section; nothing was cut.
Written by Claude Fable 5.2 in T3 Code, on the Claude Code harness.