Implement the mongo_list_collections tool with unit tests #142

New issue

Closed

opened 2026-08-31 22:05:23 +00:00 by david · 1 comment

david commented

2026-08-31 22:05:23 +00:00

Owner

Summary

Implement the mongo_list_collections tool — list the collections in a database, optionally name-only — with unit tests against a fake client.

Background

Depends on: #139

Part of the read-only tool surface of the mongodb extension. Answers "what collections exist in this database". The read-only boundary is enforced by construction: the tool calls only db.listCollections() — no schema/write operations are reachable. db is required; nameOnly lets the caller request just names for a smaller payload. The extension connects lazily, so connection/auth failures surface here as categorized ToolErrors thrown from execute() (see src/errors.ts).

Documentation Required

A separate process downloads these into the listed folder before this issue is implemented. Check the folder for the actual reference material before starting.

docs/reference/mongodb-driver/ — for Db.listCollections:

https://mongodb.github.io/node-mongodb-native/7.6/classes/Db.html — API reference for Db.listCollections(filter?, options?) → ListCollectionsCursor; ListCollectionsOptions includes nameOnly (when true, returns { name, type }[] instead of full info documents { name, type, options, info }).
https://www.mongodb.com/docs/drivers/node/current/databases-collections/ — guide: working with databases and collections via the driver.
https://mongodb.github.io/node-mongodb-native/7.6/ — TypeDoc API reference index (cursor class).

Implementation Details

Create extensions/mongodb/src/tools/listCollections.ts. Tool registered as mongo_list_collections via pi.registerTool with a TypeBox parameter schema:

db (string, required) — database name
nameOnly? (boolean, default false)

Behavior:

const infos = await db.listCollections({}, { nameOnly }).toArray() — wrap in try/catch; on error toToolError(err, context) (throws).
When nameOnly: true, the driver returns { name, type }[] — return those (the names) directly; otherwise return the full info documents { name, type, options, info }[].
Return the EJSON array as content and details: { count } (number of collections).

Mirror the structure of src/tools/find.ts / src/tools/count.ts (sibling steps) and the sibling extensions/postgres/src/tools/ implementations. Tests use a fake client whose db(name) returns an object with listCollections(filter, options) returning a cursor with toArray().

Write co-located tests in src/tools/listCollections.test.ts:

Happy path: fake returns collection info docs → EJSON array content + details: { count } correct.
nameOnly: true → names only returned.
Each error category (connection, auth, invalid, server, unexpected) surfaces as the categorized message.

Acceptance Criteria

Happy path returns the collection info documents as EJSON and details: { count }.
nameOnly: true → only collection names returned.
All five error categories throw categorized ToolErrors with correct message prefixes.
bun test in extensions/mongodb/ is green for src/tools/listCollections.ts.

Test Plan

cd extensions/mongodb
bun test   # listCollections tool tests green

## Summary Implement the `mongo_list_collections` tool — list the collections in a database, optionally name-only — with unit tests against a fake client. ## Background **Depends on:** #139 Part of the read-only tool surface of the mongodb extension. Answers "what collections exist in this database". The read-only boundary is enforced by construction: the tool calls only `db.listCollections()` — no schema/write operations are reachable. `db` is required; `nameOnly` lets the caller request just names for a smaller payload. The extension connects lazily, so connection/auth failures surface here as categorized `ToolError`s thrown from `execute()` (see `src/errors.ts`). ## Documentation Required A separate process downloads these into the listed folder before this issue is implemented. Check the folder for the actual reference material before starting. **`docs/reference/mongodb-driver/`** — for `Db.listCollections`: - https://mongodb.github.io/node-mongodb-native/7.6/classes/Db.html — API reference for `Db.listCollections(filter?, options?)` → `ListCollectionsCursor`; `ListCollectionsOptions` includes `nameOnly` (when true, returns `{ name, type }[]` instead of full info documents `{ name, type, options, info }`). - https://www.mongodb.com/docs/drivers/node/current/databases-collections/ — guide: working with databases and collections via the driver. - https://mongodb.github.io/node-mongodb-native/7.6/ — TypeDoc API reference index (cursor class). ## Implementation Details Create `extensions/mongodb/src/tools/listCollections.ts`. Tool registered as `mongo_list_collections` via `pi.registerTool` with a TypeBox parameter schema: - `db` (string, **required**) — database name - `nameOnly?` (boolean, default `false`) Behavior: 1. `const infos = await db.listCollections({}, { nameOnly }).toArray()` — wrap in try/catch; on error `toToolError(err, context)` (throws). 2. When `nameOnly: true`, the driver returns `{ name, type }[]` — return those (the names) directly; otherwise return the full info documents `{ name, type, options, info }[]`. 3. Return the EJSON array as content and `details: { count }` (number of collections). Mirror the structure of `src/tools/find.ts` / `src/tools/count.ts` (sibling steps) and the sibling `extensions/postgres/src/tools/` implementations. Tests use a fake client whose `db(name)` returns an object with `listCollections(filter, options)` returning a cursor with `toArray()`. Write co-located tests in `src/tools/listCollections.test.ts`: - Happy path: fake returns collection info docs → EJSON array content + `details: { count }` correct. - `nameOnly: true` → names only returned. - Each error category (connection, auth, invalid, server, unexpected) surfaces as the categorized message. ## Acceptance Criteria - [ ] Happy path returns the collection info documents as EJSON and `details: { count }`. - [ ] `nameOnly: true` → only collection names returned. - [ ] All five error categories throw categorized `ToolError`s with correct message prefixes. - [ ] `bun test` in `extensions/mongodb/` is green for `src/tools/listCollections.ts`. ## Test Plan ```bash cd extensions/mongodb bun test # listCollections tool tests green ```

david added this to the MongoDB: M4 - Read Tools milestone

2026-08-31 22:05:23 +00:00

david added the

feature

label

2026-08-31 22:05:23 +00:00

david referenced this issue

2026-08-31 22:06:34 +00:00

Implement index.ts async factory + lifecycle with tests #143

david added the

ready

label