Labamu MCP Server

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.

  

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

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

2. Deployment

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

3. Configuration

Copy the template and configure your Claude Desktop:

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:

{
  "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

# 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 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 for comprehensive security documentation.

Configuration

Feature Flags

Tools can be enabled/disabled via environment variables:

# 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

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

Returns server status and enabled tools:

{
  "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

# 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

# Run all tests
npm test

# Coverage report
npm run test:coverage

API Reference

Material Management

Get Materials

{
  "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

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

Update Material

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

Product Management

Get Products

{
  "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

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

Get BOMs

{
  "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:

wrangler tail --format pretty

Contributing

We welcome contributions! Please see our 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 - System design and patterns
• Development Guide - Development setup and guidelines
• Security Guide - Security practices and procedures
• Feature Flags - 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

# 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 file for details.

Support

For issues and questions:

1. Check troubleshooting section
2. Review security guidelines
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.