adilzafarr/sioms-mcp

SIOMS MCP Server

A Model Context Protocol (MCP) server for the Smart Inventory and Order Management System (SIOMS), providing comprehensive inventory management tools for AI assistants.

Overview

This MCP server enables AI assistants to interact with your SIOMS API to perform advanced inventory management operations. It provides 15+ powerful tools for checking stock levels, managing inventory, analyzing warehouse performance, and maintaining product catalogs.

Features

🏪 Core Inventory Management

• Real-time stock checking across all warehouses
• Low stock alerts with reorder recommendations
• Comprehensive inventory reports with analytics
• Cross-warehouse stock visibility

📦 Stock Management Operations

• Add stock to warehouses with validation
• Remove stock with safety checks
• Update stock to exact quantities
• Bulk operations support

📋 Product Management

• Product catalog browsing with filtering
• Detailed product analysis including stock distribution
• New product creation with validation
• Price categorization and analytics

🏬 Warehouse Analytics

• Warehouse performance metrics
• Health scoring system (0-100 scale)
• Distribution analysis across locations
• Actionable recommendations

Installation & Setup

1. Prerequisites

• .NET 9.0 SDK
• Running SIOMS API instance
• Valid SIOMS user credentials

2. Configure the Server

Edit with your SIOMS API details:

{
  "SiomsApi": {
    "BaseUrl": "http://localhost:5000",
    "Username": "your_username",
    "Password": "your_password",
    "TokenRefreshMinutes": 50,
    "TimeoutSeconds": 30
  }
}

3. Build and Run

# Navigate to the project directory
cd sioms-mcp

# Restore dependencies
dotnet restore

# Build the project
dotnet build

# Run the MCP server
dotnet run

Available MCP Tools

🔍 Inventory Tools

Get complete inventory for a specific warehouse with detailed analysis.

Parameters:

• warehouseId (int): Warehouse ID to check
• includeDetails (bool): Include detailed product information

Example Response:

{
  "WarehouseId": 1,
  "TotalItems": 150,
  "TotalValue": 45750.50,
  "LowStockItems": 12,
  "Summary": {
    "InStock": 138,
    "OutOfStock": 12,
    "NeedsReorder": 12
  }
}

Check stock levels for a product across all warehouses.

Parameters:

• productId (int): Product ID to check

Find products below reorder levels with reorder suggestions.

Parameters:

• warehouseId (int): Warehouse to check

Get total stock for a product across all warehouses.

Parameters:

• productId (int): Product ID

⚡ Stock Management Tools

Add inventory to a warehouse with validation and reporting.

Parameters:

• warehouseId (int): Target warehouse
• productId (int): Product to add stock for
• quantity (int): Quantity to add (must be positive)

Remove inventory with safety checks and low stock warnings.

Parameters:

• warehouseId (int): Source warehouse
• productId (int): Product to remove stock for
• quantity (int): Quantity to remove

Set exact stock quantity with change tracking.

Parameters:

• warehouseId (int): Target warehouse
• productId (int): Product to update
• newQuantity (int): New exact quantity

📋 Product Management Tools

Get all products with optional stock information and analytics.

Parameters:

• includeStockInfo (bool): Include real-time stock levels

Get comprehensive product information including distribution analysis.

Parameters:

• productId (int): Product ID for details

Create new products with validation and setup guidance.

Parameters:

• name (string): Product name
• sku (string): Unique SKU
• price (decimal): Product price
• reorderLevel (int): Minimum stock level (default: 10)

🏬 Warehouse Management Tools

Get all warehouses with inventory summaries and status analysis.

Parameters:

• includeInventorySummary (bool): Include detailed inventory data

Get comprehensive warehouse analysis with health scoring and recommendations.

Parameters:

• warehouseId (int): Warehouse ID for detailed analysis

Architecture

Project Structure

sioms-mcp/
├── src/
│   ├── Models/           # Data models matching SIOMS API
│   ├── Services/         # Business logic and API communication
│   ├── Tools/            # MCP tool implementations
│   ├── Constants/        # API endpoints and configuration
│   └── Extensions/       # Service registration extensions
├── appsettings.json      # Configuration file
├── Program.cs           # Application entry point
└── README.md           # This documentation

Key Components

HTTP client wrapper for SIOMS API communication with:

• Automatic authentication handling
• Request/response logging
• Error handling and retry logic
• JSON serialization

JWT token management with:

• Automatic token refresh
• Thread-safe operations
• Token validation
• Credential management

Tool Classes

• : Stock checking and inventory analysis
• : Stock modification operations
• : Product catalog management
• : Warehouse analytics and management

Configuration Options

Error Handling

The MCP server includes comprehensive error handling:

• Authentication Errors: Automatic retry with credential validation
• Network Issues: Timeout handling and connection retries
• API Errors: Detailed error messages with context
• Validation Errors: Input validation with helpful messages
• Logging: Structured logging to stderr for MCP compatibility

Security Features

• Secure credential storage in configuration
• JWT token auto-refresh before expiration
• Input validation on all parameters
• API rate limiting respect
• Connection security with HTTPS support

Performance Optimizations

• HTTP connection pooling for API calls
• Async/await throughout for scalability
• Efficient JSON serialization with Newtonsoft.Json
• Smart caching for authentication tokens
• Parallel operations where beneficial

Troubleshooting

Common Issues

❌ "Configuration validation failed"

• Ensure appsettings.json contains valid SIOMS API settings
• Verify SIOMS API is running and accessible
• Check username/password credentials

❌ "Failed to authenticate with SIOMS API"

• Verify credentials in appsettings.json
• Check SIOMS API is accessible from MCP server
• Ensure user has required permissions (Admin/Manager roles for most operations)

❌ "Network error" or timeout issues

• Verify SiomsApi:BaseUrl is correct
• Check network connectivity to SIOMS API
• Increase SiomsApi:TimeoutSeconds if needed

Debug Mode

Enable detailed logging by setting log level to Debug in appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "sioms_mcp": "Debug"
    }
  }
}

Usage Examples

Checking Warehouse Inventory

Please check the inventory for warehouse 1 with detailed product information

Managing Stock Levels

Add 100 units of product 5 to warehouse 2

Product Analysis

Show me detailed information for product 10 including stock distribution

Low Stock Monitoring

Check for low stock items in warehouse 3 and provide reorder recommendations

Dependencies

• Microsoft.Extensions.Hosting (9.0.8) - Application hosting
• ModelContextProtocol (0.3.0-preview.4) - MCP server framework
• Microsoft.Extensions.Http (9.0.8) - HTTP client factory
• Newtonsoft.Json (13.0.3) - JSON serialization
• System.IdentityModel.Tokens.Jwt (8.2.1) - JWT token handling

License

This project is part of the SIOMS ecosystem. Please refer to your SIOMS license agreement.

Support

For support with the SIOMS MCP Server:

1. Check the troubleshooting section above
2. Review the SIOMS API documentation
3. Verify your SIOMS API is running correctly
4. Check the application logs for detailed error information

🚀 Ready to enhance your inventory management with AI-powered tools!