E-commerce AI Agents on MongoDB — companion app

A runnable companion to the blog post "Building E-commerce AI Agents on MongoDB." It wires up the post's code samples — a CrewAI shopping agent backed by MongoDB Vector Search, atomic inventory checkout with Change Streams, and (as deploy-ready artifacts) an Atlas Trigger and an Atlas Stream Processing pipeline for post-purchase intelligence.

Requirements

• A MongoDB Atlas cluster. Atlas Vector Search isn't available on self-managed MongoDB, but the free M0 tier is sufficient for this app — it supports both Vector Search and Change Streams for testing (M0 caps you at 3 combined search/vector indexes; this app uses 1). Only Atlas Stream Processing (Step 5, deploy-only — see docs/DEPLOYING_CLOUD_ARTIFACTS.md) requires an M10+ cluster, and it isn't needed to run anything locally.
• Python 3.10+
• A Voyage AI API key. Embeddings use voyage-4-lite, so they're covered by Voyage's 200M free-token allowance per account — effectively free for this app.
• A Gemini API key. Agents use gemini/gemini-2.5-flash, which is covered by Gemini's free tier (1,500 requests/day, no credit card) — no OpenAI key needed.
• Node.js/npx on your PATH — only needed for the optional MongoDB MCP Server variant (search/product_search_mcp.py).

Setup

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp env.example .env
# fill in MONGODB_URI, VOYAGE_API_KEY, GEMINI_API_KEY
# (and MDB_MCP_CONNECTION_STRING if you'll use the MCP variant)

.env is loaded automatically by demo.py and the scripts/ package — nothing else reads it, so make sure any other entry point you write calls load_dotenv() before it first calls db.get_database() (or any other code that reads os.environ).

All MongoDB access in this app goes through the single memoized client in db.py rather than each module opening its own connection pool

1. Seed sample data

python -m scripts.seed_data

Inserts a handful of sample products — embedded with the same voyage-4-lite model the search tool uses — plus matching ecommerce.inventory documents, so the search and checkout flows have real data to work with. This also creates the ecommerce.products collection, which has to exist before the next step.

2. Create the Vector Search index

python -m scripts.create_vector_index

Applies indexes/product_vector_index.json to ecommerce.products. Must run after step 1 — Atlas can't create a search index on a collection that doesn't exist yet, and on a fresh cluster ecommerce.products doesn't exist until something's been inserted into it.

3. Run the demo

Search (Step 1–3 — Vector Search shopping agent):

python demo.py "lightweight running shoes under $100 with good arch support"

Checkout (Step 4 — atomic inventory reservation):

python demo.py --checkout SHOE-RUN-001

Inventory-recovery watcher (Step 4 — Change Streams), run in its own terminal so it can keep watching for sold-out products:

python -m checkout.stock_recovery

Trigger it by draining a product's inventory to 0 (e.g. run the checkout command above repeatedly against a low-stock SKU, or update it directly in ecommerce.inventory).

4. Optional: MongoDB MCP Server variant

search/product_search_mcp.py defines an alternate shopping_agent that adds the MongoDB MCP Server (in read-only mode) alongside the Vector Search tool. It requires MDB_MCP_CONNECTION_STRING in .env and npx available locally. It isn't wired into demo.py — import it directly to try it:

python -c "
from dotenv import load_dotenv; load_dotenv()
from crewai import Crew, Process, Task
from search.product_search_mcp import shopping_agent

task = Task(
    description='Look up the schema of the products collection, then find running shoes under \$100.',
    expected_output='A summary of matching products.',
    agent=shopping_agent,
)
print(Crew(agents=[shopping_agent], tasks=[task], process=Process.sequential).kickoff())
"

5. Cloud-only artifacts (Step 5)

post_purchase/atlas_trigger_shipped.js and stream_processing/delivery_delay_pipeline.json are run as managed Atlas services (Atlas Triggers / Atlas Stream Processing), not as part of this local app. See docs/DEPLOYING_CLOUD_ARTIFACTS.md for deployment steps.