Skip to content

Commit ff09d10

Browse files
ajimaeajimae
authored
[Chore] Improve Docs (#46)
1 parent faf3a23 commit ff09d10

5 files changed

Lines changed: 329 additions & 22 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,13 @@ npx -y @commercetools/mcp-essentials --tools=all.read --authType=auth_token --ac
4242

4343
Make sure to replace `CLIENT_ID`, `CLIENT_SECRET`, `PROJECT_KEY`, `AUTH_URL`, `API_URL`, and `ACCESS_TOKEN` with your actual values. If using the customerId parameter, replace `CUSTOMER_ID` with the actual customer ID. Alternatively, you could set the API_KEY in your environment variables.
4444

45+
To view information on how to develop the MCP server, see [this README](/typescript/README.md).<br>
46+
To view information on how to locally run the bootstrapped MCP server, see [this README](/modelcontextprotocol/README.md).
47+
48+
49+
Refer to our [official public documentation](https://docs.commercetools.com/sdk/commerce-mcp/essentials-mcp) for a more advanced and comprehensive guide on how to get the most out of our MCP offerings.
50+
51+
<!--
4552
### Authentication Options
4653
4754
The MCP server supports two authentication methods:

‎typescript/README.md‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,13 @@
55
You don't need this source code unless you want to modify the package. If you just
66
want to use the package run:
77

8+
```bash
9+
yarn install @commercetools/agent-essentials
810
```
11+
12+
or using `npm` package manager
13+
14+
```bash
915
npm install @commercetools/agent-essentials
1016
```
1117

@@ -14,3 +20,292 @@ The commercetools MCP Essentials enables popular agent frameworks including Lang
1420
### Requirements
1521

1622
- Node 18+
23+
24+
# Essentials Libraries
25+
26+
## Agent Essentials
27+
28+
The commercetools Agent Essentials can be used to bootstrap a custom MCP server.
29+
30+
Example:
31+
32+
```typescript
33+
import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/modelcontextprotocol";
34+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
35+
36+
const server = await CommercetoolsAgentEssentials.create({
37+
authConfig: {
38+
type: 'client_credentials',
39+
clientId: process.env.CLIENT_ID!,,
40+
clientSecret: process.env.CLIENT_SECRET!,,
41+
projectKey: process.env.PROJECT_KEY!,
42+
authUrl: process.env.AUTH_URL!,
43+
apiUrl: process.env.API_URL!,
44+
},
45+
configuration: {
46+
actions: {
47+
products: {
48+
read: true,
49+
},
50+
cart: {
51+
read: true,
52+
create: true,
53+
update: true,
54+
},
55+
},
56+
},
57+
});
58+
59+
async function main() {
60+
const transport = new StdioServerTransport();
61+
await server.connect(transport);
62+
console.error("My custom commercetools MCP Server running on stdio");
63+
}
64+
65+
main().catch((error) => {
66+
console.error("Fatal error in main():", error);
67+
process.exit(1);
68+
});
69+
```
70+
71+
## AI SDK
72+
73+
This is used to execute a specific prompts using a specific model (in this case the OpenAI 4o model)
74+
75+
Example:
76+
77+
```typescript
78+
import {generateText} from 'ai';
79+
import {openai} from '@ai-sdk/openai';
80+
import {CommercetoolsAgentEssentials} from '@commercetools/agent-essentials/ai-sdk';
81+
82+
const commercetoolsAgentEssentials = await CommercetoolsAgentEssentials({
83+
authConfig: {
84+
type: 'client_credentials',
85+
clientId: process.env.CLIENT_ID!,,
86+
clientSecret: process.env.CLIENT_SECRET!,,
87+
projectKey: process.env.PROJECT_KEY!,
88+
authUrl: process.env.AUTH_URL!,
89+
apiUrl: process.env.API_URL!,
90+
},
91+
configuration: {
92+
actions: {
93+
products: {
94+
read: true,
95+
},
96+
cart: {
97+
read: true,
98+
create: true,
99+
update: true,
100+
},
101+
},
102+
},
103+
});
104+
105+
const model = openai('gpt-4o');
106+
const tools = commercetoolsAgentEssentials.getTools();
107+
108+
(async function () {
109+
console.log('--- Starting commercetools AI SDK Task Sequence ---');
110+
// Original Task: List all products
111+
const initialPrompt = 'List all products in the commercetools project. This is the first step.';
112+
console.log(`\\nExecuting: ${initialPrompt}`);
113+
114+
const resultInitial = await generateText({
115+
model: model,
116+
tools: {...tools},
117+
prompt: initialPrompt,
118+
maxSteps: 5
119+
});
120+
121+
console.log('--- Response from "List all products" ---');
122+
console.log(resultInitial.text);
123+
console.log(
124+
'--------------------------------------------------------------------------------'
125+
);
126+
})();
127+
```
128+
129+
## LangChain
130+
131+
The langchain essentials library helps to setup an agent using a specific model suitable for machine to machine communication or for chatbot development/integration.
132+
133+
Example:
134+
135+
```typescript
136+
import {AgentExecutor, createStructuredChatAgent} from 'langchain/agents';
137+
import {CommercetoolsAgentEssentials} from '@commercetools/agent-essentials/langchain';
138+
139+
const commercetoolsAgentEssentials = await CommercetoolsAgentEssentials({
140+
authConfig: {
141+
type: 'auth_token',
142+
accessToken: process.env.ACCESS_TOKEN!,
143+
projectKey: process.env.PROJECT_KEY!,
144+
authUrl: process.env.AUTH_URL!,
145+
apiUrl: process.env.API_URL!,
146+
},
147+
configuration: {
148+
actions: {
149+
products: {
150+
read: true,
151+
create: true,
152+
update: true,
153+
},
154+
project: {
155+
read: true,
156+
},
157+
},
158+
},
159+
});
160+
161+
const tools = commercetoolsAgentEssentials.getTools();
162+
const agent = await createStructuredChatAgent({
163+
llm,
164+
tools,
165+
prompt,
166+
});
167+
168+
const agentExecutor = new AgentExecutor({
169+
agent,
170+
tools,
171+
});
172+
```
173+
174+
## Mastra
175+
176+
Just like the `@commercetools/agent-essentials/ai-sdk` the `@commercetools/agent-essentials/mastra` essentials library can be used to execute multi-step commands/prompts.
177+
178+
Example:
179+
180+
```typescript
181+
require('dotenv').config();
182+
import {Agent} from '@mastra/core/agent';
183+
import {CommercetoolsAgentEssentials} from '@commercetools/agent-essentials/mastra';
184+
185+
const commercetoolsAgentEssentials = new CommercetoolsAgentEssentials({
186+
authConfig: {
187+
type: 'client_credentials',
188+
clientId: process.env.CLIENT_ID!,
189+
clientSecret: process.env.CLIENT_SECRET!,
190+
authUrl: process.env.AUTH_URL!,
191+
projectKey: process.env.PROJECT_KEY!,
192+
apiUrl: process.env.API_URL!,
193+
},
194+
configuration: {
195+
actions: {
196+
products: {
197+
read: true,
198+
create: true,
199+
update: true,
200+
},
201+
'product-type': {
202+
read: true,
203+
create: true,
204+
},
205+
},
206+
},
207+
});
208+
209+
const agent = new Agent({
210+
name: 'CommercetoolsAgent',
211+
instructions:
212+
'You are a helpful agent that can manage products and product types in commercetools. Use the available tools to help users with their commerce operations.',
213+
tools: commercetoolsAgentEssentials.getTools(),
214+
});
215+
216+
(async () => {
217+
console.log('--- Starting Commercetools Mastra Agent Task Sequence ---');
218+
219+
// Task 1: List all products
220+
const task1Prompt =
221+
'List all products in the commercetools project. This is the first step.';
222+
console.log(`\nExecuting: ${task1Prompt}`);
223+
const result1 = await agent.step({
224+
messages: [
225+
{
226+
role: 'user',
227+
content: task1Prompt,
228+
},
229+
],
230+
});
231+
console.log('--- Response from "List all products" ---');
232+
console.log(result1.text);
233+
console.log(
234+
'--------------------------------------------------------------------------------'
235+
);
236+
237+
// Task 2: List product types
238+
const task2Prompt = `Based on the products listed above, list all product types available in the project. I need this information to select a product type for creating a product in the next step.`;
239+
console.log(`\nExecuting: ${task2Prompt}`);
240+
const result2 = await agent.step({
241+
messages: [
242+
...result1.messages,
243+
{
244+
role: 'user',
245+
content: task2Prompt,
246+
},
247+
],
248+
});
249+
console.log('--- Response from "List product types" (Task 2) ---');
250+
console.log(result2.text);
251+
console.log(
252+
'--------------------------------------------------------------------------------'
253+
);
254+
255+
// Task 3: Create a test product
256+
const productName = `Mastra Test Product ${Math.floor(Date.now() / 1000)}`;
257+
const productKey = `MASTRA-${Math.random().toString(36).substring(2, 9).toUpperCase()}`;
258+
const productSku = `MTP-${Math.random().toString(36).substring(2, 9).toUpperCase()}`;
259+
const productSlug = productName.toLowerCase().replace(/\s+/g, '-');
260+
261+
const task3Prompt = `Based on the product types listed above, please create a new product with the following details:
262+
- Name: "${productName}"
263+
- Key: "${productKey}"
264+
- Slug (en): "${productSlug}"
265+
- SKU: "${productSku}"
266+
- Description: "This product was created automatically by a Mastra AI agent."
267+
- Ensure the product is published if possible during creation.
268+
269+
Please provide the ID of this newly created product in your response.`;
270+
console.log(`\nExecuting: ${task3Prompt}`);
271+
const result3 = await agent.step({
272+
messages: [
273+
...result2.messages,
274+
{
275+
role: 'user',
276+
content: task3Prompt,
277+
},
278+
],
279+
});
280+
console.log('--- Response from "Create test product" (Task 3) ---');
281+
console.log(result3.text);
282+
console.log(
283+
'--------------------------------------------------------------------------------'
284+
);
285+
286+
// Task 4: Update the product
287+
const updateDescription =
288+
'This product was created and then updated automatically by a Mastra AI agent.';
289+
const task4Prompt = `Using the ID of the product that was just created (from the previous step), please update it.
290+
Change its description to "${updateDescription}"`;
291+
console.log(`\nExecuting: ${task4Prompt}`);
292+
const result4 = await agent.step({
293+
messages: [
294+
...result3.messages,
295+
{
296+
role: 'user',
297+
content: task4Prompt,
298+
},
299+
],
300+
});
301+
console.log('--- Response from "Update the product" (Task 4) ---');
302+
console.log(result4.text);
303+
console.log(
304+
'--------------------------------------------------------------------------------'
305+
);
306+
307+
console.log('\n--- Commercetools Mastra Agent Task Sequence Finished ---');
308+
})().catch((error) => {
309+
console.error('An error occurred during the async execution:', error);
310+
});
311+
```

‎typescript/examples/ai-sdk/index.ts‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,15 @@ import {generateText} from 'ai';
44

55
require('dotenv').config();
66

7-
const CommercetoolsAgentEssentials = new CommercetoolsAgentEssentials({
8-
clientId: process.env.CLIENT_ID!,
9-
clientSecret: process.env.CLIENT_SECRET!,
10-
authUrl: process.env.AUTH_URL!,
11-
projectKey: process.env.PROJECT_KEY!,
12-
apiUrl: process.env.API_URL!,
7+
const commercetoolsAgentEssentials = new CommercetoolsAgentEssentials({
8+
authConfig: {
9+
type: 'client_credentials',
10+
clientId: process.env.CLIENT_ID!,
11+
clientSecret: process.env.CLIENT_SECRET!,
12+
authUrl: process.env.AUTH_URL!,
13+
projectKey: process.env.PROJECT_KEY!,
14+
apiUrl: process.env.API_URL!,
15+
},
1316
configuration: {
1417
actions: {
1518
products: {
@@ -36,7 +39,7 @@ const model = openai('gpt-4o');
3639
console.log(`\\nExecuting: ${initialPrompt}`);
3740
const resultInitial = await generateText({
3841
model: model,
39-
tools: {...CommercetoolsAgentEssentials.getTools()},
42+
tools: {...commercetoolsAgentEssentials.getTools()},
4043
maxSteps: 5,
4144
prompt: initialPrompt,
4245
});

‎typescript/examples/langchain/index.ts‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,15 @@ const llm = new ChatOpenAI({
1212
temperature: 0,
1313
});
1414

15-
const CommercetoolsAgentEssentials = new CommercetoolsAgentEssentials({
16-
clientId: process.env.CLIENT_ID!,
17-
clientSecret: process.env.CLIENT_SECRET!,
18-
authUrl: process.env.AUTH_URL!,
19-
projectKey: process.env.PROJECT_KEY!,
20-
apiUrl: process.env.API_URL!,
15+
const commercetoolsAgentEssentials = new CommercetoolsAgentEssentials({
16+
authConfig: {
17+
type: 'client_credentials',
18+
clientId: process.env.CLIENT_ID!,
19+
clientSecret: process.env.CLIENT_SECRET!,
20+
authUrl: process.env.AUTH_URL!,
21+
projectKey: process.env.PROJECT_KEY!,
22+
apiUrl: process.env.API_URL!,
23+
},
2124
configuration: {
2225
actions: {
2326
products: {
@@ -42,7 +45,7 @@ const CommercetoolsAgentEssentials = new CommercetoolsAgentEssentials({
4245
'hwchase17/structured-chat-agent'
4346
);
4447

45-
const tools = CommercetoolsAgentEssentials.getTools();
48+
const tools = commercetoolsAgentEssentials.getTools();
4649

4750
const agent = await createStructuredChatAgent({
4851
llm,

0 commit comments

Comments
 (0)