@commercetools/commerce-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,12 @@
+License and Scope of Use for Commerce MCP
+
+Commerce MCP is provided under a dual-tier usage model based on the highly permissive MIT License with specific limitations on commercial use.
+
+Permitted Use
+Access to and use of Commerce MCP is governed by the following terms:
+
+- Non-Commercial Use (No Charge): The use of Commerce MCP is permitted for development, evaluation, and testing purposes at no charge. This non-commercial use is subject to a hard cap of 1,000,000 (one million) total tool invocations.
+- Commercial/Production Use (Required License): Any use of Commerce MCP in a production environment or for any other commercial purpose requires a paid license or subscription.
+
+License Enforcement
+While the underlying code adheres to the principles of the MIT License, the terms above constitute the binding agreement for utilizing Commerce MCP. commercetools reserves the right to review how customers are using Commerce MCP and to restrict or terminate access for unlicensed production use or for any non-commercial use that exceeds the stated 1,000,000 invocation limit.

package/README.md

@@ -0,0 +1,87 @@
+# commercetools Model Context Protocol
+
+This documentation focusses on the development of the MCP server. For the user documentation, view the [main README](../README.md).
+
+## Debugging locally
+
+```bash
+#  navigate to ../typescript
+pnpm run build
+# navigate to ../modelcontextprotocol
+
+# link the local package
+pnpm add link:../typescript
+
+# run the server in terminal
+npx ts-node src/index.ts --tools=products.read --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --authUrl=AUTH_URL --projectKey=PROJECT_KEY --apiUrl=API_URL
+
+# test using mcptools : Install mcptools from https://github.com/f/mcptools
+mcp call list_products --params '{"limit": 2}' npx ts-node /<absolute-path>/commerce-agent/modelcontextprotocol/src/index.ts --tools=all \
+--projectKey="PROJECT_KEY" \
+--clientSecret="CLIENT_SECRET" \
+--clientId="CLIENT_ID" \
+--authUrl="AUTH_URL" \
+--apiUrl="API_URL"
+```
+
+**_Do not commit the linked package in package.json to the repo_**
+
+## Testing Using Claude Desktop
+
+NOTE: This will not work with Claude Desktop unless you uninstall node v16 from your machine!
+
+```bash
+#  navigate to ../typescript
+pnpm run build
+
+# navigate to ../modelcontextprotocol
+
+# link the local package
+pnpm add link:../typescript
+```
+
+Configure MCP servers in Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "commercetools": {
+      "command": "npx",
+      "args": [
+        "ts-node",
+        "/<absolute-path>/commerce-agent/modelcontextprotocol/src/index.ts",
+        "--tools=all",
+        "--projectKey=PROJECT_KEY",
+        "--clientSecret=CLIENT_SECRET",
+        "--clientId=CLIENT_ID",
+        "--authUrl=AUTH_URL",
+        "--apiUrl=API_URL"
+      ]
+    }
+  }
+}
+```
+
+## Debugging the Server
+
+To debug your server, you can use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
+
+First build the server
+
+```
+npm run build
+```
+
+Run the following command in your terminal:
+
+```bash
+# Start MCP Inspector and server with all tools
+npx @modelcontextprotocol/inspector node dist/index.js --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL
+```
+
+### Instructions
+
+1. Replace `CLIENT_ID`, `CLIENT_SECRET`, `PROJECT_KEY`, `AUTH_URL`, and `API_URL` with your actual values.
+2. Run the command to start the MCP Inspector.
+3. Open the MCP Inspector UI in your browser and click Connect to start the MCP server.
+4. You can see the list of tools you selected and test each tool individually.

package/dist/index.js

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACCEPTED_TOOLS = void 0;
+exports.parseArgs = parseArgs;
+exports.main = main;
+const modelcontextprotocol_1 = require("@commercetools/commerce-agent/modelcontextprotocol");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const colors_1 = require("colors");
+const HIDDEN_ARGS = ['customerId', 'isAdmin', 'storeKey', 'businessUnitKey'];
+const PUBLIC_ARGS = [
+    'tools',
+    'authType',
+    'clientId',
+    'clientSecret',
+    'accessToken',
+    'authUrl',
+    'projectKey',
+    'apiUrl',
+    'dynamicToolLoadingThreshold',
+    'toolOutputFormat',
+];
+const ACCEPTED_ARGS = [...PUBLIC_ARGS, ...HIDDEN_ARGS];
+exports.ACCEPTED_TOOLS = [
+    'business-unit.read',
+    'business-unit.create',
+    'business-unit.update',
+    'products.read',
+    'products.create',
+    'products.update',
+    'project.read',
+    'product-search.read',
+    'category.read',
+    'category.create',
+    'category.update',
+    'channel.read',
+    'channel.create',
+    'channel.update',
+    'product-selection.read',
+    'product-selection.create',
+    'product-selection.update',
+    'order.read',
+    'order.create',
+    'order.update',
+    'cart.read',
+    'cart.create',
+    'cart.update',
+    'customer.create',
+    'customer.read',
+    'customer.update',
+    'customer-group.read',
+    'customer-group.create',
+    'customer-group.update',
+    'quote.read',
+    'quote.create',
+    'quote.update',
+    'quote-request.read',
+    'quote-request.create',
+    'quote-request.update',
+    'staged-quote.read',
+    'staged-quote.create',
+    'staged-quote.update',
+    'standalone-price.read',
+    'standalone-price.create',
+    'standalone-price.update',
+    'product-discount.read',
+    'product-discount.create',
+    'product-discount.update',
+    'cart-discount.read',
+    'cart-discount.create',
+    'cart-discount.update',
+    'discount-code.read',
+    'discount-code.create',
+    'discount-code.update',
+    'product-type.read',
+    'product-type.create',
+    'product-type.update',
+    'bulk.create',
+    'bulk.update',
+    'inventory.read',
+    'inventory.create',
+    'inventory.update',
+    'store.read',
+    'store.create',
+    'store.update',
+    'review.read',
+    'review.create',
+    'review.update',
+    'tax-category.read',
+    'tax-category.create',
+    'tax-category.update',
+    'shipping-methods.read',
+    'shipping-methods.create',
+    'shipping-methods.update',
+    'payments.read',
+    'payments.create',
+    'payments.update',
+    'zone.read',
+    'zone.create',
+    'zone.update',
+    'product-tailoring.read',
+    'product-tailoring.create',
+    'product-tailoring.update',
+    'payment-methods.read',
+    'payment-methods.create',
+    'payment-methods.update',
+    'recurring-orders.read',
+    'recurring-orders.create',
+    'recurring-orders.update',
+    'shopping-lists.read',
+    'shopping-lists.create',
+    'shopping-lists.update',
+    'extensions.read',
+    'extensions.create',
+    'extensions.update',
+    'subscriptions.read',
+    'subscriptions.create',
+    'subscriptions.update',
+    'custom-objects.read',
+    'custom-objects.create',
+    'custom-objects.update',
+    'types.read',
+    'types.create',
+    'types.update',
+    'payment-intents.update',
+    'transactions.read',
+    'transactions.create',
+];
+// eslint-disable-next-line complexity
+function parseArgs(args) {
+    const options = {};
+    const env = {};
+    // eslint-disable-next-line complexity
+    args.forEach((arg) => {
+        if (arg.startsWith('--')) {
+            const [key, value] = arg.slice(2).split('=');
+            if (key == 'tools') {
+                options.tools = value.split(',');
+            }
+            else if (key == 'authType') {
+                env.authType = value;
+            }
+            else if (key == 'accessToken') {
+                env.accessToken = value;
+            }
+            else if (key == 'clientId') {
+                env.clientId = value;
+            }
+            else if (key == 'clientSecret') {
+                env.clientSecret = value;
+            }
+            else if (key == 'authUrl') {
+                env.authUrl = value;
+            }
+            else if (key == 'projectKey') {
+                env.projectKey = value;
+            }
+            else if (key == 'apiUrl') {
+                env.apiUrl = value;
+            }
+            else if (key == 'remote') {
+                env.remote = value == 'true';
+            }
+            else if (key == 'stateless') {
+                env.stateless = value == 'true';
+            }
+            else if (key == 'port') {
+                env.port = Number(value);
+            }
+            else if (key == 'customerId') {
+                options.customerId = value;
+            }
+            else if (key == 'isAdmin') {
+                options.isAdmin = value === 'true';
+            }
+            else if (key == 'dynamicToolLoadingThreshold') {
+                options.dynamicToolLoadingThreshold = Number(value);
+            }
+            else if (key == 'toolOutputFormat') {
+                if (value === 'json' || value === 'tabular') {
+                    options.toolOutputFormat = value;
+                }
+            }
+            else if (key == 'logging') {
+                options.logging = value == 'true';
+            }
+            else if (key == 'cartId') {
+                options.cartId = value;
+            }
+            else if (key == 'storeKey') {
+                options.storeKey = value;
+            }
+            else if (key == 'businessUnitKey') {
+                options.businessUnitKey = value;
+            }
+            else {
+                throw new Error(`Invalid argument: ${key}. Accepted arguments are: ${PUBLIC_ARGS.join(', ')}`);
+            }
+        }
+    });
+    // Check if required tools arguments is present
+    if (!options.tools) {
+        if (!process.env.TOOLS) {
+            throw new Error('The --tools arguments must be provided.');
+        }
+        options.tools = process.env.TOOLS.split(',');
+    }
+    // Validate tools against accepted enum values
+    options.tools.forEach((tool) => {
+        if (tool == 'all' || tool == 'all.read') {
+            return;
+        }
+        if (!exports.ACCEPTED_TOOLS.includes(tool.trim())) {
+            throw new Error(`Invalid tool: ${tool}. Accepted tools are: ${exports.ACCEPTED_TOOLS.join(', ')}`);
+        }
+    });
+    // Check for commercetools env vars
+    env.authType =
+        env.authType ||
+            process.env.AUTH_TYPE ||
+            'client_credentials';
+    env.accessToken = env.accessToken || process.env.ACCESS_TOKEN;
+    env.clientId = env.clientId || process.env.CLIENT_ID;
+    env.clientSecret = env.clientSecret || process.env.CLIENT_SECRET;
+    env.authUrl = env.authUrl || process.env.AUTH_URL;
+    env.projectKey = env.projectKey || process.env.PROJECT_KEY;
+    env.apiUrl = env.apiUrl || process.env.API_URL;
+    env.remote = env.remote || process.env.REMOTE == 'true';
+    env.logging = env.logging || process.env.LOGGING == 'true';
+    env.stateless = env.stateless || process.env.STATELESS == 'true';
+    env.port = env.port || Number(process.env.PORT);
+    options.businessUnitKey =
+        options.businessUnitKey || process.env.BUSINESS_UNIT_KEY;
+    options.storeKey = options.storeKey || process.env.STORE_KEY;
+    options.customerId = options.customerId || process.env.CUSTOMER_ID;
+    options.isAdmin = options.isAdmin || process.env.IS_ADMIN === 'true';
+    options.logging = options.logging || process.env.LOGGING == 'true';
+    options.dynamicToolLoadingThreshold =
+        options.dynamicToolLoadingThreshold ||
+            (process.env.DYNAMIC_TOOL_LOADING_THRESHOLD
+                ? Number(process.env.DYNAMIC_TOOL_LOADING_THRESHOLD)
+                : undefined);
+    if ((process.env.TOOL_OUTPUT_FORMAT &&
+        process.env.TOOL_OUTPUT_FORMAT === 'tabular') ||
+        process.env.TOOL_OUTPUT_FORMAT === 'json') {
+        options.toolOutputFormat = process.env.TOOL_OUTPUT_FORMAT;
+    }
+    options.cartId = options.cartId || process.env.CART_ID;
+    // Validate required commercetools credentials based on auth type
+    if (!env.authUrl || !env.projectKey || !env.apiUrl) {
+        throw new Error('Missing required options. Please make sure to provide the values for "authUrl", "apiUrl", "projectKey" or via environment variables (AUTH_URL, API_URL, PROJECT_KEY).');
+    }
+    // Validate auth-specific requirements
+    switch (env.authType) {
+        case 'client_credentials':
+            if (!env.clientId || !env.clientSecret) {
+                throw new Error('Missing required client credentials when "authType" is "client_credentials". Please make sure to provide the values for "clientId", "clientSecret" or via environment variables (CLIENT_ID, CLIENT_SECRET).');
+            }
+            break;
+        case 'auth_token':
+            if (!env.accessToken) {
+                throw new Error('Missing required access token when "authType" is "auth_token". Please make sure to provide the value for "accessToken" or via environment variable (ACCESS_TOKEN).');
+            }
+            break;
+        default:
+            throw new Error(`Invalid auth type: ${env.authType}. Supported types are: client_credentials, auth_token`);
+    }
+    return { options, env };
+}
+function createAuthConfig(env) {
+    const baseConfig = {
+        authUrl: env.authUrl,
+        projectKey: env.projectKey,
+        apiUrl: env.apiUrl,
+    };
+    switch (env.authType) {
+        case 'client_credentials':
+            return {
+                type: 'client_credentials',
+                clientId: env.clientId,
+                clientSecret: env.clientSecret,
+                ...baseConfig,
+            };
+        case 'auth_token':
+            return {
+                type: 'auth_token',
+                clientId: env.clientId,
+                clientSecret: env.clientSecret,
+                accessToken: env.accessToken,
+                ...baseConfig,
+            };
+        default:
+            throw new Error(`Unsupported auth type: ${env.authType}`);
+    }
+}
+function handleError(error) {
+    console.error((0, colors_1.red)('\n🚨  Error initializing commercetools MCP server:\n'));
+    console.error((0, colors_1.yellow)(`   ${error.message}\n`));
+}
+async function main() {
+    require('dotenv').config({
+        quiet: true,
+    });
+    const { options, env } = parseArgs(process.argv.slice(2));
+    // Create the CommercetoolsCommerceAgent instance
+    const selectedTools = options.tools;
+    const configuration = {
+        actions: {},
+        context: {
+            customerId: options.customerId,
+            isAdmin: options.isAdmin,
+            dynamicToolLoadingThreshold: options.dynamicToolLoadingThreshold,
+            toolOutputFormat: options.toolOutputFormat,
+            cartId: options.cartId,
+            storeKey: options.storeKey,
+            businessUnitKey: options.businessUnitKey,
+            logging: options.logging,
+        },
+    };
+    if (selectedTools[0] === 'all') {
+        exports.ACCEPTED_TOOLS.forEach((tool) => {
+            if (!configuration.actions) {
+                configuration.actions = {};
+            }
+            const [namespace, action] = tool.split('.');
+            configuration.actions[namespace] = {
+                ...configuration.actions[namespace],
+                [action]: true,
+            };
+        });
+    }
+    else if (selectedTools[0] === 'all.read') {
+        exports.ACCEPTED_TOOLS.forEach((tool) => {
+            if (!configuration.actions) {
+                configuration.actions = {};
+            }
+            const [namespace, action] = tool.split('.');
+            if (action === 'read') {
+                configuration.actions[namespace] = {
+                    ...configuration.actions[namespace],
+                    [action]: true,
+                };
+            }
+        });
+    }
+    else {
+        selectedTools.forEach((tool) => {
+            if (!configuration.actions) {
+                configuration.actions = {};
+            }
+            const [namespace, action] = tool.split('.');
+            configuration.actions[namespace] = {
+                ...(configuration.actions[namespace] || {}),
+                [action]: true,
+            };
+        });
+    }
+    const authConfig = createAuthConfig(env);
+    // eslint-disable-next-line require-await
+    async function getServer() {
+        return modelcontextprotocol_1.CommercetoolsCommerceAgent.create({
+            authConfig,
+            configuration,
+        });
+    }
+    if (env.remote) {
+        const streamServer = new modelcontextprotocol_1.CommercetoolsCommerceAgentStreamable({
+            authConfig,
+            configuration,
+            stateless: env.stateless,
+            streamableHttpOptions: {
+                sessionIdGenerator: undefined,
+            },
+        });
+        const port = env.port || 8080;
+        streamServer.listen(port, function () {
+            console.error(`Stream server listening on`, port);
+        });
+    }
+    else {
+        const server = await getServer();
+        const transport = new stdio_js_1.StdioServerTransport();
+        await server.connect(transport);
+        console.error('MCP server is running...');
+    }
+}
+if (require.main === module) {
+    main().catch((error) => {
+        handleError(error);
+    });
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@commercetools/commerce-mcp",
+  "version": "0.0.1",
+  "homepage": "https://github.com/commercetools/commerce-mcp",
+  "description": "A command line tool for setting up commercetools MCP server",
+  "bin": "dist/index.js",
+  "files": [
+    "dist/index.js",
+    "LICENSE",
+    "README.md",
+    "VERSION",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "colors": "^1.4.0",
+    "dotenv": "^17.2.1",
+    "mcp-remote": "^0.1.18",
+    "@commercetools/commerce-agent": "0.0.1"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "commercetools"
+  ],
+  "author": "commercetools GmbH <info@commercetools.com> (https://commercetools.com)",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/compat": "^1.2.6",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.4",
+    "@typescript-eslint/eslint-plugin": "^8.24.1",
+    "concurrently": "^9.2.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jest": "^28.11.0",
+    "eslint-plugin-prettier": "^5.2.3",
+    "globals": "^15.15.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.1",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "prebuild": "pnpm --filter @commercetools/commerce-agent run build",
+    "dev": "concurrently -n BUILD,SERVER -c magenta,cyan \"pnpm dev:build\" \"pnpm dev:run\"",
+    "dev:build": "tsup --env.NODE_ENV dev",
+    "dev:run": "nodemon  dist/index.js --watch",
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"./**/*.ts*\"",
+    "prettier": "prettier './**/*.{js,ts,md,html,css}' --write",
+    "prettier-check": "prettier './**/*.{js,ts,md,html,css}' --check",
+    "test": "jest",
+    "validate": "pnpm run lint --fix && pnpm run prettier && pnpm run test"
+  }
+}