@decocms/mesh-sdk 1.2.1 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/mesh-sdk",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "SDK for building external apps that integrate with Mesh MCP servers",
   "type": "module",
   "scripts": {
@@ -11,16 +11,18 @@
     ".": "./src/index.ts",
     "./hooks": "./src/hooks/index.ts",
     "./context": "./src/context/index.ts",
-    "./types": "./src/types/index.ts"
+    "./types": "./src/types/index.ts",
+    "./plugins": "./src/plugins/index.ts"
   },
   "dependencies": {
     "@decocms/bindings": "^1.1.1",
-    "@modelcontextprotocol/sdk": "1.25.2",
+    "@modelcontextprotocol/sdk": "1.27.1",
     "zod": "^4.0.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",
     "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
     "sonner": ">=2.0.0"
   },
   "peerDependenciesMeta": {
@@ -41,7 +43,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/decocms/admin.git",
+    "url": "git+https://github.com/decocms/studio.git",
     "directory": "packages/mesh-sdk"
   },
   "license": "MIT",

package/src/context/index.ts

@@ -1,9 +1,14 @@
 export {
   ProjectContextProvider,
   useProjectContext,
+  useOrg,
+  useCurrentProject,
+  useIsOrgAdmin,
   Locator,
-  ORG_ADMIN_PROJECT_SLUG,
   type ProjectContextProviderProps,
   type ProjectLocator,
   type LocatorStructured,
+  type OrganizationData,
+  type ProjectData,
+  type ProjectUI,
 } from "./project-context";

package/src/context/project-context.tsx

@@ -1,9 +1,9 @@
 import { createContext, useContext, type PropsWithChildren } from "react";
 
 /**
- * a ProjectLocator is a github-like slug string that identifies a project in an organization.
+ * A ProjectLocator is an ID-based string that identifies a project in an organization.
  *
- * format: <org-slug>/<project-slug>
+ * format: <orgId>/<projectId>
  */
 export type ProjectLocator = `${string}/${string}`;
 
@@ -12,14 +12,8 @@ export type LocatorStructured = {
   project: string;
 };
 
-export const ORG_ADMIN_PROJECT_SLUG = "org-admin";
-
 export const Locator = {
   from({ org, project }: LocatorStructured): ProjectLocator {
-    if (org?.includes("/") || project.includes("/")) {
-      throw new Error("Org or project cannot contain slashes");
-    }
-
     return `${org}/${project}` as ProjectLocator;
   },
   parse(locator: ProjectLocator): LocatorStructured {
@@ -32,27 +26,60 @@ export const Locator = {
     }
     return { org, project };
   },
-  isOrgAdminProject(locator: ProjectLocator): boolean {
-    return locator.split("/")[1] === ORG_ADMIN_PROJECT_SLUG;
-  },
-  adminProject(org: string): ProjectLocator {
-    return `${org}/${ORG_ADMIN_PROJECT_SLUG}`;
-  },
 } as const;
 
-interface ProjectContextType {
-  org: {
-    id: string;
-    name: string;
-    slug: string;
-    logo: string | null;
-  };
-
-  project: {
-    name?: string;
-    slug: string;
-  };
+/**
+ * Project UI customization
+ */
+export interface ProjectUI {
+  banner: string | null;
+  bannerColor: string | null;
+  icon: string | null;
+  themeColor: string | null;
+  pinnedViews?: Array<{
+    connectionId: string;
+    toolName: string;
+    label: string;
+    icon: string | null;
+  }> | null;
+}
+
+/**
+ * Organization data in context
+ */
+export interface OrganizationData {
+  id: string;
+  name: string;
+  slug: string;
+  logo: string | null;
+}
+
+/**
+ * Project data in context
+ * Includes full project info when loaded from storage
+ */
+export interface ProjectData {
+  /** Project ID */
+  id: string;
+  /** Organization ID (only available when loaded from storage) */
+  organizationId?: string;
+  /** Project slug */
+  slug: string;
+  /** Project display name */
+  name?: string;
+  /** Project description */
+  description?: string | null;
+  /** Enabled plugins */
+  enabledPlugins?: string[] | null;
+  /** UI customization */
+  ui?: ProjectUI | null;
+  /** Whether this is the org-admin project */
+  isOrgAdmin?: boolean;
+}
 
+interface ProjectContextType {
+  org: OrganizationData;
+  project: ProjectData;
   locator: ProjectLocator;
 }
 
@@ -69,9 +96,31 @@ export const useProjectContext = () => {
   return context;
 };
 
+/**
+ * Convenience hook to get organization data
+ */
+export const useOrg = () => {
+  return useProjectContext().org;
+};
+
+/**
+ * Convenience hook to get current project data
+ */
+export const useCurrentProject = () => {
+  return useProjectContext().project;
+};
+
+/**
+ * Convenience hook to check if current project is org-admin
+ */
+export const useIsOrgAdmin = () => {
+  const project = useProjectContext().project;
+  return project.isOrgAdmin === true;
+};
+
 export type ProjectContextProviderProps = {
-  org: { id: string; slug: string; name: string; logo: string | null };
-  project: { name?: string; slug: string };
+  org: OrganizationData;
+  project: ProjectData;
 };
 
 export const ProjectContextProvider = ({
@@ -79,7 +128,7 @@ export const ProjectContextProvider = ({
   org,
   project,
 }: PropsWithChildren<ProjectContextProviderProps>) => {
-  const locator = Locator.from({ org: org.slug, project: project.slug });
+  const locator = Locator.from({ org: org.id, project: project.id });
 
   const value = { org, project, locator };
 

package/src/hooks/index.ts

@@ -3,9 +3,14 @@ export {
   useCollectionItem,
   useCollectionList,
   useCollectionActions,
+  buildWhereExpression,
+  buildOrderByExpression,
+  buildCollectionQueryKey,
+  EMPTY_COLLECTION_LIST_RESULT,
   type CollectionEntity,
   type CollectionFilter,
   type UseCollectionListOptions,
+  type CollectionQueryKey,
 } from "./use-collections";
 
 // Connection hooks
@@ -21,8 +26,10 @@ export {
 export {
   createMCPClient,
   useMCPClient,
+  useMCPClientOptional,
   type CreateMcpClientOptions,
   type UseMcpClientOptions,
+  type UseMcpClientOptionalOptions,
 } from "./use-mcp-client";
 
 // MCP tools hooks

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,7 +140,7 @@ 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,
@@ -143,11 +160,25 @@ 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");
+  }
+
+  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",
+    );
   }
-  return r as T;
+
+  if ("structuredContent" in result) {
+    return result.structuredContent as T;
+  }
+
+  throw new Error("No structured content found");
 }
 
 /**
@@ -165,23 +196,26 @@ export function useCollectionItem<T extends CollectionEntity>(
   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 ?? ""),
+    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);
     },
@@ -191,30 +225,38 @@ export function useCollectionItem<T extends CollectionEntity>(
   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 +269,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 +309,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 +370,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 +420,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 +440,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,15 +25,50 @@ 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;
+}
 
 /**
- * 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, ...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;
+  }
+
+  const finalOptions: UseCollectionListOptions<ConnectionEntity> = {
+    ...collectionOptions,
+    additionalToolArgs:
+      Object.keys(additionalToolArgs).length > 0
+        ? additionalToolArgs
+        : undefined,
+  };
+
   const { org } = useProjectContext();
   const client = useMCPClient({
     connectionId: SELF_MCP_ALIAS_ID,
@@ -43,7 +78,7 @@ export function useConnections(options: UseConnectionsOptions = {}) {
     org.id,
     "CONNECTIONS",
     client,
-    options,
+    finalOptions,
   );
 }