commercetools MCP Essentials

Un servidor MCP y conjunto de herramientas para integrarse con las APIs de la plataforma commercetools.

GitHub
13
Prueba este MCPPatrocinado

Documentación

[!IMPORTANT] Commerce MCP se proporciona de forma gratuita como un servicio de acceso anticipado. Nuestro Acuerdo de Nivel de Servicio no se aplica a Commerce MCP, y se proporciona "tal cual".

commercetools MCP Essentials

Este repositorio contiene tanto un servidor MCP (que puedes integrar con muchos clientes MCP) como elementos esenciales de agente que se pueden utilizar desde marcos de trabajo de agentes.

commercetools Model Context Protocol

Configuración

Para ejecutar el servidor MCP de commercetools usando npx, utiliza el siguiente comando:

Client Credentials Authentication (Default)

# To set up all available tools (authType is optional, defaults to client_credentials)
npx -y @commercetools/mcp-essentials --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# Explicitly specify client_credentials (optional)
npx -y @commercetools/mcp-essentials --tools=all --authType=client_credentials --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up all read-only tools
npx -y @commercetools/mcp-essentials --tools=all.read --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL


# To set up specific tools
npx -y @commercetools/mcp-essentials --tools=products.read,products.create --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Access Token Authentication

# To set up all available tools with access token
npx -y @commercetools/mcp-essentials --tools=all --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up all read-only tools with access token
npx -y @commercetools/mcp-essentials --tools=all.read --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Asegúrate de reemplazar CLIENT_ID, CLIENT_SECRET, PROJECT_KEY, AUTH_URL, API_URL y ACCESS_TOKEN con tus valores reales. Si usas el parámetro customerId, reemplaza CUSTOMER_ID con el ID de cliente real. Alternativamente, puedes configurar la API_KEY en tus variables de entorno.

Para ver información sobre cómo desarrollar el servidor MCP, consulta este README.
Para ver información sobre cómo ejecutar localmente el servidor MCP inicializado, consulta este README.

[!IMPORTANT] Para cargar todas las herramientas disponibles, establece --tools=all y --isAdmin=true; todas las herramientas disponibles se cargarán en el servidor MCP. Para limitar el número de herramientas cargadas, establece --tools=all.read para herramientas de solo lectura o --tools=carts.read,quote.create,quote.read,.... Para deshabilitar la carga dinámica de herramientas, establece dynamicToolLoadingThreshold a un valor muy alto, por ejemplo --dynamicToolLoadingThreshold=650.

Para ver información sobre cómo desarrollar el servidor MCP, consulta este README.
Para ver información sobre cómo ejecutar localmente el servidor MCP inicializado, consulta este README.

Consulta nuestra documentación pública oficial para obtener una guía más avanzada y completa sobre cómo aprovechar al máximo nuestras ofertas de MCP.

| Herramienta | Descripción |

| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | products.read | Leer información del producto | | products.create | Crear información del producto | | products.update | Actualizar información del producto | | project.read | Leer información del proyecto | | product-search.read | Buscar productos | | category.read | Leer información de la categoría | | category.create | Crear categoría | | category.update | Actualizar categoría | | channel.read | Leer información del canal | | channel.create | Crear canal | | channel.update | Actualizar información del canal | | product-selection.read | Leer selección de productos | | product-selection.create | Crear selección de productos | | product-selection.update | Actualizar selección de productos | | order.read | Leer información del pedido | | order.create | Crear pedido (desde carrito, cotización, importación) | | order.update | Actualizar información del pedido | | cart.read | Leer información del carrito | | cart.create | Crear carrito | | cart.update | Actualizar información del carrito | | customer.read | Leer información del cliente | | customer.create | Crear cliente | | customer.update | Actualizar información del cliente | | customer-group.read | Leer grupo de clientes | | customer-group.create | Crear grupo de clientes | | customer-group.update | Actualizar grupo de clientes | | quote.read | Leer información de la cotización | | quote.create | Crear cotización | | quote.update | Actualizar información de la cotización | | quote-request.read | Leer solicitud de cotización | | quote-request.create | Crear solicitud de cotización | | quote-request.update | Actualizar solicitud de cotización | | staged-quote.read | Leer cotización en etapas | | staged-quote.create | Crear cotización en etapas | | staged-quote.update | Actualizar cotización en etapas | | standalone-price.read | Leer precio independiente | | standalone-price.create | Crear precio independiente | | standalone-price.update | Actualizar precio independiente | | product-discount.read | Leer descuento de producto | | product-discount.create | Crear descuento de producto | | product-discount.update | Actualizar descuento de producto | | cart-discount.read | Leer descuento de carrito | | cart-discount.create | Crear descuento de carrito | | cart-discount.update | Actualizar descuento de carrito | | discount-code.read | Leer información del código de descuento | | discount-code.create | Crear código de descuento | | discount-code.update | Actualizar información del código de descuento | | product-type.read | Leer tipo de producto | | product-type.create | Crear tipo de producto | | product-type.update | Actualizar tipo de producto | | bulk.create | Crear entidades en lote | | bulk.update | Actualizar entidades en lote | | inventory.read | Leer información de inventario | | inventory.create | Crear inventario | | inventory.update | Actualizar información de inventario | | store.read | Leer tienda | | store.create | Crear tienda | | store.update | Actualizar tienda | | business-unit.read | Leer unidad de negocio | | business-unit.create | Crear unidad de negocio | | business-unit.update | Actualizar unidad de negocio | | payments.read | Leer información de pago | | payments.create | Crear pago | | payments.update | Actualizar información de pago | | tax-category.read | Leer información de la categoría fiscal | | tax-category.create | Crear categoría fiscal | | tax-category.update | Actualizar información de la categoría fiscal | | shipping-methods.read | Leer información del método de envío | | shipping-methods.create | Crear método de envío | | shipping-methods.update | Actualizar información del método de envío | | zones.read | Leer información de la zona | | zones.create | Crear zona | | zones.update | Actualizar información de la zona | | recurring-orders.read | Leer información del pedido recurrente | | recurring-orders.create | Crear pedido recurrente | | recurring-orders.update | Actualizar información del pedido recurrente | | shopping-lists.read | Leer información de la lista de compras | | shopping-lists.create | Crear lista de compras | | shopping-lists.update | Actualizar información de la lista de compras | | extensions.read | Leer información de la extensión | | extensions.create | Crear extensión | | extensions.update | Actualizar información de la extensión | | subscriptions.read | Leer información de la suscripción | | subscriptions.create | Crear suscripción | | subscriptions.update | Actualizar información de la suscripción | | payment-methods.read | Leer información del método de pago | | payment-methods.create | Crear método de pago | | payment-methods.update | Actualizar información del método de pago | | product-tailoring.read | Leer información de adaptación de producto | | product-tailoring.create| Crear adaptación de producto | | product-tailoring.update| Actualizar información de adaptación de producto| | custom-objects.read | Leer información del objeto personalizado | | custom-objects.create | Crear objeto personalizado | | custom-objects.update | Actualizar información del objeto personalizado| | types.read | Leer información del tipo | | types.create | Crear tipo | | types.update | Actualizar información del tipo |

Para ver información sobre cómo desarrollar el servidor MCP, consulta este README.

Carga Dinámica de Herramientas

El servidor MCP incluye una función de carga dinámica de herramientas que cambia automáticamente a una estrategia de carga más eficiente cuando el número de herramientas habilitadas supera un umbral configurable. Esto ayuda a optimizar el rendimiento y reducir el uso de contexto al trabajar con grandes cantidades de herramientas.

Cómo funciona

  • Umbral predeterminado: 30 herramientas
  • Comportamiento: Cuando el número de herramientas habilitadas supera el umbral, el servidor cambia a carga dinámica de herramientas

Configuración

Puedes configurar el umbral de carga dinámica de herramientas de dos maneras:

Argumento de Línea de Comandos

npx -y @commercetools/mcp-essentials --tools=all --dynamicToolLoadingThreshold=50 --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Variable de Entorno

export DYNAMIC_TOOL_LOADING_THRESHOLD=50
npx -y @commercetools/mcp-essentials --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Ejemplo con Claude Desktop

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/mcp-essentials@latest",
        "--tools=all",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL",
        "--dynamicToolLoadingThreshold=25"
      ]
    }
  }
}

MCP Essentials

El commercetools MCP Essentials permite que marcos de agentes populares, incluidos LangChain, el SDK de IA de Vercel y el Protocolo de Contexto de Modelo (MCP), se integren con las APIs mediante llamadas a funciones. La biblioteca no cubre la totalidad de la API de commercetools. Incluye soporte para TypeScript y está construida directamente sobre el SDK de [Node][node-sdk].

A continuación se incluyen instrucciones básicas, pero consulta el paquete TypeScript para obtener más información.

TypeScript

Instalación

No necesitas este código fuente a menos que quieras modificar el paquete. Si solo quieres usar el paquete, ejecuta:

npm install @commercetools/agent-essentials

Requisitos

  • Node 18+

Uso

La biblioteca debe configurarse con las credenciales de tu proyecto commercetools, disponibles en tu Centro de comerciantes. Importante: Asegúrate de que las credenciales del cliente de API tengan los alcances necesarios alineados con las acciones que configures en los agent essentials. Por ejemplo, si configuras products: { read: true }, tu cliente de API debe tener el alcance view_products. Además, configuration te permite especificar los tipos de acciones que se pueden realizar con los agent essentials.

Autenticación con Credenciales de Cliente (Predeterminada)

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/langchain";

const commercetoolsAgentEssentials = await CommercetoolsAgentEssentials.create({
  authConfig: {
    type: 'client_credentials',
    clientId: process.env.CLIENT_ID!,,
    clientSecret: process.env.CLIENT_SECRET!,,
    projectKey: process.env.PROJECT_KEY!,
    authUrl: process.env.AUTH_URL!,
    apiUrl: process.env.API_URL!,
  },
  configuration: {
    actions: {
      products: {
        read: true,
        create: true,
        update: true,
      },
      project: {
        read: true,
      },
    },
  },
});

Autenticación con Token de Acceso

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/langchain";

const commercetoolsAgentEssentials = await CommercetoolsAgentEssentials.create({
  authConfig: {
    type: "auth_token",
    accessToken: process.env.ACCESS_TOKEN!,
    projectKey: process.env.PROJECT_KEY!,
    authUrl: process.env.AUTH_URL!,
    apiUrl: process.env.API_URL!,
  },
  configuration: {
    actions: {
      products: {
        read: true,
        create: true,
        update: true,
      },
      project: {
        read: true,
      },
    },
  },
});

Herramientas

Los agent essentials funcionan con LangChain y el SDK de IA de Vercel y se pueden pasar como una lista de herramientas. Por ejemplo:

import { AgentExecutor, createStructuredChatAgent } from "langchain/agents";

const tools = commercetoolsAgentEssentials.getTools();

const agent = await createStructuredChatAgent({
  llm,
  tools,
  prompt,
});

const agentExecutor = new AgentExecutor({
  agent,
  tools,
});

Model Context Protocol

El commercetools MCP Essentials también admite la configuración de tu propio servidor MCP. Por ejemplo:

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsAgentEssentials.create({
  authConfig: {
    type: 'client_credentials',
    clientId: process.env.CLIENT_ID!,,
    clientSecret: process.env.CLIENT_SECRET!,,
    projectKey: process.env.PROJECT_KEY!,
    authUrl: process.env.AUTH_URL!,
    apiUrl: process.env.API_URL!,
  },
  configuration: {
    actions: {
      products: {
        read: true,
      },
      cart: {
        read: true,
        create: true,
        update: true,
      },
    },
  },
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("My custom commercetools MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

getTools()

Devuelve el conjunto actual de herramientas disponibles que se pueden usar con LangChain, AI SDK u otros marcos de agentes:

const tools = commercetoolsAgentEssentials.getTools();

Herramientas Personalizadas

El @commercetools/agent-essentials autogestionado incluye soporte para herramientas personalizadas. Se puede pasar una lista de implementaciones de herramientas personalizadas y registrarlas en tiempo de ejecución mediante el servidor MCP de arranque. Esto es especialmente útil cuando la herramienta deseada aún no está implementada en MCP Essentials o para dar a los usuarios control total y personalización del comportamiento de sus herramientas y cómo interactúan con el LLM subyacente.

uso

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsAgentEssentials.create({
  authConfig: {...},
  configuration: {
    customTools: [
      {
        name: "Get Project",
        method: "get_project",
        description: `This tool will fetch information about a commercetools project.\n\n
           This tool will accept a project and fetch information about the provided key. \n\n
          `, // It is important that this description is well details and explicitly descripts what this tool does and the paramenters it receieves/
        parameters: z.object({
          projectKey: z
            .string()
            .optional()
            .describe(
              "The key of the project to read. If not provided, the current project will be used."
            ),
        }),
        actions: {},
        execute: async (args: { projectKey: string }, api: ApiRoot) => {
          // already existing functions can be used here e.g const response = await import('ctService').getProject('demo-project-key-a7fc1182');
          const response = await api.withProjectKey(args).get().execute();
          return JSON.stringify(response);
        },
      },
      ...
    ],
    actions: {...},
  },
});
...

Servidor MCP HTTP Streamable

A partir de la versión v2.0.0 del servidor MCP @commercetools/mcp-essentials, ahora se admite el servidor HTTP Streamable (remoto).

npx -y @commercetools/mcp-essentials \
  --tools=all \
  --authType=client_credentials \
  --clientId=CLIENT_ID \
  --clientSecret=CLIENT_SECRET \
  --projectKey=PROJECT_KEY \
  --authUrl=AUTH_URL \
  --apiUrl=API_URL \
  --remote=true \
  --stateless=true \
  --port=8888

Puede conectarse al servidor remoto en ejecución usando Claude especificando lo siguiente en el archivo claude_desktop_config.json.

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8888/mcp", "..."]
    }
  }
}

También puede usar el servidor HTTP Streamable con Agent Essentials como un SDK y desarrollar sobre él.

import express from "express";
import {
  CommercetoolsAgentEssentials,
  CommercetoolsAgentEssentialsStreamable,
} from "@commercetools/agent-essentials/modelcontextprotocol";

const expressApp = express();

const getAgentServer = async () => {
  return CommercetoolsAgentEssentials.create({
    authConfig: {
      type: "client_credentials",
      clientId: process.env.CLIENT_ID!,
      clientSecret: process.env.CLIENT_SECRET!,
      projectKey: process.env.PROJECT_KEY!,
      authUrl: process.env.AUTH_URL!,
      apiUrl: process.env.API_URL!,
    },
    configuration: {
      actions: {
        products: {
          read: true,
        },
        cart: {
          read: true,
          create: true,
          update: true,
        },
      },
    },
  });
};

const serverStreamable = new CommercetoolsAgentEssentialsStreamable({
  stateless: false, // make the MCP server stateless/stateful
  server: getAgentServer,
  app: expressApp, // optional express app instance
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
});

serverStreamable.listen(8888, function () {
  console.log("listening on 8888");
});

Sin usar el CommercetoolsAgentEssentials, puede usar directamente solo la clase CommercetoolsAgentEssentialsStreamable y el servidor de agente se iniciará internamente.

import { CommercetoolsAgentEssentialsStreamable } from "@commercetools/agent-essentials/modelcontextprotocol";
import express from "express";

const expressApp = express();

const server = new CommercetoolsAgentEssentialsStreamable({
  authConfig: {
    type: "client_credentials",
    clientId: process.env.CLIENT_ID!,
    clientSecret: process.env.CLIENT_SECRET!,
    projectKey: process.env.PROJECT_KEY!,
    authUrl: process.env.AUTH_URL!,
    apiUrl: process.env.API_URL!,
  },
  configuration: {
    actions: {
      project: {
        read: true,
      },
      // other tools can go here
    },
  },

  stateless: false,
  app: expressApp,
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
});

server.listen(8888, function () {
  console.log("listening on 8888");
});