feat(mcp): open a session without a config by naming the engine

Merged
KR
7d ago
+728-50

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"}
}
  • engine is a package name, or the factory call a config would write as {package, export?, options?}. The second call above is mobile({ 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. export names any export, so providers already on npm work without a release.
  • app takes url, bundleId, and appPath only.
  • Plain open_session with no config still fails. The error now shows both shapes, which is how an agent finds the option.
  • engine is refused where a config exists, and together with target, config, or test.
  • @e2e-dev/web and @e2e-dev/mobile default-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 e2e works. Only the handle's brand and contract version cross.
  • Core still names no engine: packages/e2e/src/mcp/default-engine.ts imports 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.mdx says so.
  • Only installed packages load. A path, a URL, a .. segment, and a Node builtin name are refused with INVALID_ARGUMENT.
  • A __proto__ key in options stays an own property.

Open for a decision

  • A nested factory call is recognized by shape: package plus nothing but export and options. 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 model engine?: string | { package, export?, options? }. Sol opened e2e.com with the string form, tapped [ docs ], read test_lines, then opened /docs/quickstart with the object form. Every step passed.
  • Claude Code (string form). A fresh session with the server registered by claude mcp add opened 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/web installed with the printed command into a separate ~/.e2e/engines: a session opened, run_code passed a tap and an assertion.
  • iOS simulator (string form). @e2e-dev/mobile drove Safari on a local simulator to e2e.com and the docs.
Web session, docs pageLimrun device, nested provider
weblimrun

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 raw TypeError, 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.url value, 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 than engine. Declined two: offering engine when a lookalike config file exists (that branch predates this PR and names the rename as the fix), and wildcard subpaths of import-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.