Cursor rule

1---
2description: Creating a New tool Function in @commercetools/agent-essentials
3globs: 
4alwaysApply: false
5---
6# Creating a New namespace tool Function in @commercetools/agent-essentials
7 
8This document outlines the steps taken to implement a new function in @commercetools/agent-essentials to connect to commercetools API.
9 
10The following steps are defining implementation of an example `products.create`. So the `(namespace)` here refers to `product`.
11 
12## Implementation Steps
13 
141. Gather info regarding the (namespace)
15  - Search commercetools docs at https://docs.commercetools.com/api and find the (namespace)
16  - In this example `https://docs.commercetools.com/api/projects/products` and ProductDraft 
17 
182. Define Parameter Schema
19   - Using the namespace fetched in previous step , Created `createProductParameters` in `typescript/src/shared/(namespace)/parameters.ts`
20   - Used Zod for type validation
21   - Included all required and optional fields from ProductDraft
22   - Created a separate `productVariantDraft` schema for reusability
23 
243. Create a `base.functions.ts` file in the `namespace` directory. This file will export a couple of basic CRUD functions that will be used inside other files in this namespace. you can extract this base functions from current `functions.ts` file in the namespace.
25    - IMPORTANT: base functions should be generic as possible, e.g. instead of having a separate function for query cart for a specific user and another one for user in a store, we create one that accepts a "where" clause.
26    - 3.1: sometimes the commercetools SDK has different endpoint when a parameter is present, like query in store (look to the code sample below). in that case, we check that parameter inside the base function but keep the function as simple as possible and low complexity.
27    - 3.2: No delete operation.
28    - 3.3: in the base update, call the base get function to fetch the version from the entity and use it in the update call.
29    - GOAL: the goal of this step is maximize reusability.
30    - example: base functions created for 'cart.read' are: readCartById, readCartByKey, queryCart, queryCarts.
31    - file example: `typescript/src/shared/cart/base.functions.ts`
32     ***IMPORTANT***: functions.ts usually exports 3 functions: read, create and update. If there are more ways to read the entity (by id or key or query), embed all in one "read" exported function and adjust the parameters and prompts as well.
33 
34    - code sample:
35 
36```ts
37    const queryCart = async (
38        apiRoot: ApiRoot,
39        projectKey: string,
40        queryArgs: any,
41        storeKey?: string
42        ) => {
43        if (storeKey) {
44            const carts = await apiRoot
45            .withProjectKey({projectKey})
46            .inStoreKeyWithStoreKeyValue({storeKey})
47            .carts()
48            .get({queryArgs})
49            .execute();
50            return carts.body;
51        }
52        const carts = await apiRoot
53            .withProjectKey({projectKey})
54            .carts()
55            .get({queryArgs})
56            .execute();
57        return carts.body;
58        };
59```
604. Create a `customer.functions.ts` in the namespace directory. This file, uses `base.functions.ts`. it has CRUD functions when `context.customerId` is present.
61    - GOAL: these functions are to limit the operations to the specific customerId.
62    - Note: Double check so there is no usage of `apiRoot.withProjectKey(...)` in this file since all actuall sdk api-calls should be in base.functions.ts 
63    - example: when querying carts, it should always inject `context.customerId` to the query. If not possible, it should check the entity after it's fetched.
64    - file example: `typescript/src/shared/cart/customer.functions.ts`
65 
665. Create a `store.functions.ts` in the namespace directory. This file, uses `base.functions.ts`. it has CRUD functions when `context.storeKey` is present.
67    - GOAL: these functions are to limit the operations to the specific store.
68    - Note: Double check so there is no usage of `apiRoot.withProjectKey(...)` in this file since all actuall sdk api-calls should be in base.functions.ts
69    - example: Limit carts fetched to a store.
70 
716. Create a `associate.functions.ts` in the namespace directory. This file, uses `base.functions.ts`. it has CRUD functions when `context.customerId` and `context.businessUnitKey` are present.
72    - GOAL: these functions are to limit the operations to as-associate endpoints.
73    - Note: Double check so there is no usage of `apiRoot.withProjectKey(...)` in this file since all actuall sdk api-calls should be in base.functions.ts
74 
757. Create a `admin.functions.ts` in the namespace directory. This file, uses `base.functions.ts`. it has CRUD functions when `context.isAdmin` is present.
76    - GOAL: these functions doesn't have any limitations.
77    - Note: Double check so there is no usage of `apiRoot.withProjectKey(...)` in this file since all actuall sdk api-calls should be in base.functions.ts
78    - file example: `typescript/src/shared/cart/admin.functions.ts`
79 
808. Create `functions.ts` to import all exported methods from customer, admin and store. create a method called `contextTo<namespace>FunctionMapping` which accepts the context and returns an object of name to method mapping.
81    - IMPORTANT: if no context is there, empty object should return
82    - IMPORTANT: use type `Context` from `typescript/src/types/configuration.ts`
83    - example: 
84```ts
85    export const contextToCartFunctionMapping = (context?: Context) => {
86        if (context?.customerId && context?.businessUnitKey) {
87            return {
88            read_cart: associate.readCart,
89             create_cart: associate.createCart,
90             update_cart: customer.updateCart,
91             replicate_cart: associate.replicateCart,
92            };
93        }
94        if (context?.customerId) {
95            return {
96            read_cart: customer.readCart,
97             create_cart: customer.createCart,
98             update_cart: customer.updateCart,
99             replicate_cart: customer.replicateCart,
100            };
101        }
102        if (context?.storeKey) {
103            return {
104            read_cart: store.readCart,
105             create_cart: store.createCart,
106             update_cart: store.updateCart,
107             replicate_cart: store.replicateCart,
108            };
109        }
110        if (context?.isAdmin) { // IMPORTANT
111            return {
112                read_cart: admin.readCart,
113                 create_cart: admin.createAdminCart,
114                 update_cart: admin.updateAdminCart,
115                 replicate_cart: admin.replicateAdminCart,
116            };
117        }
118        return {};
119        };
120```
1219. refactor `typescript/src/shared/functions.ts` and import `import {contextToCartFunctionMapping} from './cart/functions';` then update  this method return 
122 
123 
12410. Create Prompt
125  - Create a prompt describing the function and its' params in `typescript/src/shared/(namespace)/prompts.ts`
126  - Prompts for create functions across `customer`, `store` and `admin` should be the same. same for other functions 
127 
128Refactor `const tools: Tool[]` to const tools: Record<string, Tool>
129    - example
130```
131    const tools: Record<string, Tool> = {}
132        read_category: {
133            method: 'read_category',
134            name: 'Read Category',
135            description: readCategoryPrompt,
136            parameters: readCategoryParameters,
137            actions: {
138            category: {
139                read: true,
140            },
141            },
142        }
143        ...
144```
14511. Create `typescript/src/shared/(namespace)/tools.ts` and export a method `contextToC<namespace>>Tools`. The method's return has to reflect the `typescript/src/shared/(namespae)/functions.ts` 's `contextTo<namespace>FunctionMapping` output
146    - example: 
147```ts
148    export const contextToCategoryTools = (context?: Context) => {
149        if (context?.customerId && context?.businessUnitKey) {
150            return [tools.read_category, tools.create_category, tools.update_category]
151        }
152        if (context?.customerId) {
153            return [tools.read_category]
154        }
155        if (context?.storeKey) {
156            return []
157        }
158        if (context?.isAdmin) { 
159            return [tools.read_category, tools.create_category, tools.update_category]
160        }
161        return { // IMPORTANT: usually fallback return is empty only exceptions are filled.
162            []
163        }
164        };
165```
16612. Modify `typescript/src/shared/tools.ts`
167```
168    export const contextToTools = (context?: Context) => {
169        return {
170            ...contextToCategoryTools(context)
171        }
172    }
173```
174 
17513. Add new tool to ACCEPTED_TOOLS
176   - add too to `modelcontextprotocol/src/index.ts`'s ACCEPTED_TOOLS
177 
17814. Add new tool to "bulk.create" functions.
179    - Bulk function always use admin.functions
180    - create the mapping in `typescript/src/shared/bulk/functions.ts` > `entityFunctionMap`
181    - add the new namespace's parameter to `typescript/src/shared/bulk/parameters.ts`
182    - modify bulk prompt to include the new entity `typescript/src/shared/bulk/prompts.ts`
183 
18415. Test Implementation
185   - Created `createProduct.test.ts` in test directory
186   - Implemented mock ApiRoot for testing
187   - Added test cases for successful creation
188   - Added test cases for error handling
189   - Create test cases for success and error of the new tools in `modelcontextprotocol/src/test/main.test.ts`. These tests are only checking if `CommercetoolsAgentToolkit` and `StdioServerTransport` are being called with correct params
190   example
191```
192      it('should initialize the server with specific tools correctly', async () => {
193         process.argv = [
194            'node',
195            'index.js',
196            '--tools=products.create', // new function tool
197            '--clientId=test_client_id',
198            '--clientSecret=test_client_secret',
199            '--authUrl=https://auth.commercetools.com',
200            '--projectKey=test_project',
201            '--apiUrl=https://api.commercetools.com',
202         ];
203 
204         await main();
205 
206         expect(CommercetoolsAgentToolkit).toHaveBeenCalledWith({
207            clientId: 'test_client_id',
208            clientSecret: 'test_client_secret',
209            authUrl: 'https://auth.commercetools.com',
210            projectKey: 'test_project',
211            apiUrl: 'https://api.commercetools.com',
212            configuration: {actions: {products: {create: true}}}, // new function tool
213         });
214 
215         expect(StdioServerTransport).toHaveBeenCalled();
216      });
217```
218  - create a test case to bulk namespace `typescript/src/shared/bulk/test/bulkCreate.test.ts`
219  - Update `modelcontextprotocol/src/test/main.test.ts` test and include new tool in the test `should initialize the server with tools=all correctly`
220 
22116. Update README.md:
222  - add new tool(s) to Available tools table in `modelcontextprotocol/README.md` 
223  - add new tool's api documentation in commercetools to `README.md`
224