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.