@eventcatalog/core 5.0.0-beta.3 → 5.0.0-beta.30

package/eventcatalog/src/features/integrations/eventcatalog-features.ts

@@ -13,6 +13,7 @@ import {
   isFullCatalogAPIEnabled,
   isDevMode,
   isSSR,
+  isCanvasEnabled,
 } from '../../utils/feature';
 import { getCustomPageRoutes, isApiRoute, listCustomPageFiles, resolveCustomPagesPrefix } from '../custom-pages/routes';
 
@@ -111,7 +112,8 @@ export default function eventCatalogIntegration(): AstroIntegration {
         }
 
         // Handle routes for MCP Server (requires SSR)
-        if (isEventCatalogMCPEnabled()) {
+        // Also for canvases, so agents can join them (the canvas tools are on the MCP server)
+        if (isEventCatalogMCPEnabled() || isCanvasEnabled()) {
           params.injectRoute({
             pattern: '/docs/mcp/[...path]',
             entrypoint: path.join(packageDirectory, 'src/features/mcp/mcp-server.ts'),
@@ -173,6 +175,37 @@ export default function eventCatalogIntegration(): AstroIntegration {
             entrypoint: path.join(packageDirectory, 'src/features/visualizer-layout/reset.ts'),
           });
         }
+
+        // What a server starts before anyone asks for it (the storage configured, migrated; Studio), called by
+        // `eventcatalog start` once it listens
+        if (isSSR()) {
+          params.injectRoute({
+            pattern: '/_eventcatalog/start',
+            entrypoint: path.join(packageDirectory, 'src/features/server/start.ts'),
+          });
+        }
+
+        // Collaborative canvases in EventCatalog Studio (/studio lists them, /studio?new=1 starts one). Their WebSocket
+        // server is in integrations/studio-server.mjs.
+        if (isCanvasEnabled()) {
+          params.injectRoute({
+            pattern: '/studio',
+            entrypoint: path.join(packageDirectory, 'src/features/studio/pages/index.astro'),
+          });
+          params.injectRoute({
+            pattern: '/studio/[id]',
+            entrypoint: path.join(packageDirectory, 'src/features/studio/pages/[id].astro'),
+          });
+          // The Studio API (canvases as a whole: listing, creating, deleting)
+          params.injectRoute({
+            pattern: '/api/studio/canvases/[...path]',
+            entrypoint: path.join(packageDirectory, 'src/features/studio/api/canvases.ts'),
+          });
+          params.injectRoute({
+            pattern: '/webmcp-relay/[file]',
+            entrypoint: path.join(packageDirectory, 'src/features/studio/pages/webmcp-relay.ts'),
+          });
+        }
       },
       'astro:server:setup': ({ server }) => {
         // When custom page files appear or disappear, refresh the manifest.

package/eventcatalog/src/features/mcp/apps/architecture-diagram/node-chat.tsx

@@ -6,7 +6,8 @@
 import { useEffect, useRef, useState, type FormEvent, type KeyboardEvent, type RefObject } from 'react';
 import type { Node } from '@xyflow/react';
 import { Check, Network, SendHorizontal, X } from 'lucide-react';
-import type { ArchitectureDiagramCollection } from '@utils/node-graphs/architecture-diagram-types';
+import { isArchitectureDiagramCollection } from '@utils/node-graphs/architecture-diagram-types';
+import { getNodeCatalogResource, getNodeResourceDetails } from '@utils/node-graphs/node-resource';
 import type { DiagramLink } from './links';
 import { RESOURCE_TYPE_LABELS } from '../shared/resource-types';
 
@@ -36,53 +37,13 @@ const NODE_TYPE_LABELS: Record<string, string> = {
   externalSystem: 'External system',
 };
 
-// Where each node type keeps the resource it shows
-const RESOURCE_DATA_KEYS = [
-  'service',
-  'agent',
-  'message',
-  'channel',
-  'data',
-  'dataProduct',
-  'flow',
-  'entity',
-  'domain',
-  'system',
-  'custom',
-];
-
-// The collection of each node type the architecture diagram tool can draw a diagram for
-const DIAGRAM_COLLECTIONS: Record<string, ArchitectureDiagramCollection> = {
-  services: 'services',
-  agents: 'agents',
-  events: 'events',
-  commands: 'commands',
-  queries: 'queries',
-  flows: 'flows',
-  data: 'containers',
-  containers: 'containers',
-  'data-products': 'data-products',
-  domains: 'domains',
-  'context-domain': 'domains',
-  'domain-group': 'domains',
-  systems: 'systems',
-  'system-group': 'systems',
-};
-
-// Domain and system boundaries only have their catalog id in the node id: {kind}-group-{id}-{version}
-const catalogIdOfGroup = (node: Node, version?: string) => {
-  const match = node.id.match(/^(?:domain|system)-group-(.+)$/);
-  if (!match) return undefined;
-  return version && match[1].endsWith(`-${version}`) ? match[1].slice(0, -(version.length + 1)) : match[1];
-};
-
 export function describeNode(node: Node): SelectedNode {
   const data = (node.data ?? {}) as Record<string, any>;
-  const resource = RESOURCE_DATA_KEYS.map((key) => data[key]).find(Boolean) ?? data;
-  const details = resource?.data ?? resource;
+  const details = (getNodeResourceDetails(node) ?? data) as Record<string, any>;
   const version: string | undefined = details?.version;
-  const id: string = details?.id ?? catalogIdOfGroup(node, version) ?? node.id;
-  const collection = DIAGRAM_COLLECTIONS[node.type ?? ''];
+  const id: string = details?.id ?? node.id;
+  const resource = getNodeCatalogResource(node);
+  const collection = resource && isArchitectureDiagramCollection(resource.collection) ? resource.collection : undefined;
 
   return {
     nodeId: node.id,

package/eventcatalog/src/features/mcp/apps/canvas/shared.ts

@@ -0,0 +1,47 @@
+// Shared by the canvas MCP App (client) and the MCP server: no server-only imports here
+import type { CatalogRelation, CatalogResource } from '../../../studio/catalog-resources';
+import { type CanvasStatus } from '@eventcatalog/visualiser/studio';
+
+export const CANVAS_RESOURCE_URI = 'ui://eventcatalog/canvas.html';
+/** Key of the payload in openCanvas results' `_meta` */
+export const CANVAS_META_KEY = 'eventcatalog/canvas';
+/** App-only tool the view loads the canvas from when the host doesn't pass the result's `_meta` */
+export const CANVAS_VIEW_TOOL = 'getCanvasView';
+/** App-only tool the view loads the catalog (for dragging resources in) from */
+export const CANVAS_CATALOG_TOOL = 'getCanvasCatalog';
+/** App-only tool the view syncs through when the chat's sandbox blocks the collaboration WebSocket */
+export const CANVAS_SYNC_TOOL = 'syncCanvas';
+
+/** A canvas listed in the view's picker */
+export type CanvasListItem = {
+  canvasId: string;
+  title?: string;
+  status: CanvasStatus;
+  people: string[];
+  nodeCount: number;
+  openComments: number;
+};
+
+/**
+ * What the view shows: a canvas (it connects to it itself, so people and agents edit it live), or, when opened
+ * without one (e.g. from ChatGPT's sidebar), a list of canvases to open or start.
+ */
+export type CanvasPayload = CanvasView | CanvasHome;
+
+export type CanvasHome = { view: 'home'; canvases: CanvasListItem[] };
+
+export type CanvasView = {
+  view: 'canvas';
+  canvasId: string;
+  title?: string;
+  /** The collaboration WebSocket, e.g. wss://catalog.example.com/_eventcatalog/studio */
+  socketUrl: string;
+  /** The canvas in EventCatalog */
+  canvasUrl: string;
+  /** The EventCatalog MCP server, for "Connect your agent" */
+  mcpUrl: string;
+  /** The chat's agent: the view joins the canvas as it (its name, colour and logo) */
+  agent?: { name: string; color: string };
+};
+
+export type CanvasCatalog = { resources: CatalogResource[]; relations: CatalogRelation[] };

package/eventcatalog/src/features/mcp/apps/canvas/styles.css

@@ -0,0 +1,24 @@
+/*
+ * The canvas view's Tailwind stylesheet (with Tailwind's base reset) and EventCatalog's theme variables,
+ * built from the classes of the collaborative canvas components it renders.
+ */
+@import 'tailwindcss' source(none);
+@import '../../../../styles/theme.css';
+@import '@eventcatalog/visualiser/studio.css';
+
+@source './*.tsx';
+@source '../../../studio/components/*.{ts,tsx}';
+/* Studio's shared canvas (nodes, comments, hotspots), from the visualiser in this repo */
+@source '../../../../../../../visualiser/src/studio';
+
+body {
+  margin: 0;
+  background: rgb(var(--ec-page-bg));
+  color: rgb(var(--ec-page-text));
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    'Segoe UI',
+    sans-serif;
+}

package/eventcatalog/src/features/mcp/apps/canvas/view.tsx

@@ -0,0 +1,278 @@
+/**
+ * The collaborative canvas as an MCP App: openCanvas shows it in the chat (ChatGPT, Claude...), where it
+ * joins the canvas (over the collaboration WebSocket, or through tool calls when the chat's sandbox blocks it).
+ * The user edits it there with everyone else on it, people in EventCatalog and agents, live.
+ *
+ * Opened without a canvas (e.g. from ChatGPT's sidebar or a thread tab, its entrypoints), it lists the canvases
+ * to open one or start one. Follows the OpenAI MCP extensions for ChatGPT: entrypoints, display modes, deep
+ * links (/canvas/<id>) and model context (background context, and the selection as titled attachments).
+ *
+ * Built into a single HTML file by scripts/build-mcp-apps.mjs and served as a ui:// resource.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { ArrowLeft, ExternalLink, Maximize2, Minimize2, Plus, Users } from 'lucide-react';
+import type { App } from '@modelcontextprotocol/ext-apps';
+import styles from './styles.css?inline';
+import visualiserStyles from '@eventcatalog/visualiser/styles.css?inline';
+import StudioDesigner, { type SelectedNode } from '@features/studio/components/StudioDesigner';
+import { getAgent } from '@features/studio/agents';
+import { CANVAS_STATUS_LOOK, STATUS } from '@eventcatalog/visualiser/studio';
+import { getToolResultPayload, mountView, useMcpAppView } from '../shared/app-view';
+import {
+  CANVAS_CATALOG_TOOL,
+  CANVAS_META_KEY,
+  CANVAS_SYNC_TOOL,
+  CANVAS_VIEW_TOOL,
+  type CanvasCatalog,
+  type CanvasHome,
+  type CanvasPayload,
+  type CanvasView,
+} from './shared';
+import type { SyncResponse, ToolSync } from '@features/studio/tool-sync';
+
+const isCanvasPayload = (payload?: CanvasPayload): payload is CanvasPayload =>
+  payload?.view === 'home' ? Array.isArray(payload.canvases) : Boolean(payload?.canvasId && payload.socketUrl);
+
+const VIEW_OPTIONS = {
+  name: 'EventCatalog canvas',
+  metaKey: CANVAS_META_KEY,
+  viewTool: CANVAS_VIEW_TOOL,
+  isPayload: isCanvasPayload,
+  getViewToolArguments: ({ canvasId }: Record<string, any>) => ({ canvasId }),
+  loadErrorMessage: 'The canvas could not be opened',
+};
+
+const INLINE_HEIGHT = 640;
+/** Deep links into the app (ChatGPT's `openai/deepLink`), e.g. /canvas/<id> */
+const DEEP_LINK = /^\/canvas(?:es)?\/([0-9a-f-]{36})/i;
+
+/** Loads what to show through a tool (the canvas view's own, or openCanvas to start a canvas) */
+const loadPayload = async (app: App, name: string, args: Record<string, unknown>) => {
+  const result = await app.callServerTool({ name, arguments: args });
+  const payload = getToolResultPayload<CanvasPayload>(result, CANVAS_META_KEY);
+  if (result.isError || !isCanvasPayload(payload)) throw new Error('The canvas could not be opened');
+  return payload;
+};
+
+function CanvasPicker({
+  home,
+  onOpen,
+  onCreate,
+}: {
+  home: CanvasHome;
+  onOpen: (id: string) => void;
+  onCreate: (title: string) => void;
+}) {
+  const [title, setTitle] = useState('');
+  return (
+    <div className="mx-auto max-w-2xl space-y-6 p-6">
+      <div className="space-y-1">
+        <h1 className="text-lg font-semibold">Canvases</h1>
+        <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">
+          Work together, live: people in EventCatalog, people in chats and agents, on the same canvas.
+        </p>
+      </div>
+      <form
+        className="flex gap-2"
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (title.trim()) onCreate(title.trim());
+        }}
+      >
+        <input
+          value={title}
+          onChange={(event) => setTitle(event.target.value)}
+          placeholder="What are you designing?"
+          className="min-w-0 flex-1 rounded-lg border px-3 py-2 text-sm bg-[rgb(var(--ec-input-bg))] border-[rgb(var(--ec-input-border))] text-[rgb(var(--ec-input-text))]"
+        />
+        <button
+          type="submit"
+          disabled={!title.trim()}
+          className="flex items-center gap-1.5 rounded-lg px-3 py-2 text-sm font-medium disabled:opacity-50 bg-[rgb(var(--ec-button-bg))] text-[rgb(var(--ec-button-text))] hover:bg-[rgb(var(--ec-button-bg-hover))]"
+        >
+          <Plus size={16} /> New canvas
+        </button>
+      </form>
+      <div className="space-y-2">
+        {home.canvases.length === 0 && <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">No canvases yet.</p>}
+        {home.canvases.map((canvas) => (
+          <button
+            key={canvas.canvasId}
+            onClick={() => onOpen(canvas.canvasId)}
+            className="flex w-full items-center justify-between gap-3 rounded-xl border px-4 py-3 text-left bg-[rgb(var(--ec-card-bg))] border-[rgb(var(--ec-page-border))] hover:border-[rgb(var(--ec-accent))]"
+          >
+            <span className="min-w-0">
+              <span className="flex items-center gap-2">
+                <span className="truncate text-sm font-semibold">{canvas.title ?? 'Untitled canvas'}</span>
+                <span
+                  className={`shrink-0 rounded-full border px-1.5 py-px text-[10px] font-semibold ${CANVAS_STATUS_LOOK[canvas.status].pill}`}
+                >
+                  {CANVAS_STATUS_LOOK[canvas.status].label}
+                </span>
+              </span>
+              <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+                {canvas.nodeCount} {canvas.nodeCount === 1 ? 'node' : 'nodes'}
+                {canvas.openComments > 0 && ` · ${canvas.openComments} open comments`}
+              </span>
+            </span>
+            {canvas.people.length > 0 && (
+              <span
+                className={`flex shrink-0 items-center gap-1 text-xs ${STATUS.success.text}`}
+                title={canvas.people.join(', ')}
+              >
+                <Users size={14} /> {canvas.people.length} here now
+              </span>
+            )}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function CanvasApp() {
+  const { app, payload, setPayload, error, hostContext } = useMcpAppView(VIEW_OPTIONS);
+  const [catalog, setCatalog] = useState<CanvasCatalog>({ resources: [], relations: [] });
+  const [selection, setSelection] = useState<SelectedNode[]>([]);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const canvas = payload?.view === 'canvas' ? payload : undefined;
+
+  const show = useCallback(
+    (load: Promise<CanvasPayload>) =>
+      load.then(setPayload).catch((cause) => setLoadError(String((cause as Error)?.message ?? cause))),
+    [setPayload]
+  );
+  const openCanvas = (canvasId?: string) => app && show(loadPayload(app, CANVAS_VIEW_TOOL, canvasId ? { canvasId } : {}));
+
+  // Deep links (ChatGPT's `openai/deepLink`): /canvas/<id> opens that canvas
+  const deepLink = (hostContext as Record<string, { url?: string } | undefined> | undefined)?.['openai/deepLink']?.url;
+  useEffect(() => {
+    const canvasId = deepLink?.match(DEEP_LINK)?.[1];
+    if (app && canvasId && canvasId !== canvas?.canvasId) void show(loadPayload(app, CANVAS_VIEW_TOOL, { canvasId }));
+  }, [app, deepLink]);
+
+  // Chats may not let the view open the collaboration WebSocket (sandbox CSP, local network rules...):
+  // then it syncs through the MCP server, the same way the model's tools reach the canvas
+  const syncViaTools = useMemo<ToolSync | undefined>(
+    () =>
+      app
+        ? async (request) => {
+            const result = await app.callServerTool({ name: CANVAS_SYNC_TOOL, arguments: request });
+            if (result.isError || !result.structuredContent) throw new Error('Sync failed');
+            return result.structuredContent as SyncResponse;
+          }
+        : undefined,
+    [app]
+  );
+
+  // The catalog (to drag resources in) is loaded separately, to keep tool results small
+  useEffect(() => {
+    if (!app || !canvas) return;
+    app
+      .callServerTool({ name: CANVAS_CATALOG_TOOL, arguments: {} })
+      .then((result) => {
+        const loaded = result.structuredContent as CanvasCatalog | undefined;
+        if (loaded?.resources) setCatalog(loaded);
+      })
+      .catch(() => {});
+  }, [app, canvas?.canvasId]);
+
+  // Model context (replaced on each update): which canvas is open as background context the user doesn't see,
+  // and what they've selected as an attachment they can see (and remove), titled with the names
+  useEffect(() => {
+    if (!app || !payload || !app.getHostCapabilities()?.updateModelContext) return;
+    const background = {
+      type: 'text' as const,
+      text: canvas
+        ? `The user has the canvas "${canvas.title ?? 'Untitled'}" open (canvasId ${canvas.canvasId}). Use getCanvas to see what is on it, and the canvas tools to work on it with them.`
+        : 'The user is looking at their canvases, to open one or start one.',
+      annotations: { audience: ['assistant' as const] },
+    };
+    const selected = selection.length
+      ? [
+          {
+            type: 'text' as const,
+            text: `Selected on the canvas: ${selection
+              .map(
+                (node) =>
+                  `${node.name} (${node.type}${node.catalogResource ? `, catalog ${node.catalogResource}` : ''}, nodeId ${node.id})`
+              )
+              .join('; ')}`,
+            _meta: { 'openai/title': selection.map((node) => node.name).join(', ') },
+          },
+        ]
+      : [];
+    app.updateModelContext({ content: [background, ...selected] }).catch(() => {});
+  }, [app, payload, selection]);
+
+  if (error || loadError) return <p className="p-4 text-sm">{error ?? loadError}</p>;
+  if (!payload) return <p className="p-4 text-sm text-[rgb(var(--ec-page-text-muted))]">Opening the canvas…</p>;
+
+  const fullscreen = hostContext?.displayMode === 'fullscreen';
+  const canToggle = hostContext?.availableDisplayModes?.includes(fullscreen ? 'inline' : 'fullscreen');
+  const iconButton =
+    'flex items-center gap-1 rounded-md px-2 py-1 text-xs text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-page-border)/0.5)]';
+
+  // No join form inside a chat: it joins as the chat's agent (e.g. ChatGPT or Claude, with its logo), as the agent
+  // working on the canvas does, else as the chat it's in
+  const hostName = app?.getHostVersion()?.name;
+  const agentOf = (view: CanvasView) => view.agent ?? getAgent(undefined, hostName);
+
+  return (
+    <div className="flex flex-col" style={{ height: fullscreen ? '100vh' : INLINE_HEIGHT }}>
+      <div className="flex items-center justify-between border-b px-3 py-1.5 border-[rgb(var(--ec-page-border))]">
+        <span className="flex min-w-0 items-center gap-1">
+          {canvas && (
+            <button className={iconButton} title="All canvases" onClick={() => void openCanvas()}>
+              <ArrowLeft size={14} />
+            </button>
+          )}
+          <span className="truncate text-sm font-semibold">{canvas ? (canvas.title ?? 'Canvas') : 'Canvases'}</span>
+        </span>
+        <span className="flex items-center gap-1">
+          {canvas && (
+            <button className={iconButton} onClick={() => app?.openLink({ url: canvas.canvasUrl })}>
+              <ExternalLink size={14} />
+              Open in EventCatalog
+            </button>
+          )}
+          {canToggle && (
+            <button
+              className={iconButton}
+              title={fullscreen ? 'Exit full screen' : 'Full screen'}
+              onClick={() => app?.requestDisplayMode({ mode: fullscreen ? 'inline' : 'fullscreen' })}
+            >
+              {fullscreen ? <Minimize2 size={14} /> : <Maximize2 size={14} />}
+            </button>
+          )}
+        </span>
+      </div>
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        {canvas ? (
+          <StudioDesigner
+            key={canvas.canvasId}
+            canvasId={canvas.canvasId}
+            socketUrl={canvas.socketUrl}
+            shareUrl={canvas.canvasUrl}
+            mcpUrl={canvas.mcpUrl}
+            syncViaTools={syncViaTools}
+            asAgent={agentOf(canvas)}
+            resources={catalog.resources}
+            relations={catalog.relations}
+            onSelectionChange={setSelection}
+            followChanges
+            paletteCollapsed
+          />
+        ) : (
+          <CanvasPicker
+            home={payload as CanvasHome}
+            onOpen={(canvasId) => void openCanvas(canvasId)}
+            onCreate={(title) => app && void show(loadPayload(app, 'openCanvas', { title }))}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+mountView(CanvasApp, [visualiserStyles, styles].join('\n'));