Commerce Operations Foundation MCP Server

A Model Context Protocol (MCP) server that provides standardized access to commerce operations and fulfillment systems.

Features

• 10 standardized fulfillment tools covering core order capture, fulfillment, and data queries
• Plug-and-play adapter system for different fulfillment backends
• Mock adapter for testing and development
• Full TypeScript implementation with strict type safety
• JSON Schema validation for all inputs
• stdio transport for Claude Desktop integration

Quick Start

Installation

# From the repository root
cd server
npm install

Running the Server

# Development mode with TypeScript via vite-node
npm run dev

# Production mode
npm run build
npm start

Configuration

Copy .env.example to .env and configure:

# Use built-in mock adapter (default)
ADAPTER_TYPE=built-in
ADAPTER_NAME=mock

# Set log level
LOG_LEVEL=info

# Optional: pass adapter options as JSON
ADAPTER_CONFIG='{"fixedLatency":150}'

Architecture

The server follows a three-layer architecture:

1. Protocol Layer - Handles MCP communication
2. Service Layer - Business logic and validation
3. Adapter Layer - Fulfillment integration (pluggable)

Available Tools

Action Tools

• create-sales-order - Create new orders from external systems or checkouts
• cancel-order - Cancel existing orders with optional reasons
• update-order - Modify order details and metadata
• fulfill-order - Mark orders as fulfilled and return fulfillment data

Query Tools

• get-orders - Retrieve orders with rich filtering
• get-customers - Fetch customer records
• get-products - Get product catalog entries
• get-product-variants - Retrieve variant data
• get-inventory - Check stock levels across locations
• get-fulfillments - List fulfillment records and statuses

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "cof-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"],
      "env": {
        "ADAPTER_TYPE": "built-in",
        "ADAPTER_NAME": "mock"
      }
    }
  }
}

Security Considerations

Dynamic Adapter Loading

This MCP server supports dynamic loading of adapters from NPM packages and local files to facilitate adapter development and testing. This flexibility comes with security considerations:

⚠️ IMPORTANT SECURITY NOTICE:

• Dynamically loaded adapters execute with full system permissions
• Only load adapters from trusted sources
• Never load adapters from user uploads or untrusted repositories
• The adapter code has the same access level as the MCP server itself

For Production Environments:

• Consider implementing a whitelist of allowed adapters
• Run the MCP server in a containerized/sandboxed environment
• Use Node.js experimental permission flags to restrict file/network access
• Implement code signing for adapters

For Development (Reference Implementation):

• The current implementation prioritizes developer flexibility
• Logs all adapter loading for transparency
• Validates file existence and type before loading
• Suitable for local development and testing

Best Practices

1. Adapter Development: When developing custom adapters, ensure your code:

   • Only accesses necessary Fulfillment APIs
   • Doesn't expose sensitive credentials
   • Validates all inputs properly
   • Handles errors gracefully

2. Configuration Security:

   • Store sensitive configuration in environment variables
   • Never commit .env files to version control
   • Use secrets management in production

3. Network Security:

   • Run the MCP server behind appropriate firewalls
   • Use TLS/SSL for Fulfillment API communications
   • Implement rate limiting for production use

Development

Project Structure

server/
├── src/
│   ├── adapters/      # Built-in Fulfillment adapters
│   ├── services/      # Business logic
│   ├── tools/         # Tool implementations
│   ├── types/         # TypeScript types
│   └── utils/         # Utilities
└── tests/            # Test suites

Adding a Custom Adapter

1. Create your adapter class implementing IFulfillmentAdapter
2. Register it in the adapter factory
3. Configure via environment variables

See docs/architecture for details.

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration

Documentation

• Architecture Guide
• MCP Specification
• Tool Reference

License

MIT

Contributing

See CONTRIBUTING.md for guidelines.

Support

For issues and questions, visit GitHub Issues.