@decocms/mesh-sdk 1.1.0

package/src/lib/query-keys.ts

@@ -0,0 +1,178 @@
+/**
+ * Centralized Query Keys for React Query
+ *
+ * This ensures consistent cache key management across the application
+ * and prevents inline array declarations that are harder to maintain.
+ */
+
+import type { ProjectLocator } from "../context";
+
+export const KEYS = {
+  // Auth-related queries
+  authConfig: () => ["authConfig"] as const,
+
+  // Chat store (IndexedDB) queries
+  threads: (locator: string) => ["threads", locator] as const,
+  virtualMcpThreads: (locator: string, virtualMcpId: string) =>
+    ["threads", locator, "virtual-mcp", virtualMcpId] as const,
+  thread: (locator: string, threadId: string) =>
+    ["thread", locator, threadId] as const,
+  threadMessages: (locator: string, threadId: string) =>
+    ["thread-messages", locator, threadId] as const,
+  messages: (locator: string) => ["messages", locator] as const,
+
+  // Organizations list
+  organizations: () => ["organizations"] as const,
+
+  // Organization members (scoped by org)
+  members: (locator: ProjectLocator) => [locator, "members"] as const,
+
+  // Organization invitations (scoped by org)
+  invitations: (locator: ProjectLocator) => [locator, "invitations"] as const,
+
+  // Organization roles (scoped by org)
+  organizationRoles: (locator: ProjectLocator) =>
+    [locator, "organization-roles"] as const,
+
+  // Connections (scoped by project)
+  connections: (locator: ProjectLocator) => [locator, "connections"] as const,
+  connectionsByBinding: (locator: ProjectLocator, binding: string) =>
+    [locator, "connections", `binding:${binding}`] as const,
+  connection: (locator: ProjectLocator, id: string) =>
+    [locator, "connection", id] as const,
+
+  isMCPAuthenticated: (url: string, token: string | null) =>
+    ["is-mcp-authenticated", url, token] as const,
+
+  // MCP tools (scoped by URL and optional token)
+  mcpTools: (url: string, token?: string | null) =>
+    ["mcp", "tools", url, token] as const,
+
+  // MCP client (scoped by orgId, connectionId, token, and meshUrl)
+  mcpClient: (
+    orgId: string,
+    connectionId: string,
+    token: string,
+    meshUrl: string,
+  ) => ["mcp", "client", orgId, connectionId, token, meshUrl] as const,
+
+  // MCP client-based queries (scoped by client instance)
+  mcpToolsList: (client: unknown) =>
+    ["mcp", "client", client, "tools"] as const,
+  mcpResourcesList: (client: unknown) =>
+    ["mcp", "client", client, "resources"] as const,
+  mcpPromptsList: (client: unknown) =>
+    ["mcp", "client", client, "prompts"] as const,
+  mcpReadResource: (client: unknown, uri: string) =>
+    ["mcp", "client", client, "resource", uri] as const,
+  mcpGetPrompt: (client: unknown, name: string, argsKey: string) =>
+    ["mcp", "client", client, "prompt", name, argsKey] as const,
+  mcpToolCall: (client: unknown, toolName: string, argsKey: string) =>
+    ["mcp", "client", client, "tool-call", toolName, argsKey] as const,
+
+  organizationSettings: (organizationId: string) =>
+    ["organization-settings", organizationId] as const,
+
+  // Active organization
+  activeOrganization: (org: string | undefined) =>
+    ["activeOrganization", org] as const,
+
+  // Models list (scoped by organization)
+  modelsList: (orgId: string) => ["models-list", orgId] as const,
+
+  // Collections (scoped by connection)
+  connectionCollections: (connectionId: string) =>
+    [connectionId, "collections", "discovery"] as const,
+
+  // Tool call results (generic caching for MCP tool calls)
+  // scope is required - scopes the cache (connectionId for connection-scoped, locator for org/project-scoped)
+  toolCall: (scope: string, toolName: string, paramsKey: string) =>
+    ["tool-call", scope, toolName, paramsKey] as const,
+
+  // Collection items (scoped by connection and collection name)
+  collectionItems: (connectionId: string, collectionName: string) =>
+    ["collection", connectionId, collectionName] as const,
+
+  // Collection CRUD queries (scoped by orgId, scopeKey, client, and collection name)
+  // orgId: organization ID
+  // scopeKey: connectionId for connection-scoped tools, virtualMcpId for virtual-mcp-scoped, etc.
+  // client: MCP client instance for cache isolation
+  // Base prefix for invalidating all collection variants
+  collection: (orgId: string, scopeKey: string, collectionName: string) =>
+    [orgId, scopeKey, "collection", collectionName] as const,
+  // Item query
+  collectionItem: (
+    client: unknown,
+    orgId: string,
+    scopeKey: string,
+    collectionName: string,
+    itemId: string,
+  ) => [client, orgId, scopeKey, "collection", collectionName, itemId] as const,
+  // List query
+  collectionList: (
+    client: unknown,
+    orgId: string,
+    scopeKey: string,
+    collectionName: string,
+    paramsKey: string,
+  ) =>
+    [
+      client,
+      orgId,
+      scopeKey,
+      "collection",
+      collectionName,
+      "list",
+      paramsKey,
+    ] as const,
+  // Infinite list query
+  collectionListInfinite: (
+    client: unknown,
+    orgId: string,
+    scopeKey: string,
+    collectionName: string,
+    paramsKey: string,
+  ) =>
+    [
+      client,
+      orgId,
+      scopeKey,
+      "collection",
+      collectionName,
+      "list-infinite",
+      paramsKey,
+    ] as const,
+
+  // GitHub README (scoped by owner and repo)
+  githubReadme: (
+    owner: string | null | undefined,
+    repo: string | null | undefined,
+  ) => ["github-readme", owner, repo] as const,
+
+  // Monitoring queries
+  monitoringStats: () => ["monitoring", "stats"] as const,
+  monitoringLogs: (filters: {
+    connectionId?: string;
+    toolName?: string;
+    isError?: boolean;
+    limit?: number;
+    offset?: number;
+  }) => ["monitoring", "logs", filters] as const,
+  monitoringLogsInfinite: (locator: string, paramsKey: string) =>
+    ["monitoring", "logs-infinite", locator, paramsKey] as const,
+
+  // Virtual MCP prompts (for ice breakers in chat)
+  virtualMcpPrompts: (virtualMcpId: string) =>
+    ["virtual-mcp", virtualMcpId, "prompts"] as const,
+
+  // Connection prompts (for virtual MCP settings)
+  connectionPrompts: (connectionId: string) =>
+    ["connection", connectionId, "prompts"] as const,
+
+  // Connection resources (for virtual MCP settings)
+  connectionResources: (connectionId: string) =>
+    ["connection", connectionId, "resources"] as const,
+
+  // User data
+  user: (userId: string) => ["user", userId] as const,
+} as const;

package/src/lib/streamable-http-client-transport.ts

@@ -0,0 +1,79 @@
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import {
+  StreamableHTTPClientTransport as BaseStreamableHTTPClientTransport,
+  type StreamableHTTPClientTransportOptions,
+} from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+/**
+ * Client-side HTTP transport for MCP connections.
+ * Extends StreamableHTTPClientTransport with support for mocking certain MCP protocol messages.
+ */
+export class StreamableHTTPClientTransport extends BaseStreamableHTTPClientTransport {
+  constructor(url: URL, opts?: StreamableHTTPClientTransportOptions) {
+    super(url, opts);
+  }
+
+  override send(
+    message: JSONRPCMessage,
+    options?: {
+      resumptionToken?: string;
+      onresumptiontoken?: (token: string) => void;
+    },
+  ): Promise<void> {
+    const mockAction = getMockActionFor(message);
+    if (mockAction?.type === "emit") {
+      this.onmessage?.(mockAction.message);
+      return Promise.resolve();
+    }
+    if (mockAction?.type === "suppress") {
+      return Promise.resolve();
+    }
+    return super.send(message, options);
+  }
+}
+
+type MockAction =
+  | { type: "emit"; message: JSONRPCMessage }
+  | { type: "suppress" };
+
+function getMockActionFor(message: JSONRPCMessage): MockAction | null {
+  const m = message;
+  if (!m || typeof m !== "object" || !("method" in m)) return null;
+
+  switch (m.method) {
+    case "initialize": {
+      const protocolVersion = m?.params?.protocolVersion;
+      if (!protocolVersion) return null;
+      return {
+        type: "emit",
+        message: {
+          result: {
+            protocolVersion,
+            capabilities: {
+              tools: {},
+              resources: {},
+              prompts: {},
+              tasks: {
+                list: {},
+                cancel: {},
+                requests: { tool: { call: {} } },
+              },
+            },
+            serverInfo: { name: "mesh-virtual-mcp", version: "1.0.0" },
+          },
+          jsonrpc: m.jsonrpc ?? "2.0",
+          // @ts-expect-error - id is not typed
+          id: m.id,
+        } as JSONRPCMessage,
+      };
+    }
+    case "notifications/roots/list_changed":
+    case "notifications/initialized":
+    case "notifications/cancelled":
+    case "notifications/progress": {
+      return { type: "suppress" };
+    }
+    default:
+      return null;
+  }
+}

package/src/types/connection.ts

@@ -0,0 +1,204 @@
+/**
+ * Connection Entity Schema
+ *
+ * Single source of truth for connection types.
+ * Uses snake_case field names matching the database schema directly.
+ */
+
+import { z } from "zod";
+
+/**
+ * OAuth configuration schema for downstream MCP
+ */
+const OAuthConfigSchema = z.object({
+  authorizationEndpoint: z.string().url(),
+  tokenEndpoint: z.string().url(),
+  introspectionEndpoint: z.string().url().optional(),
+  clientId: z.string(),
+  clientSecret: z.string().optional(),
+  scopes: z.array(z.string()),
+  grantType: z.enum(["authorization_code", "client_credentials"]),
+});
+
+export type OAuthConfig = z.infer<typeof OAuthConfigSchema>;
+
+/**
+ * Tool definition schema from MCP discovery
+ */
+const ToolDefinitionSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  inputSchema: z.record(z.string(), z.unknown()),
+  outputSchema: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
+
+/**
+ * Connection parameters - discriminated by connection_type
+ *
+ * HTTP/SSE/WebSocket: HTTP headers for requests
+ * STDIO: Environment variables + command config
+ */
+const HttpConnectionParametersSchema = z.object({
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+const StdioConnectionParametersSchema = z.object({
+  command: z.string().describe("Command to run (e.g., 'npx', 'node')"),
+  args: z.array(z.string()).optional().describe("Command arguments"),
+  cwd: z.string().optional().describe("Working directory"),
+  envVars: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe("Environment variables (encrypted in storage)"),
+});
+
+export type HttpConnectionParameters = z.infer<
+  typeof HttpConnectionParametersSchema
+>;
+export type StdioConnectionParameters = z.infer<
+  typeof StdioConnectionParametersSchema
+>;
+export type ConnectionParameters =
+  | HttpConnectionParameters
+  | StdioConnectionParameters;
+
+/**
+ * Connection entity schema - single source of truth.
+ * Compliant with collections binding pattern.
+ */
+export const ConnectionEntitySchema = z.object({
+  // Base collection entity fields
+  id: z.string().describe("Unique identifier for the connection"),
+  title: z.string().describe("Human-readable name for the connection"),
+  created_at: z.string().describe("When the connection was created"),
+  updated_at: z.string().describe("When the connection was last updated"),
+  created_by: z.string().describe("User ID who created the connection"),
+  updated_by: z
+    .string()
+    .optional()
+    .describe("User ID who last updated the connection"),
+
+  // Connection-specific fields
+  organization_id: z
+    .string()
+    .describe("Organization ID this connection belongs to"),
+  description: z.string().nullable().describe("Description of the connection"),
+  icon: z.string().nullable().describe("Icon URL for the connection"),
+  app_name: z.string().nullable().describe("Associated app name"),
+  app_id: z.string().nullable().describe("Associated app ID"),
+
+  connection_type: z
+    .enum(["HTTP", "SSE", "Websocket", "STDIO", "VIRTUAL"])
+    .describe("Type of connection"),
+  connection_url: z
+    .string()
+    .nullable()
+    .describe(
+      "URL for HTTP/SSE/WebSocket connections. virtual://$id for VIRTUAL. Null for STDIO.",
+    ),
+  connection_token: z
+    .string()
+    .nullable()
+    .describe("Authentication token (for HTTP connections)"),
+  connection_headers: z
+    .union([StdioConnectionParametersSchema, HttpConnectionParametersSchema])
+    .nullable()
+    .describe(
+      "Connection parameters. HTTP: { headers }. STDIO: { command, args, cwd, envVars }",
+    ),
+
+  oauth_config: OAuthConfigSchema.nullable().describe("OAuth configuration"),
+
+  // New configuration fields (snake_case)
+  configuration_state: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .describe("Configuration state (decrypted)"),
+  configuration_scopes: z
+    .array(z.string())
+    .nullable()
+    .optional()
+    .describe("Configuration scopes"),
+
+  metadata: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .describe("Additional metadata (includes repository info)"),
+  tools: z
+    .array(ToolDefinitionSchema)
+    .nullable()
+    .describe("Discovered tools from MCP"),
+  bindings: z.array(z.string()).nullable().describe("Detected bindings"),
+
+  status: z.enum(["active", "inactive", "error"]).describe("Current status"),
+});
+
+/**
+ * The connection entity type - use this everywhere instead of MCPConnection
+ */
+export type ConnectionEntity = z.infer<typeof ConnectionEntitySchema>;
+
+/**
+ * Input schema for creating connections
+ */
+export const ConnectionCreateDataSchema = ConnectionEntitySchema.omit({
+  created_at: true,
+  updated_at: true,
+  created_by: true,
+  updated_by: true,
+  organization_id: true,
+  tools: true,
+  bindings: true,
+  status: true,
+}).partial({
+  id: true,
+  description: true,
+  icon: true,
+  app_name: true,
+  app_id: true,
+  connection_url: true,
+  connection_token: true,
+  connection_headers: true,
+  oauth_config: true,
+  configuration_state: true,
+  configuration_scopes: true,
+  metadata: true,
+});
+
+export type ConnectionCreateData = z.infer<typeof ConnectionCreateDataSchema>;
+
+/**
+ * Input schema for updating connections
+ */
+export const ConnectionUpdateDataSchema = ConnectionEntitySchema.partial();
+
+export type ConnectionUpdateData = z.infer<typeof ConnectionUpdateDataSchema>;
+
+/**
+ * Type guard to check if parameters are STDIO type
+ */
+export function isStdioParameters(
+  params: ConnectionParameters | null | undefined,
+): params is StdioConnectionParameters {
+  return params !== null && params !== undefined && "command" in params;
+}
+
+/**
+ * Parse virtual MCP ID from virtual:// URL
+ * @returns The virtual MCP ID or null if not a virtual URL
+ */
+export function parseVirtualUrl(url: string | null | undefined): string | null {
+  if (!url || !url.startsWith("virtual://")) {
+    return null;
+  }
+  return url.replace("virtual://", "");
+}
+
+/**
+ * Build virtual:// URL from virtual MCP ID
+ */
+export function buildVirtualUrl(virtualMcpId: string): string {
+  return `virtual://${virtualMcpId}`;
+}

package/src/types/index.ts

@@ -0,0 +1,27 @@
+export {
+  ConnectionEntitySchema,
+  ConnectionCreateDataSchema,
+  ConnectionUpdateDataSchema,
+  isStdioParameters,
+  parseVirtualUrl,
+  buildVirtualUrl,
+  type ConnectionEntity,
+  type ConnectionCreateData,
+  type ConnectionUpdateData,
+  type ConnectionParameters,
+  type HttpConnectionParameters,
+  type StdioConnectionParameters,
+  type OAuthConfig,
+  type ToolDefinition,
+} from "./connection";
+
+export {
+  VirtualMCPEntitySchema,
+  VirtualMCPCreateDataSchema,
+  VirtualMCPUpdateDataSchema,
+  type VirtualMCPEntity,
+  type VirtualMCPCreateData,
+  type VirtualMCPUpdateData,
+  type VirtualMCPConnection,
+  type ToolSelectionMode,
+} from "./virtual-mcp";

package/src/types/virtual-mcp.ts

@@ -0,0 +1,218 @@
+/**
+ * Virtual MCP Entity Schema
+ *
+ * Single source of truth for virtual MCP types.
+ * Uses snake_case field names matching the database schema directly.
+ */
+
+import { z } from "zod";
+
+/**
+ * Tool selection mode schema
+ * - "inclusion": Include selected tools/connections (default behavior)
+ * - "exclusion": Exclude selected tools/connections (inverse filter)
+ */
+const ToolSelectionModeSchema = z
+  .enum(["inclusion", "exclusion"])
+  .describe(
+    "Tool selection mode: 'inclusion' = include selected (default), 'exclusion' = exclude selected",
+  );
+
+export type ToolSelectionMode = z.infer<typeof ToolSelectionModeSchema>;
+
+/**
+ * Virtual MCP connection schema - defines which connection and tools/resources/prompts are included/excluded
+ */
+const VirtualMCPConnectionSchema = z.object({
+  connection_id: z.string().describe("Connection ID"),
+  selected_tools: z
+    .array(z.string())
+    .nullable()
+    .describe(
+      "Selected tool names. With 'inclusion' mode: null = all tools included. With 'exclusion' mode: null = entire connection excluded",
+    ),
+  selected_resources: z
+    .array(z.string())
+    .nullable()
+    .describe(
+      "Selected resource URIs or patterns. Supports * and ** wildcards for pattern matching. With 'inclusion' mode: null = all resources included.",
+    ),
+  selected_prompts: z
+    .array(z.string())
+    .nullable()
+    .describe(
+      "Selected prompt names. With 'inclusion' mode: null = all prompts included. With 'exclusion' mode: null = entire connection excluded.",
+    ),
+});
+
+export type VirtualMCPConnection = z.infer<typeof VirtualMCPConnectionSchema>;
+
+/**
+ * Virtual MCP entity schema - single source of truth
+ * Compliant with collections binding pattern
+ */
+export const VirtualMCPEntitySchema = z.object({
+  // Base collection entity fields
+  id: z.string().describe("Unique identifier for the virtual MCP"),
+  title: z.string().describe("Human-readable name for the virtual MCP"),
+  description: z.string().nullable().describe("Description of the virtual MCP"),
+  icon: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("Icon URL for the virtual MCP"),
+  created_at: z.string().describe("When the virtual MCP was created"),
+  updated_at: z.string().describe("When the virtual MCP was last updated"),
+  created_by: z.string().describe("User ID who created the virtual MCP"),
+  updated_by: z
+    .string()
+    .optional()
+    .describe("User ID who last updated the virtual MCP"),
+
+  // Virtual MCP-specific fields
+  organization_id: z
+    .string()
+    .describe("Organization ID this virtual MCP belongs to"),
+  tool_selection_mode: ToolSelectionModeSchema.describe(
+    "Tool selection mode: 'inclusion' = include selected, 'exclusion' = exclude selected",
+  ),
+  status: z.enum(["active", "inactive"]).describe("Current status"),
+  // Metadata (stored in connections.metadata)
+  metadata: z
+    .object({
+      instructions: z.string().optional().describe("MCP server instructions"),
+    })
+    .nullable()
+    .optional()
+    .describe("Additional metadata including MCP server instructions"),
+  // Nested connections
+  connections: z
+    .array(VirtualMCPConnectionSchema)
+    .describe(
+      "Connections with their selected tools (behavior depends on tool_selection_mode)",
+    ),
+});
+
+/**
+ * The virtual MCP entity type
+ */
+export type VirtualMCPEntity = z.infer<typeof VirtualMCPEntitySchema>;
+
+/**
+ * Input schema for creating virtual MCPs
+ */
+export const VirtualMCPCreateDataSchema = z.object({
+  title: z.string().min(1).max(255).describe("Name for the virtual MCP"),
+  description: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("Optional description"),
+  tool_selection_mode: ToolSelectionModeSchema.optional()
+    .default("inclusion")
+    .describe("Tool selection mode (defaults to 'inclusion')"),
+  icon: z.string().nullable().optional().describe("Optional icon URL"),
+  status: z
+    .enum(["active", "inactive"])
+    .optional()
+    .default("active")
+    .describe("Initial status"),
+  metadata: z
+    .object({
+      instructions: z.string().optional().describe("MCP server instructions"),
+    })
+    .nullable()
+    .optional()
+    .describe("Additional metadata including MCP server instructions"),
+  connections: z
+    .array(
+      z.object({
+        connection_id: z.string().describe("Connection ID"),
+        selected_tools: z
+          .array(z.string())
+          .nullable()
+          .optional()
+          .describe(
+            "Selected tool names (null/undefined = all tools or full exclusion)",
+          ),
+        selected_resources: z
+          .array(z.string())
+          .nullable()
+          .optional()
+          .describe(
+            "Selected resource URIs or patterns with * and ** wildcards (null/undefined = all resources)",
+          ),
+        selected_prompts: z
+          .array(z.string())
+          .nullable()
+          .optional()
+          .describe(
+            "Selected prompt names (null/undefined = all prompts or full exclusion)",
+          ),
+      }),
+    )
+    .describe(
+      "Connections to include/exclude (can be empty for exclusion mode)",
+    ),
+});
+
+export type VirtualMCPCreateData = z.infer<typeof VirtualMCPCreateDataSchema>;
+
+/**
+ * Input schema for updating virtual MCPs
+ */
+export const VirtualMCPUpdateDataSchema = z.object({
+  title: z.string().min(1).max(255).optional().describe("New name"),
+  description: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("New description (null to clear)"),
+  tool_selection_mode: ToolSelectionModeSchema.optional().describe(
+    "New tool selection mode",
+  ),
+  icon: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("New icon URL (null to clear)"),
+  status: z.enum(["active", "inactive"]).optional().describe("New status"),
+  metadata: z
+    .object({
+      instructions: z.string().optional().describe("MCP server instructions"),
+    })
+    .nullable()
+    .optional()
+    .describe("Additional metadata including MCP server instructions"),
+  connections: z
+    .array(
+      z.object({
+        connection_id: z.string().describe("Connection ID"),
+        selected_tools: z
+          .array(z.string())
+          .nullable()
+          .optional()
+          .describe(
+            "Selected tool names (null/undefined = all tools or full exclusion)",
+          ),
+        selected_resources: z
+          .array(z.string())
+          .nullable()
+          .optional()
+          .describe(
+            "Selected resource URIs or patterns with * and ** wildcards (null/undefined = all resources)",
+          ),
+        selected_prompts: z
+          .array(z.string())
+          .nullable()
+          .optional()
+          .describe(
+            "Selected prompt names (null/undefined = all prompts or full exclusion)",
+          ),
+      }),
+    )
+    .optional()
+    .describe("New connections (replaces existing)"),
+});
+
+export type VirtualMCPUpdateData = z.infer<typeof VirtualMCPUpdateDataSchema>;