@copilotkit/runtime 1.9.2-next.21 → 1.9.2-next.23

package/dist/lib/integrations/node-http/index.mjs

@@ -1,6 +1,6 @@
 import {
   copilotRuntimeNodeHttpEndpoint
-} from "../../../chunk-IBYPYIVX.mjs";
+} from "../../../chunk-FIA5HRU2.mjs";
 import "../../../chunk-SHBDMA63.mjs";
 import "../../../chunk-QLLV2QVK.mjs";
 import "../../../chunk-XWBDEXDA.mjs";

package/dist/{shared-41d4988d.d.ts → shared-6b6dbf8b.d.ts}

@@ -142,9 +142,7 @@ interface MCPTool {
         };
     };
     /** The function to call to execute the tool on the MCP server. */
-    execute(options: {
-        params: any;
-    }): Promise<any>;
+    execute(params: any): Promise<any>;
 }
 /**
  * Defines the contract for *any* MCP client implementation the user might provide.

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.9.2-next.21",
+  "version": "1.9.2-next.23",
   "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -66,7 +66,7 @@
     "rxjs": "7.8.1",
     "type-graphql": "2.0.0-rc.1",
     "zod": "^3.23.3",
-    "@copilotkit/shared": "1.9.2-next.21"
+    "@copilotkit/shared": "1.9.2-next.23"
   },
   "peerDependencies": {
     "@ag-ui/client": ">=0.0.28",

package/src/lib/runtime/__tests__/mcp-tools-utils.test.ts

@@ -0,0 +1,464 @@
+import {
+  extractParametersFromSchema,
+  convertMCPToolsToActions,
+  generateMcpToolInstructions,
+  MCPTool,
+} from "../mcp-tools-utils";
+
+describe("MCP Tools Utils", () => {
+  describe("extractParametersFromSchema", () => {
+    it("should extract parameters from schema.parameters.properties", () => {
+      const tool: MCPTool = {
+        description: "Test tool",
+        schema: {
+          parameters: {
+            properties: {
+              name: { type: "string", description: "A name parameter" },
+              age: { type: "number", description: "An age parameter" },
+            },
+            required: ["name"],
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        name: "name",
+        type: "string",
+        description: "A name parameter",
+        required: true,
+      });
+      expect(result[1]).toEqual({
+        name: "age",
+        type: "number",
+        description: "An age parameter",
+        required: false,
+      });
+    });
+
+    it("should extract parameters from schema.parameters.jsonSchema", () => {
+      const tool: MCPTool = {
+        description: "Test tool with jsonSchema",
+        schema: {
+          parameters: {
+            jsonSchema: {
+              properties: {
+                title: { type: "string", description: "A title parameter" },
+                count: { type: "number", description: "A count parameter" },
+              },
+              required: ["title"],
+            },
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        name: "title",
+        type: "string",
+        description: "A title parameter",
+        required: true,
+      });
+      expect(result[1]).toEqual({
+        name: "count",
+        type: "number",
+        description: "A count parameter",
+        required: false,
+      });
+    });
+
+    it("should handle arrays with items", () => {
+      const tool: MCPTool = {
+        description: "Test tool with array parameters",
+        schema: {
+          parameters: {
+            properties: {
+              simpleArray: {
+                type: "array",
+                items: { type: "string" },
+                description: "Array of strings",
+              },
+              objectArray: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: { type: "string" },
+                    value: { type: "number" },
+                  },
+                },
+                description: "Array of objects",
+              },
+            },
+            required: ["simpleArray"],
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        name: "simpleArray",
+        type: "array<string>",
+        description: "Array of strings",
+        required: true,
+      });
+      expect(result[1]).toEqual({
+        name: "objectArray",
+        type: "array",
+        description: "Array of objects Array of objects with properties: name, value",
+        required: false,
+      });
+    });
+
+    it("should handle enums", () => {
+      const tool: MCPTool = {
+        description: "Test tool with enum parameters",
+        schema: {
+          parameters: {
+            properties: {
+              status: {
+                type: "string",
+                enum: ["active", "inactive", "pending"],
+                description: "Status value",
+              },
+              priority: {
+                type: "number",
+                enum: [1, 2, 3],
+                description: "Priority level",
+              },
+            },
+            required: ["status"],
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        name: "status",
+        type: "string",
+        description: "Status value Allowed values: active | inactive | pending",
+        required: true,
+      });
+      expect(result[1]).toEqual({
+        name: "priority",
+        type: "number",
+        description: "Priority level Allowed values: 1 | 2 | 3",
+        required: false,
+      });
+    });
+
+    it("should handle nested objects", () => {
+      const tool: MCPTool = {
+        description: "Test tool with nested object parameters",
+        schema: {
+          parameters: {
+            properties: {
+              user: {
+                type: "object",
+                properties: {
+                  name: { type: "string" },
+                  email: { type: "string" },
+                  preferences: {
+                    type: "object",
+                    properties: {
+                      theme: { type: "string" },
+                      notifications: { type: "boolean" },
+                    },
+                  },
+                },
+                description: "User object",
+              },
+            },
+            required: ["user"],
+          },
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual({
+        name: "user",
+        type: "object",
+        description: "User object Object with properties: name, email, preferences",
+        required: true,
+      });
+    });
+
+    it("should return empty array when no properties", () => {
+      const tool: MCPTool = {
+        description: "Test tool without properties",
+        schema: {
+          parameters: {},
+        },
+        execute: async () => ({}),
+      };
+
+      const result = extractParametersFromSchema(tool);
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("generateMcpToolInstructions", () => {
+    it("should generate instructions with correct parameter schema from schema.parameters.properties", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+                age: { type: "number", description: "The age parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("testTool: A test tool");
+      expect(result).toContain("- name* (string) - The name parameter");
+      expect(result).toContain("- age (number) - The age parameter");
+    });
+
+    it("should generate instructions with correct parameter schema from schema.parameters.jsonSchema", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool with jsonSchema",
+          schema: {
+            parameters: {
+              jsonSchema: {
+                properties: {
+                  title: { type: "string", description: "The title parameter" },
+                  count: { type: "number", description: "The count parameter" },
+                },
+                required: ["title"],
+              },
+            },
+          },
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("testTool: A test tool with jsonSchema");
+      expect(result).toContain("- title* (string) - The title parameter");
+      expect(result).toContain("- count (number) - The count parameter");
+    });
+
+    it("should handle complex schemas with arrays and enums", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        complexTool: {
+          description: "A complex tool",
+          schema: {
+            parameters: {
+              properties: {
+                items: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      name: { type: "string" },
+                      value: { type: "number" },
+                    },
+                  },
+                  description: "Array of items",
+                },
+                status: {
+                  type: "string",
+                  enum: ["active", "inactive"],
+                  description: "Status",
+                },
+              },
+              required: ["items"],
+            },
+          },
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("complexTool: A complex tool");
+      expect(result).toContain(
+        "- items* (array<object>) - Array of items Array of objects with properties: name, value",
+      );
+      expect(result).toContain("- status (string) - Status Allowed values: active | inactive");
+    });
+
+    it("should fallback to schema.properties for backward compatibility", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        backwardCompatTool: {
+          description: "A backward compatible tool",
+          schema: {
+            // Direct properties without nested parameters
+            properties: {
+              name: { type: "string", description: "The name parameter" },
+            },
+            required: ["name"],
+          } as any,
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("backwardCompatTool: A backward compatible tool");
+      expect(result).toContain("- name* (string) - The name parameter");
+    });
+
+    it("should show 'No parameters required' when no schema properties", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        noParamsTool: {
+          description: "A tool with no parameters",
+          schema: {
+            parameters: {},
+          },
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("noParamsTool: A tool with no parameters");
+      expect(result).toContain("No parameters required");
+    });
+
+    it("should handle tools with no schema", () => {
+      const toolsMap: Record<string, MCPTool> = {
+        noSchemaTool: {
+          description: "A tool with no schema",
+          execute: async () => ({}),
+        },
+      };
+
+      const result = generateMcpToolInstructions(toolsMap);
+      expect(result).toContain("noSchemaTool: A tool with no schema");
+      expect(result).toContain("No parameters required");
+    });
+
+    it("should return empty string for empty tools map", () => {
+      const result = generateMcpToolInstructions({});
+      expect(result).toBe("");
+    });
+  });
+
+  describe("convertMCPToolsToActions", () => {
+    it("should convert MCP tools to CopilotKit actions", () => {
+      const mcpTools: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+                age: { type: "number", description: "The age parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: async () => "test result",
+        },
+      };
+
+      const result = convertMCPToolsToActions(mcpTools, "http://test-endpoint");
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe("testTool");
+      expect(result[0].description).toBe("A test tool");
+      expect(result[0].parameters).toHaveLength(2);
+      expect(result[0].parameters[0]).toEqual({
+        name: "name",
+        type: "string",
+        description: "The name parameter",
+        required: true,
+      });
+      expect(result[0].parameters[1]).toEqual({
+        name: "age",
+        type: "number",
+        description: "The age parameter",
+        required: false,
+      });
+    });
+
+    it("should handle tool execution correctly", async () => {
+      const mockExecute = jest.fn().mockResolvedValue("mock result");
+      const mcpTools: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: mockExecute,
+        },
+      };
+
+      const result = convertMCPToolsToActions(mcpTools, "http://test-endpoint");
+      const action = result[0];
+
+      const executeResult = await action.handler({ name: "test" });
+      expect(executeResult).toBe("mock result");
+      expect(mockExecute).toHaveBeenCalledWith({ name: "test" });
+    });
+
+    it("should stringify non-string results", async () => {
+      const mcpTools: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: async () => ({ result: "complex object" }),
+        },
+      };
+
+      const result = convertMCPToolsToActions(mcpTools, "http://test-endpoint");
+      const action = result[0];
+
+      const executeResult = await action.handler({ name: "test" });
+      expect(executeResult).toBe('{"result":"complex object"}');
+    });
+
+    it("should handle execution errors", async () => {
+      const mcpTools: Record<string, MCPTool> = {
+        testTool: {
+          description: "A test tool",
+          schema: {
+            parameters: {
+              properties: {
+                name: { type: "string", description: "The name parameter" },
+              },
+              required: ["name"],
+            },
+          },
+          execute: async () => {
+            throw new Error("Test error");
+          },
+        },
+      };
+
+      const result = convertMCPToolsToActions(mcpTools, "http://test-endpoint");
+      const action = result[0];
+
+      await expect(action.handler({ name: "test" })).rejects.toThrow(
+        "Execution failed for MCP tool 'testTool': Test error",
+      );
+    });
+  });
+});

package/src/lib/runtime/copilot-runtime.ts

@@ -439,9 +439,7 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
     }
 
     const instructions =
-      "You have access to the following tools provided by external Model Context Protocol (MCP) servers:\n" +
-      mcpToolInstructions +
-      "\nUse them when appropriate to fulfill the user's request.";
+      mcpToolInstructions + "\nUse them when appropriate to fulfill the user's request.";
 
     const systemMessageIndex = messages.findIndex((msg) => msg.textMessage?.role === "system");
 

package/src/lib/runtime/mcp-tools-utils.ts

@@ -14,7 +14,7 @@ export interface MCPTool {
     };
   };
   /** The function to call to execute the tool on the MCP server. */
-  execute(options: { params: any }): Promise<any>;
+  execute(params: any): Promise<any>;
 }
 
 /**
@@ -51,7 +51,7 @@ export function extractParametersFromSchema(
       ? (toolOrSchema as MCPTool).schema
       : (toolOrSchema as MCPTool["schema"]);
 
-  const toolParameters = schema?.parameters || schema?.parameters?.jsonSchema;
+  const toolParameters = schema?.parameters?.jsonSchema || schema?.parameters;
   const properties = toolParameters?.properties;
   const requiredParams = new Set(toolParameters?.required || []);
 
@@ -62,15 +62,45 @@ export function extractParametersFromSchema(
   for (const paramName in properties) {
     if (Object.prototype.hasOwnProperty.call(properties, paramName)) {
       const paramDef = properties[paramName];
+
+      // Enhanced type extraction with support for complex types
+      let type = paramDef.type || "string";
+      let description = paramDef.description || "";
+
+      // Handle arrays with items
+      if (type === "array" && paramDef.items) {
+        const itemType = paramDef.items.type || "object";
+        if (itemType === "object" && paramDef.items.properties) {
+          // For arrays of objects, describe the structure
+          const itemProperties = Object.keys(paramDef.items.properties).join(", ");
+          description =
+            description +
+            (description ? " " : "") +
+            `Array of objects with properties: ${itemProperties}`;
+        } else {
+          // For arrays of primitives
+          type = `array<${itemType}>`;
+        }
+      }
+
+      // Handle enums
+      if (paramDef.enum && Array.isArray(paramDef.enum)) {
+        const enumValues = paramDef.enum.join(" | ");
+        description = description + (description ? " " : "") + `Allowed values: ${enumValues}`;
+      }
+
+      // Handle objects with properties
+      if (type === "object" && paramDef.properties) {
+        const objectProperties = Object.keys(paramDef.properties).join(", ");
+        description =
+          description + (description ? " " : "") + `Object with properties: ${objectProperties}`;
+      }
+
       parameters.push({
         name: paramName,
-        // Infer type, default to string. MCP schemas might have more complex types.
-        // This might need refinement based on common MCP schema practices.
-        type: paramDef.type || "string",
-        description: paramDef.description,
+        type: type,
+        description: description,
         required: requiredParams.has(paramName),
-        // Attributes might not directly map, handle if necessary
-        // attributes: paramDef.attributes || undefined,
       });
     }
   }
@@ -95,7 +125,7 @@ export function convertMCPToolsToActions(
 
     const handler = async (params: any): Promise<any> => {
       try {
-        const result = await tool.execute({ params });
+        const result = await tool.execute(params);
         // Ensure the result is a string or stringify it, as required by many LLMs.
         // This might need adjustment depending on how different LLMs handle tool results.
         return typeof result === "string" ? result : JSON.stringify(result);
@@ -148,16 +178,49 @@ export function generateMcpToolInstructions(toolsMap: Record<string, MCPTool>):
         if (tool.schema && typeof tool.schema === "object") {
           const schema = tool.schema as any;
 
-          // Extract parameters from JSON Schema
-          if (schema.properties) {
-            const requiredParams = schema.required || [];
+          // Extract parameters from JSON Schema - check both schema.parameters.properties and schema.properties
+          const toolParameters = schema.parameters?.jsonSchema || schema.parameters;
+          const properties = toolParameters?.properties || schema.properties;
+          const requiredParams = toolParameters?.required || schema.required || [];
 
-            // Build parameter documentation from properties
-            const paramsList = Object.entries(schema.properties).map(([paramName, propSchema]) => {
+          if (properties) {
+            // Build parameter documentation from properties with enhanced type information
+            const paramsList = Object.entries(properties).map(([paramName, propSchema]) => {
               const propDetails = propSchema as any;
               const requiredMark = requiredParams.includes(paramName) ? "*" : "";
-              const typeInfo = propDetails.type || "any";
-              const description = propDetails.description ? ` - ${propDetails.description}` : "";
+              let typeInfo = propDetails.type || "any";
+              let description = propDetails.description ? ` - ${propDetails.description}` : "";
+
+              // Enhanced type display for complex schemas
+              if (typeInfo === "array" && propDetails.items) {
+                const itemType = propDetails.items.type || "object";
+                if (itemType === "object" && propDetails.items.properties) {
+                  const itemProps = Object.keys(propDetails.items.properties).join(", ");
+                  typeInfo = `array<object>`;
+                  description =
+                    description +
+                    (description ? " " : " - ") +
+                    `Array of objects with properties: ${itemProps}`;
+                } else {
+                  typeInfo = `array<${itemType}>`;
+                }
+              }
+
+              // Handle enums
+              if (propDetails.enum && Array.isArray(propDetails.enum)) {
+                const enumValues = propDetails.enum.join(" | ");
+                description =
+                  description + (description ? " " : " - ") + `Allowed values: ${enumValues}`;
+              }
+
+              // Handle objects
+              if (typeInfo === "object" && propDetails.properties) {
+                const objectProps = Object.keys(propDetails.properties).join(", ");
+                description =
+                  description +
+                  (description ? " " : " - ") +
+                  `Object with properties: ${objectProps}`;
+              }
 
               return `    - ${paramName}${requiredMark} (${typeInfo})${description}`;
             });
@@ -183,6 +246,9 @@ ${toolsDoc}
 When using these tools:
 1. Only provide valid parameters according to their type requirements
 2. Required parameters are marked with *
-3. Format API calls correctly with the expected parameter structure
-4. Always check tool responses to determine your next action`;
+3. For array parameters, provide data in the correct array format
+4. For object parameters, include all required nested properties
+5. For enum parameters, use only the allowed values listed
+6. Format API calls correctly with the expected parameter structure
+7. Always check tool responses to determine your next action`;
 }