Mongo Db Client Tool

Interact with a MongoDB database for persistent document storage. Supports full CRUD operations (find, insert, update, delete), aggregation pipelines, collec...

Security Scan

The skill's code, instructions, and requirements match its stated purpose of providing a Python-based MongoDB CLI client; nothing requests unrelated credentials or installs unexpected tooling.

Purpose & Capability

Name/description (MongoDB client) align with the provided files: a Python CLI (mongo_client.py), a setup script that installs pymongo, and docs for configuring MONGO_URI or config.json. Required binary (python3) and the documented env vars are appropriate for the stated purpose.

Instruction Scope

SKILL.md restricts actions to MongoDB operations via a JSON payload and documents connection resolution and destructive-operation safeguards (drop/delete require a 'confirm' flag). One minor note: the client searches for config.json in both the skill dir and workspace paths (Path.cwd() candidate), so it could pick up a config outside the skill directory if present — expected for convenience, but worth being aware of.

Install Mechanism

There is no remote arbitrary download. Setup is a local shell script that creates a venv and pip-installs pymongo from PyPI (expected for a Python skill). INSTALL-UBUNTU.md references official MongoDB repos for local server install. These are standard and proportionate to the purpose.

Credentials

Declared and used environment variables are limited to MongoDB connection settings (MONGO_URI, MONGO_DB, MONGO_HOST, MONGO_PORT, MONGO_USER, MONGO_PASSWORD). No unrelated secrets or service credentials are requested.

Persistence & Privilege

Skill is not force-included (always: false). It creates a venv under its own scripts directory and does not modify other skills or system-wide agent settings. The skill can be invoked autonomously (platform default), which is expected for skills that perform DB operations — users should control when destructive payloads are sent.

Assessment

This skill appears to do exactly what it says: run MongoDB operations via a Python CLI. Before installing, verify which MongoDB instance the agent will talk to (MONGO_URI or config.json) and avoid pointing it at production data without review. Be cautious about granting any automated agent the ability to call operations that include 'confirm': true — those flags are the protection against accidental destructive actions (drop/delete). Running the provided setup script in an isolated environment is advisable (it creates a .venv and pip-installs pymongo). If you need higher assurance, inspect the full mongo_client.py (it’s included) and test against a non-production database.

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:[e-mail]/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

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

{
  "operation": "delete_many",
  "database": "mydb",
  "collection": "transactions",
  "filter": {"source_file": "january_statement.pdf"},
  "confirm": true
}

---

Aggregate

{
  "operation": "aggregate",
  "database": "mydb",
  "collection": "transactions",
  "pipeline": [
    {"$match": {"type": "expense"}},
    {"$group": {"_id": "$category", "total": {"$sum": "$amount"}, "count": {"$sum": 1}}},
    {"$sort": {"total": 1}}
  ]
}

---

Notes

• Destructive operations (delete_one, delete_many, drop_collection) require "confirm": true in the payload. Always ask the user to confirm before including this flag.
• ObjectId fields are serialized as strings in all output.
• Database override: the "database" field in the payload overrides the default database from config/env for that single call.
• Schema validation: use create_collection with a "validator" to enforce document structure at the MongoDB level. This is the recommended approach for agents that write structured data (e.g. the finance-budget agent's budget and transaction collections).
• Upsert pattern: for config-like documents (one per type), use replace_one with "upsert": true to create-or-replace atomically.
• If pymongo is missing, re-run bash skills/mongo-db/scripts/setup.sh.