feat: implement debugger tool logic COMPASS-10826 by paula-stacho · Pull Request #8340 · mongodb-js/compass

paula-stacho · 2026-08-11T14:59:05Z

Description

Integrating the debugger tool with the atlas admin api calls.

Known gaps (to be added as follow ups):

telemetry
user's IP address fetching - hardcoded for now, waiting for COMPASS-10994

Note: ipaddr.js was chosen because mms uses the same one AND it was already included in Compass as a subdependency

Screenshots

Checklist

New tests and/or benchmarks are included
Documentation is changed or added
If this change updates the UI, screenshots/videos are added and a design review is requested
If this change could impact the load on the MongoDB cluster, please describe the expected and worst case impact
I have signed the MongoDB Contributor License Agreement (https://www.mongodb.com/legal/contributor-agreement)

Motivation and Context

Bugfix
New feature
Dependency update
Misc

Open Questions

Dependents

Types of changes

Backport Needed
Patch (non-breaking change which fixes an issue)
Minor (non-breaking change which adds functionality)
Major (fix or feature that would cause existing functionality to change)

Copilot

Pull request overview

This PR adds initial wiring for an “Atlas connection error debugger” tool in Compass Generative AI, introducing Atlas Admin API calls to derive cluster state diagnostics and plumbing atlasService through the controller/provider layers.

Changes:

Implements initial debugConnection() logic backed by AtlasAdminApiService (cluster state + project access list retrieval).
Wires atlasService into ToolsController and the React provider so the debugger tool can use Atlas service capabilities.
Updates the assistant eval harness to construct ToolsController with the new dependency shape.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
packages/compass-generative-ai/src/tools/debug-connection.ts	Adds the connection-debugging tool logic and result mapping.
packages/compass-generative-ai/src/tools-controller.ts	Wires `atlasService` into the tool execution path and tool config.
packages/compass-generative-ai/src/provider.tsx	Passes `atlasService` to `ToolsController` via provider memoization.
packages/compass-assistant/test/tool-calls.eval.ts	Updates eval harness construction of `ToolsController`.

Suppressed comments (3)

packages/compass-generative-ai/src/tools/debug-connection.ts:47

isUserIPIncluded() trims userIp into userIP, but then compares ipAddress against the untrimmed userIp. This will incorrectly return false when userIp has leading/trailing whitespace.

  const userIP = userIp.trim();
  return ipAccessList.some(
    ({ ipAddress }) => ipAddress && ipAddress === userIp
  );

packages/compass-generative-ai/src/tools/debug-connection.ts:72

ipAccessList is fetched and then only used for console.log(). This creates unnecessary network load and leaves debug logging in production code.

  const ipAccessList = await atlasAdminApi.getProjectIPAccessList(projectId);
  console.log({ clusterDetails, ipAccessList });
  // TODO: we can't authenticate for this endpoint yet

packages/compass-generative-ai/src/tools/debug-connection.ts:85

ipAccessAllowed is currently hard-coded to true, and the return path wraps a plain object in await Promise.resolve(...). This makes the tool report misleading diagnostics and adds unnecessary async noise; until the user IP check is implemented, it should return 'unknown' and return the object directly.

    }),
    ipAccessAllowed: true,
    // ipAccessAllowed: isUserIPIncluded(ipAccessList, userIp),
  });

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

dudaschar · 2026-08-18T16:21:04Z

-  clusterState: 'ready' | 'paused' | 'provisioning' | 'deleted' | 'notFound';
-  ipAccessAllowed: boolean;
+  clusterName: string;
+  clusterState: string;


Would we not be able to calculate the state from the previous states?

I was confused what you mean by previous states, but I think you mean to specify the type, not derive the value, right?

If that's the case - I've thought about this but in the end I chose to not type it strictly as we don't care about most states, and the assistant might be able to interpret even new states that we didn't account for originally. Let me know if you disagree, I'm not feeling too strongly about this

dudaschar · 2026-08-18T16:29:34Z

+          Use to debug a Compass connection failure to an Atlas cluster. 
+          Returns Atlas-side diagnostics (cluster state, IP access list) as well as targeted advice. 
+          Provide the advice to the user


You can make the description more specific if you want to force the agent to provide the url. For example:

This tool provides a debugger helper to identify issues and provide assistance when connecting Compass to an Atlas cluster. You will have access to Atlas-side diagnostics (cluster state, IP access list) and targeted advice as result when running this tool. When advice is provided: 1. Check if that's any url as part of the advice content which the user should follow. 2. Provide the url as part of your response, and a 1-line explanation about what they should to when visiting the url.

If we have structured output, usually is not necessary to add details about the response, but I don't think would hurt in this case.

Good idea, I'll add it. Actually I was surprised that the advice wasn't mentioned until I called it out explicitly, - the assistant only mentioned the fields that were in the tool description. Apparently this model needs more hand-holding.

esvm · 2026-08-18T19:12:29Z

+  projectId: string;
+  clusterName: string;
+}): string {
+  if (clusterState === 'notFound') {


this is never reached right? the not found is returned in the debugConnection directly with if ('clusterNotFound' in clusterInfo)

ah right, I forgot to clean this up after refactor, thanks for noticing!

esvm · 2026-08-18T19:16:41Z

+      advice.push(`You can resume it in the Atlas UI: ${clusterOverviewUrl}.`);
+    }
+  }
+  if (clusterState === 'CREATING') {


I believe if the cluster is DELETING it also can't accept connections (but not too sure)

esvm · 2026-08-18T19:22:38Z

+      preferences,
+      atlasAdminApi,
+      authService,
+      atlasService,


you'll need to add atlasService in the ToolsController constructor. I believe you can replace the authService in there as it's not being used

esvm · 2026-08-18T19:25:33Z

+  it('returns unknown values when the cluster does not exist or the user has no access to it', async function () {
+    const api = mockAtlasAdminApi({ projectIdAndClusterName: undefined });
+
+    const result = await debugConnection(CONNECTION_STRING, api, atlasService);


I believe you forgot to update the tests: debugConnection after your changes only has 3 params, you can remove atlasService:

Suggested change

const result = await debugConnection(CONNECTION_STRING, api, atlasService);

const result = await debugConnection(CONNECTION_STRING, api);

in all the tests below as well

esvm · 2026-08-18T19:27:52Z

+  }
+}
+
+function isAddressEqual(ipAddress: string, address: string): boolean {


nit: the names are slightly confusing here

Suggested change

function isAddressEqual(ipAddress: string, address: string): boolean {

function isAddressEqual(allowedIp: string, userIp: string): boolean {

or if you prefer more generic

Suggested change

function isAddressEqual(ipAddress: string, address: string): boolean {

function isAddressEqual(expected: string, actual: string): boolean {

thanks, I knew they were confusing but I was too tired to come up with something better 😅

esvm · 2026-08-18T19:28:31Z

+  });
+}
+
+function isAddressInCidrRange(cidrNotation: string, address: string): boolean {


nit: I'd change these params as well:

Suggested change

function isAddressInCidrRange(cidrNotation: string, address: string): boolean {

function isAddressInCidrRange(allowedCidr: string, userIp: string): boolean {

esvm · 2026-08-18T19:29:38Z

+    };
+  }
+  const { projectId, clusterName, clusterState } = clusterInfo;
+  console.log({ projectId, clusterName, clusterState });


Suggested change

console.log({ projectId, clusterName, clusterState });

esvm · 2026-08-18T19:29:47Z

+    projectId,
+    atlasAdminApi,
  });
+  console.log({ ipAccessAllowed, networkAccessDetails });


Suggested change

console.log({ ipAccessAllowed, networkAccessDetails });

Copilot AI lite review requested due to automatic review settings August 11, 2026 14:59

github-actions Bot added the feat label Aug 11, 2026

Copilot started reviewing on behalf of paula-stacho August 11, 2026 14:59 View session

Copilot AI reviewed Aug 11, 2026

View reviewed changes

paula-stacho added the feature flagged PRs labeled with this label will not be included in the release notes of the next release label Aug 11, 2026

paula-stacho added 3 commits August 17, 2026 11:41

feat: implement debugger tool logic COMPASS-10826

679f7f4

update tests

9dc07c4

add advice with links

199c060

paula-stacho force-pushed the COMPASS-10826 branch from 68bbcc7 to 199c060 Compare August 17, 2026 09:42

paula-stacho added 3 commits August 17, 2026 22:08

update debug logic

9976466

update

9e407a5

ip matching

1c3cd3e

paula-stacho force-pushed the COMPASS-10826 branch from 2b8a0b5 to 1c3cd3e Compare August 18, 2026 15:38

cleanup

70f2540

paula-stacho marked this pull request as ready for review August 18, 2026 15:46

paula-stacho requested a review from a team as a code owner August 18, 2026 15:46

paula-stacho requested review from Anemy, dudaschar, esvm and misbamongo August 18, 2026 15:46

dudaschar reviewed Aug 18, 2026

View reviewed changes

Comment thread packages/compass-generative-ai/src/tools/debug-connection.ts

dudaschar reviewed Aug 18, 2026

View reviewed changes

Comment thread packages/compass-generative-ai/src/tools/debug-connection.ts

dudaschar reviewed Aug 18, 2026

View reviewed changes

esvm reviewed Aug 18, 2026

View reviewed changes

	const result = await debugConnection(CONNECTION_STRING, api, atlasService);
	const result = await debugConnection(CONNECTION_STRING, api);

	function isAddressEqual(ipAddress: string, address: string): boolean {
	function isAddressEqual(allowedIp: string, userIp: string): boolean {

	function isAddressEqual(ipAddress: string, address: string): boolean {
	function isAddressEqual(expected: string, actual: string): boolean {

	function isAddressInCidrRange(cidrNotation: string, address: string): boolean {
	function isAddressInCidrRange(allowedCidr: string, userIp: string): boolean {

Uh oh!

Conversation

paula-stacho commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Screenshots

Checklist

Motivation and Context

Open Questions

Dependents

Types of changes

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!

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!

Uh oh!

Uh oh!

dudaschar Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paula-stacho Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

paula-stacho commented Aug 11, 2026 •

edited

Loading

dudaschar Aug 18, 2026 •

edited

Loading

paula-stacho Aug 19, 2026 •

edited

Loading