@decocms/mesh-sdk 1.1.0

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

@@ -0,0 +1,128 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  useQuery,
+  useSuspenseQuery,
+  type UseQueryOptions,
+  type UseQueryResult,
+  type UseSuspenseQueryOptions,
+  type UseSuspenseQueryResult,
+} from "@tanstack/react-query";
+import type {
+  ListResourcesResult,
+  ReadResourceResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import { KEYS } from "../lib/query-keys";
+
+/**
+ * List resources from an MCP client.
+ * This is the raw async function that can be used outside of React hooks.
+ */
+export async function listResources(
+  client: Client,
+): Promise<ListResourcesResult> {
+  const capabilities = client.getServerCapabilities();
+  if (!capabilities?.resources) {
+    return { resources: [] };
+  }
+  return await client.listResources();
+}
+
+/**
+ * Read a specific resource from an MCP client.
+ * This is the raw async function that can be used outside of React hooks.
+ */
+export async function readResource(
+  client: Client,
+  uri: string,
+): Promise<ReadResourceResult> {
+  return await client.readResource({ uri });
+}
+
+export interface UseMcpResourcesListOptions
+  extends Omit<
+    UseSuspenseQueryOptions<ListResourcesResult, Error>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+}
+
+/**
+ * Suspense hook to list resources from an MCP client.
+ * Must be used within a Suspense boundary.
+ */
+export function useMCPResourcesList({
+  client,
+  ...queryOptions
+}: UseMcpResourcesListOptions): UseSuspenseQueryResult<
+  ListResourcesResult,
+  Error
+> {
+  return useSuspenseQuery<ListResourcesResult, Error>({
+    ...queryOptions,
+    queryKey: KEYS.mcpResourcesList(client),
+    queryFn: () => listResources(client),
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}
+
+export interface UseMcpResourcesListQueryOptions
+  extends Omit<
+    UseQueryOptions<ListResourcesResult, Error>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+}
+
+/**
+ * Non-suspense hook to list resources from an MCP client.
+ */
+export function useMCPResourcesListQuery({
+  client,
+  ...queryOptions
+}: UseMcpResourcesListQueryOptions): UseQueryResult<
+  ListResourcesResult,
+  Error
+> {
+  return useQuery<ListResourcesResult, Error>({
+    ...queryOptions,
+    queryKey: KEYS.mcpResourcesList(client),
+    queryFn: () => listResources(client),
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}
+
+export interface UseMcpReadResourceOptions
+  extends Omit<
+    UseSuspenseQueryOptions<ReadResourceResult, Error>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+  /** Resource URI to read */
+  uri: string;
+}
+
+/**
+ * Suspense hook to read a specific resource from an MCP client.
+ * Must be used within a Suspense boundary.
+ */
+export function useMCPReadResource({
+  client,
+  uri,
+  ...queryOptions
+}: UseMcpReadResourceOptions): UseSuspenseQueryResult<
+  ReadResourceResult,
+  Error
+> {
+  return useSuspenseQuery<ReadResourceResult, Error>({
+    ...queryOptions,
+    queryKey: KEYS.mcpReadResource(client, uri),
+    queryFn: () => readResource(client, uri),
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}

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

@@ -0,0 +1,184 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  useMutation,
+  useQuery,
+  useSuspenseQuery,
+  type UseMutationOptions,
+  type UseMutationResult,
+  type UseQueryOptions,
+  type UseQueryResult,
+  type UseSuspenseQueryOptions,
+  type UseSuspenseQueryResult,
+} from "@tanstack/react-query";
+import type {
+  CallToolRequest,
+  CallToolResult,
+  ListToolsResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import { KEYS } from "../lib/query-keys";
+
+export interface UseMcpToolsListOptions
+  extends Omit<
+    UseSuspenseQueryOptions<ListToolsResult, Error>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+}
+
+/**
+ * Suspense hook to list tools from an MCP client.
+ * Must be used within a Suspense boundary.
+ */
+export function useMCPToolsList({
+  client,
+  ...queryOptions
+}: UseMcpToolsListOptions): UseSuspenseQueryResult<ListToolsResult, Error> {
+  return useSuspenseQuery<ListToolsResult, Error>({
+    ...queryOptions,
+    queryKey: KEYS.mcpToolsList(client),
+    queryFn: async () => {
+      return await client.listTools();
+    },
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}
+
+export interface UseMcpToolsListQueryOptions
+  extends Omit<
+    UseQueryOptions<ListToolsResult, Error>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+}
+
+/**
+ * Non-suspense hook to list tools from an MCP client.
+ */
+export function useMCPToolsListQuery({
+  client,
+  ...queryOptions
+}: UseMcpToolsListQueryOptions): UseQueryResult<ListToolsResult, Error> {
+  return useQuery<ListToolsResult, Error>({
+    ...queryOptions,
+    queryKey: KEYS.mcpToolsList(client),
+    queryFn: async () => {
+      return await client.listTools();
+    },
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}
+
+export interface UseMcpToolCallOptions<TData = CallToolResult>
+  extends Omit<
+    UseSuspenseQueryOptions<CallToolResult, Error, TData>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+  /** Tool name to call */
+  toolName: string;
+  /** Tool arguments */
+  toolArguments?: Record<string, unknown>;
+}
+
+/**
+ * Suspense hook to call a tool on an MCP client.
+ * Must be used within a Suspense boundary.
+ *
+ * @template TData - The type of data returned (after optional select transformation)
+ */
+export function useMCPToolCall<TData = CallToolResult>({
+  client,
+  toolName,
+  toolArguments,
+  ...queryOptions
+}: UseMcpToolCallOptions<TData>): UseSuspenseQueryResult<TData, Error> {
+  const argsKey = JSON.stringify(toolArguments ?? {});
+
+  return useSuspenseQuery<CallToolResult, Error, TData>({
+    ...queryOptions,
+    queryKey: KEYS.mcpToolCall(client, toolName, argsKey),
+    queryFn: async () => {
+      const result = await client.callTool({
+        name: toolName,
+        arguments: toolArguments,
+      });
+      return result as CallToolResult;
+    },
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}
+
+export interface UseMcpToolCallQueryOptions<TData = CallToolResult>
+  extends Omit<
+    UseQueryOptions<CallToolResult, Error, TData>,
+    "queryKey" | "queryFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+  /** Tool name to call */
+  toolName: string;
+  /** Tool arguments */
+  toolArguments?: Record<string, unknown>;
+}
+
+/**
+ * Non-suspense hook to call a tool on an MCP client.
+ *
+ * @template TData - The type of data returned (after optional select transformation)
+ */
+export function useMCPToolCallQuery<TData = CallToolResult>({
+  client,
+  toolName,
+  toolArguments,
+  ...queryOptions
+}: UseMcpToolCallQueryOptions<TData>): UseQueryResult<TData, Error> {
+  const argsKey = JSON.stringify(toolArguments ?? {});
+
+  return useQuery<CallToolResult, Error, TData>({
+    ...queryOptions,
+    queryKey: KEYS.mcpToolCall(client, toolName, argsKey),
+    queryFn: async () => {
+      const result = await client.callTool({
+        name: toolName,
+        arguments: toolArguments,
+      });
+      return result as CallToolResult;
+    },
+    staleTime: queryOptions.staleTime ?? 30000,
+    retry: false,
+  });
+}
+
+export interface UseMcpToolCallMutationOptions
+  extends Omit<
+    UseMutationOptions<CallToolResult, Error, CallToolRequest["params"]>,
+    "mutationFn"
+  > {
+  /** The MCP client from useMCPClient */
+  client: Client;
+}
+
+/**
+ * Mutation hook to call a tool on an MCP client.
+ */
+export function useMCPToolCallMutation({
+  client,
+  ...mutationOptions
+}: UseMcpToolCallMutationOptions): UseMutationResult<
+  CallToolResult,
+  Error,
+  CallToolRequest["params"]
+> {
+  return useMutation<CallToolResult, Error, CallToolRequest["params"]>({
+    ...mutationOptions,
+    mutationFn: async (params) => {
+      return (await client.callTool(params)) as CallToolResult;
+    },
+  });
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Virtual MCP Collection Hooks
+ *
+ * Provides React hooks for working with virtual MCPs using React Query.
+ * These hooks offer a reactive interface for accessing and manipulating virtual MCPs.
+ */
+
+import type { VirtualMCPEntity } from "../types/virtual-mcp";
+import { useProjectContext } from "../context";
+import {
+  useCollectionActions,
+  useCollectionItem,
+  useCollectionList,
+  type CollectionFilter,
+  type UseCollectionListOptions,
+} from "./use-collections";
+import { useMCPClient } from "./use-mcp-client";
+import { SELF_MCP_ALIAS_ID } from "../lib/constants";
+
+/**
+ * Filter definition for virtual MCPs (matches @deco/ui Filter shape)
+ */
+export type VirtualMCPFilter = CollectionFilter;
+
+/**
+ * Options for useVirtualMCPs hook
+ */
+export type UseVirtualMCPsOptions = UseCollectionListOptions<VirtualMCPEntity>;
+
+/**
+ * Hook to get all virtual MCPs
+ *
+ * @param options - Filter and configuration options
+ * @returns Suspense query result with virtual MCPs as VirtualMCPEntity[]
+ */
+export function useVirtualMCPs(options: UseVirtualMCPsOptions = {}) {
+  const { org } = useProjectContext();
+  const client = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+
+  return useCollectionList<VirtualMCPEntity>(
+    org.id,
+    "VIRTUAL_MCP",
+    client,
+    options,
+  );
+}
+
+/**
+ * Hook to get a single virtual MCP by ID
+ *
+ * @param virtualMcpId - The ID of the virtual MCP to fetch (null/undefined for default virtual MCP)
+ * @returns VirtualMCPEntity | null - null means use default virtual MCP
+ */
+export function useVirtualMCP(
+  virtualMcpId: string | null | undefined,
+): VirtualMCPEntity | null {
+  const { org } = useProjectContext();
+  const client = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+
+  // If null/undefined, return null (use default virtual MCP)
+  // Use collection item hook for database virtual MCPs
+  const dbVirtualMCP = useCollectionItem<VirtualMCPEntity>(
+    org.id,
+    "VIRTUAL_MCP",
+    virtualMcpId ?? undefined,
+    client,
+  );
+
+  return dbVirtualMCP;
+}
+
+/**
+ * Hook to get virtual MCP mutation actions (create, update, delete)
+ *
+ * @returns Object with create, update, and delete mutation hooks
+ */
+export function useVirtualMCPActions() {
+  const { org } = useProjectContext();
+  const client = useMCPClient({
+    connectionId: SELF_MCP_ALIAS_ID,
+    orgId: org.id,
+  });
+
+  return useCollectionActions<VirtualMCPEntity>(org.id, "VIRTUAL_MCP", client);
+}

package/src/index.ts

@@ -0,0 +1,128 @@
+// Context
+export {
+  ProjectContextProvider,
+  useProjectContext,
+  Locator,
+  ORG_ADMIN_PROJECT_SLUG,
+  type ProjectContextProviderProps,
+  type ProjectLocator,
+  type LocatorStructured,
+} from "./context";
+
+// Hooks
+export {
+  // Collection hooks
+  useCollectionItem,
+  useCollectionList,
+  useCollectionActions,
+  type CollectionEntity,
+  type CollectionFilter,
+  type UseCollectionListOptions,
+  // Connection hooks
+  useConnections,
+  useConnection,
+  useConnectionActions,
+  type ConnectionFilter,
+  type UseConnectionsOptions,
+  // MCP client hook and factory
+  createMCPClient,
+  useMCPClient,
+  type CreateMcpClientOptions,
+  type UseMcpClientOptions,
+  // MCP tools hooks
+  useMCPToolsList,
+  useMCPToolsListQuery,
+  useMCPToolCall,
+  useMCPToolCallQuery,
+  useMCPToolCallMutation,
+  type UseMcpToolsListOptions,
+  type UseMcpToolsListQueryOptions,
+  type UseMcpToolCallOptions,
+  type UseMcpToolCallQueryOptions,
+  type UseMcpToolCallMutationOptions,
+  // MCP resources hooks and helpers
+  listResources,
+  readResource,
+  useMCPResourcesList,
+  useMCPResourcesListQuery,
+  useMCPReadResource,
+  type UseMcpResourcesListOptions,
+  type UseMcpResourcesListQueryOptions,
+  type UseMcpReadResourceOptions,
+  // MCP prompts hooks and helpers
+  listPrompts,
+  getPrompt,
+  useMCPPromptsList,
+  useMCPPromptsListQuery,
+  useMCPGetPrompt,
+  type UseMcpPromptsListOptions,
+  type UseMcpPromptsListQueryOptions,
+  type UseMcpGetPromptOptions,
+  // Virtual MCP hooks
+  useVirtualMCPs,
+  useVirtualMCP,
+  useVirtualMCPActions,
+  type VirtualMCPFilter,
+  type UseVirtualMCPsOptions,
+} from "./hooks";
+
+// Types
+export {
+  ConnectionEntitySchema,
+  ConnectionCreateDataSchema,
+  ConnectionUpdateDataSchema,
+  isStdioParameters,
+  parseVirtualUrl,
+  buildVirtualUrl,
+  type ConnectionEntity,
+  type ConnectionCreateData,
+  type ConnectionUpdateData,
+  type ConnectionParameters,
+  type HttpConnectionParameters,
+  type StdioConnectionParameters,
+  type OAuthConfig,
+  type ToolDefinition,
+  // Virtual MCP types
+  VirtualMCPEntitySchema,
+  VirtualMCPCreateDataSchema,
+  VirtualMCPUpdateDataSchema,
+  type VirtualMCPEntity,
+  type VirtualMCPCreateData,
+  type VirtualMCPUpdateData,
+  type VirtualMCPConnection,
+  type ToolSelectionMode,
+} from "./types";
+
+// Streamable HTTP transport
+export { StreamableHTTPClientTransport } from "./lib/streamable-http-client-transport";
+
+// Query keys
+export { KEYS } from "./lib/query-keys";
+
+// MCP OAuth utilities
+export {
+  authenticateMcp,
+  handleOAuthCallback,
+  isConnectionAuthenticated,
+  type McpOAuthProviderOptions,
+  type OAuthTokenInfo,
+  type AuthenticateMcpResult,
+  type McpAuthStatus,
+  type OAuthWindowMode,
+} from "./lib/mcp-oauth";
+
+// Constants and well-known MCP definitions
+export {
+  // Frontend self MCP ID
+  SELF_MCP_ALIAS_ID,
+  // Org-scoped MCP ID generators
+  WellKnownOrgMCPId,
+  // Connection factory functions
+  getWellKnownRegistryConnection,
+  getWellKnownCommunityRegistryConnection,
+  getWellKnownSelfConnection,
+  getWellKnownOpenRouterConnection,
+  getWellKnownMcpStudioConnection,
+  // Virtual MCP factory functions
+  getWellKnownDecopilotAgent,
+} from "./lib/constants";