npm package: @ludovicl33/cds-grc-mcp
Description: MCP server for simluated GRC operations into Agent IA
Author: Ludovic Lefebvre
Latest version: 1.4.0

# CDS GRC MCP Server

[![npm version](https://badge.fury.io/js/%40ludovicl33%2Fcds-grc-mcp.svg)](https://badge.fury.io/js/%40ludovicl33%2Fcds-grc-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that simulates e-commerce marketplace operations for GRC (Governance, Risk, and Compliance) testing and development purposes.

## 🚀 Features

### Seller Management
- **GetInfoSeller**: Retrieve detailed seller information including ratings, sales statistics, policies, and verification status

### Product Management
- **ProductList**: List products with advanced filtering, sorting, and pagination
- **ProductGet**: Get detailed product information by GTIN
- **ProductCount**: Count products matching specified filters
- **ProductGetVariants**: Retrieve product variants with pagination

### Order Management
- **OrderList**: List orders with filtering by status, sales channel, date range, and more
- **OrderGet**: Get detailed order information
- **OrderAcknowledge**: Acknowledge orders (global acceptance, not per line)
- **OrderShip**: Ship orders with tracking information
- **OrderCancel**: Cancel orders according to business rules

## 📋 Requirements

- Node.js 18+ 
- npm or yarn

## 🛠️ Installation

```bash
npm install @ludovicl33/cds-grc-mcp
```

## 🔧 Usage

### As a Library

```typescript
import { 
  getInfoSeller, 
  productList, 
  orderList,
  orderAcknowledge,
  generateSeller
} from '@ludovicl33/cds-grc-mcp';

// Get seller information
const sellerInfo = await getInfoSeller('oauth-token');

// List products
const products = await productList({ 
  limit: 10, 
  sortBy: 'updatedAt' 
});

// List orders
const orders = await orderList({ 
  filters: { status: 'pending' } 
});

// Acknowledge an order
const result = await orderAcknowledge({ orderId: 'ORD-001' });

// Generate a random seller (for testing)
const randomSeller = generateSeller();
```

### As an MCP Server

```bash
# Start the MCP server
npm start

# Or run directly
node build/index.js

# Or use the CLI command (after installation)
cds-grc-mcp
```

### As an MCP Server in LLMs

This package is designed to work with LLMs that support the Model Context Protocol (MCP). Here's how to integrate it:

#### **Claude Desktop/Anthropic**
1. Install the package globally: `npm install -g @ludovicl33/cds-grc-mcp`
2. In Claude, use the MCP integration to connect to the server
3. The server will be available as `cds-grc-mcp` command

#### **Other MCP Clients**
```bash
# Start the server
cds-grc-mcp

# Or with specific configuration
cds-grc-mcp --config mcp-config.json
```

#### **MCP Configuration Example**
```json
{
  "mcpServers": {
    "cds-grc-mcp": {
      "command": "cds-grc-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

## 🎯 MCP Tools Available

| Tool | Description | Parameters |
|------|-------------|------------|
| `GetInfoSeller` | Get seller information | `oauthToken` |
| `ProductList` | List products with filters | `filters`, `cursor`, `limit`, `sortBy`, `sortDir` |
| `ProductGet` | Get product by GTIN | `gtin` |
| `ProductCount` | Count products | `filters` |
| `ProductGetVariants` | Get product variants | `groupReference`, `cursor`, `limit` |
| `OrderList` | List orders with filters | `filters`, `cursor`, `limit`, `sortBy`, `sortDir` |
| `OrderGet` | Get order details | `orderId` |
| `OrderAcknowledge` | Acknowledge order | `orderId` |
| `OrderShip` | Ship order | `orderId`, `trackingNumber`, `carrier` |
| `OrderCancel` | Cancel order | `orderId`, `reason` |
| `CustomerComplaintsList` | List customer complaints | `filters`, `cursor`, `limit`, `sortBy`, `sortDir` |
| `RespondToComplaint` | Respond to customer complaint | `complaintId`, `responseContent`, `responderType` |

## 🔍 Data Structure

### Mock Data Included
- **Products**: 3 sample products with different visibility rules
- **Orders**: 4 sample orders in various states (pending, acknowledged, shipped, cancelled)
- **Customer Complaints**: 4 sample complaints with various statuses, priorities, and categories
- **Consistent relationships** between products, orders, and complaints

### Seller Distribution
- **Cdiscount**: 50% probability (marketplace owner)
- **Seller1, Seller2, Seller3, Seller4, Seller5**: 10% probability each (third-party sellers)
- **Distribution function**: `generateSeller()` provides realistic seller assignment

### Business Rules
- **Field visibility**: Products have different field access based on `createdBySeller` flag
- **Order workflow**: Strict state transitions (pending → acknowledged → shipped)
- **Complaint management**: Seller responses automatically close complaints, client responses keep them open
- **Validation**: Comprehensive input validation with meaningful error messages

### Customer Complaints Structure
Each complaint includes:
- **Basic info**: ID, discussion ID, order details, product information
- **Status**: `ouvert` (open) or `fermé` (closed)
- **Priority**: `basse`, `moyenne`, `haute`, or `critique`
- **Category**: `livraison`, `qualité`, `facturation`, or `autre`
- **Origin**: `vendeur` (seller) or `client` (customer)
- **Platform**: `Cdiscount`, `Amazon`, `Fnac`, or `Rakuten`
- **Timestamps**: Creation, update, and closure dates

## 🧪 Testing

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Build and test
npm run build && npm test
```

## 📦 Build

```bash
# Build the project
npm run build

# Build and start
npm run dev
```

## 🔐 Authentication

This is a **mock/simulation server**. All authentication is simulated and returns consistent test data. No real API keys or credentials are required.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 👨‍💻 Author

**Ludovic Lefebvre** - [@ludovicl33](https://github.com/ludovicl33)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📝 Changelog

### 1.4.0
- Added `RespondToComplaint` MCP tool for responding to customer complaints
- Automatic complaint closure when sellers respond
- Enhanced complaint management workflow
- Comprehensive test coverage for complaint responses

### 1.3.0
- Added customer complaints management system
- New `CustomerComplaintsList` MCP tool with filtering, sorting, and pagination
- Comprehensive complaint data structure including status, priority, category, and origin
- Mock data for 4 sample complaints with realistic scenarios
- Full test coverage for complaints functionality

### 1.2.0
- Added seller field to products and orders
- Implemented `generateSeller()` function with realistic probability distribution
- Cdiscount: 50% probability, other sellers: 10% each
- Enhanced data consistency between products and orders

### 1.0.0
- Initial release
- Complete MCP server implementation
- Mock e-commerce marketplace operations
- Comprehensive test coverage
- TypeScript support with ES modules
- CLI executable support for LLM integration

## 🔗 Related Links

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)
- [CDiscount API Documentation](https://developer.octopia-io.net/)

---

**Note**: This package is designed for testing, development, and educational purposes. It provides realistic mock data and behavior for e-commerce operations without requiring actual marketplace integrations.