chore(build): build a universal ESM and CommonJS package #371

gagik · 2025-07-15T11:24:10Z

Adds ESM and CommonJS-based exports to the package.

The motivation is largely to add support for VSCode to use the library.

Possible Alternatives

Target cjs and use gen-esm-wrapper - might be simpler in a sense and more consistent with how we deal with it in i.e. mongosh and other packages. But because we were distributing an ESM package until now, the potential breaking change is a bit worrying.

Inspired by #325

Relevant reading:

…gagik/vitest

…gagik/cjs-target

gagik · 2025-07-15T12:34:46Z

scripts/update-package-info.ts

+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as PackageJson;
+
+// Define the packageInfo.ts content
+const packageInfoContent = `// This file was generated by scripts/update-package-info.ts - Do not edit it manually.


there's no good way to have __dirname / import.meta.dirname as explored in https://evertpot.com/universal-commonjs-esm-typescript-packages/ and I couldn't think of anything better either. so instead we'll generate the file on-demand. This is similar to how it is done in github.com/mongodb-js/mongosh/

coveralls · 2025-07-15T12:38:49Z

Pull Request Test Coverage Report for Build 16804714278

Details

79 of 90 (87.78%) changed or added relevant lines in 5 files are covered.
1 unchanged line in 1 file lost coverage.
Overall coverage increased (+0.1%) to 81.376%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/lib.ts	0	3	0.0%
src/resources/resource.ts	41	49	83.67%

Files with Coverage Reduction	New Missed Lines	%
src/resources/common/config.ts	1	58.14%

Totals
Change from base Build 16790900568:	0.1%
Covered Lines:	3538
Relevant Lines:	4306

💛 - Coveralls

gagik · 2025-07-15T12:39:04Z

package.json

  "scripts": {
    "prepare": "npm run build",
    "build:clean": "rm -rf dist",
-    "build:compile": "tsc --project tsconfig.build.json",
+    "build:update-package-info": "tsx scripts/update-package-info.ts",
+    "build:esm": "tsc --project tsconfig.esm.json && echo '{\"type\":\"module\"}' > dist/package.json",


Source: As you can also see that both our cjs and esm packages get a 1-line package.json file with a type property.

This is required because Node needs to know wether files with a .js extensions should be interpreted as CommonJS or ESM. It can’t figure it out after opening it.

Node will look at the nearest package.json to see if the type property was specified.

tsconfig.esm.json

gagik · 2025-07-15T15:41:10Z

.github/workflows/check.yml

@@ -55,4 +55,4 @@ jobs:
          rm -rf node_modules
          npm pkg set scripts.prepare="exit 0"
          npm install --omit=dev
-      - run: npx -y @modelcontextprotocol/inspector --cli --method tools/list -- node dist/index.js --connectionString "mongodb://localhost"


I'm setting to ESM to keep the changes minimal. Doing cjs default won't change our issues with the oidc-plugin, I think the only way to deal with that is to make some changes on the plugin itself to not depend on the require of an ESM module which is a higher Node version feature.

Generally worth checking if we're going to have any problems with dist/index.js going away.

I'd expect the worst being our dev environment configurations no longer being correct.

Otherwise we can also create a index.js alias to point to esm.

I think this is solved, now that you have dist/index.js pointing to esm.

gagik · 2025-07-15T15:44:12Z

src/lib.ts

@@ -0,0 +1,4 @@
+export { Server, type ServerOptions } from "./server.js";
+export { Telemetry } from "./telemetry/telemetry.js";


we can consider exporting a single class which would make the setup easier but I'll leave that to future followups

gagik · 2025-07-16T08:15:14Z

scripts/createUniversalPackage.ts

+
+// Create a dist/index.js file that imports the ESM index.js file
+// To minimize breaking changes from pre-universal package time.
+const indexPath = resolve(distDir, "index.js");


this is just out of precaution in case some of our deployments end up looking for dist/index.js... can be removed though

I personally think its fine to have it.

himanshusinghs

Looks perfect. Tested it locally with vscode and works as expected 🚀

Totally unrelated but you might wanna cherry-pick the changes in this commit because currently we are shipping some unnecessary files in our final dist.

himanshusinghs · 2025-07-16T11:37:17Z

.github/workflows/check.yml

@@ -55,4 +55,4 @@ jobs:
          rm -rf node_modules
          npm pkg set scripts.prepare="exit 0"
          npm install --omit=dev
-      - run: npx -y @modelcontextprotocol/inspector --cli --method tools/list -- node dist/index.js --connectionString "mongodb://localhost"


I think this is solved, now that you have dist/index.js pointing to esm.

.github/workflows/prepare_release.yaml

package.json

himanshusinghs · 2025-07-16T11:45:15Z

scripts/createUniversalPackage.ts

+
+// Create a dist/index.js file that imports the ESM index.js file
+// To minimize breaking changes from pre-universal package time.
+const indexPath = resolve(distDir, "index.js");


I personally think its fine to have it.

…gagik/cjs-target

Copilot

Pull Request Overview

This pull request implements universal ESM and CommonJS package support for the MongoDB MCP server, enabling compatibility with both module systems while maintaining backwards compatibility.

Creates separate ESM and CommonJS build configurations with dual TypeScript compilation
Adds a new library entry point with explicit exports for better module resolution
Updates all references from the old build output path to the new ESM path for consistency

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tsconfig.esm.json	New ESM-specific TypeScript configuration targeting esnext modules
tsconfig.cjs.json	New CommonJS-specific TypeScript configuration targeting commonjs modules
tsconfig.build.json	Updated base build config to enable declaration files and maps
tests/integration/build.test.ts	Integration tests to verify both module formats work correctly
src/lib.ts	New library entry point exporting all public APIs
src/common/packageInfo.ts	Generated file with hardcoded version to avoid JSON import issues
scripts/updatePackageVersion.ts	Script to generate packageInfo.ts with current package version
scripts/createUniversalPackage.ts	Script to create package.json files for each module format
package.json	Updated with dual exports configuration and new build scripts
CONTRIBUTING.md	Updated documentation paths to reference ESM build
.smithery/smithery.yaml	Updated command path to ESM build
.smithery/Dockerfile	Updated Docker command to use ESM build
.github/workflows/prepare_release.yaml	Added version update step to release workflow
.github/workflows/check.yml	Updated CI command path to ESM build

.github/workflows/prepare_release.yaml

.github/workflows/check.yml

src/common/packageInfo.ts

gagik · 2025-08-07T12:40:07Z

src/resources/resource.ts

-                });
-            }
-        }
+        this.setupEventListeners();


this is technically a side effect in a constructor which we generally avoid but won't tackle this here.

gagik added 16 commits July 14, 2025 19:47

chore(tests): switch to vitest

6eed483

fix: remove traces of jest

463b6cc

fix: add and fix vitest linting

3b03327

fix: coverage

2d63956

fix: use --exclude

6e24d64

fix: increase hook timeout

3f10cbd

fix: from feedback

52ccf24

feat: use custom toIncludeSameMembers matcher

cbebf3e

Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into …

8fc12bc

…gagik/vitest

fix: remove unneeded globals

3bf00e6

WIP:

c138c1e

wip

2e76d9a

fix: add test, keep backwards compatibility

49dccbe

Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into …

a262914

…gagik/cjs-target

fix: update package-lock

5a12fec

fix: less scripts

ad51a41

gagik commented Jul 15, 2025

View reviewed changes

fix: clearer typescript

7064ad0

gagik changed the title ~~WIP ESM-CJS targetting~~ chore(build): build a universal ESM and CommonJS package Jul 15, 2025

fix: add dist/cjs

70cd5c9

gagik commented Jul 15, 2025

View reviewed changes

tsconfig.esm.json Outdated Show resolved Hide resolved

gagik added 7 commits July 15, 2025 14:53

fix: conver to proper file URLs

00a1b19

fix: use arelative

515b7c5

fix: use project root

6f5540e

fix: use esm/lib.js

c61e643

fix: resolve directly

9e4d91b

fix: use a script to ensure windows support

bf35972

fix: use esm as default

c70853e

gagik commented Jul 15, 2025

View reviewed changes

gagik marked this pull request as ready for review July 15, 2025 15:41

gagik requested a review from a team as a code owner July 15, 2025 15:41

gagik commented Jul 15, 2025

View reviewed changes

gagik added 2 commits July 16, 2025 09:22

fix: remove redundant bits

384a3be

fix: add backwards compatibility

6a70bbe

gagik commented Jul 16, 2025

View reviewed changes

himanshusinghs approved these changes Jul 16, 2025

View reviewed changes

gagik and others added 3 commits July 16, 2025 15:18

fix: add types

820292c

chore: package only dist and other req files

cce6ddb

Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into …

9555dcd

…gagik/cjs-target

Copilot AI review requested due to automatic review settings August 7, 2025 10:18

Copilot AI reviewed Aug 7, 2025

View reviewed changes

.github/workflows/prepare_release.yaml Outdated Show resolved Hide resolved

.github/workflows/check.yml Outdated Show resolved Hide resolved

src/common/packageInfo.ts Outdated Show resolved Hide resolved

gagik force-pushed the gagik/cjs-target branch 2 times, most recently from dfcc23c to f8bc161 Compare August 7, 2025 10:21

fix: update to match

4ea91c3

gagik force-pushed the gagik/cjs-target branch 2 times, most recently from ed8766c to 1ce9aa0 Compare August 7, 2025 10:37

fix: use conventional inheritance pattern

f7942de

gagik force-pushed the gagik/cjs-target branch from a693929 to f7942de Compare August 7, 2025 10:39

gagik added 4 commits August 7, 2025 12:41

fix: remove unnecessary cast

cd0c393

fix: make reducapply public

be5c06b

fix: remove event listeners bit

f7e5167

fix: bring back event listeners

0e28212

gagik commented Aug 7, 2025

View reviewed changes

gagik merged commit 91b1079 into main Aug 7, 2025
18 checks passed

gagik deleted the gagik/cjs-target branch August 7, 2025 13:42

himanshusinghs mentioned this pull request Aug 7, 2025

chore: provides dedicated cli and library entrypoints - MCP-6 #325

Closed

1 task

		@@ -0,0 +1,4 @@
		export { Server, type ServerOptions } from "./server.js";
		export { Telemetry } from "./telemetry/telemetry.js";

chore(build): build a universal ESM and CommonJS package #371

chore(build): build a universal ESM and CommonJS package #371

Uh oh!

Conversation

gagik commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Possible Alternatives

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 16804714278

Details

💛 - Coveralls

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

himanshusinghs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gagik commented Jul 15, 2025 •

edited

Loading

coveralls commented Jul 15, 2025 •

edited

Loading