Store Management MCP Servers

A comprehensive Google Business Analytics MCP (Model Context Protocol) server system for store management, customer analytics, and executive insights.

This project implements specialized MCP servers for Google Business data collection and executive analytics, featuring:

• Collection Agent: Gathers data from Google Business Profile API

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Collection     │    │   Aggregation    │    │   Dashboard     │
│  Agent (8000)   │────│   Agent (8001)   │────│   (8501)        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │                       │
         ▼                        ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Google Business │    │ Azure OpenAI     │    │ Streamlit UI    │
│ Profile API     │    │ / TextBlob       │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

• Real-time Data Collection: Automated gathering of reviews, Q&A, and store information
• AI-Powered Analytics: Sentiment analysis, theme extraction, and trend identification
• Executive Dashboards: Business intelligence for decision-making
• Scalable Architecture: Container-based deployment with Azure Container Apps

• Customer sentiment tracking
• Review trend analysis
• Question categorization
• Performance metrics
• Alert mechanisms for critical issues

• Python 3.11+
• Docker Desktop
• Azure CLI (for deployment)
• Google Cloud Platform account with Business Profile API access

1. Clone the repository

   git clone https://github.com/ashburn-young/store_management_mcp.git
   cd store_management_mcp

2. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

3. Install dependencies

   pip install -e .[dev]

4. Run the services

   # Start Collection Agent
   python -m google_business_analytics.collection_agent.server
   
   # Start Aggregation Agent (in another terminal)
   python -m google_business_analytics.aggregation_agent.server
   
   # Start Dashboard (in another terminal)
   streamlit run dashboard/app.py --server.port 8501

The project includes pre-configured VS Code tasks for easy development:

• Start Collection Agent Server: Runs the collection MCP server
• Start Aggregation Agent Server: Runs the aggregation MCP server
• Start Streamlit Dashboard: Launches the dashboard
• Run Tests: Execute the test suite
• Format Code: Apply Black formatting
• Lint Code: Run Ruff linting
• Type Check: Run MyPy type checking

Copy .env.example to .env and configure:

# Azure OpenAI Configuration
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
AZURE_OPENAI_API_VERSION=2024-02-01

# Google API Configuration  
GOOGLE_API_KEY=your_google_api_key
GOOGLE_SERVICE_ACCOUNT_JSON=path/to/service-account.json

# Development Settings
ENVIRONMENT=development
USE_MOCK_DATA=true
LOG_LEVEL=INFO

1. Create a Google Cloud Platform project
2. Enable the Google Business Profile API
3. Create service account credentials
4. Download the service account JSON file
5. Set the GOOGLE_SERVICE_ACCOUNT_JSON environment variable

1. Create an Azure OpenAI resource
2. Deploy a GPT-4 model
3. Configure the endpoint and deployment name in .env
4. Authentication uses DefaultAzureCredential (Azure CLI login)

1. Install Azure Developer CLI (azd)

   # Windows (PowerShell)
   winget install microsoft.azd
   
   # macOS
   brew install azure-cli

2. Initialize and deploy

   azd init
   azd up

3. Access deployed services

   • Dashboard: https://{env-name}-dashboard.{region}.azurecontainerapps.io
   • Collection API: https://{env-name}-collection.{region}.azurecontainerapps.io
   • Aggregation API: https://{env-name}-aggregation.{region}.azurecontainerapps.io

1. Build images

   docker build -f Dockerfile.dashboard -t store-management-dashboard .
   docker build -f Dockerfile.collection -t store-management-collection .
   docker build -f Dockerfile.aggregation -t store-management-aggregation .

2. Run containers

   docker run -p 8501:8501 store-management-dashboard
   docker run -p 8000:8000 store-management-collection
   docker run -p 8001:8001 store-management-aggregation

• GET /health - Health check
• POST /tools/collect_reviews - Collect business reviews
• POST /tools/collect_qna - Collect Q&A data
• POST /tools/collect_store_info - Collect store information

• GET /health - Health check
• POST /tools/generate_insights - Process collected data
• POST /tools/create_snapshot - Create executive snapshot
• GET /resources/processed_data - Get processed insights

• Interactive Streamlit web interface
• Real-time data visualization
• Executive summary reports
• Performance analytics

Run the test suite:

# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html -v

# Run specific test files
python -m pytest tests/test_aggregator.py -v

• Use type hints throughout (Python 3.8+ compatible)
• Follow PEP 8 with Black formatting
• Use Pydantic models for data validation
• Implement proper async/await patterns

• Modular separation between collection and aggregation
• Configuration-driven approach for parameters
• Proper error handling and logging
• JSON schema contracts for compatibility

Raw Data → Store Insights → Executive Snapshots

1. Raw Data: Direct API responses from Google Business Profile
2. Store Insights: Processed data with sentiment analysis and themes
3. Executive Snapshots: High-level summaries for business decisions

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the development guidelines
4. Run tests and ensure they pass
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

├── src/google_business_analytics/
│   ├── collection_agent/          # Data collection MCP server
│   ├── aggregation_agent/         # Data processing MCP server
│   └── shared/                    # Common utilities and schemas
├── dashboard/                     # Streamlit web interface
├── infra/                        # Azure deployment templates (Bicep)
├── config/                       # Configuration files and schemas
├── data/                         # Sample data and mock files
├── tests/                        # Test suite
├── scripts/                      # Utility scripts
└── logs/                         # Application logs

This project is licensed under the MIT License - see the LICENSE file for details.

For questions, issues, or contributions:

• 📧 Email: ashburnyoung@outlook.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Project Wiki

• Built with the Model Context Protocol (MCP)
• Powered by Azure OpenAI and Google Business Profile API
• UI built with Streamlit
• Deployed on Azure Container Apps

MIT License - see LICENSE file for details.