README.md•10.3 kB
# CS-Cart MCP Server
A Model Context Protocol (MCP) server that provides comprehensive tools for managing CS-Cart e-commerce stores, including product management, order handling, and sales analytics.
## Features
### Product Management
- **get_products**: Retrieve product listings with filtering and pagination
- **get_product**: Get detailed product information
- **create_product**: Add new products to the store
- **update_product**: Modify existing product details
- **delete_product**: Remove products from the store
- **update_product_stock**: Update product inventory levels
### Order Management
- **get_orders**: Retrieve order listings with various filters
- **get_order**: Get detailed order information
- **update_order_status**: Change order status and notify customers
### Category Management
- **get_categories**: Retrieve product categories and subcategories
### User Management
- **get_users**: Get customer and user information
### Analytics
- **get_sales_statistics**: Retrieve sales data and statistics
## Installation
### Option 1: Quick Setup (Recommended)
1. Clone this repository:
```bash
git clone <repository-url>
cd cscart-mcp-server
```
2. Run the setup script:
```bash
npm run setup
```
3. Install dependencies:
```bash
npm install
```
4. Update `.env` with your CS-Cart credentials and start:
```bash
npm start
```
### Option 2: Manual Local Installation
1. Clone this repository:
```bash
git clone <repository-url>
cd cscart-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Configure environment variables:
```bash
cp .env.example .env
```
Edit `.env` with your CS-Cart API credentials:
```bash
CSCART_API_URL=https://your-store.com/api
CSCART_API_EMAIL=admin@yourstore.com
CSCART_API_KEY=your-api-key-here
```
### Option 2: Docker Installation
1. Clone this repository:
```bash
git clone <repository-url>
cd cscart-mcp-server
```
2. Configure environment variables:
```bash
cp .env.example .env
```
3. Build and run with Docker Compose:
```bash
docker-compose up -d
```
Or build and run with Docker:
```bash
# Build the image
docker build -t cscart-mcp-server .
# Run the container
docker run -d \
--name cscart-mcp-server \
--env-file .env \
cscart-mcp-server
```
### Option 3: Production Docker Build
For production deployment with optimized image:
```bash
# Build production image
docker build -f Dockerfile.production -t cscart-mcp-server:prod .
# Run production container
docker run -d \
--name cscart-mcp-server-prod \
--env-file .env \
--restart unless-stopped \
cscart-mcp-server:prod
```
## CS-Cart API Setup
1. **Enable API Access**:
- Log into your CS-Cart admin panel
- Go to **Administration → API access**
- Enable API access for your store
2. **Generate API Key**:
- Create a new API key or use existing one
- Note the API key and admin email for configuration
3. **API Permissions**:
- Ensure the API user has appropriate permissions for:
- Products (read/write)
- Orders (read/write)
- Categories (read)
- Users (read)
- Statistics (read)
## Usage
### Running the Server
#### Quick Commands
```bash
# Setup project
npm run setup
# Development
npm run dev
# Production
npm start
# Docker commands
npm run docker:build # Build standard image
npm run docker:build:prod # Build production image
npm run docker:run # Start with docker-compose
npm run docker:stop # Stop docker-compose
npm run docker:logs # View logs
```
#### Docker Deployment
Start with Docker Compose:
```bash
docker-compose up -d
```
View logs:
```bash
docker-compose logs -f cscart-mcp-server
```
Stop the service:
```bash
docker-compose down
```
#### Production Deployment
For production use the optimized Dockerfile:
```bash
docker build -f Dockerfile.production -t cscart-mcp-server:latest .
docker run -d \
--name cscart-mcp-prod \
--env-file .env \
--restart unless-stopped \
--memory=512m \
--cpus=0.5 \
cscart-mcp-server:latest
```
### Integration with MCP Clients
Add this server to your MCP client configuration. For example, with Claude Desktop:
```json
{
"mcpServers": {
"cscart": {
"command": "node",
"args": ["/path/to/cscart-mcp-server/src/index.js"],
"env": {
"CSCART_API_URL": "https://your-store.com/api",
"CSCART_API_EMAIL": "admin@yourstore.com",
"CSCART_API_KEY": "your-api-key-here"
}
}
}
}
```
**Note**: Use the full path to the `node` executable. Common paths:
- **macOS**: `/usr/local/bin/node` or `/opt/homebrew/bin/node`
- **Linux**: `/usr/bin/node` or `/usr/local/bin/node`
- **Windows**: `C:\\Program Files\\nodejs\\node.exe`
### Integration with AnythingLLM
To integrate this MCP server with AnythingLLM:
1. **Navigate to AnythingLLM Settings**:
- Open your AnythingLLM instance
- Go to **Settings** → **Integrations** → **MCP Servers**
2. **Add the CS-Cart MCP Server**:
```json
{
"command": "/usr/local/bin/node",
"args": ["/full/path/to/cscart-mcp-server/src/index.js"],
"env": {
"CSCART_API_URL": "https://your-store.com/api",
"CSCART_API_EMAIL": "admin@yourstore.com",
"CSCART_API_KEY": "your-api-key-here"
}
}
```
3. **Important Path Notes**:
- Use the **full absolute path** to the `node` executable
- Use the **full absolute path** to the `src/index.js` file
- Ensure the paths are accessible from the AnythingLLM container/environment
4. **Example for macOS**:
```json
{
"command": "/usr/local/bin/node",
"args": ["/Users/username/GitHub/cscart-mcp/src/index.js"],
"env": {
"CSCART_API_URL": "https://your-store.com/api",
"CSCART_API_EMAIL": "admin@yourstore.com",
"CSCART_API_KEY": "your-api-key-here"
}
}
```
5. **Docker Integration** (if AnythingLLM is running in Docker):
- Mount the CS-Cart MCP server directory as a volume
- Use the container path in the configuration
- Ensure proper file permissions
6. **Test the Integration**:
- Restart AnythingLLM after adding the MCP server
- Check the logs for any connection errors
- Try using CS-Cart tools in your conversations
## Available Tools
### Product Tools
#### get_products
Retrieve a list of products with optional filtering:
```json
{
"page": 1,
"items_per_page": 10,
"status": "A",
"category_id": 123,
"q": "search term"
}
```
#### create_product
Create a new product:
```json
{
"product": "Product Name",
"price": 29.99,
"category_ids": [123, 456],
"description": "Short description",
"full_description": "Full product description",
"status": "A",
"amount": 100
}
```
### Order Tools
#### get_orders
Retrieve orders with filtering:
```json
{
"page": 1,
"items_per_page": 10,
"status": "P",
"period": "M",
"user_id": 123
}
```
#### update_order_status
Update order status:
```json
{
"order_id": 12345,
"status": "C",
"notify_user": true
}
```
### Status Codes
**Product Status:**
- `A` - Active
- `D` - Disabled
- `H` - Hidden
**Order Status:**
- `O` - Open
- `P` - Processed
- `C` - Complete
- `F` - Failed
- `D` - Declined
- `B` - Backordered
- `I` - Incomplete
**User Status:**
- `A` - Active
- `D` - Disabled
**User Types:**
- `A` - Admin
- `V` - Vendor
- `C` - Customer
## Error Handling
The server includes comprehensive error handling:
- API connection errors
- Invalid parameters
- Missing required fields
- CS-Cart API errors
All errors are returned with descriptive messages to help with debugging.
## Docker Configuration
### Environment Variables
When using Docker, you can set environment variables in several ways:
1. **Using .env file** (recommended):
```bash
CSCART_API_URL=https://your-store.com/api
CSCART_API_EMAIL=admin@yourstore.com
CSCART_API_KEY=your-api-key-here
LOG_LEVEL=info
```
2. **Using docker-compose.yml**:
```yaml
environment:
- CSCART_API_URL=https://your-store.com/api
- CSCART_API_EMAIL=admin@yourstore.com
- CSCART_API_KEY=your-api-key-here
```
3. **Using Docker run command**:
```bash
docker run -d \
-e CSCART_API_URL=https://your-store.com/api \
-e CSCART_API_EMAIL=admin@yourstore.com \
-e CSCART_API_KEY=your-api-key-here \
cscart-mcp-server
```
### Docker Images
- **Dockerfile**: Standard development image (~200MB)
- **Dockerfile.production**: Optimized production image (~150MB)
- Multi-stage build for smaller size
- Non-root user for security
- Proper signal handling with dumb-init
- Health checks included
### Resource Limits
The docker-compose.yml includes resource limits:
- CPU: 0.5 cores max, 0.25 cores reserved
- Memory: 512MB max, 256MB reserved
Adjust these based on your server capacity and usage requirements.
### Project Structure
```
cscart-mcp-server/
├── src/
│ └── index.js # Main server file (moved here)
├── scripts/
│ └── setup.js # Setup automation script
├── logs/ # Log files directory
├── tests/ # Test files directory
├── config/ # Configuration files
├── package.json # Updated paths
├── project.config.js # Project configuration
├── Dockerfile # Updated for new structure
├── Dockerfile.production # Updated for new structure
├── docker-compose.yml # Docker orchestration
├── .env.example # Environment template
└── README.md # Updated documentation
```
### Adding New Tools
To add new tools, extend the `ListToolsRequestSchema` handler and add corresponding methods to the `CSCartMCPServer` class.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For issues related to:
- **CS-Cart API**: Check CS-Cart documentation or support
- **MCP Protocol**: Refer to MCP documentation
- **This Server**: Open an issue in this repository
## Changelog
### v0.1.0
- Initial release
- Basic product management tools
- Order management functionality
- Category and user tools
- Sales statistics support