🛍️ 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

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

Advanced Tools

filter_products - Django-style filtering with pagination
- Field lookups: category__icontains, stock__gte, price__lte, etc.
- Sorting: ["-stock", "title"]
- Pagination: page, page_size
get_categories - List all product categories and subcategories
get_low_stock_products - Find products with low inventory
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

Locate Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add MCP server configuration:

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

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

Install Perplexity Desktop or use Perplexity API
Configure MCP connection in Perplexity settings
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

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

Production Workflow

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

Business User Workflow

Open Claude Desktop
Ask natural language questions:
- "What's our inventory status?"
- "Show me slow-moving products"
- "Find products that need restocking"
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

Explore Sample Questions: Check sample_questions.txt for 25 comprehensive examples
Customize Tools: Modify MCP tools for your specific needs
Scale Database: Add more products or customize schema
Extend AI Integration: Add more AI platforms or models
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

🛍️ 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

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

Advanced Tools

filter_products - Django-style filtering with pagination
- Field lookups: category__icontains, stock__gte, price__lte, etc.
- Sorting: ["-stock", "title"]
- Pagination: page, page_size
get_categories - List all product categories and subcategories
get_low_stock_products - Find products with low inventory
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

Locate Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add MCP server configuration:

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

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

Install Perplexity Desktop or use Perplexity API
Configure MCP connection in Perplexity settings
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

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

Production Workflow

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

Business User Workflow

Open Claude Desktop
Ask natural language questions:
- "What's our inventory status?"
- "Show me slow-moving products"
- "Find products that need restocking"
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

Explore Sample Questions: Check sample_questions.txt for 25 comprehensive examples
Customize Tools: Modify MCP tools for your specific needs
Scale Database: Add more products or customize schema
Extend AI Integration: Add more AI platforms or models
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