@decocms/mesh-sdk 1.1.0

package/README.md

@@ -0,0 +1,368 @@
+# @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.
+
+## Installation
+
+```bash
+npm install @decocms/mesh-sdk @decocms/bindings
+# or
+bun add @decocms/mesh-sdk @decocms/bindings
+```
+
+### Peer Dependencies
+
+```bash
+npm install react @tanstack/react-query
+# Optional: for toast notifications
+npm install sonner
+```
+
+## Quick Start
+
+### 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.
+
+```typescript
+// Example: Create an API key via MCP
+await client.callTool({
+  name: "API_KEY_CREATE",
+  arguments: {
+    name: "My External App",
+    scopes: ["connections:read", "connections:write"],
+  },
+});
+```
+
+### 2. Server-Side: Connect to Mesh
+
+```typescript
+// server.ts (Node.js / Bun / your backend)
+import { createMCPClient } from "@decocms/mesh-sdk";
+
+// Create an MCP client - keep API key on server only!
+const client = await createMCPClient({
+  meshUrl: "https://mesh.your-company.com",  // Your Mesh server URL
+  connectionId: "self",                       // "self" for management API
+  orgId: "org_xxxxx",                         // Your organization ID
+  token: process.env.MESH_API_KEY,            // API key from environment
+});
+
+// List connections
+const result = await client.callTool({
+  name: "COLLECTION_CONNECTIONS_LIST",
+  arguments: { limit: 100 },
+});
+```
+
+### 3. Client-Side: Set Up React App
+
+```tsx
+// app.tsx (React client)
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Toaster } from "sonner";
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+      <Toaster />
+    </QueryClientProvider>
+  );
+}
+```
+
+## Full Example: User Sandbox Integration
+
+The most common use case for external apps is letting your end-users connect their own MCPs via the **User Sandbox plugin**. This creates isolated connections per user.
+
+### Server-Side: Create a Connect Session
+
+```typescript
+// server/api.ts (Hono / Express / your backend)
+import { Hono } from "hono";
+import { createMCPClient } from "@decocms/mesh-sdk";
+
+const app = new Hono();
+
+const MESH_URL = process.env.MESH_URL!;
+const ORG_ID = process.env.MESH_ORG_ID!;
+const API_KEY = process.env.MESH_API_KEY!;
+
+let meshClient: Awaited<ReturnType<typeof createMCPClient>> | null = null;
+
+async function getMeshClient() {
+  if (!meshClient) {
+    meshClient = await createMCPClient({
+      meshUrl: MESH_URL,
+      connectionId: "self",
+      orgId: ORG_ID,
+      token: API_KEY,
+    });
+  }
+  return meshClient;
+}
+
+// POST /api/connect-session - Create a session for end-user to connect MCPs
+app.post("/api/connect-session", async (c) => {
+  const { userId } = await c.req.json();
+  const client = await getMeshClient();
+
+  // Call User Sandbox plugin to create a connect session
+  const result = await client.callTool({
+    name: "USER_SANDBOX_CREATE_SESSION",
+    arguments: {
+      templateId: "your-template-id",  // Created in Mesh dashboard
+      externalUserId: userId,           // Your app's user ID
+      redirectUrl: "https://your-app.com/connect/complete",
+    },
+  });
+
+  const payload = result as { structuredContent?: { sessionUrl: string } };
+  return c.json({ connectUrl: payload.structuredContent?.sessionUrl });
+});
+
+export default app;
+```
+
+### Client-Side: Redirect User to Connect
+
+```tsx
+// client/connect-button.tsx (React)
+
+function ConnectIntegrationsButton({ userId }: { userId: string }) {
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleConnect = async () => {
+    setIsLoading(true);
+
+    // Get connect session URL from your server
+    const res = await fetch("/api/connect-session", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ userId }),
+    });
+    const { connectUrl } = await res.json();
+
+    // Redirect user to Mesh connect flow
+    window.location.href = connectUrl;
+  };
+
+  return (
+    <button
+      onClick={handleConnect}
+      disabled={isLoading}
+      className="px-4 py-2 bg-blue-600 text-white rounded"
+    >
+      {isLoading ? "Loading..." : "Connect Your Apps"}
+    </button>
+  );
+}
+```
+
+## Example: Direct MCP Tool Calls
+
+For server-side automation or admin tasks, you can call any MCP tool directly:
+
+```typescript
+// server-side only
+import { createMCPClient } from "@decocms/mesh-sdk";
+
+const client = await createMCPClient({
+  meshUrl: "https://mesh.your-company.com",
+  connectionId: "self",
+  orgId: process.env.ORG_ID!,
+  token: process.env.MESH_API_KEY!,
+});
+
+// List Virtual MCPs (agents)
+const agents = await client.callTool({
+  name: "COLLECTION_VIRTUAL_MCP_LIST",
+  arguments: { limit: 100 },
+});
+
+// Create a connection
+const newConn = await client.callTool({
+  name: "COLLECTION_CONNECTIONS_CREATE",
+  arguments: {
+    data: {
+      title: "My MCP Server",
+      url: "https://mcp.example.com/sse",
+    },
+  },
+});
+
+// Call a tool on a specific connection
+const specificClient = await createMCPClient({
+  meshUrl: "https://mesh.your-company.com",
+  connectionId: "conn_xxx",  // Target connection ID
+  orgId: process.env.ORG_ID!,
+  token: process.env.MESH_API_KEY!,
+});
+
+const result = await specificClient.callTool({
+  name: "SOME_TOOL_ON_THAT_MCP",
+  arguments: { /* ... */ },
+});
+```
+
+## API Reference
+
+### `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.
+
+```typescript
+// server-side only
+const client = await createMCPClient({
+  meshUrl: "https://mesh.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
+});
+```
+
+### `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).
+
+```typescript
+// client-side - only for same-origin apps
+function MyComponent() {
+  const client = useMCPClient({
+    connectionId: "self",
+    orgId: "org_xxx",
+    // No token needed when using cookies on same origin
+  });
+
+  // client is ready to use
+}
+```
+
+### `authenticateMcp(options)` - Client-Side
+
+Triggers OAuth authentication flow for an MCP connection. **This runs client-side** - it doesn't expose your API key.
+
+```typescript
+// client-side - safe to use in browser
+const result = await authenticateMcp({
+  meshUrl: "https://mesh.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)
+  scope: ["read", "write"],              // OAuth scopes (optional)
+  windowMode: "popup",                   // "popup" (default) or "tab"
+});
+
+if (result.error) {
+  console.error("Auth failed:", result.error);
+} else {
+  console.log("Got token:", result.token);
+}
+```
+
+**Window modes:**
+- `"popup"` (default): Opens OAuth in a popup window. May be blocked on some mobile devices.
+- `"tab"`: Opens OAuth in a new tab. Works on all devices. Uses localStorage for cross-tab communication.
+
+### `isConnectionAuthenticated(options)` - Server or Client
+
+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",
+  token: "bearer_token",  // Optional
+  meshUrl: "https://mesh.example.com",  // For API calls
+});
+
+console.log(status.isAuthenticated);  // boolean
+console.log(status.supportsOAuth);    // boolean
+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).
+
+```typescript
+// client-side - only for same-origin apps (inside Mesh)
+import {
+  ProjectContextProvider,
+  useConnections,
+  useConnection,
+  useConnectionActions,
+} from "@decocms/mesh-sdk";
+
+function App() {
+  return (
+    <ProjectContextProvider
+      org={{ id: "org_xxx", slug: "my-org", name: "My Org", logo: null }}
+      project={{ slug: "org-admin" }}
+    >
+      <ConnectionsManager />
+    </ProjectContextProvider>
+  );
+}
+
+function ConnectionsManager() {
+  // List all connections
+  const connections = useConnections();
+
+  // Get single connection
+  const connection = useConnection("conn_xxx");
+
+  // CRUD actions
+  const { create, update, delete: remove } = useConnectionActions();
+
+  await create.mutateAsync({
+    title: "My MCP",
+    url: "https://mcp.example.com",
+  });
+}
+```
+
+## OAuth Callback Setup - Client-Side
+
+If you're using `authenticateMcp()` directly (not via User Sandbox plugin), you need an OAuth callback route. This is a **client-side page** that receives the OAuth authorization code:
+
+```tsx
+// pages/oauth/callback.tsx (React client-side page)
+export function OAuthCallback() {
+  const params = new URLSearchParams(window.location.search);
+
+  if (window.opener) {
+    window.opener.postMessage({
+      type: "mcp:oauth:callback",
+      success: !params.get("error"),
+      code: params.get("code"),
+      state: params.get("state"),
+      error: params.get("error"),
+    }, window.location.origin);
+  }
+
+  return <p>Authentication complete. You can close this window.</p>;
+}
+```
+
+> **Note**: If you're using the User Sandbox plugin, OAuth is handled automatically in the connect flow - you don't need this callback page.
+
+## Types
+
+```typescript
+import type {
+  ConnectionEntity,
+  ConnectionCreateData,
+  ConnectionUpdateData,
+  VirtualMCPEntity,
+  VirtualMCPCreateData,
+  VirtualMCPUpdateData,
+} from "@decocms/mesh-sdk";
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@decocms/mesh-sdk",
+  "version": "1.1.0",
+  "description": "SDK for building external apps that integrate with Mesh MCP servers",
+  "type": "module",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./hooks": "./src/hooks/index.ts",
+    "./context": "./src/context/index.ts",
+    "./types": "./src/types/index.ts"
+  },
+  "dependencies": {
+    "@decocms/bindings": "^1.1.1",
+    "@modelcontextprotocol/sdk": "1.25.2",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "react": ">=18.0.0",
+    "sonner": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "sonner": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mesh",
+    "mcp",
+    "model-context-protocol",
+    "sdk",
+    "react",
+    "hooks"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/decocms/admin.git",
+    "directory": "packages/mesh-sdk"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/context/index.ts

@@ -0,0 +1,9 @@
+export {
+  ProjectContextProvider,
+  useProjectContext,
+  Locator,
+  ORG_ADMIN_PROJECT_SLUG,
+  type ProjectContextProviderProps,
+  type ProjectLocator,
+  type LocatorStructured,
+} from "./project-context";

package/src/context/project-context.tsx

@@ -0,0 +1,89 @@
+import { createContext, useContext, type PropsWithChildren } from "react";
+
+/**
+ * a ProjectLocator is a github-like slug string that identifies a project in an organization.
+ *
+ * format: <org-slug>/<project-slug>
+ */
+export type ProjectLocator = `${string}/${string}`;
+
+export type LocatorStructured = {
+  org: string;
+  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 {
+    if (locator.startsWith("/")) {
+      locator = locator.slice(1) as ProjectLocator;
+    }
+    const [org, project] = locator.split("/");
+    if (!org || !project) {
+      throw new Error("Invalid 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;
+  };
+
+  locator: ProjectLocator;
+}
+
+const ProjectContext = createContext<ProjectContextType | undefined>(undefined);
+
+export const useProjectContext = () => {
+  const context = useContext(ProjectContext);
+  if (!context) {
+    throw new Error(
+      "useProjectContext must be used within a ProjectContextProvider",
+    );
+  }
+
+  return context;
+};
+
+export type ProjectContextProviderProps = {
+  org: { id: string; slug: string; name: string; logo: string | null };
+  project: { name?: string; slug: string };
+};
+
+export const ProjectContextProvider = ({
+  children,
+  org,
+  project,
+}: PropsWithChildren<ProjectContextProviderProps>) => {
+  const locator = Locator.from({ org: org.slug, project: project.slug });
+
+  const value = { org, project, locator };
+
+  return (
+    <ProjectContext.Provider value={value}>{children}</ProjectContext.Provider>
+  );
+};

package/src/hooks/index.ts

@@ -0,0 +1,73 @@
+// Collection hooks
+export {
+  useCollectionItem,
+  useCollectionList,
+  useCollectionActions,
+  type CollectionEntity,
+  type CollectionFilter,
+  type UseCollectionListOptions,
+} from "./use-collections";
+
+// Connection hooks
+export {
+  useConnections,
+  useConnection,
+  useConnectionActions,
+  type ConnectionFilter,
+  type UseConnectionsOptions,
+} from "./use-connection";
+
+// MCP client hook and factory
+export {
+  createMCPClient,
+  useMCPClient,
+  type CreateMcpClientOptions,
+  type UseMcpClientOptions,
+} from "./use-mcp-client";
+
+// MCP tools hooks
+export {
+  useMCPToolsList,
+  useMCPToolsListQuery,
+  useMCPToolCall,
+  useMCPToolCallQuery,
+  useMCPToolCallMutation,
+  type UseMcpToolsListOptions,
+  type UseMcpToolsListQueryOptions,
+  type UseMcpToolCallOptions,
+  type UseMcpToolCallQueryOptions,
+  type UseMcpToolCallMutationOptions,
+} from "./use-mcp-tools";
+
+// MCP resources hooks and helpers
+export {
+  listResources,
+  readResource,
+  useMCPResourcesList,
+  useMCPResourcesListQuery,
+  useMCPReadResource,
+  type UseMcpResourcesListOptions,
+  type UseMcpResourcesListQueryOptions,
+  type UseMcpReadResourceOptions,
+} from "./use-mcp-resources";
+
+// MCP prompts hooks and helpers
+export {
+  listPrompts,
+  getPrompt,
+  useMCPPromptsList,
+  useMCPPromptsListQuery,
+  useMCPGetPrompt,
+  type UseMcpPromptsListOptions,
+  type UseMcpPromptsListQueryOptions,
+  type UseMcpGetPromptOptions,
+} from "./use-mcp-prompts";
+
+// Virtual MCP hooks
+export {
+  useVirtualMCPs,
+  useVirtualMCP,
+  useVirtualMCPActions,
+  type VirtualMCPFilter,
+  type UseVirtualMCPsOptions,
+} from "./use-virtual-mcp";