@decocms/mesh-sdk 1.2.2 → 1.2.3

package/README.md

@@ -1,6 +1,6 @@
 # @decocms/mesh-sdk
 
-SDK for building external apps that integrate with Mesh MCP servers. Provides React hooks and utilities for managing connections, authenticating with OAuth, and calling MCP tools.
+SDK for building external apps that integrate with Studio MCP servers. Provides React hooks and utilities for managing connections, authenticating with OAuth, and calling MCP tools.
 
 ## Installation
 
@@ -22,7 +22,7 @@ npm install sonner
 
 ### 1. Create an API Key
 
-In Mesh, call the `API_KEY_CREATE` tool to create an API key with the appropriate scopes for the connections you want to access. The API key will be used to authenticate your external app.
+In Studio, call the `API_KEY_CREATE` tool to create an API key with the appropriate scopes for the connections you want to access. The API key will be used to authenticate your external app.
 
 ```typescript
 // Example: Create an API key via MCP
@@ -35,7 +35,7 @@ await client.callTool({
 });
 ```
 
-### 2. Server-Side: Connect to Mesh
+### 2. Server-Side: Connect to Studio
 
 ```typescript
 // server.ts (Node.js / Bun / your backend)
@@ -213,12 +213,12 @@ const result = await specificClient.callTool({
 
 ### `createMCPClient(options)` - Server-Side
 
-Creates and connects an MCP client to a Mesh server. **Use on server only** - don't expose your API key to the client.
+Creates and connects an MCP client to a Studio server. **Use on server only** - don't expose your API key to the client.
 
 ```typescript
 // server-side only
 const client = await createMCPClient({
-  meshUrl: "https://mesh.example.com",  // Required for external apps
+  meshUrl: "https://studio.example.com",  // Required for external apps
   connectionId: "self",                  // "self" for management API, or connection ID
   orgId: "org_xxx",                      // Organization ID
   token: process.env.MESH_API_KEY,       // API key from environment
@@ -227,7 +227,7 @@ const client = await createMCPClient({
 
 ### `useMCPClient(options)` - Client-Side (Same-Origin Only)
 
-React hook version of `createMCPClient`. Uses Suspense. **Only use when running on the same origin as Mesh** (e.g., inside the Mesh app itself).
+React hook version of `createMCPClient`. Uses Suspense. **Only use when running on the same origin as Studio** (e.g., inside Studio app itself).
 
 ```typescript
 // client-side - only for same-origin apps
@@ -249,7 +249,7 @@ Triggers OAuth authentication flow for an MCP connection. **This runs client-sid
 ```typescript
 // client-side - safe to use in browser
 const result = await authenticateMcp({
-  meshUrl: "https://mesh.example.com",  // Required for external apps
+  meshUrl: "https://studio.example.com",  // Required for external apps
   connectionId: "conn_xxx",              // Connection to authenticate
   callbackUrl: "https://your-app.com/oauth/callback",  // Your OAuth callback URL
   timeout: 120000,                       // Timeout in ms (default: 120000)
@@ -274,9 +274,9 @@ Check if a connection is authenticated. Can be used on either server or client.
 
 ```typescript
 const status = await isConnectionAuthenticated({
-  url: "https://mesh.example.com/mcp/conn_xxx",
+  url: "https://studio.example.com/mcp/conn_xxx",
   token: "bearer_token",  // Optional
-  meshUrl: "https://mesh.example.com",  // For API calls
+  meshUrl: "https://studio.example.com",  // For API calls
 });
 
 console.log(status.isAuthenticated);  // boolean
@@ -286,7 +286,7 @@ console.log(status.hasOAuthToken);    // boolean
 
 ### Collection Hooks - Client-Side (Same-Origin Only)
 
-When using with `ProjectContextProvider`, you get access to collection hooks. **Only use when running on the same origin as Mesh** (e.g., inside the Mesh app or plugins).
+When using with `ProjectContextProvider`, you get access to collection hooks. **Only use when running on the same origin as Studio** (e.g., inside Studio app or plugins).
 
 ```typescript
 // client-side - only for same-origin apps (inside Mesh)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/mesh-sdk",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "SDK for building external apps that integrate with Mesh MCP servers",
   "type": "module",
   "scripts": {
@@ -16,7 +16,8 @@
   },
   "dependencies": {
     "@decocms/bindings": "^1.1.1",
-    "@modelcontextprotocol/sdk": "1.27.1",
+    "@decocms/mcp-utils": "workspace:*",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4.0.0"
   },
   "peerDependencies": {

package/src/context/index.ts

@@ -3,7 +3,6 @@ export {
   useProjectContext,
   useOrg,
   useCurrentProject,
-  useIsOrgAdmin,
   Locator,
   type ProjectContextProviderProps,
   type ProjectLocator,

package/src/context/project-context.tsx

@@ -73,8 +73,6 @@ export interface ProjectData {
   enabledPlugins?: string[] | null;
   /** UI customization */
   ui?: ProjectUI | null;
-  /** Whether this is the org-admin project */
-  isOrgAdmin?: boolean;
 }
 
 interface ProjectContextType {
@@ -110,14 +108,6 @@ 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: OrganizationData;
   project: ProjectData;

package/src/hooks/index.ts

@@ -74,7 +74,10 @@ export {
 export {
   useVirtualMCPs,
   useVirtualMCP,
+  virtualMcpItemQueryOptions,
   useVirtualMCPActions,
+  useVirtualMCPsLastUsed,
   type VirtualMCPFilter,
   type UseVirtualMCPsOptions,
+  type VirtualMCPLastUsed,
 } from "./use-virtual-mcp";

package/src/hooks/use-collections.ts

@@ -146,7 +146,7 @@ export function buildOrderByExpression<T extends CollectionEntity>(
   defaultSortKey: keyof T,
 ): OrderByExpression[] | undefined {
   const key = sortKey ?? defaultSortKey;
-  const direction = sortDirection ?? "asc";
+  const direction = sortDirection ?? "desc";
 
   return [
     {
@@ -182,15 +182,12 @@ function extractPayload<T>(result: unknown): 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
+ * 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,
@@ -198,8 +195,7 @@ export function useCollectionItem<T extends CollectionEntity>(
 ) {
   const upperName = collectionName.toUpperCase();
   const getToolName = `COLLECTION_${upperName}_GET`;
-
-  const { data } = useSuspenseQuery({
+  return {
     queryKey: KEYS.collectionItem(
       client,
       scopeKey,
@@ -220,7 +216,18 @@ export function useCollectionItem<T extends CollectionEntity>(
       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;
 }

package/src/hooks/use-connection.ts

@@ -37,6 +37,10 @@ export interface UseConnectionsOptions
    * 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;
 }
 
 /**
@@ -46,7 +50,7 @@ export interface UseConnectionsOptions
  * @returns Suspense query result with connections as ConnectionEntity[]
  */
 export function useConnections(options: UseConnectionsOptions = {}) {
-  const { binding, includeVirtual, ...collectionOptions } = options;
+  const { binding, includeVirtual, slug, ...collectionOptions } = options;
 
   // Build additional tool args for the COLLECTION_CONNECTIONS_LIST tool
   const additionalToolArgs: Record<string, unknown> = {
@@ -61,6 +65,10 @@ export function useConnections(options: UseConnectionsOptions = {}) {
     additionalToolArgs.include_virtual = includeVirtual;
   }
 
+  if (slug !== undefined) {
+    additionalToolArgs.slug = slug;
+  }
+
   const finalOptions: UseCollectionListOptions<ConnectionEntity> = {
     ...collectionOptions,
     additionalToolArgs:
@@ -73,6 +81,7 @@ export function useConnections(options: UseConnectionsOptions = {}) {
   const client = useMCPClient({
     connectionId: SELF_MCP_ALIAS_ID,
     orgId: org.id,
+    orgSlug: org.slug,
   });
   return useCollectionList<ConnectionEntity>(
     org.id,
@@ -93,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,
@@ -112,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) */
@@ -28,10 +30,14 @@ export interface UseMcpClientOptionalOptions
 }
 
 /**
- * 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);
@@ -41,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;
 }
 
@@ -55,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: {
@@ -79,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}` } : {}),
       },
     },
@@ -112,6 +121,7 @@ export async function createMCPClient({
 export function useMCPClient({
   connectionId,
   orgId,
+  orgSlug,
   token,
   meshUrl,
 }: UseMcpClientOptions): Client {
@@ -124,9 +134,13 @@ export function useMCPClient({
 
   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,
   });
 
   return client!;
@@ -146,6 +160,7 @@ export function useMCPClient({
 export function useMCPClientOptional({
   connectionId,
   orgId,
+  orgSlug,
   token,
   meshUrl,
 }: UseMcpClientOptionalOptions): Client | null {
@@ -168,12 +183,14 @@ export function useMCPClientOptional({
       return createMCPClient({
         connectionId: connectionId as string | null,
         orgId,
+        orgSlug,
         token,
         meshUrl,
       });
     },
     staleTime: Infinity,
-    gcTime: 0,
+    // Match the non-optional variant — see useMCPClient for the rationale.
+    gcTime: 60_000,
   });
 
   return client ?? null;

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

@@ -5,17 +5,28 @@
  * These hooks offer a reactive interface for accessing and manipulating virtual MCPs.
  */
 
+import { useQuery } from "@tanstack/react-query";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { VirtualMCPEntity } from "../types/virtual-mcp";
 import { useProjectContext } from "../context";
 import {
+  collectionItemQueryOptions,
   useCollectionActions,
   useCollectionItem,
   useCollectionList,
   type CollectionFilter,
   type UseCollectionListOptions,
 } from "./use-collections";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { useMCPClient } from "./use-mcp-client";
 import { SELF_MCP_ALIAS_ID } from "../lib/constants";
+import { KEYS } from "../lib/query-keys";
+
+export interface VirtualMCPLastUsed {
+  id: string;
+  last_used_at?: string;
+  last_used_by?: string;
+}
 
 /**
  * Filter definition for virtual MCPs (matches @deco/ui Filter shape)
@@ -38,6 +49,7 @@ export function useVirtualMCPs(options: UseVirtualMCPsOptions = {}) {
   const client = useMCPClient({
     connectionId: SELF_MCP_ALIAS_ID,
     orgId: org.id,
+    orgSlug: org.slug,
   });
 
   return useCollectionList<VirtualMCPEntity>(
@@ -48,6 +60,23 @@ export function useVirtualMCPs(options: UseVirtualMCPsOptions = {}) {
   );
 }
 
+/**
+ * Query options for a single virtual MCP — shared with parallel-prefetch
+ * batches so they warm the exact cache entry useVirtualMCP reads.
+ */
+export function virtualMcpItemQueryOptions(
+  orgId: string,
+  virtualMcpId: string | null | undefined,
+  client: Client,
+) {
+  return collectionItemQueryOptions<VirtualMCPEntity>(
+    orgId,
+    "VIRTUAL_MCP",
+    virtualMcpId ?? undefined,
+    client,
+  );
+}
+
 /**
  * Hook to get a single virtual MCP by ID
  *
@@ -61,6 +90,7 @@ export function useVirtualMCP(
   const client = useMCPClient({
     connectionId: SELF_MCP_ALIAS_ID,
     orgId: org.id,
+    orgSlug: org.slug,
   });
 
   // If null/undefined, return null (use default virtual MCP)
@@ -75,6 +105,39 @@ export function useVirtualMCP(
   return dbVirtualMCP;
 }
 
+/**
+ * Hook to fetch last-used info (most recent thread timestamp + user) for a set
+ * of virtual MCPs. Backed by VIRTUAL_MCP_LAST_USED_LIST so the data isn't
+ * loaded on the agent fetch hot path.
+ */
+export function useVirtualMCPsLastUsed(ids: string[]) {
+  const { org } = useProjectContext();
+  const client = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+    orgSlug: org.slug,
+  });
+  const sortedIds = [...ids].sort();
+
+  return useQuery<Map<string, VirtualMCPLastUsed>>({
+    queryKey: KEYS.virtualMcpLastUsed(org.id, sortedIds),
+    enabled: sortedIds.length > 0,
+    staleTime: 30_000,
+    queryFn: async () => {
+      const result = (await client.callTool({
+        name: "VIRTUAL_MCP_LAST_USED_LIST",
+        arguments: { ids: sortedIds },
+      })) as CallToolResult;
+      const payload = (result.structuredContent ?? { items: [] }) as {
+        items: VirtualMCPLastUsed[];
+      };
+      const map = new Map<string, VirtualMCPLastUsed>();
+      for (const item of payload.items) map.set(item.id, item);
+      return map;
+    },
+  });
+}
+
 /**
  * Hook to get virtual MCP mutation actions (create, update, delete)
  *
@@ -85,6 +148,7 @@ export function useVirtualMCPActions() {
   const client = useMCPClient({
     connectionId: SELF_MCP_ALIAS_ID,
     orgId: org.id,
+    orgSlug: org.slug,
   });
 
   return useCollectionActions<VirtualMCPEntity>(org.id, "VIRTUAL_MCP", client);

package/src/index.ts

@@ -4,7 +4,6 @@ export {
   useProjectContext,
   useOrg,
   useCurrentProject,
-  useIsOrgAdmin,
   Locator,
   type ProjectContextProviderProps,
   type ProjectLocator,
@@ -73,9 +72,12 @@ export {
   // Virtual MCP hooks
   useVirtualMCPs,
   useVirtualMCP,
+  virtualMcpItemQueryOptions,
   useVirtualMCPActions,
+  useVirtualMCPsLastUsed,
   type VirtualMCPFilter,
   type UseVirtualMCPsOptions,
+  type VirtualMCPLastUsed,
 } from "./hooks";
 
 // Types
@@ -109,10 +111,28 @@ export {
   VirtualMCPEntitySchema,
   VirtualMCPCreateDataSchema,
   VirtualMCPUpdateDataSchema,
+  VirtualMcpUILayoutSchema,
+  VirtualMcpUILayoutTabSchema,
   type VirtualMCPEntity,
   type VirtualMCPCreateData,
   type VirtualMCPUpdateData,
   type VirtualMCPConnection,
+  type VirtualMcpUILayout,
+  type VirtualMcpUILayoutTab,
+  type VirtualMcpHomeTile,
+  getHomeTiles,
+  SandboxMapSchema,
+  type SandboxMap,
+  SandboxRecordSchema,
+  type SandboxRecord,
+  type RuntimeMetadata,
+  type RuntimeEnvEntry,
+  ENV_VAR_KEY_RE,
+  parseSandboxRecord,
+  parseBranchMap,
+  normalizeSandboxMap,
+  type SandboxProviderKind,
+  type GithubRepo,
   // Decopilot event types
   THREAD_STATUSES,
   THREAD_DISPLAY_STATUSES,
@@ -155,8 +175,15 @@ export { KEYS } from "./lib/query-keys";
 export {
   DEFAULT_MODEL_PREFERENCES,
   FAST_MODEL_PREFERENCES,
+  SMART_MODEL_PREFERENCES,
+  THINKING_MODEL_PREFERENCES,
+  IMAGE_MODEL_PREFERENCES,
+  WEB_RESEARCH_MODEL_PREFERENCES,
   selectDefaultModel,
   getFastModel,
+  pickSimpleModeDefaults,
+  type SimpleModeModelSlot,
+  type SimpleModeDefaults,
 } from "./lib/default-model";
 
 // MCP OAuth utilities
@@ -196,7 +223,6 @@ export {
   getWellKnownCommunityRegistryConnection,
   getWellKnownSelfConnection,
   getWellKnownDevAssetsConnection,
-  getWellKnownOpenRouterConnection,
   getWellKnownMcpStudioConnection,
   // Virtual MCP factory functions
   getWellKnownDecopilotVirtualMCP,
@@ -204,4 +230,14 @@ export {
   // Decopilot utilities
   isDecopilot,
   getDecopilotId,
+  // Site Diagnostics utilities
+  isSiteDiagnostics,
+  getSiteDiagnosticsId,
+  // Brand-Context Setup utilities
+  isBrandContextSetup,
+  getBrandContextSetupId,
+  getWellKnownBrandContextSetupVirtualMCP,
+  // Studio Pack utilities
+  StudioPackAgentId,
+  isStudioPackAgent,
 } from "./lib/constants";