pysorflow/mcpdemo

🛍️ MCP Product Management System

A comprehensive Model Context Protocol (MCP) server for product inventory management with PostgreSQL database backend, Docker containerization, and multiple AI platform integrations.

🎯 System Overview

This system provides a sophisticated product management platform with:

• 9,739 products across multiple categories
• 9 advanced MCP tools with Django-style filtering
• PostgreSQL database with Docker containerization
• Multi-platform AI integration (Claude Desktop, Ollama, Perplexity)
• Advanced filtering & pagination capabilities
• Natural language query processing

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude Desktop│    │   MCP Inspector  │    │     Ollama      │    │   Perplexity    │
│                 │    │                  │    │     Bridge      │    │     Local       │
└─────────┬───────┘    └─────────┬────────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                       │                      │
          └──────────────────────┼───────────────────────┼──────────────────────┘
                                 │                       │
                    ┌────────────┴───────────┐           │
                    │   Local MCP Server     │           │
                    │ (local_mcp_server.py)  │           │
                    │   • 9 Advanced Tools   │           │
                    │   • Django Filtering   │           │
                    │   • Pagination         │           │
                    └────────────┬───────────┘           │
                                 │                       │
                    ┌────────────┴───────────┐           │
                    │   Docker MCP Server    │           │
                    │   (mcp_server.py)      │           │
                    │   • Container-based    │           │
                    └────────────┬───────────┘           │
                                 │                       │
                    ┌────────────┴───────────┐           │
                    │   PostgreSQL DB        │◄─────────-┘
                    │   • 9,739 products     │   Direct Connection
                    │   • Full-text search   │   (ollama_mcp_bridge.py)
                    │   • Advanced indexes   │
                    └────────────────────────┘

🛠️ Setup & Installation

Prerequisites

• Docker & Docker Compose
• Python 3.10+ (required for MCP library)
• Node.js (for MCP Inspector)
• Ollama (optional, for Ollama integration)

🔍 Python Version Check

# Check your Python version first
python3 --version

# If you have Python < 3.10, you need to upgrade or use a different Python version
# On macOS with Homebrew:
# brew install python@3.11

# On Ubuntu/Debian:
# sudo apt update && sudo apt install python3.11

# On Windows: Download from python.org

1. Clone & Setup

git clone https://github.com/pysorflow/mcpdemo.git
cd mcpdemo

# Create Python virtual environment (use Python 3.10+)
python3 -m venv venv
source venv/bin/activate  # On macOS/Linux
# venv\Scripts\activate   # On Windows

# If python3 is too old, try specific version:
# python3.11 -m venv venv
# python3.10 -m venv venv

# Install dependencies
pip install -r requirements.txt

2. Start Docker Services

# Start PostgreSQL database
docker-compose up -d

# Verify services are running
docker-compose ps

3. Import Product Data

# Import 9,739 products into database
python import_products.py

4. Test System

# Run comprehensive tests
python test.py

🔧 Available MCP Tools

Core Tools

1. get_product - Get detailed product information by SKU
2. list_products - List products with optional category filtering
3. search_products - Basic search across product fields
4. advanced_search_products - Comprehensive search with filtering
5. update_stock - Update product stock levels

Advanced Tools

6. filter_products - Django-style filtering with pagination

   • Field lookups: category__icontains, stock__gte, price__lte, etc.
   • Sorting: ["-stock", "title"]
   • Pagination: page, page_size

7. get_categories - List all product categories and subcategories

8. get_low_stock_products - Find products with low inventory

9. get_filter_stats - Get filtering statistics and breakdowns

Django-Style Filter Examples

{
  "filters": {
    "category__icontains": "shirt",
    "color__icontains": "blue", 
    "stock__gte": 50,
    "price__lte": 25.00,
    "size__in": ["L", "XL"]
  },
  "ordering": ["-stock", "price"],
  "page": 1,
  "page_size": 20
}

🖥️ Platform Integration

1. MCP Inspector (Testing & Development)

Setup & Run

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Start local MCP server + Inspector
npx @modelcontextprotocol/inspector python local_mcp_server.py

Usage

• URL: Opens automatically in browser (usually http://localhost:5173)
• Features: Test all 9 tools, view JSON schemas, debug responses
• Best for: Development, testing, debugging MCP tools

2. Claude Desktop Integration

Setup Configuration

1. Locate Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add MCP server configuration:

{
  "mcpServers": {
    "product-manager": {
      "command": "/Users/arunss/Documents/myroot/mcpdemo/run_mcp_server.sh",
      "args": []
    }
  }
}

3. Make shell script executable:

chmod +x run_mcp_server.sh

Usage

• Restart Claude Desktop after config changes
• Natural language queries: "Show me blue shirts under $20 with good stock"
• Complex filtering: "Find size XL products sorted by price"
• Business queries: "What are our top categories by inventory?"

Example Queries

• "Give me details of SKU 120715"
• "Show products with more than 1000 units in stock"
• "What black items do we have from Gildan warehouse?"
• "Filter polo shirts with prices between $15 and $30"

3. Ollama Integration

Setup Ollama

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Download recommended models
ollama pull qwen2.5:7b-instruct  # Best for natural language
ollama pull llama3.2:1b          # Fastest, lightweight
ollama pull llama3.1:8b          # Balanced performance

Run Ollama Bridge

# Start enhanced Ollama bridge
python ollama_mcp_bridge.py

Features

• Model selection at startup
• Natural language processing with LLM-based query parsing
• Advanced filtering through conversational interface
• Statistics commands: stats, examples, models

Usage Example

💬 Your question [qwen2.5:7b-instruct]: Show me blue shirts under $20 with good stock

🔍 Analyzing: 'Show me blue shirts under $20 with good stock'
🎯 Initial classification: ADVANCED_FILTER
🤖 LLM filter analysis: {"filters": {"color__icontains": "blue", "category__icontains": "shirt", "price__lte": 20, "stock__gte": 50}, "ordering": ["-stock"], "page_size": 10}
📊 Data retrieved: 1247 characters

🤖 Answer:
Based on your search for blue shirts under $20 with good stock, I found several excellent options...

4. Perplexity Local Integration

Setup

1. Install Perplexity Desktop or use Perplexity API
2. Configure MCP connection in Perplexity settings
3. Add server endpoint:

{
  "mcp_servers": {
    "product_manager": {
      "type": "local",
      "command": "python",
      "args": ["/Users/arunss/Documents/myroot/mcpdemo/local_mcp_server.py"],
      "working_directory": "/Users/arunss/Documents/myroot/mcpdemo"
    }
  }
}

Usage

• Research queries: "Analyze our product inventory distribution"
• Business intelligence: "What's our stock situation across categories?"
• Data exploration: "Show me patterns in our product pricing"

📋 Usage Workflows

Development Workflow

1. Start Docker: docker-compose up -d
2. Test with Inspector: npx @modelcontextprotocol/inspector python local_mcp_server.py
3. Debug tools, test filters, verify responses
4. Deploy to AI platforms

Production Workflow

1. Docker services running: docker-compose up -d
2. Claude Desktop configured with shell script
3. Ollama bridge available for advanced NLP
4. Multiple access points for different use cases

Business User Workflow

1. Open Claude Desktop
2. Ask natural language questions:
   • "What's our inventory status?"
   • "Show me slow-moving products"
   • "Find products that need restocking"
3. Get instant, detailed responses

🔍 Sample Questions & Use Cases

Basic Queries

• "Give me details of product SKU 120715"
• "List all T-shirt categories we have"
• "Show me products with low stock"

Advanced Filtering

• "Show blue shirts under $20 with good stock levels"
• "Find size XL products sorted by price ascending"
• "What black items do we have from Gildan warehouse?"

Business Intelligence

• "What are our top 5 categories by product count?"
• "Show me inventory distribution across warehouses"
• "Which products have the highest stock levels?"

Inventory Management

• "Products with more than 1000 units in stock"
• "Show items that are running low on inventory"
• "What's our most expensive product in each category?"

Complex Analysis

• "Filter polo shirts with prices between $15 and $30"
• "Show me all products from Hanes with sizes L and XL"
• "Find products with zero stock sorted by category"

🧪 Testing

Run Test Suite

python test.py

Test Individual Components

# Test database connection
python -c "import psycopg2; print('DB OK')"

# Test MCP server
python local_mcp_server.py

# Test Ollama bridge
python ollama_mcp_bridge.py

Verification Checklist

• ✅ Docker services running (docker-compose ps)
• ✅ Database populated (9,739 products)
• ✅ MCP tools functional (test.py passes)
• ✅ Claude Desktop integration working
• ✅ Ollama models available

📁 File Structure

mcpdemo/
├── 📄 README.md                 # This comprehensive guide
├── 🐳 docker-compose.yml        # Docker services configuration
├── 🐳 Dockerfile               # MCP server container
├── 📋 requirements.txt         # Python dependencies
├── 🛠️ local_mcp_server.py      # Main MCP server (9 tools)
├── 🛠️ mcp_server.py            # Docker-based MCP server
├── 🤖 ollama_mcp_bridge.py     # Enhanced Ollama integration
├── 📊 import_products.py       # Data import script
├── 🧪 test.py                  # Comprehensive test suite
├── 📝 sample_questions.txt     # 25 sample questions + examples
├── ⚙️ run_mcp_server.sh        # Claude Desktop shell script
├── ⚙️ claude_desktop_config.json # Claude Desktop configuration
├── 📦 products-master.csv      # Product data (9,739 items)
└── 📁 venv/                    # Python virtual environment

⚠️ Troubleshooting

Common Issues

1. Database Connection Failed

# Check Docker services
docker-compose ps

# Restart if needed
docker-compose down && docker-compose up -d

2. Python Version Error (MCP requires Python 3.10+)

# Check your Python version
python3 --version

# If version is < 3.10, upgrade Python:
# macOS (Homebrew): brew install python@3.11
# Ubuntu/Debian: sudo apt install python3.11
# Windows: Download from python.org

# Create virtual environment with correct Python version
python3.11 -m venv venv  # or python3.10
source venv/bin/activate
pip install -r requirements.txt

3. MCP Server Not Starting

# Check Python environment
source venv/bin/activate
pip install -r requirements.txt

4. Claude Desktop Not Connecting

• Verify config file path
• Check shell script permissions: chmod +x run_mcp_server.sh
• Restart Claude Desktop after config changes

5. Ollama Models Not Found

# List available models
ollama list

# Download missing models
ollama pull qwen2.5:7b-instruct

🚀 Advanced Features

Django-Style Filtering

• Field lookups: __icontains, __exact, __gte, __lte, __in
• Pagination: Automatic with page/page_size
• Sorting: Multi-field with direction control
• Global search: Across all text fields

Natural Language Processing

• LLM-powered query parsing in Ollama bridge
• Intent classification for optimal tool selection
• Fallback strategies for complex queries
• Context-aware responses

Performance Optimizations

• Database indexes on key fields
• Connection pooling for high-load scenarios
• Query optimization for large datasets
• Efficient pagination with offset/limit

📈 Statistics

• Total Products: 9,739
• Categories: 15+ major categories
• MCP Tools: 9 advanced tools
• Database: PostgreSQL 16
• Docker Services: 2 containers
• AI Platforms: 4 integrations
• Filter Options: 16 Django-style filters
• Status: ✅ FULLY OPERATIONAL

🎯 Next Steps

1. Explore Sample Questions: Check sample_questions.txt for 25 comprehensive examples
2. Customize Tools: Modify MCP tools for your specific needs
3. Scale Database: Add more products or customize schema
4. Extend AI Integration: Add more AI platforms or models
5. Build Applications: Use MCP protocol for custom applications

🎉 Your MCP Product Management System is ready for production use!

Last updated: August 2025 System tested and verified across all platforms