MongoDB — Document Storage Skill

Use this skill whenever an agent needs to read or write persistent data to MongoDB. All operations are performed via a Python CLI script and return JSON output.

When to use

User asks to "save to the database", "store this in Mongo", "retrieve from MongoDB"
An agent needs to persist data across sessions (budgets, transactions, summaries, watchlists)
An agent needs to query, filter, or aggregate stored records
A new collection or schema (validator) needs to be set up

Setup (first run only)

Local MongoDB: If you need to install MongoDB on Ubuntu, see INSTALL-UBUNTU.md. For Atlas, use your connection string in config or env.

Run the setup script once from the workspace root to create a virtual environment and install pymongo:

bash skills/mongo-db/scripts/setup.sh

This creates skills/mongo-db/scripts/.venv/ and installs dependencies there. After setup, invoke the client using the venv interpreter:

skills/mongo-db/scripts/.venv/bin/python3 skills/mongo-db/scripts/mongo_client.py '<json>'

Configuration

Connection is resolved in this order (first match wins):

Option 1 — Environment variable (recommended)

MONGO_URI=mongodb+srv://user:password@cluster.mongodb.net/mydb
MONGO_DB=mydb   # optional if the db is in the URI

Option 2 — config.json (local file, gitignored)

Copy the example and fill in your values:

cp skills/mongo-db/config.example.json skills/mongo-db/config.json

Edit skills/mongo-db/config.json:

{
  "uri": "mongodb://localhost:27017",
  "database": "mydb",
  "username": "optional",
  "password": "optional"
}

Option 3 — Individual env vars

MONGO_HOST=localhost
MONGO_PORT=27017
MONGO_USER=myuser
MONGO_PASSWORD=mypassword
MONGO_DB=mydb

CLI interface

All operations use a single JSON payload argument:

PYTHON=skills/mongo-db/scripts/.venv/bin/python3
$PYTHON skills/mongo-db/scripts/mongo_client.py '<json_payload>'

Payload schema:

{
  "operation": "<op>",
  "database": "<optional override>",
  "collection": "<collection name>",
  ...operation-specific fields
}

Output is always JSON: {"success": true, ...result_fields} or {"success": false, "error": "..."}.

Operations Reference

List databases

{"operation": "list_databases"}

List collections in a database

{"operation": "list_collections", "database": "mydb"}

Create a collection (with optional JSON Schema validator)

{
  "operation": "create_collection",
  "database": "mydb",
  "collection": "budgets",
  "validator": {
    "$jsonSchema": {
      "bsonType": "object",
      "required": ["period", "income"],
      "properties": {
        "period": {"bsonType": "string"},
        "income": {"bsonType": "number"}
      }
    }
  }
}

Drop a collection

Always confirm with the user before dropping. Requires "confirm": true.

{"operation": "drop_collection", "database": "mydb", "collection": "old_data", "confirm": true}

Create an index

{
  "operation": "create_index",
  "database": "mydb",
  "collection": "transactions",
  "keys": {"date": 1, "category": 1},
  "unique": false
}

Find documents

{
  "operation": "find",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"category": "groceries"},
  "projection": {"_id": 0, "date": 1, "amount": 1, "description": 1},
  "sort": {"date": -1},
  "limit": 20
}

Find one document

{
  "operation": "find_one",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"id": "txn_20260131_0001"}
}

Count documents

{
  "operation": "count",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"type": "expense"}
}

Insert one document

{
  "operation": "insert_one",
  "database": "mydb",
  "collection": "transactions",
  "document": {
    "id": "txn_20260201_0001",
    "date": "2026-02-01",
    "description": "Supermarket",
    "amount": -85.50,
    "category": "groceries",
    "type": "expense"
  }
}

Insert many documents

{
  "operation": "insert_many",
  "database": "mydb",
  "collection": "transactions",
  "documents": [
    {"date": "2026-02-01", "description": "Coffee", "amount": -4.50, "category": "dining"},
    {"date": "2026-02-02", "description": "Salary", "amount": 5000, "category": "income"}
  ]
}

Update one document

{
  "operation": "update_one",
  "database": "mydb",
  "collection": "budget",
  "filter": {"period": "monthly"},
  "update": {"$set": {"income": 5500, "last_updated": "2026-02-01"}},
  "upsert": false
}

Update many documents

{
  "operation": "update_many",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"category": "food"},
  "update": {"$set": {"category": "groceries"}}
}

Replace one document

{
  "operation": "replace_one",
  "database": "mydb",
  "collection": "budget",
  "filter": {"period": "monthly"},
  "replacement": {"period": "monthly", "income": 5500, "currency": "USD"},
  "upsert": true
}

Delete one document

Always confirm with the user before deleting. Requires "confirm": true.

{
  "operation": "delete_one",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"id": "txn_20260131_0001"},
  "confirm": true
}

Delete many documents