Decoupling of mcp tools

Author: goanpeca

src/tools/API_REFERENCE.md

@@ -0,0 +1,138 @@
+/*
+ * Copyright (c) 2021-2025 Datalayer, Inc.
+ *
+ * MIT License
+ */
+
+/**
+ * ag-ui/CopilotKit Tool Adapter
+ *
+ * Converts unified tool definitions to CopilotKit's useCopilotAction format.
+ *
+ * @module tools/adapters/agui/AgUIToolAdapter
+ */
+
+import type { ToolDefinition } from "../../definitions/schema";
+import type { ToolOperation } from "../../core/interfaces";
+import type { SaaSToolContext } from "../saas/SaaSToolContext";
+import { SaaSToolAdapter } from "../saas/SaaSToolAdapter";
+
+/**
+ * CopilotKit action definition (matches useCopilotAction interface)
+ */
+export interface CopilotKitAction {
+  /** Action name (tool identifier) */
+  name: string;
+
+  /** Human-readable description for AI model */
+  description: string;
+
+  /** JSON Schema for parameters */
+  parameters: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+
+  /** Handler function that executes the action */
+  handler: (params: any) => Promise<string>;
+
+  /** Optional: Render function for custom UI */
+  render?: (props: { status: string; args: any; result: any }) => React.ReactNode;
+}
+
+/**
+ * Converts a unified tool definition to CopilotKit action format
+ *
+ * @param definition - Unified tool definition
+ * @param operation - Core operation implementation
+ * @param context - SaaS tool context (reuses SaaS document handle)
+ * @returns CopilotKit action ready for useCopilotAction
+ */
+export function createCopilotKitAction(
+  definition: ToolDefinition,
+  operation: ToolOperation<any, any>,
+  context: SaaSToolContext,
+): CopilotKitAction {
+  // Create SaaS adapter (ag-ui runs in browser, same as SaaS)
+  const adapter = new SaaSToolAdapter(definition, operation, context);
+
+  return {
+    name: definition.toolReferenceName || definition.name,
+    description: definition.description,
+    parameters: {
+      type: "object",
+      properties: definition.parameters.properties,
+      required: definition.parameters.required,
+    },
+
+    handler: async (params: any): Promise<string> => {
+      try {
+        const result = await adapter.execute(params);
+
+        // Format result as string for CopilotKit
+        if (typeof result === "object" && result !== null) {
+          const resultObj = result as any;
+
+          // Return success message if available
+          if (resultObj.message) {
+            return resultObj.message;
+          }
+
+          // Return error if failed
+          if (resultObj.success === false && resultObj.error) {
+            return `❌ Error: ${resultObj.error}`;
+          }
+
+          // Otherwise format as JSON
+          return JSON.stringify(result, null, 2);
+        }
+
+        return String(result);
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        return `❌ Error: ${errorMessage}`;
+      }
+    },
+
+    // Optional: Custom render function for ag-ui
+    render: definition.platformConfig?.agui?.renderingHints?.customRender
+      ? (definition.platformConfig.agui.renderingHints.customRender as any)
+      : undefined,
+  };
+}
+
+/**
+ * Creates all CopilotKit actions from tool definitions
+ *
+ * @param definitions - Array of tool definitions
+ * @param operations - Registry of core operations
+ * @param context - SaaS tool context
+ * @returns Array of CopilotKit actions
+ */
+export function createAllCopilotKitActions(
+  definitions: ToolDefinition[],
+  operations: Record<string, ToolOperation<any, any>>,
+  context: SaaSToolContext,
+): CopilotKitAction[] {
+  const actions: CopilotKitAction[] = [];
+
+  for (const definition of definitions) {
+    const operation = operations[definition.operation];
+
+    if (!operation) {
+      console.warn(
+        `[ag-ui Tools] No operation found for ${definition.name} (operation: ${definition.operation})`,
+      );
+      continue;
+    }
+
+    const action = createCopilotKitAction(definition, operation, context);
+    actions.push(action);
+  }
+
+  console.log(`[ag-ui Tools] Created ${actions.length} CopilotKit actions`);
+
+  return actions;
+}

src/tools/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,169 @@
+/*
+ * Copyright (c) 2021-2025 Datalayer, Inc.
+ *
+ * MIT License
+ */
+
+/**
+ * React hooks for ag-ui tool registration
+ *
+ * @module tools/adapters/agui/hooks
+ */
+
+import { useEffect, useMemo } from "react";
+import type { ToolDefinition } from "../../definitions/schema";
+import type { ToolOperation } from "../../core/interfaces";
+import type { SaaSToolContext } from "../saas/SaaSToolContext";
+import { createAllCopilotKitActions } from "./AgUIToolAdapter";
+
+// Type for useCopilotAction (from @copilotkit/react-core)
+type UseCopilotActionFn = (action: {
+  name: string;
+  description: string;
+  parameters: any;
+  handler: (params: any) => Promise<string>;
+  render?: (props: any) => any;
+}) => void;
+
+/**
+ * React hook that automatically registers all Datalayer tools with CopilotKit
+ *
+ * This hook converts unified tool definitions to CopilotKit actions and
+ * registers them using useCopilotAction.
+ *
+ * @param definitions - Array of tool definitions (defaults to all)
+ * @param operations - Registry of core operations (defaults to all)
+ * @param context - SaaS tool context (required)
+ * @param useCopilotAction - CopilotKit's useCopilotAction hook
+ *
+ * @example
+ * ```typescript
+ * import { useCopilotAction } from '@copilotkit/react-core';
+ * import { useNotebookTools } from './tools/adapters/agui';
+ *
+ * function NotebookEditor() {
+ *   const context = useSaaSToolContext(); // Your context hook
+ *
+ *   // Auto-register all notebook tools with CopilotKit
+ *   useNotebookTools(context, useCopilotAction);
+ *
+ *   return <YourNotebookUI />;
+ * }
+ * ```
+ */
+export function useNotebookTools(
+  context: SaaSToolContext,
+  useCopilotAction: UseCopilotActionFn,
+  definitions?: ToolDefinition[],
+  operations?: Record<string, ToolOperation<any, any>>,
+): void {
+  // Import defaults if not provided
+  const { allToolDefinitions } = require("../../definitions/tools");
+  const { allOperations } = require("../../core/operations");
+
+  const toolDefinitions = definitions || allToolDefinitions;
+  const toolOperations = operations || allOperations;
+
+  // Create CopilotKit actions from definitions
+  const actions = useMemo(
+    () => createAllCopilotKitActions(toolDefinitions, toolOperations, context),
+    [toolDefinitions, toolOperations, context],
+  );
+
+  // Register each action with CopilotKit
+  useEffect(() => {
+    console.log(
+      `[ag-ui Tools] Registering ${actions.length} tools with CopilotKit`,
+    );
+
+    actions.forEach((action) => {
+      useCopilotAction(action);
+      console.log(`[ag-ui Tools] ✓ Registered ${action.name}`);
+    });
+
+    return () => {
+      console.log("[ag-ui Tools] Cleanup (if needed)");
+    };
+  }, [actions, useCopilotAction]);
+}
+
+/**
+ * React hook that registers a single tool with CopilotKit
+ *
+ * Use this for selective tool registration or custom tools.
+ *
+ * @example
+ * ```typescript
+ * import { useSingleTool } from './tools/adapters/agui';
+ *
+ * function MyComponent() {
+ *   const context = useSaaSToolContext();
+ *
+ *   // Register only insertCell tool
+ *   useSingleTool(insertCellTool, insertCellOperation, context, useCopilotAction);
+ *
+ *   return <UI />;
+ * }
+ * ```
+ */
+export function useSingleTool(
+  definition: ToolDefinition,
+  operation: ToolOperation<any, any>,
+  context: SaaSToolContext,
+  useCopilotAction: UseCopilotActionFn,
+): void {
+  const action = useMemo(
+    () => {
+      const { createCopilotKitAction } = require("./AgUIToolAdapter");
+      return createCopilotKitAction(definition, operation, context);
+    },
+    [definition, operation, context],
+  );
+
+  useEffect(() => {
+    console.log(`[ag-ui Tools] Registering ${action.name}`);
+    useCopilotAction(action);
+
+    return () => {
+      console.log(`[ag-ui Tools] Cleanup for ${action.name}`);
+    };
+  }, [action, useCopilotAction]);
+}
+
+/**
+ * React hook that provides tool actions without auto-registration
+ *
+ * Use this when you want manual control over registration or need
+ * to inspect actions before registering.
+ *
+ * @returns Array of CopilotKit actions ready for registration
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const context = useSaaSToolContext();
+ *   const actions = useToolActions(context);
+ *
+ *   // Manually register specific actions
+ *   actions.filter(a => a.name.includes('cell')).forEach(useCopilotAction);
+ *
+ *   return <UI />;
+ * }
+ * ```
+ */
+export function useToolActions(
+  context: SaaSToolContext,
+  definitions?: ToolDefinition[],
+  operations?: Record<string, ToolOperation<any, any>>,
+): ReturnType<typeof createAllCopilotKitActions> {
+  const { allToolDefinitions } = require("../../definitions/tools");
+  const { allOperations } = require("../../core/operations");
+
+  const toolDefinitions = definitions || allToolDefinitions;
+  const toolOperations = operations || allOperations;
+
+  return useMemo(
+    () => createAllCopilotKitActions(toolDefinitions, toolOperations, context),
+    [toolDefinitions, toolOperations, context],
+  );
+}

src/tools/MIGRATION_GUIDE.md

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2021-2025 Datalayer, Inc.
+ *
+ * MIT License
+ */
+
+/**
+ * ag-ui/CopilotKit Adapter Module
+ *
+ * Provides ag-ui (CopilotKit) integration for the unified tool architecture.
+ *
+ * @module tools/adapters/agui
+ */
+
+export * from "./AgUIToolAdapter";
+export * from "./hooks";