Skip to content

fix(mcp): resolve named engines using export conditions - #1762

Open
BloggerBust wants to merge 4 commits into
e2e-inc:mainfrom
BloggerBust:fix/mcp-import-conditions
Open

BloggerBust wants to merge 4 commits into
e2e-inc:mainfrom
BloggerBust:fix/mcp-import-conditions

Conversation

@BloggerBust

@BloggerBust BloggerBust commented Nov 13, 2026 •

Copy link
Copy Markdown

What and why

  • Resolve MCP engine packages using exsolve with ESM import conditions, matching how the modules are loaded.
  • Preserve the existing package lookup order and add regression tests.

Issue

Fixes #1758

Verified

Ran it locally: yes

  • Published e2e@0.23.1: the standalone reproduction confirms the wrong export is selected.
  • Fix branch: pnpm build and pnpm plugins:check passed. MCP regression tests and e2e package tests passed.

Checklist

  • Changeset added (pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only.
  • Breaking change: title carries !, the changeset body names what breaks and what replaces it, and the deprecation warning landed a window earlier (stability policy in CONTRIBUTING.md).
  • Docs updated in the same PR: the docs/**/*.mdx page for the behavior, and skills/e2e/ if the skill describes it.
  • Contract change: emitted .d.ts reviewed, tests/types/sdk-types.ts updated; wire change edits the schema and both fixtures.
  • Engine contract change (e2e/engine): changesets for e2e, @e2e-dev/web, and @e2e-dev/mobile.

View guided diff

@github-actions github-actions Bot added the size:L Up to 499 changed lines, not counting tests, fixtures, or the lockfile label Nov 13, 2026

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 9 files

Heads up: you’ve reached your flex budget. Increase your flex budget or wait for usage to reset.

View guided diff | Re-trigger cubic

@okwasniewski okwasniewski left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[claude-opus-5-5] automated review on behalf of @okwasniewski

Thanks for the issue, the repro and the fix! #1759 also fixes #1758, so both PRs get the same comparison.

I tested it with a fake engine package in 22 export shapes and compared the file each resolver picks with the file a real import() loads (Node 24). The main problem is the rule. default-engine.ts:~31 resolves with node, import and require all on, so the package's own key order decides. import() never matches require, which means this only fixes packages that list import first (the issue's repro). These all still load the require file:

  • {require, import}
  • {".": {types, require, import}}
  • nested node: {require, import}
  • {require, default}
  • require-first subpath and pattern exports, and pnpm-linked require-first packages

The tests lock in that behavior: "loads dual ... require" expects cjs, and the nested tests compare against import() run with --conditions=require.

Asks:

  • Resolve with import conditions only (['node', 'import', 'module-sync']), and fall back to main's createRequire().resolve on ERR_PACKAGE_PATH_NOT_EXPORTED for CommonJS-only engines. With that one change, resolveModuleURL matched import() in all 22 cases.
  • Remove addonsEnabled/nodeOptionsArgs, the hand-written NODE_OPTIONS parser that only decides node-addons, along with the ~20 child-process tests that cover it.
  • Flip the require-first tests to expect esm.
  • 5/51 tests fail on macOS because /var and /private/var differ. Compare realpaths in the error-path tests.
  • Remove the additions to docs/reference/mcp.mdx:589-593 and both skills/.../mcp.md copies. --conditions and loader hooks are internals.
  • Reword the changeset: "first matching entry in export order" describes the wrong rule. Something like: "MCP sessions load an engine package's import entry, as import() does."
  • nodeEngineConditions needs JSDoc.

Whether e2e takes exsolve (1.2.0, no dependencies of its own, 59 KB) as a runtime dependency is a maintainer call, and so is which of the two PRs carries the fix.

Resolve named MCP engine packages using ESM import conditions
to match how the modules are loaded.
@BloggerBust
BloggerBust force-pushed the fix/mcp-import-conditions branch from 34886e6 to b55cba1 Compare November 13, 2026 23:52
@github-actions github-actions Bot added size:M Up to 99 changed lines, not counting tests, fixtures, or the lockfile and removed size:L Up to 499 changed lines, not counting tests, fixtures, or the lockfile labels Nov 13, 2026
@BloggerBust

BloggerBust commented Nov 14, 2026 •

Copy link
Copy Markdown
Author

@okwasniewski Thanks for the review. I have updated the PR to use ESM import conditions, removed the NODE_OPTIONS handling, corrected the tests, and addressed the macOS path issue. For your awareness, removing the NODE_OPTIONS handling also means the loader no longer supports the node-addons export condition. Let me know if you'd like to retain that behavior.

Also, the require-only fallback is still outstanding. I am heading out for dinner now, but I will look into it when I get back.

@BloggerBust

BloggerBust commented Nov 14, 2026 •

Copy link
Copy Markdown
Author

Hey @okwasniewski, there are some challenges implementing the require only fallback while distinguishing between unmatched import conditions and explicitly blocked imports. I investigated several alternative resolvers, but have not found one that reliably exposes that distinction. One possible approach to consider would be a small inspection of package.json when import resolution fails. This could support straightforward require only exports without adding another dependency or implementing a full export map resolver.

Here is the behavior I am proposing:

Export configuration Expected behavior
{ import: './engine.mjs' } Load ESM
{ import: './engine.mjs', require: './engine.cjs' } Load ESM
{ require: './engine.cjs', import: './engine.mjs' } Load ESM
{ require: './engine.cjs' } Fall back to CommonJS
{ './web': { require: './web.cjs' } } Fall back to CommonJS for the exact pkg/web subpath
{ import: null, require: './engine.cjs' } Fail because explicitly blocked
{ import: './missing.mjs', require: './engine.cjs' } Fail because declared import target is missing
{ default: './engine.mjs', require: './engine.cjs' } Load the default entry
Nested, array, or pattern based require-only exports Fallback only where eligibility can be safely established

The idea is to keep exsolve responsible for resolution and use the manifest inspection only to decide whether a CommonJS fallback is appropriate. Ambiguous cases would remain errors. Would this fallback strategy be acceptable?

In the meantime, I will investigate a few more resolver candidates to see whether there is a better solution.

@okwasniewski

Copy link
Copy Markdown
Member

[claude-opus-5-5] automated review on behalf of @okwasniewski

Thanks, all previous asks are in. I compared 36 export shapes against a real import() on Node 24 and this head matches in 35. The miss is node-addons, which import() matches by default.

  • default-engine.ts:20-25: make the conditions one plain const and add 'node-addons', e.g. const ENGINE_CONDITIONS = ['node', 'import', ...(process.features.require_module ? ['module-sync'] : []), 'node-addons'];. Then the [...] copy at :168 can go.
  • Require-only fallback: you're right that it can't be done through exsolve. It rethrows every failure as a generic not-found, and Node raises the same ERR_PACKAGE_PATH_NOT_EXPORTED for {import: null, require} and {require} anyway. Please hold off on the package.json inspection. We lean toward no fallback (matching import()); if we keep one, the rule would be: after exsolve fails, use createRequire().resolve only when every leaf (string or null) of exports sits under a require key, no subpath or pattern matching. A maintainer will confirm which, along with the exsolve dependency itself.
  • Optional: the two spawnSync harnesses in the unit test could share one helper.

Approved CI for this head.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 2 files (changes from recent commits).

Heads up: you’ve reached your flex budget. Increase your flex budget or wait for usage to reset.

Requires human review: Auto-approval skipped because cubic reviewed only this push, not the earlier force-push. Comment @cubic review to review the whole pull request.

View guided diff | Re-trigger cubic

Comment thread packages/e2e/src/mcp/default-engine.ts Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 3 files (changes from recent commits).

Heads up: you’ve reached your flex budget. Increase your flex budget or wait for usage to reset.

Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

View guided diff | Re-trigger cubic

@okwasniewski

Copy link
Copy Markdown
Member

[claude-opus-5-5] automated review on behalf of @okwasniewski

Re-reviewed at 5b466791c. The node-addons ask is done, and checking it through Node's own resolver (#e2e-node-addons in imports) is the right call. It catches --no-addons, NODE_OPTIONS and Bun, with no flag parsing.

  • I compared 40 export shapes (the 36 from before, plus 4 node-addons variants) against real import(). 0 mismatches on Node 24 source (default, --no-addons, NODE_OPTIONS=--no-addons, --no-experimental-require-module), on dist with Node 22 and 26, and on the packed tarball under node, --no-addons, NODE_OPTIONS and bun.
  • MCP tests pass 55/55 on Node 22/24/26. Typecheck and lint are clean. I broke the condition logic in 9 different ways and a test failed every time.
  • exsolve 1.2.0 is the latest version, exact-pinned, and has no transitive deps.

Optional nits:

  • default-engine.ts:24: add one line saying the #e2e-node-addons entry exists so Node's resolver can report whether addons are on. Without that, the package.json entry looks like dead config.
  • tests/unit/mcp-default-engine.test.ts: the two spawnSync harnesses still repeat the loader URL and the NODE_OPTIONS: '' setup.

Nothing blocking on the code. The only open item is a maintainer call on adding exsolve as a dependency (#1759 is the no-dep alternative), so this is going to human review.

@okwasniewski
okwasniewski dismissed their stale review November 14, 2026 22:16

All asks done at 5b46679, see latest comment (automated review).

# Conflicts:
#	packages/e2e/src/mcp/default-engine.ts
@okwasniewski

Copy link
Copy Markdown
Member

Note

Automated review.

Main moved the engine imports to @e2e-dev/core (#1736), which conflicted with this branch. I pushed a merge of main (96e82da0f): the only conflict was the import block in default-engine.ts, kept exsolve plus the new core paths. mcp-default-engine unit (42) and mcp-server integration (13) pass locally, typecheck clean. The earlier red test (26) was the known ACP ENOTEMPTY flake, not this change. Will re-label once CI is green.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Ready for Human Review size:M Up to 99 changed lines, not counting tests, fixtures, or the lockfile

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MCP engine resolution selects require export condition instead of import

2 participants