mcp-reference

The Commerce Operations Foundation MCP Server exposes a standardized set of fulfillment operations that AI agents can invoke through the Model Context Protocol (MCP). It acts as a bridge between AI platforms (like Claude Desktop or other MCP-enabled agents) and a fulfillment backend, routing 12 standardized operations—5 actions and 7 queries—to adapters that implement the specific fulfillment system. By default, the server ships with a mock adapter to support testing and development, and prod deployments can swap in real adapters for order management, inventory, and shipment workflows. To run locally, start the server and point your AI platform to the provided MCP interface; AI agents can issue MCP requests such as creating a sales order, updating an order, checking inventory, or retrieving customers and products.

Typical usage involves configuring an adapter (built-in mock or a custom adapter) via environment variables (e.g., ADAPTER_TYPE and ADAPTER_NAME) and then issuing MCP calls from your AI tooling layer. The server exposes both action tools (create-sales-order, update-order, cancel-order, fulfill-order, create-return) and query tools (get-orders, get-customers, get-products, get-product-variants, get-inventory, get-fulfillments, get-returns) so you can orchestrate end-to-end fulfillment scenarios using a single, consistent interface.

Prerequisites:

• Node.js 16+ and npm/yarn installed
• Git available to clone the repository

Install and run locally:

# 1) Clone the repository
git clone https://github.com/cof-org/mcp-reference-server.git
cd mcp-reference-server

# 2) Install server dependencies
cd server
npm install

# 3) Build the server (transpiles TS to JS if using TS sources)
npm run build

# 4) Start the MCP reference server with mock adapter (default)
npm start

Notes:

• The server uses a mock adapter by default. You can customize the adapter by setting ADAPTER_TYPE and ADAPTER_NAME in a .env file or via your hosting environment, as described in the project docs.
• If you plan to deploy with Docker or another runtime, follow the Installation Guide in docs for platform-specific steps.

Environment variables to consider:

• ADAPTER_TYPE: Type of adapter (e.g., built-in, custom)
• ADAPTER_NAME: Name of the adapter (e.g., mock, your-adapter-name)
• MCP_LOG_LEVEL: Logging level (debug, info, warn, error)

Common issues:

• Ensure the adapter is reachable and correctly wired to the MCP server routes.
• If you change ADAPTER_TYPE, make sure to provide a compatible ADAPTER_NAME and any required adapter-specific configuration.
• When migrating from mock to a real backend, validate all 12 operations against a test suite to ensure compatibility with your fulfillment system.

Configuration options are documented in the Documentation folder under docs/guides and the Configuration Guide.