ConsignCloud MCP Server

# ConsignCloud MCP Server - Project Summary ## 🎯 Project Overview A complete Model Context Protocol (MCP) server implementation for the ConsignCloud API, enabling AI assistants like Claude to manage inventory, sales, accounts, and operations for consignment/retail businesses. ## ✅ What's Been Built ### Core Components 1. **TypeScript Client Library** ([src/client.ts](src/client.ts)) - Full ConsignCloud API client with 30+ methods - Type-safe with comprehensive TypeScript definitions - Error handling and request interceptors - Support for all inventory management operations 2. **MCP Server Implementation** ([src/server.ts](src/server.ts)) - 22 MCP tools covering all major operations - Proper JSON-RPC request/response handling - Centralized tool definitions and handlers 3. **Dual Transport Support** - **STDIO Mode** ([src/index.ts](src/index.ts)) - For Claude Desktop integration - **HTTP/SSE Mode** ([src/http-server.ts](src/http-server.ts)) - For MCP Inspector and web testing ### API Coverage ✅ **Inventory Management** (Focus Area) - List items with advanced filtering (price, category, status, location, date) - Create, read, update, delete items - Bulk operations and status updates - Inventory statistics and analytics ✅ **Sales Operations** - List and filter sales by date, location, customer, status - Get sale details - Void and refund sales - Sales trends and reporting ✅ **Account Management** (Vendors/Consignors) - Full CRUD operations - Account statistics (balance, items, purchases) - Bulk account operations ✅ **Additional Features** - Item categories management - Store locations - Batch operations (groups of items) - Cross-entity search and suggestions - Balance entries tracking ❌ **Explicitly Excluded** (as requested) - Company registration and management ### Documentation 1. **[README.md](README.md)** - Main documentation - Installation and setup - Usage for both modes - Claude Desktop integration - Available tools reference 2. **[QUICK_START.md](QUICK_START.md)** - Get started in 5 minutes - Fast setup guide - Common commands - Quick troubleshooting 3. **[TESTING.md](TESTING.md)** - MCP Inspector testing guide - Step-by-step Inspector setup - Test scenarios with examples - Debugging tips - Common issues and solutions 4. **[CLAUDE_DESKTOP_SETUP.md](CLAUDE_DESKTOP_SETUP.md)** - Claude integration - Detailed configuration guide - Platform-specific instructions - Example prompts - Advanced configuration 5. **[CONSIGNCLOUD_API_SUMMARY.md](CONSIGNCLOUD_API_SUMMARY.md)** - API reference - Complete API endpoint documentation - Authentication details - Data models - Rate limits and pagination ## 📁 Project Structure ``` mcp-consigncloud/ ├── src/ │ ├── client.ts # ConsignCloud API client │ ├── server.ts # MCP server setup & tools │ ├── index.ts # STDIO transport (Claude Desktop) │ ├── http-server.ts # HTTP/SSE transport (Inspector) │ └── types.ts # TypeScript type definitions ├── dist/ # Compiled JavaScript (gitignored) ├── .env.example # Environment template ├── .gitignore # Git ignore rules ├── package.json # Dependencies & scripts ├── tsconfig.json # TypeScript config ├── README.md # Main documentation ├── QUICK_START.md # Quick setup guide ├── TESTING.md # Testing guide ├── CLAUDE_DESKTOP_SETUP.md # Claude integration ├── CONSIGNCLOUD_API_SUMMARY.md # API reference └── PROJECT_SUMMARY.md # This file ``` ## 🚀 Available Tools (22 Total) ### Inventory (6 tools) - `list_items` - List with filters - `get_item` - Get by ID - `create_item` - Create new - `update_item` - Update existing - `delete_item` - Soft delete - `get_item_stats` - Statistics ### Sales (4 tools) - `list_sales` - List with filters - `get_sale` - Get by ID - `void_sale` - Void a sale - `get_sales_trends` - Analytics ### Accounts (5 tools) - `list_accounts` - List vendors/consignors - `get_account` - Get by ID - `create_account` - Create new - `update_account` - Update existing - `get_account_stats` - Account statistics ### Categories (2 tools) - `list_categories` - List item categories - `create_category` - Create new category ### Locations (1 tool) - `list_locations` - List store locations ### Batches (3 tools) - `list_batches` - List item batches - `create_batch` - Create new batch - `update_batch_status` - Update status ### Search (1 tool) - `search_suggest` - Cross-entity search ## 🔧 NPM Scripts ```bash # Development npm run dev # Run STDIO server in dev mode npm run dev:http # Run HTTP/SSE server in dev mode # Production npm run build # Compile TypeScript to JavaScript npm start # Run STDIO server (production) npm run start:http # Run HTTP/SSE server (production) # Utilities npm run watch # Watch mode for TypeScript compilation ``` ## 🔐 Environment Variables ```env # Required CONSIGNCLOUD_API_KEY=your_api_key_here # Optional CONSIGNCLOUD_API_BASE_URL=https://api.consigncloud.com/api/v1 # Default PORT=3000 # HTTP mode only HOST=localhost # HTTP mode only ``` ## 📊 Technology Stack - **Runtime:** Node.js 18+ - **Language:** TypeScript 5.9 - **MCP SDK:** @modelcontextprotocol/sdk ^1.22.0 - **HTTP Server:** Express 5.1 - **HTTP Client:** Axios 1.13 - **Environment:** dotenv 17.2 ## 🎓 How to Use ### With MCP Inspector (Testing) ```bash # Terminal 1: Start server npm run dev:http # Terminal 2: Launch inspector npx @modelcontextprotocol/inspector http://localhost:3000/sse ``` ### With Claude Desktop (Production) Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "consigncloud": { "command": "node", "args": ["/absolute/path/to/mcp-consigncloud/dist/index.js"], "env": { "CONSIGNCLOUD_API_KEY": "your_api_key_here" } } } } ``` ## 💡 Example Use Cases ### Inventory Management - "Show me all items under $50" - "List items in the Clothing category" - "What's my current inventory value?" - "Create a new item: Vintage Lamp, $75" ### Sales Analysis - "Show me sales from last week" - "What are the sales trends for November?" - "Get details for sale #12345" ### Vendor Management - "List all vendor accounts" - "Show me John Smith's account balance" - "Create a new vendor account" - "What are the top 5 vendors by sales?" ### Operations - "Find items that haven't sold in 30 days" - "Show me all draft batches" - "Search for 'vintage' items" ## 🔒 Security Features - ✅ API keys stored in environment variables (never in code) - ✅ `.env` file excluded from git - ✅ CORS enabled for HTTP server - ✅ Bearer token authentication - ✅ Error messages sanitized ## 📈 API Characteristics - **Base URL:** `https://api.consigncloud.com/api/v1` - **Authentication:** Bearer token (API key) - **Rate Limit:** 100 requests bucket, 10/sec refill - **Pagination:** Cursor-based - **Currency:** Smallest denomination (cents for USD) - **Date Format:** ISO 8601 ## ✨ Key Features 1. **Type Safety** - Full TypeScript coverage with proper types 2. **Error Handling** - Comprehensive error catching and user-friendly messages 3. **Dual Transport** - Both STDIO and HTTP/SSE support 4. **Developer Experience** - Hot reload in dev mode, built for production 5. **Testing Support** - MCP Inspector integration out of the box 6. **Documentation** - 5 comprehensive documentation files 7. **Modular Design** - Separated concerns (client, server, transports) ## 🎯 Project Goals Achieved ✅ Learn about ConsignCloud API structure ✅ Create Node.js MCP server ✅ Handle products, prices, sales (inventory management focus) ✅ Exclude company registration ✅ Use environment variables for secrets ✅ Support HTTP/SSE for testing ✅ Provide comprehensive documentation ✅ Enable MCP Inspector testing ## 🔄 Next Steps (Optional Enhancements) - [ ] Add webhook support for real-time updates - [ ] Implement caching for frequently accessed data - [ ] Add custom reporting tools - [ ] Support bulk import/export operations - [ ] Add data validation schemas - [ ] Implement retry logic for failed requests - [ ] Add monitoring and logging capabilities - [ ] Create integration tests ## 📞 Support Resources - **ConsignCloud API:** team@consigncloud.com - **MCP Documentation:** https://modelcontextprotocol.io - **MCP Inspector:** https://modelcontextprotocol.io/docs/tools/inspector - **Claude Desktop:** https://support.anthropic.com ## 📝 License ISC License --- **Status:** ✅ Complete and ready for use **Last Updated:** 2025-01-22 **Version:** 1.0.0