@decocms/mesh-sdk 1.1.0

package/src/hooks/use-collections.ts

@@ -0,0 +1,357 @@
+/**
+ * Collection Hooks using React Query
+ *
+ * Provides React hooks for working with collection-binding-compliant tools.
+ * Uses TanStack React Query for caching, loading states, and mutations.
+ */
+
+import {
+  type BaseCollectionEntity,
+  type CollectionDeleteInput,
+  type CollectionDeleteOutput,
+  type CollectionGetInput,
+  type CollectionGetOutput,
+  type CollectionInsertInput,
+  type CollectionInsertOutput,
+  type CollectionListInput,
+  type CollectionListOutput,
+  type CollectionUpdateInput,
+  type CollectionUpdateOutput,
+  type OrderByExpression,
+  type WhereExpression,
+} from "@decocms/bindings/collections";
+import {
+  useMutation,
+  useQueryClient,
+  useSuspenseQuery,
+} from "@tanstack/react-query";
+import { toast } from "sonner";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { useMCPToolCall } from "./use-mcp-tools";
+import { KEYS } from "../lib/query-keys";
+
+/**
+ * Collection entity base type that matches the collection binding pattern
+ */
+export type CollectionEntity = BaseCollectionEntity;
+
+/**
+ * Filter definition for collection queries (matches @deco/ui Filter shape)
+ */
+export interface CollectionFilter {
+  /** Field to filter on (must match an entity property) */
+  column: string;
+  /** Value to match */
+  value: string | boolean | number;
+}
+
+/**
+ * Options for useCollectionList hook
+ */
+export interface UseCollectionListOptions<T extends CollectionEntity> {
+  /** Text search term (searches configured searchable fields) */
+  searchTerm?: string;
+  /** Field filters */
+  filters?: CollectionFilter[];
+  /** Sort key (field to sort by) */
+  sortKey?: keyof T;
+  /** Sort direction */
+  sortDirection?: "asc" | "desc" | null;
+  /** Fields to search when searchTerm is provided (default: ["title", "description"]) */
+  searchFields?: (keyof T)[];
+  /** Default sort key when none provided */
+  defaultSortKey?: keyof T;
+  /** Page size for pagination (default: 100) */
+  pageSize?: number;
+}
+
+/**
+ * Build a where expression from search term and filters
+ */
+function buildWhereExpression<T extends CollectionEntity>(
+  searchTerm: string | undefined,
+  filters: CollectionFilter[] | undefined,
+  searchFields: (keyof T)[],
+): WhereExpression | undefined {
+  const conditions: WhereExpression[] = [];
+
+  // Add search conditions (OR)
+  if (searchTerm?.trim()) {
+    const trimmedSearchTerm = searchTerm.trim();
+    const searchConditions = searchFields.map((field) => ({
+      field: [String(field)],
+      operator: "contains" as const,
+      value: trimmedSearchTerm,
+    }));
+
+    if (searchConditions.length === 1 && searchConditions[0]) {
+      conditions.push(searchConditions[0]);
+    } else if (searchConditions.length > 1) {
+      conditions.push({
+        operator: "or",
+        conditions: searchConditions,
+      });
+    }
+  }
+
+  // Add filter conditions (AND)
+  if (filters && filters.length > 0) {
+    for (const filter of filters) {
+      conditions.push({
+        field: [filter.column],
+        operator: "eq" as const,
+        value: filter.value,
+      });
+    }
+  }
+
+  if (conditions.length === 0) {
+    return undefined;
+  }
+
+  if (conditions.length === 1) {
+    return conditions[0];
+  }
+
+  // Combine all conditions with AND
+  return {
+    operator: "and",
+    conditions,
+  };
+}
+
+/**
+ * Build orderBy expression from sort key and direction
+ */
+function buildOrderByExpression<T extends CollectionEntity>(
+  sortKey: keyof T | undefined,
+  sortDirection: "asc" | "desc" | null | undefined,
+  defaultSortKey: keyof T,
+): OrderByExpression[] | undefined {
+  const key = sortKey ?? defaultSortKey;
+  const direction = sortDirection ?? "asc";
+
+  return [
+    {
+      field: [String(key)],
+      direction,
+    },
+  ];
+}
+
+/**
+ * Extract payload from MCP tool result (handles structuredContent wrapper)
+ */
+function extractPayload<T>(result: unknown): T {
+  const r = result as { structuredContent?: T } | T;
+  if (r && typeof r === "object" && "structuredContent" in r) {
+    return r.structuredContent as T;
+  }
+  return r as T;
+}
+
+/**
+ * Get a single item by ID from a collection
+ *
+ * @param scopeKey - The scope key (connectionId for connection-scoped, virtualMcpId for virtual-mcp-scoped, etc.)
+ * @param collectionName - The name of the collection (e.g., "CONNECTIONS", "AGENT")
+ * @param itemId - The ID of the item to fetch (undefined returns null without making an API call)
+ * @param client - The MCP client used to call collection tools
+ * @returns Suspense query result with the item, or null if itemId is undefined
+ */
+export function useCollectionItem<T extends CollectionEntity>(
+  scopeKey: string,
+  collectionName: string,
+  itemId: string | undefined,
+  client: Client,
+) {
+  void scopeKey; // Reserved for future use (e.g., cache scoping)
+  const upperName = collectionName.toUpperCase();
+  const getToolName = `COLLECTION_${upperName}_GET`;
+
+  const { data } = useSuspenseQuery({
+    queryKey: KEYS.mcpToolCall(client, getToolName, itemId ?? ""),
+    queryFn: async () => {
+      if (!itemId) {
+        return { item: null } as CollectionGetOutput<T>;
+      }
+
+      const result = (await client.callTool({
+        name: getToolName,
+        arguments: {
+          id: itemId,
+        } as CollectionGetInput,
+      })) as { structuredContent?: unknown };
+
+      return extractPayload<CollectionGetOutput<T>>(result);
+    },
+    staleTime: 60_000,
+  });
+
+  return data?.item ?? null;
+}
+
+/**
+ * Get a paginated list of items from a collection
+ *
+ * @param scopeKey - The scope key (connectionId for connection-scoped, virtualMcpId for virtual-mcp-scoped, etc.)
+ * @param collectionName - The name of the collection (e.g., "CONNECTIONS", "AGENT")
+ * @param client - The MCP client used to call collection tools
+ * @param options - Filter and configuration options
+ * @returns Suspense query result with items array
+ */
+export function useCollectionList<T extends CollectionEntity>(
+  scopeKey: string,
+  collectionName: string,
+  client: Client,
+  options: UseCollectionListOptions<T> = {},
+) {
+  void scopeKey; // Reserved for future use (e.g., cache scoping)
+  const {
+    searchTerm,
+    filters,
+    sortKey,
+    sortDirection,
+    searchFields = ["title", "description"] as (keyof T)[],
+    defaultSortKey = "updated_at" as keyof T,
+    pageSize = 100,
+  } = options;
+
+  const upperName = collectionName.toUpperCase();
+  const listToolName = `COLLECTION_${upperName}_LIST`;
+
+  const where = buildWhereExpression(searchTerm, filters, searchFields);
+  const orderBy = buildOrderByExpression(
+    sortKey,
+    sortDirection,
+    defaultSortKey,
+  );
+
+  const toolArguments: CollectionListInput = {
+    ...(where && { where }),
+    ...(orderBy && { orderBy }),
+    limit: pageSize,
+    offset: 0,
+  };
+
+  const { data } = useMCPToolCall({
+    client,
+    toolName: listToolName,
+    toolArguments,
+    select: (result) => {
+      const payload = extractPayload<CollectionListOutput<T>>(result);
+      return payload?.items ?? [];
+    },
+  });
+
+  return data;
+}
+
+/**
+ * Get mutation actions for create, update, and delete operations
+ *
+ * @param scopeKey - The scope key (connectionId for connection-scoped, virtualMcpId for virtual-mcp-scoped, etc.)
+ * @param collectionName - The name of the collection (e.g., "CONNECTIONS", "AGENT")
+ * @param client - The MCP client used to call collection tools
+ * @returns Object with create, update, and delete mutation hooks
+ */
+export function useCollectionActions<T extends CollectionEntity>(
+  scopeKey: string,
+  collectionName: string,
+  client: Client,
+) {
+  void scopeKey; // Reserved for future use (e.g., cache scoping)
+  const queryClient = useQueryClient();
+  const upperName = collectionName.toUpperCase();
+  const createToolName = `COLLECTION_${upperName}_CREATE`;
+  const updateToolName = `COLLECTION_${upperName}_UPDATE`;
+  const deleteToolName = `COLLECTION_${upperName}_DELETE`;
+
+  // Invalidate all tool call queries for this collection
+  const invalidateCollection = () => {
+    queryClient.invalidateQueries({
+      predicate: (query) => {
+        const key = query.queryKey;
+        // Match mcpToolCall keys: ["mcp", "client", client, "tool-call", toolName, argsKey]
+        if (key[0] !== "mcp" || key[1] !== "client" || key[3] !== "tool-call") {
+          return false;
+        }
+        const toolName = key[4] as string;
+        return toolName?.startsWith(`COLLECTION_${upperName}_`);
+      },
+    });
+  };
+
+  const create = useMutation({
+    mutationFn: async (data: Partial<T>) => {
+      const result = (await client.callTool({
+        name: createToolName,
+        arguments: {
+          data,
+        } as CollectionInsertInput<T>,
+      })) as { structuredContent?: unknown };
+      const payload = extractPayload<CollectionInsertOutput<T>>(result);
+
+      return payload.item;
+    },
+    onSuccess: () => {
+      invalidateCollection();
+      toast.success("Item created successfully");
+    },
+    onError: (error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      toast.error(`Failed to create item: ${message}`);
+    },
+  });
+
+  const update = useMutation({
+    mutationFn: async ({ id, data }: { id: string; data: Partial<T> }) => {
+      const result = (await client.callTool({
+        name: updateToolName,
+        arguments: {
+          id,
+          data,
+        } as CollectionUpdateInput<T>,
+      })) as { structuredContent?: unknown };
+      const payload = extractPayload<CollectionUpdateOutput<T>>(result);
+
+      return payload.item;
+    },
+    onSuccess: () => {
+      invalidateCollection();
+      toast.success("Item updated successfully");
+    },
+    onError: (error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      toast.error(`Failed to update item: ${message}`);
+    },
+  });
+
+  const remove = useMutation({
+    mutationFn: async (id: string) => {
+      const result = (await client.callTool({
+        name: deleteToolName,
+        arguments: {
+          id,
+        } as CollectionDeleteInput,
+      })) as { structuredContent?: unknown };
+      const payload = extractPayload<CollectionDeleteOutput<T>>(result);
+
+      return payload.item.id;
+    },
+    onSuccess: () => {
+      invalidateCollection();
+      toast.success("Item deleted successfully");
+    },
+    onError: (error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      toast.error(`Failed to delete item: ${message}`);
+    },
+  });
+
+  return {
+    create,
+    update,
+    delete: remove,
+  };
+}

package/src/hooks/use-connection.ts

@@ -0,0 +1,82 @@
+/**
+ * Connection Collection Hooks
+ *
+ * Provides React hooks for working with connections using React Query.
+ * These hooks offer a reactive interface for accessing and manipulating connections.
+ */
+
+import type { ConnectionEntity } from "../types/connection";
+import { useProjectContext } from "../context/project-context";
+import {
+  type CollectionFilter,
+  useCollectionActions,
+  useCollectionItem,
+  useCollectionList,
+  type UseCollectionListOptions,
+} from "./use-collections";
+import { useMCPClient } from "./use-mcp-client";
+import { SELF_MCP_ALIAS_ID } from "../lib/constants";
+
+/**
+ * Filter definition for connections (matches @deco/ui Filter shape)
+ */
+export type ConnectionFilter = CollectionFilter;
+
+/**
+ * Options for useConnections hook
+ */
+export type UseConnectionsOptions = UseCollectionListOptions<ConnectionEntity>;
+
+/**
+ * Hook to get all connections
+ *
+ * @param options - Filter and configuration options
+ * @returns Suspense query result with connections as ConnectionEntity[]
+ */
+export function useConnections(options: UseConnectionsOptions = {}) {
+  const { org } = useProjectContext();
+  const client = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+  return useCollectionList<ConnectionEntity>(
+    org.id,
+    "CONNECTIONS",
+    client,
+    options,
+  );
+}
+
+/**
+ * Hook to get a single connection by ID
+ *
+ * @param connectionId - The ID of the connection to fetch (undefined returns null without making an API call)
+ * @returns Suspense query result with the connection as ConnectionEntity | null
+ */
+export function useConnection(connectionId: string | undefined) {
+  const { org } = useProjectContext();
+  const client = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+  return useCollectionItem<ConnectionEntity>(
+    org.id,
+    "CONNECTIONS",
+    connectionId,
+    client,
+  );
+}
+
+/**
+ * Hook to get connection mutation actions (create, update, delete)
+ *
+ * @returns Object with create, update, and delete mutation hooks
+ */
+export function useConnectionActions() {
+  const { org } = useProjectContext();
+  const client = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+  return useCollectionActions<ConnectionEntity>(org.id, "CONNECTIONS", client);
+}

package/src/hooks/use-mcp-client.ts

@@ -0,0 +1,127 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { KEYS } from "../lib/query-keys";
+import { StreamableHTTPClientTransport } from "../lib/streamable-http-client-transport";
+
+const DEFAULT_CLIENT_INFO = {
+  name: "mesh-sdk",
+  version: "1.0.0",
+};
+
+export interface CreateMcpClientOptions {
+  /** Connection ID - use SELF_MCP_ALIAS_ID for the self/management MCP (ALL_TOOLS), or any connectionId for other MCPs */
+  connectionId: string | null;
+  /** Organization ID - required, transforms to x-org-id header */
+  orgId: string;
+  /** Authorization token - optional */
+  token?: string | null;
+  /** Mesh server URL - optional, defaults to window.location.origin (for external apps, provide your Mesh server URL) */
+  meshUrl?: string;
+}
+
+export type UseMcpClientOptions = CreateMcpClientOptions;
+
+/**
+ * Build the MCP URL from connectionId and optional meshUrl
+ * Uses /mcp/:connectionId for all servers
+ */
+function buildMcpUrl(connectionId: string | null, meshUrl?: string): string {
+  const baseUrl =
+    meshUrl ??
+    (typeof window !== "undefined" ? window.location.origin : undefined);
+  if (!baseUrl) {
+    throw new Error(
+      "MCP client requires either meshUrl option or a browser environment.",
+    );
+  }
+
+  const path = connectionId ? `/mcp/${connectionId}` : "/mcp";
+  return new URL(path, baseUrl).href;
+}
+
+/**
+ * Create and connect an MCP client with Streamable HTTP transport.
+ * This is the low-level function for creating clients outside of React hooks.
+ *
+ * @param options - Configuration for the MCP client
+ * @returns Promise resolving to the connected MCP client
+ */
+export async function createMCPClient({
+  connectionId,
+  orgId,
+  token,
+  meshUrl,
+}: CreateMcpClientOptions): Promise<Client> {
+  const url = buildMcpUrl(connectionId, meshUrl);
+
+  const client = new Client(DEFAULT_CLIENT_INFO, {
+    capabilities: {
+      tasks: {
+        list: {},
+        cancel: {},
+        requests: {
+          tool: {
+            call: {},
+          },
+        },
+      },
+    },
+  });
+
+  const transport = new StreamableHTTPClientTransport(new URL(url), {
+    requestInit: {
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        "x-org-id": orgId,
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+    },
+  });
+
+  await client.connect(transport);
+
+  // Add toJSON method for query key serialization
+  // This allows the client to be used directly in query keys
+  const queryKey = KEYS.mcpClient(
+    orgId,
+    connectionId ?? "self",
+    token ?? "",
+    meshUrl ?? "",
+  );
+  (client as Client & { toJSON: () => string }).toJSON = () =>
+    `mcp-client:${queryKey.join(":")}`;
+
+  return client;
+}
+
+/**
+ * Hook to create and manage an MCP client with Streamable HTTP transport.
+ * Uses Suspense - must be used within a Suspense boundary.
+ *
+ * @param options - Configuration for the MCP client
+ * @returns The MCP client instance (never null - suspends until ready)
+ */
+export function useMCPClient({
+  connectionId,
+  orgId,
+  token,
+  meshUrl,
+}: UseMcpClientOptions): Client {
+  const queryKey = KEYS.mcpClient(
+    orgId,
+    connectionId ?? "",
+    token ?? "",
+    meshUrl ?? "",
+  );
+
+  const { data: client } = useSuspenseQuery({
+    queryKey,
+    queryFn: () => createMCPClient({ connectionId, orgId, token, meshUrl }),
+    staleTime: Infinity, // Keep client alive while query is active
+    gcTime: 0, // Clean up immediately when query is inactive
+  });
+
+  // useSuspenseQuery guarantees data is available (suspends until ready)
+  return client!;
+}

package/src/hooks/use-mcp-prompts.ts

@@ -0,0 +1,126 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  useQuery,
+  UseQueryResult,
+  useSuspenseQuery,
+  UseSuspenseQueryResult,
+  type UseQueryOptions,
+  type UseSuspenseQueryOptions,
+} from "@tanstack/react-query";
+import type {
+  GetPromptRequest,
+  GetPromptResult,
+  ListPromptsResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import { KEYS } from "../lib/query-keys";
+
+/**
+ * List prompts from an MCP client.
+ * This is the raw async function that can be used outside of React hooks.
+ */
+export async function listPrompts(client: Client): Promise<ListPromptsResult> {
+  const capabilities = client.getServerCapabilities();
+  if (!capabilities?.prompts) {
+    return { prompts: [] };
+  }
+  return await client.listPrompts();
+}
+
+/**
+ * Get a specific prompt from an MCP client.
+ * This is the raw async function that can be used outside of React hooks.
+ */
+export async function getPrompt(
+  client: Client,
+  name: string,
+  args?: GetPromptRequest["params"]["arguments"],
+): Promise<GetPromptResult> {
+  const capabilities = client.getServerCapabilities();
+  if (!capabilities?.prompts) {
+    throw new Error("Prompts capability not supported");
+  }
+  return await client.getPrompt({ name, arguments: args ?? {} });
+}
+
+export interface UseMcpPromptsListOptions
+  extends Omit<
+    UseSuspenseQueryOptions<ListPromptsResult, Error>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+}
+
+/**
+ * Suspense hook to list prompts from an MCP client.
+ * Must be used within a Suspense boundary.
+ */
+export function useMCPPromptsList({
+  client,
+  ...queryOptions
+}: UseMcpPromptsListOptions): UseSuspenseQueryResult<ListPromptsResult, Error> {
+  return useSuspenseQuery<ListPromptsResult, Error>({
+    ...queryOptions,
+    queryKey: KEYS.mcpPromptsList(client),
+    queryFn: () => listPrompts(client),
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}
+
+export interface UseMcpPromptsListQueryOptions
+  extends Omit<
+    UseQueryOptions<ListPromptsResult, Error>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+}
+
+/**
+ * Non-suspense hook to list prompts from an MCP client.
+ */
+export function useMCPPromptsListQuery({
+  client,
+  ...queryOptions
+}: UseMcpPromptsListQueryOptions): UseQueryResult<ListPromptsResult, Error> {
+  return useQuery<ListPromptsResult, Error>({
+    ...queryOptions,
+    queryKey: KEYS.mcpPromptsList(client),
+    queryFn: () => listPrompts(client),
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}
+
+export interface UseMcpGetPromptOptions
+  extends Omit<
+    UseSuspenseQueryOptions<GetPromptResult, Error>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+  /** Prompt name */
+  name: string;
+  /** Optional prompt arguments */
+  arguments?: GetPromptRequest["params"]["arguments"];
+}
+
+/**
+ * Suspense hook to get a specific prompt from an MCP client.
+ * Must be used within a Suspense boundary.
+ */
+export function useMCPGetPrompt({
+  client,
+  name,
+  arguments: args,
+  ...queryOptions
+}: UseMcpGetPromptOptions): UseSuspenseQueryResult<GetPromptResult, Error> {
+  return useSuspenseQuery<GetPromptResult, Error>({
+    ...queryOptions,
+    queryKey: KEYS.mcpGetPrompt(client, name, JSON.stringify(args ?? {})),
+    queryFn: () => getPrompt(client, name, args),
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}