Write extensions/mongodb/README.md #145

New issue

Closed

opened 2026-08-31 22:06:47 +00:00 by david · 1 comment

david commented

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

Owner

Summary

Write extensions/mongodb/README.md — setup, configuration, the read-only-user recommendation, the tool list with example prompts, and v1 caveats — matching the extension's actual implemented behavior.

Background

Depends on: #143

The README is the first thing a user reads about the extension; it must describe real behavior, not intentions. Model the structure on extensions/postgres/README.md and extensions/victorialogs/README.md (this repo's sibling extensions). The current README.md is a stub from the scaffold milestone — replace it.

Implementation Details

Cover, in order:

Setup — bun install inside extensions/mongodb/; note the repo-root install hoists the dependency, and the extension is registered in the repo root pi.extensions.
Configuration — MONGODB_URI=mongodb://user:pass@host:27017/db in the project's .env (never committed). Note: mongodb+srv:// (Atlas) and TLS (?tls=true) are supported purely via the connection string; the URI lookup is case-insensitive and also accepts a nested config__MONGODB_URI key.
Security recommendation — create a dedicated read-only DB user for this extension (read role on the target database). The extension cannot verify server-side privileges; it restricts its own driver surface to read methods (find, countDocuments, listCollections) only, and the README should say so.
Tools — one line each for mongo_find (query documents, EJSON output, default limit 100 / cap 1000), mongo_count (count matching docs), mongo_list_collections (list collections, optional nameOnly), each with an example prompt (e.g. "show me the users created last week", "how many orders are pending?", "what collections are in this database?").
Caveats / v1 non-goals — no write operations of any kind; no mongo_aggregate; single configured instance only (MONGODB_URI); no read-preference forcing or privilege probing.
Unconfigured behavior — when MONGODB_URI is absent, pi boots cleanly with zero mongo_* tools registered (no error, no warning).

Keep claims consistent with the code: no writes, no aggregation, default limit/cap values as implemented.

Acceptance Criteria

README covers setup, configuration (incl. mongodb+srv:///TLS), read-only-user recommendation, tool list with example prompts, caveats, and the unconfigured-behavior note.
Every claim matches the implemented behavior (read-only surface, defaults 100/1000, 100 KB cap, silent-when-unconfigured).
Structure/format is consistent with the sibling postgres/victorialogs READMEs.

Test Plan

Read the README top to bottom; cross-check each claim against the implemented index.ts, src/tools/*, src/defaults.ts, and src/serialize.ts (e.g. grep the constants, read the tool registrations). Fix any mismatch found.

## Summary Write `extensions/mongodb/README.md` — setup, configuration, the read-only-user recommendation, the tool list with example prompts, and v1 caveats — matching the extension's actual implemented behavior. ## Background **Depends on:** #143 The README is the first thing a user reads about the extension; it must describe real behavior, not intentions. Model the structure on `extensions/postgres/README.md` and `extensions/victorialogs/README.md` (this repo's sibling extensions). The current `README.md` is a stub from the scaffold milestone — replace it. ## Implementation Details Cover, in order: 1. **Setup** — `bun install` inside `extensions/mongodb/`; note the repo-root install hoists the dependency, and the extension is registered in the repo root `pi.extensions`. 2. **Configuration** — `MONGODB_URI=mongodb://user:pass@host:27017/db` in the project's `.env` (never committed). Note: `mongodb+srv://` (Atlas) and TLS (`?tls=true`) are supported purely via the connection string; the URI lookup is case-insensitive and also accepts a nested `config__MONGODB_URI` key. 3. **Security recommendation** — create a dedicated **read-only DB user** for this extension (`read` role on the target database). The extension cannot verify server-side privileges; it restricts its own driver surface to read methods (`find`, `countDocuments`, `listCollections`) only, and the README should say so. 4. **Tools** — one line each for `mongo_find` (query documents, EJSON output, default limit 100 / cap 1000), `mongo_count` (count matching docs), `mongo_list_collections` (list collections, optional `nameOnly`), each with an example prompt (e.g. "show me the users created last week", "how many orders are pending?", "what collections are in this database?"). 5. **Caveats / v1 non-goals** — no write operations of any kind; no `mongo_aggregate`; single configured instance only (`MONGODB_URI`); no read-preference forcing or privilege probing. 6. **Unconfigured behavior** — when `MONGODB_URI` is absent, pi boots cleanly with **zero** `mongo_*` tools registered (no error, no warning). Keep claims consistent with the code: no writes, no aggregation, default limit/cap values as implemented. ## Acceptance Criteria - [ ] README covers setup, configuration (incl. `mongodb+srv://`/TLS), read-only-user recommendation, tool list with example prompts, caveats, and the unconfigured-behavior note. - [ ] Every claim matches the implemented behavior (read-only surface, defaults 100/1000, 100 KB cap, silent-when-unconfigured). - [ ] Structure/format is consistent with the sibling postgres/victorialogs READMEs. ## Test Plan Read the README top to bottom; cross-check each claim against the implemented `index.ts`, `src/tools/*`, `src/defaults.ts`, and `src/serialize.ts` (e.g. `grep` the constants, read the tool registrations). Fix any mismatch found.

david added this to the MongoDB: M6 - Documentation & Load Validation milestone

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

david added the

documentation

label

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

david referenced this issue

2026-08-31 22:07:25 +00:00

Add mongodb row to the repo root README extension table #147

david added the

ready

label