@commercetools/commerce-mcp 4.1.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,18 +1,11 @@
 #!/usr/bin/env node
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-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 = __importDefault(require("colors"));
-const red = colors_1.default.red;
-const yellow = colors_1.default.yellow;
+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',
@@ -32,11 +25,8 @@ const PUBLIC_ARGS = [
     '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) => {
@@ -130,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
@@ -148,7 +138,7 @@ 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 || modelcontextprotocol_1.DEFAULT_HOST;
+    env.host = env.host || process.env.HOST || DEFAULT_HOST;
     env.allowedHosts =
         env.allowedHosts || splitList(process.env.ALLOWED_HOSTS) || undefined;
     env.allowedOrigins =
@@ -299,7 +289,7 @@ function splitList(value) {
  * in front of a proxy, a container hostname, ...).
  */
 function resolveAllowedHosts(env) {
-    const hosts = new Set([...modelcontextprotocol_1.LOOPBACK_HOSTNAMES, ...(env.allowedHosts ?? [])]);
+    const hosts = new Set([...LOOPBACK_HOSTNAMES, ...(env.allowedHosts ?? [])]);
     const host = env.host;
     if (host && !isWildcardHost(host)) {
         hosts.add(host);
@@ -333,6 +323,26 @@ function warnIfPubliclyBound(host) {
         `   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;
@@ -343,12 +353,12 @@ function onServerError(server, listener) {
     if (typeof on === 'function')
         on.call(server, 'error', listener);
 }
-function handleError(error) {
+export function handleError(error) {
     console.error(red('\n🚨  Error initializing commercetools MCP server:\n'));
     console.error(yellow(`   ${error.message}\n`));
 }
-async function main() {
-    require('dotenv').config({ quiet: true });
+export async function main() {
+    dotenv.config({ quiet: true });
     const { options, env } = parseArgs(process.argv.slice(2));
     // Create the CommercetoolsCommerceAgent instance
     const selectedTools = options.tools;
@@ -364,34 +374,32 @@ 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,
             allowedHosts: resolveAllowedHosts(env),
             allowedOrigins: env.allowedOrigins,
-            streamableHttpOptions: {
-                sessionIdGenerator: undefined,
-            },
         });
         const port = env.port || 8080;
         // `*` and an empty value mean "every interface"; the OS needs 0.0.0.0.
-        const host = (0, modelcontextprotocol_1.normalizeBindHost)(env.host);
+        const host = normalizeBindHost(env.host);
         warnIfPubliclyBound(host);
         /**
          * Kept in a holder so the listen callback can read the server without a
@@ -421,13 +429,8 @@ async function main() {
     }
     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.1.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.1.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",