@decocms/mesh-sdk 1.2.1 → 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.1",
+  "version": "1.2.3",
   "description": "SDK for building external apps that integrate with Mesh MCP servers",
   "type": "module",
   "scripts": {
@@ -11,16 +11,19 @@
     ".": "./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",
+    "@decocms/mcp-utils": "workspace:*",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "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 +44,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,13 @@
 export {
   ProjectContextProvider,
   useProjectContext,
+  useOrg,
+  useCurrentProject,
   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,58 @@ 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;
+}
+
+interface ProjectContextType {
+  org: OrganizationData;
+  project: ProjectData;
   locator: ProjectLocator;
 }
 
@@ -69,9 +94,23 @@ 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;
+};
+
 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 +118,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
@@ -67,7 +74,10 @@ export {
 export {
   useVirtualMCPs,
   useVirtualMCP,
+  virtualMcpItemQueryOptions,
   useVirtualMCPActions,
+  useVirtualMCPsLastUsed,
   type VirtualMCPFilter,
   type UseVirtualMCPsOptions,
+  type VirtualMCPLastUsed,
 } from "./use-virtual-mcp";