feat: Adds the atlas-list-performance-advisor base tool #528

kylelai1 · 2025-09-08T12:26:53Z

Proposed changes

This PR adds the atlas-list-performance-advisor tool to the MCP server, which retrieves the following performance advisor recommendations from the admin API: index suggestions, drop index suggestions, schema suggestions, slow query logs.

This PR merges the changes into the atlas-list-performance-advisor-tool branch.

Testing

Manually tested that the MCP server is able to retrieve performance advisor suggestions.

Checklist

I have signed the MongoDB CLA

nirinchev

Did a quick pass - overall, looks reasonable, but I'm worried that it might not be too LLM-friendly. I suggest testing it thoroughly with different agents/models and confirming it's outputting meaningful insights.

nirinchev · 2025-09-10T19:06:23Z

src/tools/atlas/read/listPerformanceAdvisor.ts

+            .array(z.nativeEnum(PerformanceAdvisorOperation))
+            .describe("Operations to list performance advisor recommendations"),
+        since: z.number().describe("Date to list slow query logs since").optional(),
+        processId: z.string().describe("Process ID to list slow query logs").optional(),


Is this something we expect the LLM to know how to get? As far as I can tell, you get it by calling atlas processes list but we don't have any tools that mirror that behavior in the MCP server.

Since it's an optional, the LLM does not need to pass this in. It's also noted that it's only for slow query logs. If the processId is not passed in, we use inspect cluster to get the hostname + port that can be used for the process ID, which is handled by the performance advisor util functions that the atlas-list-performance-advisor tool calls.

I also think that when we do more manual testing in the "QA" phase of adding the performance advisor tool, we can more thoroughly test prompts and see how the LLM will prompt the user for more data.

If we know the model has no way of figuring out this processId, what's the point of exposing it as an argument?

Hm, I might be approaching this incorrectly. This is something that if the user is able to provide, then it'll be passed in. Otherwise, we retrieve the process ID thru the tool. If this is something that the LLM is unable to figure out and we rely on the user to provide the processId, would this be convention to leave out the processId argument?

nirinchev · 2025-09-10T19:08:18Z

src/tools/atlas/read/listPerformanceAdvisor.ts

+        operations: z
+            .array(z.nativeEnum(PerformanceAdvisorOperation))
+            .describe("Operations to list performance advisor recommendations"),
+        since: z.number().describe("Date to list slow query logs since").optional(),


Should this be z.date instead? Does the LLM do a good job at converting dates to unix epoch?

Good point. Yes, the LLM does a good job of converting dates to unix epoch. I've manually tested just telling the LLM to get metrics for the past X hours for example, and it handled that well.

I can change this to z.date

nirinchev · 2025-09-10T19:10:30Z

src/tools/atlas/read/listPerformanceAdvisor.ts

+
+        // If operations is empty, get all performance advisor recommendations
+        // Otherwise, get only the specified operations
+        const operationsToExecute = operations.length === 0 ? Object.values(PerformanceAdvisorOperation) : operations;


Should we mark operations as optional and provide a default instead? Right now there's nothing to hint to the LLM it could provide an empty array here.

This is intended behavior here, so providing an empty array is ok. The LLM will ask the user which operations if we don't specify any, and it was discussed with product to just list all the PA suggestions if none were given here.

Not sure I understand - right now this is a required argument, which tells the LLM to try and figure out a value for it - either by asking the user or hallucinating something. Instead, if we specify it as an optional argument with a default value, we still achieve the goals we set for ourselves in the PD, but we're also more clearly communicating the behavior of the server.

I see what you mean. There's nothing to suggest to the LLM that an empty array is ok to pass in here.
We can provide a default which is all operations in an array, and the LLM will be able to figure out that the default will then be all operations.

nirinchev · 2025-09-10T19:12:03Z

src/tools/atlas/read/listPerformanceAdvisor.ts

+
+        try {
+            if (operationsToExecute.includes(PerformanceAdvisorOperation.SUGGESTED_INDEXES)) {
+                const { suggestedIndexes } = await getSuggestedIndexes(this.session.apiClient, projectId, clusterName);


This is probably not super critical, but right now, all of these async operations are evaluated sequentially, which means that we need to wait for one to finish before starting the next one. Instead, it would be a good idea to run them in parallel.

Will change this one!

nirinchev · 2025-09-10T19:13:38Z

src/tools/atlas/read/listPerformanceAdvisor.ts

+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };


We should wrap the response in formatUntrustedData to avoid injection attacks where someone creates a slow query that contains llm instructions. Also, it might be helpful to give hints to the llm what the different fields in the json data represent and how those can be used.

Yes, I'll go ahead and make this change. I'll see how other tools use this.

nirinchev · 2025-09-10T19:16:42Z

src/common/atlas/performanceAdvisorUtils.ts

+
+interface DropIndexSuggestion {
+    accessCount?: number;
+    index?: Array<{ [key: string]: 1 | -1 }>;


Is this type definition true? Would PA not suggest dropping geo or text indexes?

Let me look into this. I used the Open API definitions for the Atlas Admin API, but it would be weird to not include text indexes to drop suggestions for example (same for index creation suggestions!)

I read some of the code where we return the index suggestions in the performance advisor, and there's a check to skip complex index types, which include geospatial, text, and hashed indexes. I've confirmed this with Frank (intel PM) to make sure.

nirinchev · 2025-09-10T19:17:21Z

src/common/atlas/performanceAdvisorUtils.ts

+type SchemaTriggerType =
+    | "PERCENT_QUERIES_USE_LOOKUP"
+    | "NUMBER_OF_QUERIES_USE_LOOKUP"
+    | "DOCS_CONTAIN_UNBOUNDED_ARRAY"
+    | "NUMBER_OF_NAMESPACES"
+    | "DOC_SIZE_TOO_LARGE"
+    | "NUM_INDEXES"
+    | "QUERIES_CONTAIN_CASE_INSENSITIVE_REGEX";
+
+type SchemaRecommedationType =
+    | "REDUCE_LOOKUP_OPS"
+    | "AVOID_UNBOUNDED_ARRAY"
+    | "REDUCE_DOCUMENT_SIZE"
+    | "REMOVE_UNNECESSARY_INDEXES"
+    | "REDUCE_NUMBER_OF_NAMESPACES"
+    | "OPTIMIZE_CASE_INSENSITIVE_REGEX_QUERIES"
+    | "OPTIMIZE_TEXT_QUERIES";


Do we need to translate these to something the LLM would have an easier time interpreting?

Added maps where we can get readable descriptions so that the LLM understands this better.

kylelai1 added 6 commits September 4, 2025 11:18

Add base atlas performance advisor MCP server tool

bd69450

Cleanup comments

f331bac

Merge main

78f9888

Fix API return type

2f023eb

Clean up getting slow query logs from atlas admin api

a4cbc8b

Fix types for performance advisor api response

2ef0ded

kylelai1 marked this pull request as ready for review September 8, 2025 20:24

kylelai1 requested a review from a team as a code owner September 8, 2025 20:24

kylelai1 requested a review from blva September 8, 2025 20:24

kylelai1 changed the title ~~Adds the atlas-list-performance-advisor base tool~~ feat: Adds the atlas-list-performance-advisor base tool Sep 8, 2025

nirinchev reviewed Sep 10, 2025

View reviewed changes

kylelai1 added 3 commits September 12, 2025 21:39

Address comments

923263e

Move utils to util file

8272719

Cleanup naming

5871dc0

feat: Adds the atlas-list-performance-advisor base tool #528

Are you sure you want to change the base?

feat: Adds the atlas-list-performance-advisor base tool #528

Conversation

kylelai1 commented Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Testing

Checklist

Uh oh!

nirinchev left a comment

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!

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!

Uh oh!

kylelai1 commented Sep 8, 2025 •

edited

Loading