# Labamu MCP Server

A secure, production-ready Model Context Protocol (MCP) server that provides Claude Desktop with access to Labamu's business APIs for material inventory management, vendor management, batch tracking, customer data, and invoice operations.

[![Version](https://img.shields.io/badge/version-2.9.0-blue.svg)](./package.json)
[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
[![Security](https://img.shields.io/badge/Security-Hardened-green.svg)](./SECURITY.md)

## Overview

The Labamu MCP Server enables AI assistants like Claude to securely interact with Labamu's Material Resource Planning (MRP) and business APIs through the Model Context Protocol. Built on Cloudflare Workers for global edge deployment with enterprise-grade security.

### Key Features

- **🔒 Security First**: JWT authentication, input validation, sanitized logging
- **⚡ High Performance**: Global edge deployment, <100ms response times
- **🔧 Developer Friendly**: Clean architecture, comprehensive documentation
- **📊 Production Ready**: Monitoring, error handling, feature flags
- **🚀 Scalable**: Serverless architecture with automatic scaling

## Quick Start

### Prerequisites

- Node.js 18+
- Cloudflare account
- Labamu API credentials
- Claude Desktop

### 1. Installation

```bash
git clone https://github.com/your-org/labamu-mcp
cd labamu-mcp
npm install
```

### 2. Deployment

```bash
# Build and deploy to Cloudflare Workers
npm run build
npm run deploy
```

### 3. Configuration

Copy the template and configure your Claude Desktop:

```bash
cp claude-desktop-config-template.json claude-desktop-config.json
# Edit claude-desktop-config.json with your JWT token
```

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "labamu": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://labamu-mcp.your-subdomain.workers.dev/sse",
        "--header",
        "Authorization:Bearer ${LABAMU_API_KEY}"
      ],
      "env": {
        "LABAMU_API_KEY": "your-jwt-token-here"
      }
    }
  }
}
```

## Available Tools

### Material Management

| Tool | Description | Status |
|------|-------------|--------|
| `get_materials` | List materials with filtering and pagination | ✅ Active |
| `get_material_by_id` | Retrieve specific material by UUID | ✅ Active |
| `update_material` | Update material properties | ✅ Active |
| `delete_material` | Remove material from inventory | ✅ Active |
| `bulk_create_materials` | Create multiple materials from CSV/JSON | ✅ Active |

### Vendor Management

| Tool | Description | Status |
|------|-------------|--------|
| `get_vendors` | List vendors with filtering and pagination | ✅ Active |
| `bulk_create_vendors` | Create multiple vendors in bulk | ✅ Active |
| `bulk_delete_vendors` | Delete multiple vendors by IDs | ✅ Active |
| `update_vendor` | Update vendor information | ✅ Active |

### Batch Management

| Tool | Description | Status |
|------|-------------|--------|
| `get_batches` | List material batches with filtering | ✅ Active |
| `bulk_create_batches` | Create multiple batches with vendor tracking | ✅ Active |
| `bulk_update_batches` | Update multiple batches (partial updates) | ✅ Active |
| `bulk_delete_batches` | Delete batches by IDs | ✅ Active |

### Product Management

| Tool | Description | Status |
|------|-------------|--------|
| `get_products` | List products with category, BOM, and pricing | ✅ Active |
| `create_product` | Create new product with pricing and category | ✅ Active |
| `bulk_create_products` | Create multiple products in bulk | ✅ Active |
| `get_products_with_bom` | List products that have BOMs attached | ✅ Active |
| `get_product_by_id` | Get product details by UUID | ✅ Active |
| `update_product` | Update product information | ✅ Active |
| `delete_product` | Delete product by ID | ✅ Active |
| `get_categories` | List product categories | ✅ Active |
| `create_category` | Create new category | ✅ Active |
| `get_category_by_id` | Get category details by UUID | ✅ Active |
| `update_category` | Update category information | ✅ Active |
| `delete_category` | Delete category by ID | ✅ Active |
| `get_boms` | List Bills of Materials with routing and costs | ✅ Active |
| `create_bom` | Create new BOM with materials and routing | ✅ Active |
| `get_bom_cogs_breakdown` | Get COGS breakdown for a BOM | ✅ Active |
| `get_bom_suggested_price` | Get suggested pricing from BOM costs | ✅ Active |
| `get_bom_by_id` | Get BOM details by UUID | ✅ Active |
| `update_bom` | Update BOM information | ✅ Active |
| `delete_bom` | Delete BOM by ID | ✅ Active |
| `check_bom_usage` | Check if BOM is used in products | ✅ Active |
| `get_material_usages` | List material usages with filtering | ✅ Active |
| `create_material_usage` | Create material usage for BOM | ✅ Active |
| `bulk_create_material_usages` | Create multiple material usages | ✅ Active |
| `get_material_usage_by_id` | Get material usage by UUID | ✅ Active |
| `update_material_usage` | Update material usage | ✅ Active |
| `delete_material_usage` | Delete material usage by ID | ✅ Active |

### Legacy Tools (Disabled)

| Tool | Description | Status |
|------|-------------|--------|
| `get_merchant` | Fetch merchant profile | 🚫 Disabled |
| `list_customers` | List customer data | 🚫 Disabled |
| `create_invoice` | Generate invoices | 🚫 Disabled |
| `search` | General search functionality | 🚫 Disabled |
| `fetch` | HTTP fetch utility | 🚫 Disabled |

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude        │    │   MCP Server    │    │   Labamu APIs   │
│   Desktop       │◄──►│  (CF Workers)   │◄──►│   (MRP/Business)│
│                 │    │                 │    │                 │
│ - Authentication│    │ - Validation    │    │ - Business Logic│
│ - Tool Calls    │    │ - Security      │    │ - Data Storage  │
│ - Responses     │    │ - Logging       │    │ - Processing    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### Security Model

- **Client-side Authentication**: JWT tokens stored securely in Claude Desktop
- **Header-based Transport**: Secure token transmission via Authorization headers
- **Input Validation**: Comprehensive schema validation for all inputs
- **Sanitized Logging**: Sensitive data automatically redacted
- **CORS Protection**: Restrictive cross-origin resource sharing

## Development

### Local Development

```bash
# Start development server
npm run dev

# Run tests
npm run test

# Watch mode
npm run test:watch

# Type checking
npm run build
```

### Project Structure

```
src/
├── config/           # Security and configuration
├── core/             # Base classes and MCP server
├── tools/            # Tool implementations
│   └── materials/    # Material management tools
├── types/            # TypeScript definitions
├── utils/            # Shared utilities
└── index.ts         # Worker entry point
```

### Adding New Tools

1. Create tool class extending `BaseTool`
2. Add to tool registry in server
3. Configure feature flag in `wrangler.toml`
4. Write comprehensive tests
5. Update documentation

See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed guidelines.

## Security

### Authentication Flow

1. JWT token stored in Claude Desktop environment variables
2. Token transmitted via `Authorization: Bearer` header
3. Server validates JWT format and structure
4. Token forwarded to upstream Labamu APIs
5. Response data sanitized before logging

### Security Features

- JWT format validation
- Input schema validation
- Request sanitization
- Error message sanitization
- Security headers on all responses
- No sensitive data logging

See [SECURITY.md](./SECURITY.md) for comprehensive security documentation.

## Configuration

### Feature Flags

Tools can be enabled/disabled via environment variables:

```toml
# wrangler.toml
FEATURE_GET_MATERIALS_ENABLED = "true"
FEATURE_UPDATE_MATERIAL_ENABLED = "true"
FEATURE_DELETE_MATERIAL_ENABLED = "true"
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `LABAMU_MRP_API_BASE` | MRP API base URL | `https://mrp-api-dev.cashenable.com` |
| `LABAMU_API_BASE` | Business API base URL | `https://openapi-stg.cashenable.com` |

## Monitoring

### Health Check

```bash
curl https://labamu-mcp.your-subdomain.workers.dev/healthz
```

Returns server status and enabled tools:

```json
{
  "status": "ok",
  "version": "2.4.0",
  "timestamp": "2025-09-30T12:00:00.000Z",
  "tools": ["get_materials", "get_material_by_id", "update_material", "delete_material", "bulk_create_materials"],
  "auth_mode": "client_provided"
}
```

### Logging

```bash
# Monitor live logs
wrangler tail --format pretty

# Filter specific events
wrangler tail | grep ERROR
```

## Testing

### Test Coverage

- **Unit Tests**: Tool logic and validation
- **Integration Tests**: End-to-end MCP protocol
- **Security Tests**: Authentication and input validation

```bash
# Run all tests
npm test

# Coverage report
npm run test:coverage
```

## API Reference

### Material Management

#### Get Materials

```json
{
  "tool": "get_materials",
  "arguments": {
    "page": 1,
    "size": 10,
    "category_id": "uuid",
    "sku": "MAT-001",
    "name": "Steel Rod",
    "classification": "A",
    "type": "RAW",
    "is_stockable": true,
    "keyword": "search term"
  }
}
```

#### Get Material by ID

```json
{
  "tool": "get_material_by_id",
  "arguments": {
    "id": "20858588-ef10-4629-b01c-5b3fa6bfef6d"
  }
}
```

#### Update Material

```json
{
  "tool": "update_material",
  "arguments": {
    "id": "20858588-ef10-4629-b01c-5b3fa6bfef6d",
    "name": "Updated Steel Rod",
    "classification": "A",
    "status": "ACTIVE"
  }
}
```

### Product Management

#### Get Products

```json
{
  "tool": "get_products",
  "arguments": {
    "page": 1,
    "size": 10,
    "name": "Meja",
    "sku": "PROD-001",
    "category_id": "uuid",
    "status": "ACTIVE",
    "keyword": "furniture",
    "sort": "updated_at:desc"
  }
}
```

#### Get Categories

```json
{
  "tool": "get_categories",
  "arguments": {
    "page": 1,
    "size": 10,
    "name": "Rak Besi",
    "status": "ACTIVE",
    "keyword": "metal",
    "sort": "name:asc"
  }
}
```

#### Get BOMs

```json
{
  "tool": "get_boms",
  "arguments": {
    "page": 1,
    "size": 10,
    "name": "Pembuatan",
    "product_id": "uuid",
    "status": "ACTIVE",
    "without_product": false,
    "sort": "created_at:desc"
  }
}
```

See individual tool files for complete API documentation.

## Troubleshooting

### Common Issues

#### Authentication Errors

```
Failed to retrieve materials: Invalid token provided
```

**Solution**: Verify JWT token format and expiration in Claude Desktop config.

#### Tool Not Available

```
Unknown tool: get_materials
```

**Solution**: Check feature flag is enabled in `wrangler.toml`.

#### CORS Errors

**Solution**: Ensure requests include proper headers and origin.

### Debug Mode

Enable detailed logging by checking Cloudflare Workers logs:

```bash
wrangler tail --format pretty
```

## Contributing

We welcome contributions! Please see our [DEVELOPMENT.md](./DEVELOPMENT.md) guide for:

- Development setup
- Coding standards
- Testing requirements
- Security guidelines

### Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Implement changes with tests
4. Update documentation
5. Submit pull request

## Documentation

- [Architecture Guide](./ARCHITECTURE.md) - System design and patterns
- [Development Guide](./DEVELOPMENT.md) - Development setup and guidelines
- [Security Guide](./SECURITY.md) - Security practices and procedures
- [Feature Flags](./FEATURE_FLAGS.md) - Feature flag documentation

## Deployment

### Production Checklist

- [ ] All tests passing
- [ ] TypeScript compilation successful
- [ ] Feature flags configured
- [ ] Health endpoint accessible
- [ ] Claude Desktop configuration updated
- [ ] Security review completed

### Rollback Procedure

```bash
# Quick feature disable
# Set feature flag to "false" in wrangler.toml
npm run deploy

# Full rollback
git revert HEAD
npm run deploy
```

## License

This project is licensed under the ISC License - see the [LICENSE](./LICENSE) file for details.

## Support

For issues and questions:

1. Check [troubleshooting section](#troubleshooting)
2. Review [security guidelines](./SECURITY.md)
3. Open an issue with detailed information

## Changelog

### v2.9.0 (Current)
- **Major Release**: Added 23 new product management tools (CRUD operations)
- **Products**: Full CRUD + bulk operations + BOM-filtered queries
- **Categories**: Complete category management (create, read, update, delete)
- **BOMs**: Full BOM lifecycle + COGS breakdown + pricing suggestions + usage tracking
- **Material Usages**: Complete material usage management for BOMs
- All tools follow TDD with comprehensive unit tests (80+ tests passing)
- Total active tools: **39 tools** (up from 16)

### v2.8.0
- Added product management tools (get_products, get_categories, get_boms)
- Support for complex product structures with BOMs and routing
- Category filtering and management
- Cost of Goods Sold (COGS) calculations in BOMs
- Comprehensive unit tests for all product tools

### v2.7.0
- Added batch management with vendor tracking
- Bulk operations for batches (create, update, delete)
- Enhanced filtering capabilities

### v2.4.0
- Added material management tools (get, update, delete by ID)
- Improved security with sanitized logging
- Added comprehensive error handling
- Enhanced authentication validation

### v2.3.0
- Added get_materials tool with filtering
- Fixed authentication header handling
- Improved documentation

### v2.2.0
- Added bulk material creation
- Enhanced error handling

---

**Built with TypeScript, Cloudflare Workers, and security best practices.**