@decocms/mesh-sdk 1.2.1 → 1.2.3

package/src/hooks/use-collections.ts

@@ -20,20 +20,22 @@ import {
   type OrderByExpression,
   type WhereExpression,
 } from "@decocms/bindings/collections";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 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
+ * Note: id can be nullable for synthetic entities like Decopilot agent
  */
-export type CollectionEntity = BaseCollectionEntity;
+export type CollectionEntity = Omit<BaseCollectionEntity, "id"> & {
+  id: string | null;
+};
 
 /**
  * Filter definition for collection queries (matches @deco/ui Filter shape)
@@ -63,12 +65,27 @@ export interface UseCollectionListOptions<T extends CollectionEntity> {
   defaultSortKey?: keyof T;
   /** Page size for pagination (default: 100) */
   pageSize?: number;
+  /** Additional arguments forwarded to the collection tool call (e.g., binding, include_virtual) */
+  additionalToolArgs?: Record<string, unknown>;
 }
 
+/**
+ * Query key type for collection list queries
+ */
+export type CollectionQueryKey = readonly [
+  unknown,
+  string,
+  string,
+  "collection",
+  string,
+  "list",
+  string,
+];
+
 /**
  * Build a where expression from search term and filters
  */
-function buildWhereExpression<T extends CollectionEntity>(
+export function buildWhereExpression<T extends CollectionEntity>(
   searchTerm: string | undefined,
   filters: CollectionFilter[] | undefined,
   searchFields: (keyof T)[],
@@ -123,13 +140,13 @@ function buildWhereExpression<T extends CollectionEntity>(
 /**
  * Build orderBy expression from sort key and direction
  */
-function buildOrderByExpression<T extends CollectionEntity>(
+export 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";
+  const direction = sortDirection ?? "desc";
 
   return [
     {
@@ -143,78 +160,110 @@ function buildOrderByExpression<T extends CollectionEntity>(
  * 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;
+  if (!result || typeof result !== "object") {
+    throw new Error("Invalid result");
   }
-  return r as T;
+
+  if ("isError" in result && result.isError) {
+    throw new Error(
+      "content" in result &&
+        Array.isArray(result.content) &&
+        result.content[0]?.type === "text"
+        ? result.content[0].text
+        : "Unknown error",
+    );
+  }
+
+  if ("structuredContent" in result) {
+    return result.structuredContent as T;
+  }
+
+  throw new Error("No structured content found");
 }
 
 /**
- * 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
+ * Query options for a single collection item. Shared between useCollectionItem
+ * and parallel-prefetch batches (useSuspenseQueries) so both build an identical
+ * query key + queryFn — letting a prefetch warm the exact cache entry the hook
+ * later reads.
  */
-export function useCollectionItem<T extends CollectionEntity>(
+export function collectionItemQueryOptions<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 ?? ""),
+  return {
+    queryKey: KEYS.collectionItem(
+      client,
+      scopeKey,
+      "",
+      upperName,
+      itemId ?? "",
+    ),
     queryFn: async () => {
       if (!itemId) {
-        return { item: null } as CollectionGetOutput<T>;
+        return { item: null } satisfies CollectionGetOutput<T>;
       }
 
-      const result = (await client.callTool({
+      const result = await client.callTool({
         name: getToolName,
-        arguments: {
-          id: itemId,
-        } as CollectionGetInput,
-      })) as { structuredContent?: unknown };
+        arguments: { id: itemId } satisfies CollectionGetInput,
+      });
 
       return extractPayload<CollectionGetOutput<T>>(result);
     },
     staleTime: 60_000,
-  });
+  };
+}
+
+export function useCollectionItem<T extends CollectionEntity>(
+  scopeKey: string,
+  collectionName: string,
+  itemId: string | undefined,
+  client: Client,
+) {
+  const { data } = useSuspenseQuery(
+    collectionItemQueryOptions<T>(scopeKey, collectionName, itemId, client),
+  );
 
   return data?.item ?? null;
 }
 
+/** Fake MCP result for empty collection list when client is skipped */
+export const EMPTY_COLLECTION_LIST_RESULT = {
+  structuredContent: {
+    items: [],
+  } satisfies CollectionListOutput<CollectionEntity>,
+  isError: false,
+} as const;
+
 /**
  * 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 client - The MCP client used to call collection tools (null/undefined returns [] without MCP call)
  * @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,
+  client: Client | null | undefined,
   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,
+    searchFields = ["title", "description"] satisfies (keyof T)[],
+    defaultSortKey = "updated_at" satisfies keyof T,
     pageSize = 100,
+    additionalToolArgs,
   } = options;
 
   const upperName = collectionName.toUpperCase();
@@ -227,19 +276,39 @@ export function useCollectionList<T extends CollectionEntity>(
     defaultSortKey,
   );
 
-  const toolArguments: CollectionListInput = {
+  const toolArguments: CollectionListInput & Record<string, unknown> = {
     ...(where && { where }),
     ...(orderBy && { orderBy }),
     limit: pageSize,
     offset: 0,
+    ...additionalToolArgs,
   };
 
-  const { data } = useMCPToolCall({
+  const argsKey = JSON.stringify(toolArguments);
+  const queryKey = KEYS.collectionList(
     client,
-    toolName: listToolName,
-    toolArguments,
+    scopeKey,
+    "",
+    upperName,
+    argsKey,
+  );
+
+  const { data } = useSuspenseQuery({
+    queryKey,
+    queryFn: async () => {
+      if (!client) {
+        return EMPTY_COLLECTION_LIST_RESULT;
+      }
+      const result = await client.callTool({
+        name: listToolName,
+        arguments: toolArguments,
+      });
+      return result;
+    },
+    staleTime: 30_000,
+    retry: false,
     select: (result) => {
-      const payload = extractPayload<CollectionListOutput<T>>(result);
+      const payload = extractPayload<CollectionListOutput<T>>(result ?? {});
       return payload?.items ?? [];
     },
   });
@@ -247,6 +316,54 @@ export function useCollectionList<T extends CollectionEntity>(
   return data;
 }
 
+/**
+ * Builds a query key for a collection list query
+ * Matches the internal logic of useCollectionList exactly
+ *
+ * @param client - The MCP client used to call collection tools (null/undefined is valid for skip queries)
+ * @param collectionName - The name of the collection (e.g., "THREAD_MESSAGES", "CONNECTIONS")
+ * @param scopeKey - The scope key (connectionId for connection-scoped, virtualMcpId for virtual-mcp-scoped, etc.)
+ * @param options - Filter and configuration options
+ * @returns Query key array
+ */
+export function buildCollectionQueryKey<T extends CollectionEntity>(
+  client: Client | null | undefined,
+  collectionName: string,
+  scopeKey: string,
+  options: UseCollectionListOptions<T> = {},
+): CollectionQueryKey {
+  const {
+    searchTerm,
+    filters,
+    sortKey,
+    sortDirection,
+    searchFields = ["title", "description"] satisfies (keyof T)[],
+    defaultSortKey = "updated_at" satisfies keyof T,
+    pageSize = 100,
+    additionalToolArgs,
+  } = options;
+
+  const upperName = collectionName.toUpperCase();
+
+  const where = buildWhereExpression(searchTerm, filters, searchFields);
+  const orderBy = buildOrderByExpression(
+    sortKey,
+    sortDirection,
+    defaultSortKey,
+  );
+
+  const toolArguments: CollectionListInput & Record<string, unknown> = {
+    ...(where && { where }),
+    ...(orderBy && { orderBy }),
+    limit: pageSize,
+    offset: 0,
+    ...additionalToolArgs,
+  };
+
+  const argsKey = JSON.stringify(toolArguments);
+  return KEYS.collectionList(client, scopeKey, "", upperName, argsKey);
+}
+
 /**
  * Get mutation actions for create, update, and delete operations
  *
@@ -260,36 +377,40 @@ export function useCollectionActions<T extends CollectionEntity>(
   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
+  // Invalidate all collection queries for this scope and 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}_`);
+        // Match collectionList/collectionItem keys: [client, scopeKey, "", "collection", collectionName, ...]
+        return (
+          key[1] === scopeKey && key[3] === "collection" && key[4] === upperName
+        );
       },
     });
   };
 
   const create = useMutation({
     mutationFn: async (data: Partial<T>) => {
-      const result = (await client.callTool({
+      const result = await client.callTool({
         name: createToolName,
-        arguments: {
-          data,
-        } as CollectionInsertInput<T>,
-      })) as { structuredContent?: unknown };
+        arguments: { data } satisfies CollectionInsertInput<T>,
+      });
+
+      if (result.isError) {
+        throw new Error(
+          Array.isArray(result.content)
+            ? result.content[0]?.text
+            : String(result.content),
+        );
+      }
+
       const payload = extractPayload<CollectionInsertOutput<T>>(result);
 
       return payload.item;
@@ -306,13 +427,10 @@ export function useCollectionActions<T extends CollectionEntity>(
 
   const update = useMutation({
     mutationFn: async ({ id, data }: { id: string; data: Partial<T> }) => {
-      const result = (await client.callTool({
+      const result = await client.callTool({
         name: updateToolName,
-        arguments: {
-          id,
-          data,
-        } as CollectionUpdateInput<T>,
-      })) as { structuredContent?: unknown };
+        arguments: { id, data } satisfies CollectionUpdateInput<T>,
+      });
       const payload = extractPayload<CollectionUpdateOutput<T>>(result);
 
       return payload.item;
@@ -329,12 +447,10 @@ export function useCollectionActions<T extends CollectionEntity>(
 
   const remove = useMutation({
     mutationFn: async (id: string) => {
-      const result = (await client.callTool({
+      const result = await client.callTool({
         name: deleteToolName,
-        arguments: {
-          id,
-        } as CollectionDeleteInput,
-      })) as { structuredContent?: unknown };
+        arguments: { id } satisfies CollectionDeleteInput,
+      });
       const payload = extractPayload<CollectionDeleteOutput<T>>(result);
 
       return payload.item.id;

package/src/hooks/use-connection.ts

@@ -25,25 +25,69 @@ export type ConnectionFilter = CollectionFilter;
 /**
  * Options for useConnections hook
  */
-export type UseConnectionsOptions = UseCollectionListOptions<ConnectionEntity>;
+export interface UseConnectionsOptions
+  extends UseCollectionListOptions<ConnectionEntity> {
+  /**
+   * Server-side binding filter. Only returns connections whose tools satisfy the binding.
+   * Can be a well-known binding name (e.g., "LLM", "ASSISTANTS", "OBJECT_STORAGE")
+   * or a custom binding schema object.
+   */
+  binding?: string | Record<string, unknown> | Record<string, unknown>[];
+  /**
+   * Whether to include VIRTUAL connections in results. Defaults to false (server default).
+   */
+  includeVirtual?: boolean;
+  /**
+   * Filter by computed connection slug (matches app_name, or slug derived from connection_url/title).
+   */
+  slug?: string;
+}
 
 /**
- * Hook to get all connections
+ * Hook to get connections with server-side filtering.
  *
- * @param options - Filter and configuration options
+ * @param options - Filter and configuration options (binding, search, etc.)
  * @returns Suspense query result with connections as ConnectionEntity[]
  */
 export function useConnections(options: UseConnectionsOptions = {}) {
+  const { binding, includeVirtual, slug, ...collectionOptions } = options;
+
+  // Build additional tool args for the COLLECTION_CONNECTIONS_LIST tool
+  const additionalToolArgs: Record<string, unknown> = {
+    ...collectionOptions.additionalToolArgs,
+  };
+
+  if (binding !== undefined) {
+    additionalToolArgs.binding = binding;
+  }
+
+  if (includeVirtual !== undefined) {
+    additionalToolArgs.include_virtual = includeVirtual;
+  }
+
+  if (slug !== undefined) {
+    additionalToolArgs.slug = slug;
+  }
+
+  const finalOptions: UseCollectionListOptions<ConnectionEntity> = {
+    ...collectionOptions,
+    additionalToolArgs:
+      Object.keys(additionalToolArgs).length > 0
+        ? additionalToolArgs
+        : undefined,
+  };
+
   const { org } = useProjectContext();
   const client = useMCPClient({
     connectionId: SELF_MCP_ALIAS_ID,
     orgId: org.id,
+    orgSlug: org.slug,
   });
   return useCollectionList<ConnectionEntity>(
     org.id,
     "CONNECTIONS",
     client,
-    options,
+    finalOptions,
   );
 }
 
@@ -58,6 +102,7 @@ export function useConnection(connectionId: string | undefined) {
   const client = useMCPClient({
     connectionId: SELF_MCP_ALIAS_ID,
     orgId: org.id,
+    orgSlug: org.slug,
   });
   return useCollectionItem<ConnectionEntity>(
     org.id,
@@ -77,6 +122,7 @@ export function useConnectionActions() {
   const client = useMCPClient({
     connectionId: SELF_MCP_ALIAS_ID,
     orgId: org.id,
+    orgSlug: org.slug,
   });
   return useCollectionActions<ConnectionEntity>(org.id, "CONNECTIONS", client);
 }

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

@@ -11,8 +11,10 @@ const DEFAULT_CLIENT_INFO = {
 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 */
+  /** Organization ID - required for query-key scoping */
   orgId: string;
+  /** Organization slug - required, used to build the /api/:org/mcp URL */
+  orgSlug: string;
   /** Authorization token - optional */
   token?: string | null;
   /** Mesh server URL - optional, defaults to window.location.origin (for external apps, provide your Mesh server URL) */
@@ -21,11 +23,21 @@ export interface CreateMcpClientOptions {
 
 export type UseMcpClientOptions = CreateMcpClientOptions;
 
+export interface UseMcpClientOptionalOptions
+  extends Omit<CreateMcpClientOptions, "connectionId"> {
+  /** Connection ID - string for connection MCP, null for default/self, undefined to skip (returns null) */
+  connectionId: string | null | undefined;
+}
+
 /**
- * Build the MCP URL from connectionId and optional meshUrl
- * Uses /mcp/:connectionId for all servers
+ * Build the MCP URL from connectionId and optional meshUrl.
+ * Uses /api/:org/mcp/:connectionId for all servers (org-scoped routing).
  */
-function buildMcpUrl(connectionId: string | null, meshUrl?: string): string {
+function buildMcpUrl(
+  connectionId: string | null,
+  orgSlug: string,
+  meshUrl?: string,
+): string {
   const baseUrl =
     meshUrl ??
     (typeof window !== "undefined" ? window.location.origin : undefined);
@@ -35,7 +47,10 @@ function buildMcpUrl(connectionId: string | null, meshUrl?: string): string {
     );
   }
 
-  const path = connectionId ? `/mcp/${connectionId}` : "/mcp";
+  const orgPath = `/api/${encodeURIComponent(orgSlug)}`;
+  const path = connectionId
+    ? `${orgPath}/mcp/${connectionId}`
+    : `${orgPath}/mcp`;
   return new URL(path, baseUrl).href;
 }
 
@@ -49,10 +64,11 @@ function buildMcpUrl(connectionId: string | null, meshUrl?: string): string {
 export async function createMCPClient({
   connectionId,
   orgId,
+  orgSlug,
   token,
   meshUrl,
 }: CreateMcpClientOptions): Promise<Client> {
-  const url = buildMcpUrl(connectionId, meshUrl);
+  const url = buildMcpUrl(connectionId, orgSlug, meshUrl);
 
   const client = new Client(DEFAULT_CLIENT_INFO, {
     capabilities: {
@@ -73,7 +89,6 @@ export async function createMCPClient({
       headers: {
         "Content-Type": "application/json",
         Accept: "application/json, text/event-stream",
-        "x-org-id": orgId,
         ...(token ? { Authorization: `Bearer ${token}` } : {}),
       },
     },
@@ -89,6 +104,7 @@ export async function createMCPClient({
     token ?? "",
     meshUrl ?? "",
   );
+
   (client as Client & { toJSON: () => string }).toJSON = () =>
     `mcp-client:${queryKey.join(":")}`;
 
@@ -105,23 +121,77 @@ export async function createMCPClient({
 export function useMCPClient({
   connectionId,
   orgId,
+  orgSlug,
   token,
   meshUrl,
 }: UseMcpClientOptions): Client {
   const queryKey = KEYS.mcpClient(
     orgId,
-    connectionId ?? "",
+    connectionId ?? "self",
     token ?? "",
     meshUrl ?? "",
   );
 
   const { data: client } = useSuspenseQuery({
     queryKey,
-    queryFn: () => createMCPClient({ connectionId, orgId, token, meshUrl }),
+    queryFn: () =>
+      createMCPClient({ connectionId, orgId, orgSlug, token, meshUrl }),
     staleTime: Infinity, // Keep client alive while query is active
-    gcTime: 0, // Clean up immediately when query is inactive
+    // Keep the client cached for a minute after the last subscriber detaches so
+    // brief unmount/remount transitions (sidebar collapse toggle, popover open,
+    // etc.) re-use the same transport instead of re-establishing it.
+    gcTime: 60_000,
   });
 
-  // useSuspenseQuery guarantees data is available (suspends until ready)
   return client!;
 }
+
+/**
+ * Optional MCP client - returns null when connectionId is undefined (skip creating client).
+ * Use when the connection may not be selected yet (e.g. model picker with no connections).
+ *
+ * - connectionId: string → connection-specific MCP
+ * - connectionId: null → default/self MCP
+ * - connectionId: undefined → skip (returns null, no MCP call)
+ *
+ * @param options - Configuration for the MCP client
+ * @returns The MCP client instance, or null when connectionId is undefined
+ */
+export function useMCPClientOptional({
+  connectionId,
+  orgId,
+  orgSlug,
+  token,
+  meshUrl,
+}: UseMcpClientOptionalOptions): Client | null {
+  const queryKey =
+    connectionId !== undefined
+      ? KEYS.mcpClient(
+          orgId,
+          connectionId ?? "self",
+          token ?? "",
+          meshUrl ?? "",
+        )
+      : (["mcp", "client", "skip", orgId] as const);
+
+  const { data: client } = useSuspenseQuery({
+    queryKey,
+    queryFn: async () => {
+      if (connectionId === undefined) {
+        return null;
+      }
+      return createMCPClient({
+        connectionId: connectionId as string | null,
+        orgId,
+        orgSlug,
+        token,
+        meshUrl,
+      });
+    },
+    staleTime: Infinity,
+    // Match the non-optional variant — see useMCPClient for the rationale.
+    gcTime: 60_000,
+  });
+
+  return client ?? null;
+}

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

@@ -1,4 +1,11 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  ErrorCode,
+  McpError,
+  type GetPromptRequest,
+  type GetPromptResult,
+  type ListPromptsResult,
+} from "@modelcontextprotocol/sdk/types.js";
 import {
   useQuery,
   UseQueryResult,
@@ -7,11 +14,6 @@ import {
   type UseQueryOptions,
   type UseSuspenseQueryOptions,
 } from "@tanstack/react-query";
-import type {
-  GetPromptRequest,
-  GetPromptResult,
-  ListPromptsResult,
-} from "@modelcontextprotocol/sdk/types.js";
 import { KEYS } from "../lib/query-keys";
 
 /**
@@ -23,7 +25,15 @@ export async function listPrompts(client: Client): Promise<ListPromptsResult> {
   if (!capabilities?.prompts) {
     return { prompts: [] };
   }
-  return await client.listPrompts();
+
+  try {
+    return await client.listPrompts();
+  } catch (error) {
+    if (error instanceof McpError && error.code === ErrorCode.MethodNotFound) {
+      return { prompts: [] };
+    }
+    throw error;
+  }
 }
 
 /**