🏢 CFO Agent - AI-Powered Shopify Store Management

An intelligent Multi-Agent Orchestration System for managing your Shopify store using natural language. Built with FastMCP, Streamlit, and powered by Groq LLM (Llama 3.3 70B).

🎯 What is CFO Agent?

CFO Agent is an AI assistant that lets you manage your Shopify store through a conversational interface. Instead of navigating complex admin panels, simply tell the agent what you need:

• "Show me the store dashboard"
• "Create a new product called Summer Hat priced at $29.99"
• "What are my recent orders?"
• "Update the price of variant 123 to $19.99"

🤖 Multi-Agent Architecture

The system uses three specialized agents:

Agent	Role	Capabilities
🎯 Triage	Orchestrator	Routes requests to the right specialist
🛍️ ShopifyManager	Write Operations	Create products, update prices, edit descriptions
📊 DataAnalyst	Read Operations	Dashboard, orders, products, abandoned checkouts

---

📋 Prerequisites

Before you begin, ensure you have:

• Python 3.12+ installed
• uv - Fast Python package manager
• A Shopify Partner account with a custom app
• A Groq API key (free at console.groq.com)
• ngrok (for exposing local server to Shopify OAuth)

---

🚀 Setup Guide

Step 1: Clone the Repository

git clone https://github.com/yourusername/CFO.git
cd CFO

Step 2: Install Dependencies

Using uv (recommended):

uv sync

This will create a virtual environment and install all dependencies from pyproject.toml.

Step 3: Create Shopify Custom App

1. Go to Shopify Partners → Apps → Create app
2. Choose Create app manually
3. Note down:
   • Client ID (API Key)
   • Client Secret (API Secret Key)
4. In App setup → URLs, configure:
   • App URL: https://your-ngrok-url.ngrok-free.app
   • Redirect URL: https://your-ngrok-url.ngrok-free.app/oauth/callback
5. In API access scopes, add:
   • read_products, write_products
   • read_orders
   • read_checkouts
   • read_analytics

Step 4: Get a Groq API Key

1. Visit console.groq.com
2. Sign up / Log in
3. Go to API Keys → Create API Key
4. Copy your API key

Step 5: Configure Environment Variables

Create a .env file in the project root:

SHOPIFY_CLIENT_ID=your_shopify_client_id
SHOPIFY_CLIENT_SECRET=your_shopify_client_secret
SHOPIFY_HOST_URL=https://your-ngrok-url.ngrok-free.app
GROQ_API_KEY=your_groq_api_key

Step 6: Start ngrok Tunnel

Open a terminal and run:

ngrok http 8000

Copy the Forwarding URL (e.g., https://abc123.ngrok-free.app) and:

1. Update SHOPIFY_HOST_URL in your .env file
2. Update your Shopify app URLs in the Partner Dashboard

Step 7: Start the MCP Server

In a new terminal:

uv run uvicorn mcp_servers.main:mcp.app --reload --port 8000

The server will be running at http://localhost:8000.

Step 8: Install the App on Your Store

1. Open your browser and go to:

   https://your-ngrok-url.ngrok-free.app/install?shop=your-store.myshopify.com
   

2. Authorize the app on Shopify
3. After successful installation, a tokens.json file will be created

Alternative: If OAuth doesn't work, use the manual token setup:

uv run python set_token.py

Enter your shop domain and Admin API Access Token.

Step 9: Launch the Streamlit App

uv run streamlit run CFO_agent/app.py

The app will open at http://localhost:8501.

Step 10: Connect and Chat!

1. Enter your Shopify store domain (e.g., your-store.myshopify.com)
2. Click Connect
3. Start chatting with your AI assistant!

---

📁 Project Structure

CFO/
├── CFO_agent/              # Multi-agent orchestration
│   ├── agents.py           # Agent definitions (Triage, ShopifyManager, DataAnalyst)
│   ├── app.py              # Streamlit frontend
│   ├── config.py           # Groq LLM configuration
│   ├── mcp_client.py       # MCP client for tool execution
│   ├── orchestrator.py     # Agent orchestration logic
│   └── main.py             # CLI entry point
├── mcp_servers/
│   └── main.py             # FastMCP server with Shopify tools
├── .env                    # Environment variables (create this)
├── tokens.json             # Shopify access tokens (auto-generated)
├── set_token.py            # Manual token setup script
├── pyproject.toml          # Project dependencies
└── README.md               # This file

---

🛠️ Available Tools

Read Operations (DataAnalyst)

Tool	Description
get_store_dashboard	High-level store overview (orders, products, sales)
get_recent_orders	Fetch recent orders with customer details
get_products	Search products by keyword
get_product_description	Get a product's description
get_abandoned_checkouts	View incomplete checkouts

Write Operations (ShopifyManager)

Tool	Description
create_product	Create a new product with price and stock
update_price	Update variant price
update_product_description	Update product description

---

💡 Example Queries

📊 Analytics
- "Show me the store dashboard"
- "What are my recent orders?"
- "Find products containing 'jacket'"
- "List abandoned checkouts"

🛍️ Management
- "Create a product called 'Winter Coat' priced at $149.99 with 50 in stock"
- "Update the price of variant 12345 to $99.99"
- "Change the description of product 67890 to 'Premium quality...'"

---

🔧 Troubleshooting

"No access token found for shop"

• Ensure you've installed the app on your store (Step 8)
• Check that tokens.json exists and contains your shop's token
• Try the manual token setup with uv run python set_token.py

OAuth redirect issues

• Verify your ngrok URL is running and matches .env
• Ensure Shopify app URLs are correctly configured in Partner Dashboard
• Check that the redirect URL includes /oauth/callback

MCP Server not responding

• Confirm the server is running on port 8000
• Check terminal for any error messages
• Restart with uv run uvicorn mcp_servers.main:mcp.app --reload --port 8000

---

📝 License

MIT License - feel free to use and modify as needed.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Built with ❤️ using FastMCP, Streamlit, and Groq