@leonar2cp/ct-agent-toolkit NPM

NOTE: This is NOT an official commercetools code and NOT production ready. Use it at your own risk

Agent Toolkit

The commercetools Agent Toolkit enables popular agent frameworks including LangChain, Vercel's AI SDK, and Model Context Protocol (MCP) to integrate with APIs through function calling. The library is not exhaustive of the entire commercetools API. It includes support for TypeScript and is built directly on top of the Node SDK.

Included below are basic instructions, but refer to the TypeScript package for more information.

TypeScript

Installation

You don't need this source code unless you want to modify the package. If you just want to use the package run:

npm install @commercetools-demo/ct-agent-toolkit

Requirements

Node 18+

Usage

The library needs to be configured with your commercetools project API client credentials which is available in your Merchant center. Important: Ensure that the API client credentials have the necessary scopes aligned with the actions you configure in the toolkit. For example, if you configure products: { read: true }, your API client must have the view_products scope. Additionally, configuration enables you to specify the types of actions that can be taken using the toolkit.

import { CommercetoolsAgentToolkit } from "@commercetools-demo/ct-agent-toolkit/langchain";

const commercetoolsAgentToolkit = new CommercetoolsAgentToolkit({
  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,
      },
      'product-search': {
        read: true,
      },
      cart: {
        read: true,
        create: true,
        update: true,
      },
    },
  },
});

Tools

The toolkit works with LangChain and Vercel's AI SDK and can be passed as a list of tools. For example:

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

const tools = commercetoolsAgentToolkit.getTools();

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

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

Context

In some cases you will want to provide values that serve as defaults when making requests. Currently, the account context value enables you to make API calls for your connected accounts.

const commercetoolsAgentToolkit = new CommercetoolsAgentToolkit({
  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: {
    context: {
      account: "acct_123",
    },
  },
});

Model Context Protocol

The commercetools Agent Toolkit also supports the Model Context Protocol (MCP).

If you prefer to install the MCP package directly (for example, to run it via a script or manage it as a project dependency), you can use:

npm install @commercetools-demo/mcp

Then, you might need to configure your PATH or use npx @commercetools-demo/mcp ... to run it.

To run the commercetools MCP server directly using npx (which handles downloading the package if needed), use the following command:

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

Replace CLIENT_ID, CLIENT_SECRET, PROJECT_KEY, AUTH_URL, and API_URL with your actual values. Or, you could set the API_SECRET_KEY in your environment variables.

Alternatively, you can set up your own MCP server. For example:

import { CommercetoolsAgentToolkit } from "@commercetools-demo/ct-agent-toolkit/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new CommercetoolsAgentToolkit({
  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("Commercetools MCP Server running on stdio");
}

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

Supported API methods

@commercetools/platform-sdk @commercetools/ts-client

1.0.2

6 months ago

1.0.1

7 months ago

1.0.0

7 months ago