Skip to content

chore(compass-assistant): migrate Database Tools to mongodb-mcp-server v3 COMPASS-11280 - #8580

Merged
gagik merged 30 commits into
mainfrom
gagik/mcp-server-v3
Nov 9, 2026
Merged

gagik merged 30 commits into
mainfrom
gagik/mcp-server-v3

Conversation

@gagik

@gagik gagik commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

mongodb-mcp-server v3 is binary-only — library embedding moved to the scoped @mongodb-js/mcp-* packages. Compass used the v1 library API directly (in-memory runner, session-scoped config, session-scoped connection manager), none of which exists in v3.

  • Replace the in-memory TransportRunnerBase runner with a hand-built MongoDBToolServer composition (@mongodb-js/mcp-core + @mongodb-js/mcp-types + @mongodb-js/mcp-tools-mongodb), inside the assistant tools utility (ToolsHost, feat(utility): create an utility for the ai assistant COMPASS-11269 #8636) where the server now lives.
  • Expose Compass's active connection through a ConnectionRegistry, and inject the tool's connection handle at invocation time instead of exposing it to the model.
  • Move the Atlas telemetry pipeline into the utility: hosting_mode: 'compass' is preserved and the usage-statistics preference is read live, so toggling it needs no restart.
  • Remove the webpack aliases that only existed for the v1 package, plus the @mongodb-js/atlas-local alias in the desktop config.

Note: the ai-assistant utility entry (packages/compass-utilities/src/ai-assistant/index.mts) now only calls into ./main.mts and exports nothing. Nothing consumes its exports (utility entries are loaded for side effects), and with webpack >= 5.107 an unused export on an ESM worker chunk entry crashes the compass-web build in ModuleLibraryPlugin (TypeError: p.charCodeAt is not a function). This deserves a proper fix in webpack-config-compass (or upstream) rather than moving the implementation out of the entry.

mongodb-mcp-server v3 is binary-only; library embedding moved to the scoped
@mongodb-js/mcp-* packages. Compass used the v1 library API directly (in-memory
runner, session-scoped config, session-scoped connection manager), none of which
exists in v3.

Build the in-memory server composition by hand instead of via TransportRunnerBase,
expose Compass's active connection through a ConnectionRegistry, and inject the
tool connection handle at invocation time rather than exposing it to the model.

MCP telemetry is now a no-op and the webpack aliases that only existed for the v1
package are gone.
Copilot AI balanced review requested due to automatic review settings October 14, 2026 14:23

Copilot AI 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.

🟡 Changes recommended

The startup-failure test no longer exercises the error path and should be corrected before approval.

1 open finding
What changed in this PR

Migrates Compass Database Tools to the scoped MCP v3 APIs. The composition is well-contained, but startup error handling lacks effective test coverage.

Changes:

  • Replaces the v1 runner with an in-memory MCP v3 composition.
  • Adds a Compass connection registry and injects connection handles.
  • Updates dependencies, webpack aliases, telemetry wiring, and tests.
File Description
packages/​compass/​webpack.config.js Removes obsolete alias.
packages/​compass-web/​webpack.config.js Updates MCP bundling aliases.
packages/​compass-web/​polyfills/​diagnostics_channel/​index.ts Removes unused polyfill.
packages/​compass-web/​package.json Removes legacy dependency.
packages/​compass-generative-ai/​src/​tools-logger.ts Adopts MCP v3 logging.
packages/​compass-generative-ai/​src/​tools-controller.ts Implements MCP v3 server composition.
packages/​compass-generative-ai/​src/​tools-controller.spec.ts Updates controller tests.
packages/​compass-generative-ai/​src/​tools-connection-manager.ts Adds the connection registry adapter.
packages/​compass-generative-ai/​src/​tools-connection-manager.spec.ts Updates connection tests.
packages/​compass-generative-ai/​src/​tools-connection-error-handler.ts Updates MCP types.
packages/​compass-generative-ai/​src/​provider.tsx Removes telemetry configuration.
packages/​compass-generative-ai/​package.json Adds scoped MCP packages.
packages/​compass-assistant/​test/​tool-calls.eval.ts Updates evaluation setup.
packages/​compass-assistant/​src/​compass-assistant-provider.tsx Removes MCP telemetry context.
packages/​compass-assistant/​src/​compass-assistant-provider.spec.tsx Updates provider expectations.
package-lock.json Refreshes dependency resolution.

🧠 Review effort: Balanced


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@gagik gagik changed the title chore(deps): migrate Database Tools to mongodb-mcp-server v3 chore(compass-assistant): migrate Database Tools to mongodb-mcp-server v3 Oct 14, 2026
@gagik
gagik requested a balanced review from Copilot October 14, 2026 14:47

Copilot AI 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.

🔵 Needs a closer look

The startup-error test no longer triggers the error path and currently passes as a false positive.

1 open finding

🧠 Review effort: Balanced

gagik added 2 commits October 15, 2026 13:45
The startup-error test only made getTelemetryAnonymousId throw, which
startServer() no longer calls, so the catch block was never entered.
@gagik
gagik marked this pull request as ready for review October 15, 2026 12:19
@gagik
gagik requested a review from a team as a code owner October 15, 2026 12:19
@gagik
gagik requested a review from esvm October 15, 2026 12:19
@gagik gagik changed the title chore(compass-assistant): migrate Database Tools to mongodb-mcp-server v3 chore(compass-assistant): migrate Database Tools to mongodb-mcp-server v3 COMPASS-11280 Oct 15, 2026
@kmruiz

kmruiz commented Oct 15, 2026

Copy link
Copy Markdown
Collaborator

It seems that we are removing the telemetry everywhere, is that on purpose?

@esvm esvm left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

just a few questions but overall LGTM

readOnly: true,
// NOTE: the preferences could change at runtime. As a best-effort way of
// keeping them in sync we'll change them every time we set the tools' context
telemetry: enableMCPTelemetry ? 'enabled' : 'disabled',

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

do we have telemetry on this new format?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I was dropping it originally but should be back now

Comment thread package-lock.json Resolved
gagik added 4 commits October 15, 2026 23:49
The v3 migration replaced the MCP telemetry pipeline with a no-op and dropped
enableMCPTelemetry, so the events the v1 integration reported stopped being
sent. v1 was inconsistent about it (it only scheduled its send timer when the
server happened to start with the preference already on, otherwise it just
flushed a batch of cached events on shutdown), but it did report.

Wire AtlasTelemetry back up behind an unauthenticated Atlas API client, keep
the hosting_mode: 'compass' property, and read trackUsageStatistics live so
toggling the preference takes effect without restarting the server.
The pipeline was constructed enabled so that turning the preference on
mid-session would start collection, which also meant the machine id lookup,
container probe and 30s send timer ran even when Compass telemetry was off.

Start the pipeline lazily instead: nothing is set up until the first event the
preference actually allows through, and the machine id is resolved on first use
rather than at construction.
…ules

Move CompassMcpTelemetry and its factory into compass-mcp-telemetry.ts and
LazyDeviceId into lazy-device-id.ts, and trim the comments added alongside them.
…down

The telemetry module now builds the Atlas API client it sends through, so
closing the pipeline releases everything it uses and ToolsController no longer
has to know about the client at all.

Also abort the machine id lookup before the flush rather than after: the base
close() waits for setup, which waits on that lookup, so aborting afterwards
never shortened shutdown.
Comment on lines +44 to +47
// Held separately from the base class' private fields so `close` can release
// them; the pipeline itself only ever flushes.
private readonly apiClientRef: ApiClient;
private readonly deviceIdRef: IDeviceId;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

agh this is so annoying I might do an upstream release just avoid this 😅

@gagik

gagik commented Oct 15, 2026

Copy link
Copy Markdown
Contributor Author

I was under an impression we were never sending telemetry to Compass, TIL... will need to adjust some more

@gagik
gagik marked this pull request as draft October 15, 2026 22:48
gagik added 7 commits October 16, 2026 09:50
'syncs telemetry setting with runner userConfig' asserted on the v1 runner's
config, which the migration removed, so it came back as 'syncs telemetry
setting with the tools config' asserting the pipeline's own gate.

Also cover the other ways telemetry ends up off: DO_NOT_TRACK, and the
trackUsageStatistics preference reaching the tools context from the provider.
Compass never reads DO_NOT_TRACK, so the test only pinned inherited upstream
behaviour rather than anything Compass controls.
…e API client

The existing telemetry tests only asserted the enable/disable gate, so a broken
pipeline or a dropped hosting_mode property would still have passed. Run a real
tool call and assert the event handed to the Atlas API client carries the tool
name and Compass properties, plus the counterpart that nothing is sent while
telemetry is off.
gagik added 3 commits October 27, 2026 11:29
# Conflicts:
#	package-lock.json
#	packages/compass-generative-ai/package.json
#	packages/compass-web/package.json
# Conflicts:
#	packages/compass-generative-ai/src/tools-controller.spec.ts
#	packages/compass-generative-ai/src/tools-controller.ts
#	packages/compass-generative-ai/src/tools-logger.ts
# Conflicts:
#	package-lock.json
#	packages/compass/webpack.config.js
@gagik
gagik marked this pull request as ready for review October 29, 2026 09:40
gagik added 2 commits November 6, 2026 13:27
# Conflicts:
#	package-lock.json
#	packages/compass-generative-ai/package.json
#	packages/compass-generative-ai/src/tools-controller.spec.ts
#	packages/compass-generative-ai/src/tools-controller.ts
# Conflicts:
#	package-lock.json
#	packages/compass-generative-ai/package.json
gagik added 6 commits November 6, 2026 13:59
…xports

The entry module has to stay export-free: compass-web bundles it as an ESM
worker chunk and webpack's ModuleLibraryPlugin crashes on an unused export of
a chunk entry module. `main` still has to be importable for the utility spec,
so the implementation now lives in `main.mts` and the entry only calls it.
Drops the mongodb-mcp-server#1620 workarounds now that the upstream
fields are protected, the connection error handler type matches, and
NoopExportsManager is exported.

The upgrade also removes the per-operation `maxTimeMS`, so the Compass
preference is applied as the connection's driver `timeoutMS`, and the
count caps are renamed to `queryCountTimeoutMs`/`aggregationCountTimeoutMs`.
…emetry

The telemetry API client hardcoded the production Atlas URL, so internal
dev/qa/staging presets reported to the wrong backend. The renderer already
resolves the preset via `getAtlasConfigForPreset`; thread that
`atlasUiBaseUrl` through `setUserConfig` and use it as the telemetry base
URL, falling back to production.
…metadata

`serverMetadata.version` was a hardcoded `0.0.0`, so telemetry's
`mcp_server_version` and the Atlas API client User-Agent never carried the
running Compass version. Use `HADRON_APP_VERSION`, which the desktop
utility build inlines, with `0.0.0` as the compass-web fallback.
Drop restated and padded comments, keeping the non-obvious constraints
(lazy telemetry setup, close() ordering, the maxTimeMS -> timeoutMS
migration, and the HADRON_APP_VERSION fallback) to one or two lines.
The explain plan cancel test read the chat text as soon as the messages
container was displayed, but the confirmation is appended only after
`ToolsController.startServer()` resolves, so the assertion raced with it.
The sibling "confirm" test only passes because clicking Confirm implicitly
waits for the button. Wait for the confirmation (and for the cancelled
state) instead, keeping the pause that guards the "no request sent" check.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

any specific reasons for this refactor? This was following the same pattern as the embedded-shell 🤔

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

exporting inside the entry module leads to a crash. compass-web bundles it as an ESM worker chunk and webpack's ModuleLibraryPlugin crashes on an unused export of a chunk entry module. main still has to be importable for the utility spec, so the implementation now lives in main.mts and the entry only calls it.

@gagik gagik Nov 9, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I guess we could also avoid the export, not sure why this only came forward with this

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

hmm that's odd. This code is currently live in dev. We had issues with the export that's correct, but that was addressed in #8663 so this is not needed

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

ahh cool then this was applied before that PR merge, I'll revert and see

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

hm right it's related to the hoisted webpack version indeed, I must say that the newer versions also seem to throw this error (which is what happened here) so we'll probably do this change eventually anyway.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

to keep changes minimal I'll keep structure and resolved webpack the same though, should work now

@esvm esvm left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

overall LGTM, just a few nits and there are some merging conflicts

gagik added 5 commits November 9, 2026 12:45
# Conflicts:
#	package-lock.json
#	packages/compass-generative-ai/package.json
#	packages/compass-utilities/src/ai-assistant/index.mts
`webpack-compass` resolves webpack relative to this package (it sets
`WEBPACK_PACKAGE` from `require.resolve('webpack/package.json')`), so the
version installed here is the one the Compass builds run. With the caret
range, a lockfile regeneration dedupes it to the hoisted 5.112.2, which
crashes building compass-web:

  ERROR in [entry] ai-assistant.<hash>.mjs
  TypeError: p.charCodeAt is not a function
    at propertyAccess (webpack/lib/util/property.js:88)
    at ModuleLibraryPlugin.renderStartup (webpack/lib/library/ModuleLibraryPlugin.js:1062)

The ai-assistant worker chunk is an ESM library chunk whose entry has unused
exports; 5.112.2 passes the undefined `getUsedName()` result straight into
`propertyAccess`, while 5.107.0 (the version #8663 bumped this package to)
does not take that path.
The export-free entry (`index.mts` + `main.mts`) was a workaround for the
webpack 5.112.2 crash. With webpack pinned back to 5.107.0 the entry can
export `name`/`main` again and the spec can import from it directly.
The exact pin is not needed: the lock carries the nested
`configs/webpack-config-compass/node_modules/webpack@5.107.0` (the copy
`webpack-compass` resolves via `WEBPACK_PACKAGE`), and npm keeps an existing
lock entry as long as it satisfies the range. Back to `^5.107.0`, consistent
with the rest of the repo, with the lock doing the pinning.

Note: this relies on the lock entry, so a from-scratch lock resolution would
dedupe it to the hoisted 5.112.2 (which crashes the compass-web build) — the
same latent state main is in.
@gagik

gagik commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

@esvm all green now! 🟢 should hopefully cover everything

@esvm esvm left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

LGTM

@esvm
esvm requested a review from nbbeeken November 9, 2026 14:44
@gagik
gagik merged commit 57f5aec into main Nov 9, 2026
57 checks passed
@gagik
gagik deleted the gagik/mcp-server-v3 branch November 9, 2026 15:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants