docbase

docbase gives an agent — or you, at a terminal — a complete set of MongoDB database tools: browse databases and collections, run find queries and aggregation pipelines, insert, update, and delete documents, manage indexes and collections, read database statistics and server logs, and ask the server to explain a query plan.

There is no bundled MongoDB driver. Every tool call is first mapped to a plain MongoDB command document ({ find: ... }, { aggregate: ... }, { createIndexes: ... }), and the default executor runs that document through the mongosh command-line client with db.runCommand(...). A machine that wants live answers therefore needs mongosh on its PATH and a reachable MongoDB instance. Without either, the server still starts and lists its tools; only the call itself reports the problem, in plain language.

Install

npx @reneturcios/docbase call list-databases

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/docbase

The container defaults to the MCP server (see below). Note the stock image bundles no mongosh binary, so containerised live queries need a mongosh provided on the host or mounted into the image.

CLI

# Run one tool; the JSON-args argument is optional for no-arg tools
docbase call list-databases
docbase call find '{"database":"shop","collection":"users","filter":{"active":true},"limit":5}'
docbase call db-stats '{"database":"shop"}'

# Start the MCP server (connection string optional, see below)
docbase mcp mongodb://alice@localhost:27017/shop

docbase --version

Exit codes: 0 on success, 1 when the tool call, the connection, or mongosh itself fails (the error says which), 2 for usage errors.

The connection string is a normal MongoDB URL (mongodb:// or mongodb+srv://). For both mcp and call it can be left off the command line and supplied through the MDB_MCP_CONNECTION_STRING environment variable. The connect tool also accepts a connectionString argument, which is validated and used for that call's ping.

How a call flows

1. Arguments are validated (required database/collection names, object-shaped filters, non-empty document arrays, and so on). Invalid calls fail before anything reaches an executor.
2. The call is mapped to its command document — for example update-many becomes { update: <collection>, updates: [{ q: filter, u: update, multi: true }] }.
3. The executor runs the document. Three tools post-process the reply: collection-schema samples 25 documents ($sample) and infers a field-to-types map from them; mongodb-logs runs getLog and applies the requested limit to the returned lines; export runs a find and returns the matching documents under the requested export title.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/docbase mcp mongodb://alice@localhost:27017/shop

MCP client configuration:

{
  "mcpServers": {
    "docbase": {
      "command": "npx",
      "args": ["-y", "@reneturcios/docbase", "mcp"],
      "env": { "MDB_MCP_CONNECTION_STRING": "mongodb://alice@localhost:27017/shop" }
    }
  }
}

Tools

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live database
npm run dev     # run the CLI from source via tsx

All command construction, validation, schema inference, and log limiting are covered by tests that drive the core through a fake executor — no MongoDB server and no mongosh binary are needed to run the suite.

License

MIT — see LICENSE.