Resource response data transformation to tabular-like LLM formatting, with command-line flag to revert back to JSON.

Co-authored-by: Ajima Chukwuemeka <32770340+ajimae@users.noreply.github.com>

Author: Trackerchum

.changeset/mean-carrots-grab.md

@@ -0,0 +1,6 @@
+---
+"@commercetools/agent-essentials": minor
+"@commercetools/mcp-essentials": minor
+---
+
+Resource response data transformation to tabular-like LLM formatting, with command-line flag to revert back to JSON.

modelcontextprotocol/src/index.ts

@@ -19,6 +19,7 @@ type Options = {
   businessUnitKey?: string;
   dynamicToolLoadingThreshold?: number;
   logging?: boolean;
+  toolOutputFormat?: 'json' | 'tabular';
 };
 
 type EnvVars = {
@@ -47,6 +48,7 @@ const PUBLIC_ARGS = [
   'projectKey',
   'apiUrl',
   'dynamicToolLoadingThreshold',
+  'toolOutputFormat',
 ];
 
 const ACCEPTED_ARGS = [...PUBLIC_ARGS, ...HIDDEN_ARGS];
@@ -176,6 +178,7 @@ export function parseArgs(args: string[]): {options: Options; env: EnvVars} {
   const options: Options = {};
   const env: EnvVars = {};
 
+  // eslint-disable-next-line complexity
   args.forEach((arg) => {
     if (arg.startsWith('--')) {
       const [key, value] = arg.slice(2).split('=');
@@ -208,6 +211,10 @@ export function parseArgs(args: string[]): {options: Options; env: EnvVars} {
         options.isAdmin = value === 'true';
       } else if (key == 'dynamicToolLoadingThreshold') {
         options.dynamicToolLoadingThreshold = Number(value);
+      } else if (key == 'toolOutputFormat') {
+        if (value === 'json' || value === 'tabular') {
+          options.toolOutputFormat = value;
+        }
       } else if (key == 'logging') {
         options.logging = value == 'true';
       } else if (key == 'cartId') {
@@ -276,6 +283,15 @@ export function parseArgs(args: string[]): {options: Options; env: EnvVars} {
     (process.env.DYNAMIC_TOOL_LOADING_THRESHOLD
       ? Number(process.env.DYNAMIC_TOOL_LOADING_THRESHOLD)
       : undefined);
+
+  if (
+    (process.env.TOOL_OUTPUT_FORMAT &&
+      process.env.TOOL_OUTPUT_FORMAT === 'tabular') ||
+    process.env.TOOL_OUTPUT_FORMAT === 'json'
+  ) {
+    options.toolOutputFormat = process.env.TOOL_OUTPUT_FORMAT;
+  }
+
   options.cartId = options.cartId || process.env.CART_ID;
 
   // Validate required commercetools credentials based on auth type
@@ -357,6 +373,7 @@ export async function main() {
       customerId: options.customerId,
       isAdmin: options.isAdmin,
       dynamicToolLoadingThreshold: options.dynamicToolLoadingThreshold,
+      toolOutputFormat: options.toolOutputFormat,
       cartId: options.cartId,
       storeKey: options.storeKey,
       businessUnitKey: options.businessUnitKey,

typescript/jest.config.ts

@@ -4,7 +4,7 @@ const config: Config = {
   preset: 'ts-jest',
   testEnvironment: 'node',
   roots: ['<rootDir>/src'],
-  testMatch: ['**/__tests__/**/*.ts?(x)', '**/test/**/*.ts?(x)'],
+  testMatch: ['**/__tests__/**/*.test.ts?(x)', '**/test/**/*.test.ts?(x)'],
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
   collectCoverage: true,
   coverageDirectory: 'coverage',

typescript/package.json

@@ -11,7 +11,8 @@
     "prettier": "prettier './**/*.{js,ts,md,html,css}' --write",
     "prettier-check": "prettier './**/*.{js,ts,md,html,css}' --check",
     "validate": "pnpm run lint --fix && pnpm run prettier && pnpm run test",
-    "test": "jest"
+    "test": "jest",
+    "test:watch": "jest --watch --collectCoverage=false"
   },
   "exports": {
     "./ai-sdk": {

typescript/src/ai-sdk/__tests__/essentials.test.ts

@@ -5,6 +5,7 @@ import {isToolAllowed} from '../../shared/configuration';
 import {contextToTools} from '../../shared/tools'; // Assuming this is the source of all tools
 import {z} from 'zod';
 import {Configuration, Context} from '../../types/configuration';
+
 // Mock dependencies
 jest.mock('../../shared/api');
 jest.mock('../tool');
@@ -43,8 +44,9 @@ jest.mock('../../shared/tools', () => {
 const tools = contextToTools({});
 
 describe('CommercetoolsAgentEssentials with Admin tools', () => {
+  const toolFormat = 'json';
   const mockConfiguration = {
-    context: {isAdmin: true},
+    context: {isAdmin: true, toolOutputFormat: toolFormat},
     actions: {cart: {read: true}, products: {read: true}},
   } as any;
   const mockCommercetoolsAPIInstance = {} as CommercetoolsAPI;
@@ -122,21 +124,24 @@ describe('CommercetoolsAgentEssentials with Admin tools', () => {
       mockCommercetoolsAPIInstance,
       tools[0].method,
       tools[0].description,
-      expect.any(Object)
+      expect.any(Object),
+      toolFormat
     );
     // Detailed check for tool2 (namespace 'product', method 'tool2')
     expect(CommercetoolsTool).toHaveBeenCalledWith(
       mockCommercetoolsAPIInstance,
       tools[1].method,
       tools[1].description,
-      expect.any(Object)
+      expect.any(Object),
+      toolFormat
     );
     // Ensure tool3 was filtered out
     expect(CommercetoolsTool).not.toHaveBeenCalledWith(
       expect.anything(),
       tools[2].method,
       expect.anything(),
-      expect.anything()
+      expect.anything(),
+      toolFormat
     );
 
     expect(Object.keys(agentEssentials.tools)).toContain('tool1');

typescript/src/ai-sdk/__tests__/tool.test.ts

@@ -27,6 +27,7 @@ describe('CommercetoolsTool', () => {
     param1: z.string().describe('Parameter 1'),
     param2: z.number().optional().describe('Parameter 2'),
   });
+  const toolFormat = 'json';
 
   beforeEach(() => {
     // Clear all instances and calls to constructor and all methods:
@@ -53,11 +54,13 @@ describe('CommercetoolsTool', () => {
       mockCommercetoolsAPI,
       testMethod,
       testDescription,
-      testSchema
+      testSchema,
+      toolFormat
     ) as any; // Cast to any to access execute for testing
 
     const executeArgs = {param1: 'testValue'};
-    mockCommercetoolsAPI.run.mockResolvedValue('API Result');
+    const apiReturnValue = 'API Result';
+    mockCommercetoolsAPI.run.mockResolvedValue(apiReturnValue);
 
     const result = await coreToolConfig.execute(executeArgs);
 
@@ -66,25 +69,31 @@ describe('CommercetoolsTool', () => {
       testMethod,
       executeArgs
     );
-    expect(result).toBe('API Result');
+    expect(result).toBe(
+      `{"TEST METHOD RESULT":${JSON.stringify(apiReturnValue)}}`
+    );
   });
 
   it('should correctly handle execute with optional parameters', async () => {
     const coreToolConfig = CommercetoolsTool(
       mockCommercetoolsAPI,
       testMethod,
       testDescription,
-      testSchema
+      testSchema,
+      toolFormat
     ) as any;
 
     const executeArgs = {param1: 'testValue', param2: 123};
+    const apiReturnValue = 'API Result with optional';
     mockCommercetoolsAPI.run.mockResolvedValue('API Result with optional');
 
     const result = await coreToolConfig.execute(executeArgs);
     expect(mockCommercetoolsAPI.run).toHaveBeenCalledWith(
       testMethod,
       executeArgs
     );
-    expect(result).toBe('API Result with optional');
+    expect(result).toBe(
+      `{"TEST METHOD RESULT":${JSON.stringify(apiReturnValue)}}`
+    );
   });
 });

typescript/src/ai-sdk/essentials.ts

@@ -40,7 +40,8 @@ class CommercetoolsAgentEssentials {
         this._commercetools,
         tool.method,
         tool.description,
-        tool.parameters
+        tool.parameters,
+        configuration.context?.toolOutputFormat
       );
     });
   }

typescript/src/ai-sdk/tool.ts

@@ -2,18 +2,25 @@ import type {Tool} from 'ai';
 import {tool} from 'ai';
 import {z} from 'zod';
 import CommercetoolsAPI from '../shared/api';
+import {transformToolOutput} from '../modelcontextprotocol/transform';
 
 export default function CommercetoolsTool(
   commercetoolsAPI: CommercetoolsAPI,
   method: string,
   description: string,
-  schema: z.ZodObject<any, any, any, any, {[x: string]: any}>
+  schema: z.ZodObject<any, any, any, any, {[x: string]: any}>,
+  toolOutputFormat?: 'json' | 'tabular'
 ): Tool {
   return tool({
     description: description,
     parameters: schema,
-    execute: (arg: z.output<typeof schema>) => {
-      return commercetoolsAPI.run(method, arg);
+    execute: async (arg: z.output<typeof schema>) => {
+      const result = await commercetoolsAPI.run(method, arg);
+      return transformToolOutput({
+        title: `${method} result`,
+        data: result,
+        format: toolOutputFormat,
+      });
     },
   });
 }

typescript/src/langchain/__tests__/essentials.test.ts

@@ -56,9 +56,10 @@ jest.mock('../../shared/tools', () => {
 let mockToolDefinitions: any[]; // To hold the data for assertions
 
 describe('CommercetoolsAgentEssentials (Langchain)', () => {
+  const toolOutputFormat = 'json';
   const mockConfiguration = {
     enabledTools: ['cart', 'product.lcTool2'],
-    context: {isAdmin: true},
+    context: {isAdmin: true, toolOutputFormat},
   } as any;
   const mockCommercetoolsAPIInstance = {} as CommercetoolsAPI;
   const mockLangchainTool = new DynamicStructuredTool({
@@ -141,13 +142,15 @@ describe('CommercetoolsAgentEssentials (Langchain)', () => {
       mockCommercetoolsAPIInstance,
       mockToolDefinitions[0].method,
       mockToolDefinitions[0].description,
-      expect.any(Object)
+      expect.any(Object),
+      toolOutputFormat
     );
     expect(CommercetoolsTool).toHaveBeenCalledWith(
       mockCommercetoolsAPIInstance,
       mockToolDefinitions[1].method,
       mockToolDefinitions[1].description,
-      expect.any(Object)
+      expect.any(Object),
+      toolOutputFormat
     );
     expect(CommercetoolsTool).not.toHaveBeenCalledWith(
       expect.anything(),

typescript/src/langchain/__tests__/tool.test.ts

@@ -65,12 +65,13 @@ describe('CommercetoolsTool (Langchain)', () => {
     expect(toolArgs.schema).toBe(testSchema);
   });
 
-  it('should call commercetoolsAPI.run and stringify the result when func is called', async () => {
+  it('should call commercetoolsAPI.run and transform the result when func is called', async () => {
     CommercetoolsTool(
       mockCommercetoolsAPI,
       testMethod,
       testDescription,
-      testSchema
+      testSchema,
+      'json'
     );
     // Access the mock's call arguments through the imported DynamicStructuredTool
     const toolConstructorArgs = (DynamicStructuredTool as unknown as jest.Mock)
@@ -88,15 +89,18 @@ describe('CommercetoolsTool (Langchain)', () => {
       testMethod,
       executeArgs
     );
-    expect(result).toBe(JSON.stringify(apiResultObject));
+    expect(result).toBe(
+      `{"LC TEST METHOD RESULT":${JSON.stringify(apiResultObject)}}`
+    );
   });
 
-  it('should handle func with optional parameters and stringify result', async () => {
+  it('should handle func with optional parameters and transform result', async () => {
     CommercetoolsTool(
       mockCommercetoolsAPI,
       testMethod,
       testDescription,
-      testSchema
+      testSchema,
+      'json'
     );
     const toolConstructorArgs = (DynamicStructuredTool as unknown as jest.Mock)
       .mock.calls[0][0];
@@ -111,6 +115,8 @@ describe('CommercetoolsTool (Langchain)', () => {
       testMethod,
       executeArgs
     );
-    expect(result).toBe(JSON.stringify(apiResultObject));
+    expect(result).toBe(
+      `{"LC TEST METHOD RESULT":${JSON.stringify(apiResultObject)}}`
+    );
   });
 });