SkuVault Server

A Model Context Protocol (MCP) server that provides seamless integration with the SkuVault inventory management system API. Built for production use with enterprise-grade features.

🚀 Features

Core Functionality

• Product Management: Create, read, update products individually or in batches
• Inventory Control: Add, remove, and set inventory quantities across warehouses
• Warehouse Operations: List warehouses and manage inventory by location
• Smart Analytics: Active/inactive products, low stock alerts, inventory summaries

Production-Ready

• ✅ Rate Limiting: Dynamic rate limit learning with exponential backoff
• ✅ Caching: Intelligent response caching to minimize API calls
• ✅ Safety: Confirmation requirements for all mutating operations
• ✅ Validation: Comprehensive input validation for all operations
• ✅ Performance: Connection pooling and request queuing

📦 Installation

1. Clone the repository:

git clone https://github.com/dbankscard/skuvault-mcp-server.git
cd skuvault-mcp-server

2. Install dependencies:

pip install -e .

3. Set up authentication:

cp .env.example .env
# Edit .env and add your SkuVault credentials

🔧 Configuration

For Claude Desktop

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "skuvault": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/skuvault-mcp-server",
      "env": {
        "SKUVAULT_TENANT_TOKEN": "your_tenant_token",
        "SKUVAULT_USER_TOKEN": "your_user_token"
      }
    }
  }
}

Troubleshooting: PYTHONPATH Configuration

If you encounter import errors when running the server, you may need to set the PYTHONPATH environment variable. This is necessary because:

1. Module Structure: The server uses absolute imports (e.g., from src.auth import SkuVaultAuth) which require Python to know where to find the src module.
2. MCP Integration: When Claude Desktop launches the server, it may not automatically include the project root in Python's module search path.

To fix this, add PYTHONPATH to your configuration:

{
  "mcpServers": {
    "skuvault": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/skuvault-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/skuvault-mcp-server",
        "SKUVAULT_TENANT_TOKEN": "your_tenant_token",
        "SKUVAULT_USER_TOKEN": "your_user_token"
      }
    }
  }
}

Note: The PYTHONPATH should point to the root directory of the project (where the src folder is located), not to the src folder itself.

🛠️ Available Tools

Product Operations

• get_product(sku) - Get product details
• get_products(page_number, page_size, skus, get_all, active_only) - List products
• create_product(...) - Create new product
• update_product(...) - Update product
• batch_update_products(updates) - Update multiple products efficiently

Inventory Management

• get_inventory_by_location(...) - Get inventory with filtering
• add_inventory(...) - Add inventory
• remove_inventory(...) - Remove inventory
• set_item_quantity(...) - Set exact quantity

Analytics

• get_all_active_products() - All active products with pagination
• get_all_inactive_products() - All inactive products
• get_low_stock_products(threshold) - Products at/below reorder point
• get_product_summary_report() - Comprehensive statistics

System Tools

• get_cache_stats() - Cache performance metrics
• clear_cache(pattern) - Clear cached data
• get_rate_limits() - View current rate limits
• call_api_endpoint(endpoint, **params) - Access any SkuVault API endpoint

📚 Documentation

• Best Practices Guide - Detailed workflows and usage patterns
• API Schema - Complete API specification

💡 Example Questions You Can Ask

📦 Product Management

• "Show me details for SKU ABC123"
• "Get all active products"
• "Find all inactive products"
• "List products with SKUs ABC123, DEF456, and GHI789"
• "Show me all products from brand XYZ"
• "Create a new product with SKU NEW001, description 'Test Product', cost $10"
• "Update the price of SKU ABC123 to $29.99"
• "Update the cost to $15 for SKUs ABC123, DEF456, and GHI789"
• "Change the description of SKU XYZ789 to 'Updated Product Name'"

📊 Inventory Analysis

• "What's my current inventory for SKU ABC123?"
• "Show inventory by location for warehouse 1"
• "Get inventory for location A1 in warehouse 2"
• "Show me all products that are low on stock"
• "Which products are at or below their reorder point?"
• "Show me inventory summary for all warehouses"
• "What products have zero quantity?"
• "List all inventory in warehouse 1, location B2"

📈 Analytics & Reports

• "Give me a product summary report"
• "Show product breakdown by brand"
• "How many active vs inactive products do I have?"
• "Show me inventory value by warehouse"
• "Which locations have the most inventory?"
• "Get product statistics including total value"
• "Show me products that need reordering"

➕ Add Inventory

• "Add 50 units of SKU ABC123 to warehouse 1, location A1"
• "Receive 100 units of SKU XYZ789 into warehouse 2"
• "Add inventory for SKU DEF456 with a note about the shipment"

➖ Remove Inventory

• "Remove 10 units of SKU ABC123 from warehouse 1, location A1"
• "Remove 5 units of SKU XYZ789 for order fulfillment"
• "Deduct inventory for damaged items"

🔧 Set Exact Quantities

• "Set the quantity of SKU ABC123 to exactly 100 units in warehouse 1"
• "Update SKU XYZ789 to have 0 units in location B2"
• "Correct the inventory count for SKU DEF456 to 75 units"

🏭 Warehouse Operations

• "List all warehouses"
• "Show me warehouse details"
• "Which warehouses do we have?"

🔍 Advanced Queries

• "Get the first 10 products"
• "Show me products on page 3 with 50 items per page"
• "Find all products and get complete details"
• "Check inventory across all locations for SKU ABC123"

💻 System Operations

• "Show cache statistics"
• "Clear the product cache"
• "Show current rate limits"
• "Clear all cached data"
• "Show queue statistics"

🌐 Generic API Access

• "Call the getSuppliers endpoint"
• "Use the getBrands API endpoint"
• "Call getSales endpoint with date range parameters"

📝 Natural Language Understanding

The MCP server understands natural variations of these questions:

• "What's in stock for ABC123?" → Gets inventory
• "I need to update prices for multiple products" → Batch update
• "Show me what needs to be reordered" → Low stock report
• "Fix the quantity for this SKU" → Set item quantity

🔒 Safety Features

All operations that modify data require explicit confirmation:

• Clear summary of what will be changed
• Visual warnings for destructive operations
• Explicit "yes" or "confirm" required to proceed

To bypass for automation, set confirm=True parameter.

🏗️ Architecture

skuvault-mcp-server/
├── src/
│   ├── server.py          # Main MCP server
│   ├── api_client.py      # SkuVault API client
│   ├── models/            # Pydantic models
│   ├── tools/             # Analytics tools
│   └── utils/             # Utilities (cache, rate limiter, validators)
├── api_schema_complete.json  # Complete API specification
├── pyproject.toml         # Package configuration
└── README.md              # This file

🧪 Testing

Run the test suite:

python test_server.py

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🔗 Resources

• SkuVault API Documentation
• Model Context Protocol
• Claude Desktop

⚡ Quick Start

1. Clone → 2. Install → 3. Configure → 4. Add to Claude Desktop → 5. Start using!

# Clone and install
git clone https://github.com/dbankscard/skuvault-mcp-server.git
cd skuvault-mcp-server
pip install -e .

# Configure
cp .env.example .env
# Add your tokens to .env

# Test
python test_server.py

# Add to Claude Desktop and start using!