fix: add guards against possible memory overflow in find and aggregate tools MCP-21

[himanshusinghs]

Proposed changes

This PR targets find and aggregate tool and does the following to hopefully guard against the memory overflow possibility:

1. Adds a configurable limit to restrict the maximum number of documents fetched per query / aggregation. This defaults to 100 and can be configured through CLI args / env variables. This limit will be applied in addition to find tool's provided limit (default to 10) and the smaller one will be considered always.
2. Replaces the use of Cursor.toArray with a dedicated cursor iterator that keeps track of bytes consumed in memory by the retrieved documents and cuts off the cursor iteration when there is a possibility of overflow. The overflow is based on configured maxBytesPerQuery parameter which defaults to 16MB. The tools that use the cursor iterator such as find and aggregate also expose responseBytesLimit as one of the parameter that defaults to 1MB to allow LLMs to invoke the tool with a bigger limit if needed, capped by the configured maxBytesPerQuery.

Some key decisions that were taken on a call and not documented anywhere:

• We will use hard limit cap to limit the number of documents retrieved by the query and the aggregation.
• We will avoid using .toArray and replace that with a cursor restricted to a configured limit.
• We will introduce a concept of configurable max bytes per query and by default will keep it relatively lower (1MB) and will restrict the cursor iteration to be within this limit.

Note for reviewers

Please review with whitespaces turned off.

Checklist

• I have signed the MongoDB CLA

[coveralls]

Pull Request Test Coverage Report for Build 17863910702

Details

• 275 of 289 (95.16%) changed or added relevant lines in 7 files are covered.
• 2 unchanged lines in 1 file lost coverage.
• Overall coverage increased (+0.5%) to 82.391%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/helpers/collectCursorUntilMaxBytes.ts	61	63	96.83%
src/tools/mongodb/read/aggregate.ts	101	107	94.39%
src/tools/mongodb/read/find.ts	90	96	93.75%

Files with Coverage Reduction	New Missed Lines	%
src/tools/mongodb/read/find.ts	2	92.26%

Totals
Change from base Build 17860042369:	0.5%
Covered Lines:	5238
Relevant Lines:	6247

---

💛 - Coveralls

[Copilot]

Pull Request Overview

This PR adds memory overflow protection to MongoDB find and aggregate tools by implementing configurable limits on document retrieval and memory usage.

Key changes:

• Introduces maxDocumentsPerQuery (default: 50) and maxBytesPerQuery (default: 1MB) configuration parameters
• Replaces toArray() with custom cursor iteration that monitors memory consumption
• Adds fallback mechanisms for count operations with timeout protection

Reviewed Changes

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

Show a summary per file

File	Description
src/common/config.ts	Adds new configuration parameters for document and byte limits
src/helpers/constants.ts	Defines timeout constants for count operations
src/helpers/operationWithFallback.ts	Utility for operations with fallback values
src/helpers/iterateCursor.ts	Core cursor iteration logic with memory monitoring
src/tools/mongodb/read/find.ts	Updates find tool to use new memory-safe cursor iteration
src/tools/mongodb/read/aggregate.ts	Updates aggregate tool to use new memory-safe cursor iteration
tests/unit/helpers/*.test.ts	Unit tests for new helper functions
tests/integration/tools/mongodb/read/*.test.ts	Integration tests for memory limits and updated response messages
tests/integration/indexCheck.test.ts	Updates test expectations for new response format

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[nirinchev]

Going to let Kevin and Gagik review the actual code, but do the limits sound reasonable? If we're preventing OOM situations, 1 MB sounds incredibly conservative - can we instead base it off the available memory of the machine - e.g. using v8.getHeapStatistics?

[himanshusinghs]

The memory limit is to applied per tool response, so letting one tool call take almost entire available heap size seems too lenient, particularly given the case that we now support multiple clients connecting to the same server.

I still think 16MB default through configuration and 1 MB on tool interface, (configurable by LLM and capped to configured limit) seems pretty reasonable.

[kmruiz]

Yes, the memory limit is per tool call, and 1MB of results is a big chunk of results, and even more when some models are pretty aggressively using projections to reduce the context they use when reading the results. I think the question here would be: why would we need more memory?

1. In the HTTP Transport server will likely run multiple tools for multiple users at the same time and we don't want noisy neighbors to overload the system.
2. 1MB can hold a lot of data. To give you an example, in the sample_mflix.movies collection from our sample data, a single movie (with descriptions and summaries) bsonsize is 1.8KB. It means that we can fit around 550 movies in a single query result.
3. Most agents still have context windows of 128k to 256k tokens and 1MB of JSON is already a big hit on the agent context, which makes that much content pretty useless because of the loss of accuracy.

If users want more accurate results, they should instruct the agent to delegate some of the work to an aggregation pipeline as in any other application.

[github-actions]

📊 Accuracy Test Results

📈 Summary

Metric	Value
Commit SHA	32e61661029ff721d10ec52287c72f342ac0e220
Run ID	e2b5e3eb-e87a-4309-b34c-1a9b0469abdc
Status	done
Total Prompts Evaluated	61
Models Tested	1
Average Accuracy	88.9%
Responses with 0% Accuracy	6
Responses with 75% Accuracy	3
Responses with 100% Accuracy	52

📊 Baseline Comparison

Metric	Value
Baseline Commit	c10955af6e78cc03aa30f3817e248bf130e053d3
Baseline Run ID	1d631660-589e-428e-b8a9-3d13f6f35615
Baseline Run Status	done
Responses Improved	0
Responses Regressed	2

---

📎 Download Full HTML Report - Look for the accuracy-test-summary artifact for detailed results.

Report generated on: 9/19/2025, 4:06:32 PM

[Copilot]

Pull Request Overview

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