@commercetools/commerce-mcp 4.0.0 → 4.2.0

package/README.md

@@ -12,11 +12,14 @@ pnpm run build
 # link the local package
 pnpm add link:../typescript
 
+# build this package: the executable is dist/cli.js
+pnpm run build
+
 # run the server in terminal
-npx ts-node src/index.ts --tools=read_products --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --authUrl=AUTH_URL --projectKey=PROJECT_KEY --apiUrl=API_URL
+node dist/cli.js --tools=read_products --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 read_products --params '{"limit": 2}' npx ts-node /<absolute-path>/commerce-agent/modelcontextprotocol/src/index.ts --tools=all \
+mcp call read_products --params '{"limit": 2}' node /<absolute-path>/commerce-agent/modelcontextprotocol/dist/cli.js --tools=all \
 --projectKey="PROJECT_KEY" \
 --clientSecret="CLIENT_SECRET" \
 --clientId="CLIENT_ID" \
@@ -24,11 +27,14 @@ mcp call read_products --params '{"limit": 2}' npx ts-node /<absolute-path>/comm
 --apiUrl="API_URL"
 ```
 
+`src/index.ts` exports `main()` but does not call it, so running that file
+directly starts nothing. `dist/cli.js` is the entry point that does.
+
 **_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!
+NOTE: This package requires Node.js 20 or newer. Make sure the `node` on Claude Desktop's PATH is a v20+ install.
 
 ```bash
 #  navigate to ../typescript
@@ -38,6 +44,9 @@ pnpm run build
 
 # link the local package
 pnpm add link:../typescript
+
+# build this package: the executable is dist/cli.js
+pnpm run build
 ```
 
 Configure MCP servers in Claude Desktop
@@ -46,10 +55,9 @@ Configure MCP servers in Claude Desktop
 {
   "mcpServers": {
     "commercetools": {
-      "command": "npx",
+      "command": "node",
       "args": [
-        "ts-node",
-        "/<absolute-path>/commerce-agent/modelcontextprotocol/src/index.ts",
+        "/<absolute-path>/commerce-agent/modelcontextprotocol/dist/cli.js",
         "--tools=all",
         "--projectKey=PROJECT_KEY",
         "--clientSecret=CLIENT_SECRET",
@@ -76,7 +84,7 @@ 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
+npx @modelcontextprotocol/inspector node dist/cli.js --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL
 ```
 
 ### Instructions

package/dist/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Executable entry point. Kept separate from `index.ts` so that module's
+ * exports stay importable from tests and from other packages without running
+ * the server as a side effect.
+ */
+import { handleError, main } from './index.js';
+main().catch((error) => {
+    handleError(error);
+    process.exitCode = 1;
+});

package/dist/index.js

@@ -1,13 +1,11 @@
 #!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveToolsForConfiguration = exports.applyResolvedToolsToConfiguration = exports.ACCEPTED_TOOLS = void 0;
-exports.parseArgs = parseArgs;
-exports.main = main;
-const modelcontextprotocol_1 = require("@commercetools/commerce-agent/modelcontextprotocol");
-const processors_1 = require("@commercetools/processors");
-const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
-const colors_1 = require("colors");
+import { ACCEPTED_TOOLS, applyResolvedToolsToConfiguration, CommercetoolsCommerceAgent, CommercetoolsCommerceAgentStreamable, DEFAULT_HOST, LOOPBACK_HOSTNAMES, normalizeBindHost, resolveToolsForConfiguration, } from '@commercetools/commerce-agent/modelcontextprotocol';
+import { FieldFilteringHandler, } from '@commercetools/processors';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import dotenv from 'dotenv';
+import colors from 'colors';
+const red = colors.red;
+const yellow = colors.yellow;
 const HIDDEN_ARGS = ['customerId', 'isAdmin', 'storeKey', 'businessUnitKey'];
 const PUBLIC_ARGS = [
     'tools',
@@ -21,13 +19,14 @@ const PUBLIC_ARGS = [
     'dynamicToolLoadingThreshold',
     'toolOutputFormat',
     'logging',
+    'host',
+    'port',
+    'allowedHosts',
+    'allowedOrigins',
 ];
 const ACCEPTED_ARGS = [...PUBLIC_ARGS, ...HIDDEN_ARGS];
-var modelcontextprotocol_2 = require("@commercetools/commerce-agent/modelcontextprotocol");
-Object.defineProperty(exports, "ACCEPTED_TOOLS", { enumerable: true, get: function () { return modelcontextprotocol_2.ACCEPTED_TOOLS; } });
-Object.defineProperty(exports, "applyResolvedToolsToConfiguration", { enumerable: true, get: function () { return modelcontextprotocol_2.applyResolvedToolsToConfiguration; } });
-Object.defineProperty(exports, "resolveToolsForConfiguration", { enumerable: true, get: function () { return modelcontextprotocol_2.resolveToolsForConfiguration; } });
-function parseArgs(args) {
+export { ACCEPTED_TOOLS, applyResolvedToolsToConfiguration, resolveToolsForConfiguration, } from '@commercetools/commerce-agent/modelcontextprotocol';
+export function parseArgs(args) {
     const options = {};
     const env = {};
     args.forEach((arg) => {
@@ -63,6 +62,15 @@ function parseArgs(args) {
             else if (key == 'stateless') {
                 env.stateless = value == 'true';
             }
+            else if (key == 'host') {
+                env.host = value;
+            }
+            else if (key == 'allowedHosts') {
+                env.allowedHosts = splitList(value);
+            }
+            else if (key == 'allowedOrigins') {
+                env.allowedOrigins = splitList(value);
+            }
             else if (key == 'port') {
                 env.port = Number(value);
             }
@@ -112,8 +120,8 @@ function parseArgs(args) {
         if (tool == 'all' || tool == 'read_all') {
             return;
         }
-        if (!modelcontextprotocol_1.ACCEPTED_TOOLS.includes(tool.trim())) {
-            throw new Error(`Invalid tool: ${tool}. Accepted tools are: ${modelcontextprotocol_1.ACCEPTED_TOOLS.join(', ')}`);
+        if (!ACCEPTED_TOOLS.includes(tool.trim())) {
+            throw new Error(`Invalid tool: ${tool}. Accepted tools are: ${ACCEPTED_TOOLS.join(', ')}`);
         }
     });
     // Check for commercetools env vars
@@ -130,6 +138,11 @@ function parseArgs(args) {
     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.host = env.host || process.env.HOST || DEFAULT_HOST;
+    env.allowedHosts =
+        env.allowedHosts || splitList(process.env.ALLOWED_HOSTS) || undefined;
+    env.allowedOrigins =
+        env.allowedOrigins || splitList(process.env.ALLOWED_ORIGINS) || undefined;
     env.port = env.port || Number(process.env.PORT);
     options.businessUnitKey =
         options.businessUnitKey || process.env.BUSINESS_UNIT_KEY;
@@ -160,7 +173,7 @@ function parseArgs(args) {
             }
             break;
         case 'auth_token':
-            if (!env.accessToken) {
+            if (!env.remote && !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;
@@ -260,14 +273,92 @@ function createAuthConfig(env) {
             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`));
+function splitList(value) {
+    if (!value)
+        return undefined;
+    const entries = value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return entries.length > 0 ? entries : undefined;
 }
-async function main() {
-    require('dotenv').config({
-        quiet: true,
-    });
+/**
+ * Hostnames the server will answer for. Loopback always works; the interface
+ * it was told to bind is added so addressing the server by that address works
+ * without extra configuration, and `--allowedHosts` covers the rest (a domain
+ * in front of a proxy, a container hostname, ...).
+ */
+function resolveAllowedHosts(env) {
+    const hosts = new Set([...LOOPBACK_HOSTNAMES, ...(env.allowedHosts ?? [])]);
+    const host = env.host;
+    if (host && !isWildcardHost(host)) {
+        hosts.add(host);
+    }
+    return [...hosts];
+}
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1', '::ffff:127.0.0.1'];
+/** Hosts that mean "listen on every interface" rather than a single address. */
+const WILDCARD_HOSTS = ['0.0.0.0', '::', '::0', '*', ''];
+function isLoopbackHost(host) {
+    return LOOPBACK_HOSTS.includes(host) || host.startsWith('127.');
+}
+function isWildcardHost(host) {
+    return WILDCARD_HOSTS.includes(host.trim());
+}
+/**
+ * Binding beyond loopback puts the server on the network, where anything that
+ * can reach the port can talk to it. That is a legitimate choice behind a
+ * gateway, but it should never happen without the operator noticing — and a
+ * wildcard bind deserves a louder warning than a single chosen interface,
+ * since it also covers interfaces the operator may not have had in mind.
+ */
+function warnIfPubliclyBound(host) {
+    if (isLoopbackHost(host))
+        return;
+    const exposure = isWildcardHost(host)
+        ? `bound to ${host || '0.0.0.0'} — every network interface on this machine, including\n` +
+            `   any that is publicly routable`
+        : `bound to ${host}, so it is reachable from outside this machine`;
+    console.error(yellow(`\n\u26a0\ufe0f  The MCP server is ${exposure}.\n` +
+        `   Callers still need a valid "Authorization: Bearer <token>" header, but make sure the port\n` +
+        `   is only exposed to networks you trust. Use --host=127.0.0.1 to keep it local.\n`));
+}
+/**
+ * Stateful mode is on its way out (DEVX-888). The 2026-07-28 spec removes
+ * protocol sessions and `Mcp-Session-Id` entirely, and the v2 handler answers
+ * the session operations (GET/DELETE) with 405.
+ *
+ * An audit found nothing kept across calls but the transport instance and the
+ * token fingerprint that binds a session to its opener, so per-request auth
+ * already covers what sessions were carrying. Nothing changes yet — this only
+ * warns, because remote currently defaults to stateful and silently flipping
+ * that would break clients mid-release.
+ */
+function warnIfStateful(stateless) {
+    if (stateless)
+        return;
+    console.error(yellow(`\n\u26a0\ufe0f  Stateful session mode is deprecated and will be removed.\n` +
+        `   The 2026-07-28 MCP spec has no protocol sessions, so this mode cannot carry\n` +
+        `   forward. Nothing is stored across calls today beyond the session's own auth\n` +
+        `   binding, which per-request credentials already provide.\n` +
+        `   Pass --stateless=true to adopt the future default now.\n`));
+}
+/** True once the server actually holds an address. */
+function isBound(server) {
+    const address = server?.address;
+    return typeof address === 'function' ? address.call(server) !== null : true;
+}
+function onServerError(server, listener) {
+    const on = server?.on;
+    if (typeof on === 'function')
+        on.call(server, 'error', listener);
+}
+export function handleError(error) {
+    console.error(red('\n🚨  Error initializing commercetools MCP server:\n'));
+    console.error(yellow(`   ${error.message}\n`));
+}
+export async function main() {
+    dotenv.config({ quiet: true });
     const { options, env } = parseArgs(process.argv.slice(2));
     // Create the CommercetoolsCommerceAgent instance
     const selectedTools = options.tools;
@@ -283,43 +374,63 @@ async function main() {
             businessUnitKey: options.businessUnitKey,
             logging: options.logging,
             fieldFiltering: options.fieldFiltering
-                ? new processors_1.FieldFilteringHandler(options.fieldFiltering)
+                ? new FieldFilteringHandler(options.fieldFiltering)
                 : undefined,
         },
     };
-    const resolution = (0, modelcontextprotocol_1.resolveToolsForConfiguration)(selectedTools, Boolean(options.isAdmin));
-    (0, modelcontextprotocol_1.applyResolvedToolsToConfiguration)(configuration, resolution);
+    const resolution = resolveToolsForConfiguration(selectedTools, Boolean(options.isAdmin));
+    applyResolvedToolsToConfiguration(configuration, resolution);
     const authConfig = createAuthConfig(env);
     // eslint-disable-next-line require-await
     async function getServer() {
-        return modelcontextprotocol_1.CommercetoolsCommerceAgent.create({
+        return CommercetoolsCommerceAgent.create({
             authConfig,
             configuration,
         });
     }
     if (env.remote) {
-        const streamServer = new modelcontextprotocol_1.CommercetoolsCommerceAgentStreamable({
+        warnIfStateful(Boolean(env.stateless));
+        const streamServer = new CommercetoolsCommerceAgentStreamable({
             authConfig,
             configuration,
             stateless: env.stateless,
-            streamableHttpOptions: {
-                sessionIdGenerator: undefined,
-            },
+            allowedHosts: resolveAllowedHosts(env),
+            allowedOrigins: env.allowedOrigins,
         });
         const port = env.port || 8080;
-        streamServer.listen(port, function () {
-            console.error(`Stream server listening on`, port);
+        // `*` and an empty value mean "every interface"; the OS needs 0.0.0.0.
+        const host = normalizeBindHost(env.host);
+        warnIfPubliclyBound(host);
+        /**
+         * Kept in a holder so the listen callback can read the server without a
+         * binding that is still in its temporal dead zone should an app
+         * implementation invoke the callback synchronously.
+         */
+        const bound = {};
+        bound.server = streamServer.listen(port, host, function () {
+            /**
+             * Express runs this callback even when the bind failed (an unresolvable
+             * host leaves `address()` null), so confirm before claiming success —
+             * the error handler below reports the failure instead.
+             */
+            if (!isBound(bound.server))
+                return;
+            console.error(`Stream server listening on ${host}:${port}`);
+        });
+        /**
+         * A bind failure — port already taken, address not available, a host that
+         * does not resolve — arrives as an 'error' event. Left unhandled it kills
+         * the process with no explanation of what went wrong.
+         */
+        onServerError(bound.server, (error) => {
+            handleError(new Error(`Unable to bind ${host}:${port}${error.code ? ` (${error.code})` : ''}. ${error.message}`));
+            process.exitCode = 1;
         });
     }
     else {
         const server = await getServer();
-        const transport = new stdio_js_1.StdioServerTransport();
+        const transport = new StdioServerTransport();
         await server.connect(transport);
         console.error('MCP server is running...');
     }
 }
-if (require.main === module) {
-    main().catch((error) => {
-        handleError(error);
-    });
-}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@commercetools/commerce-mcp",
-  "version": "4.0.0",
+  "version": "4.2.0",
+  "type": "module",
   "mcpName": "io.github.commercetools/commerce-mcp",
   "homepage": "https://github.com/commercetools/commerce-mcp",
   "description": "A command line tool for setting up commercetools MCP server",
-  "bin": "dist/index.js",
+  "bin": "dist/cli.js",
   "files": [
+    "dist/cli.js",
     "dist/index.js",
     "LICENSE",
     "README.md",
@@ -13,18 +15,18 @@
     "package.json"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/server": "^2",
     "colors": "^1.4.0",
     "dotenv": "^17.2.1",
     "mcp-remote": "^0.1.18",
-    "@commercetools/commerce-agent": "4.0.0",
-    "@commercetools/processors": "0.0.0"
+    "@commercetools/commerce-agent": "4.2.0",
+    "@commercetools/processors": "0.1.0"
   },
   "keywords": [
     "mcp",
@@ -59,8 +61,8 @@
     "prebuild": "pnpm --filter @commercetools/processors run build && 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')\"",
+    "dev:run": "nodemon --watch dist dist/cli.js",
+    "build": "tsc && node --input-type=module -e \"import {chmodSync} from 'node:fs'; chmodSync('dist/cli.js', '755')\"",
     "clean": "rm -rf dist",
     "lint": "eslint \"./**/*.ts*\"",
     "prettier": "prettier './**/*.{js,ts,md,html,css}' --write",