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

package/eventcatalog/src/features/mcp/apps/shared/app-view.tsx

@@ -84,7 +84,8 @@ export function useMcpAppView<Payload>(options: McpAppViewOptions<Payload>) {
     setHostContext(context);
   }, [app]);
 
-  return { app, payload, error: connectionError?.message ?? error, hostContext };
+  // setPayload: views that switch what they show themselves (e.g. picking a canvas) without a new tool result
+  return { app, payload, setPayload, error: connectionError?.message ?? error, hostContext };
 }
 
 /** Adds the view's styles and renders it */

package/eventcatalog/src/features/mcp/mcp-apps.ts

@@ -12,7 +12,7 @@ const mcpAppViews = import.meta.glob<string>('./apps/generated/*.html', { query:
 export const getMcpAppViewLoader = (name: string) => mcpAppViews[`./apps/generated/${name}.html`];
 
 /** Tool `_meta` telling MCP hosts that support MCP Apps to show the tool's result in a view */
-const appViewMeta = (resourceUri: string, visibility?: Array<'model' | 'app'>) => ({
+export const appViewMeta = (resourceUri: string, visibility?: Array<'model' | 'app'>) => ({
   ui: { resourceUri, ...(visibility && { visibility }) },
   [RESOURCE_URI_META_KEY]: resourceUri,
 });
@@ -38,6 +38,8 @@ type ToolDefinition<Shape extends z.ZodRawShape> = {
   description: string;
   /** The tool's arguments, as a Zod shape */
   input: Shape;
+  /** More `_meta` for the tool, e.g. host extensions such as ChatGPT's `openai/ui` entrypoints */
+  meta?: Record<string, unknown>;
 };
 
 export type McpAppDefinition<Shape extends z.ZodRawShape, ViewShape extends z.ZodRawShape, Payload> = {
@@ -47,7 +49,8 @@ export type McpAppDefinition<Shape extends z.ZodRawShape, ViewShape extends z.Zo
     name: string;
     uri: string;
     description: string;
-    csp?: { resourceDomains: string[] };
+    /** Origins the view may load from (resourceDomains) and connect to with fetch or WebSockets (connectDomains) */
+    csp?: { resourceDomains?: string[]; connectDomains?: string[] };
     /** How hosts open the view: ChatGPT reads these before loading it, so it can open straight in that mode */
     displayModes?: { preferred: McpUiDisplayMode; available: McpUiDisplayMode[] };
   };
@@ -110,7 +113,7 @@ export function registerMcpApp<Shape extends z.ZodRawShape, ViewShape extends z.
       description: app.tool.description,
       inputSchema: toolInput,
       annotations: app.annotations,
-      _meta: loadView ? appViewMeta(app.resource.uri) : undefined,
+      _meta: loadView ? { ...appViewMeta(app.resource.uri), ...app.tool.meta } : undefined,
     },
     showInView
   );

package/eventcatalog/src/features/mcp/mcp-server.ts

@@ -22,6 +22,9 @@ import { RESOURCE_VIEWS, VIEWER_META_KEY, VIEWER_RESOURCE_URI, VIEWER_VIEW_TOOL,
 import { toSchemaViewerSchemas } from './schema-viewer';
 import { getMcpAppViewLoader, mcpAppNote, registerMcpApp } from './mcp-apps';
 import { buildUrl } from '@utils/url-builder';
+import { isCanvasEnabled } from '@utils/feature';
+import { CANVAS_TOOL_NAMES, registerCanvasTools } from '@features/studio/server/canvas-mcp';
+import { startStudio } from '@features/studio/server/runtime';
 
 const loadViewerView = getMcpAppViewLoader('viewer');
 
@@ -36,6 +39,10 @@ const SHOW_RESOURCE_DESCRIPTION = [
 type McpServerOptions = {
   /** Where this EventCatalog is served, for links from MCP App views back to it */
   catalogUrl: string;
+  /** The MCP client's user agent, to name agents that join a canvas */
+  userAgent?: string;
+  /** Offer the canvas tools (by default when Studio is on, for the whole catalog) */
+  canvases?: boolean;
 };
 
 const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
@@ -115,7 +122,10 @@ function getServerInstructions(scope?: McpScope) {
 }
 
 // Create MCP Server with tools that access Astro collections
-function createMcpServer(scope: McpScope | undefined, { catalogUrl }: McpServerOptions) {
+function createMcpServer(
+  scope: McpScope | undefined,
+  { catalogUrl, userAgent, canvases = !scope && isCanvasEnabled() }: McpServerOptions
+) {
   const server = new McpServer(
     {
       name: scope ? `EventCatalog MCP Server — ${scope.name} ${scope.ref.kind}` : 'EventCatalog MCP Server',
@@ -396,7 +406,7 @@ function createMcpServer(scope: McpScope | undefined, { catalogUrl }: McpServerO
     if (resource.error !== undefined) return { error: resource.error };
 
     const schemas = await tools.getSchemaForResource({ ...params, resourceVersion: resource.version });
-    if ('error' in schemas) return schemas;
+    if ('error' in schemas && schemas.error !== undefined) return { error: schemas.error };
 
     return {
       resource: {
@@ -831,6 +841,9 @@ function createMcpServer(scope: McpScope | undefined, { catalogUrl }: McpServerO
     );
   }
 
+  // Collaborative canvases (when the collaboration server runs in this process)
+  if (canvases) registerCanvasTools(server, { catalogUrl, userAgent });
+
   return server;
 }
 
@@ -964,7 +977,9 @@ const handleGetRequest = async (c: Context, kind?: McpScopeKind) => {
       version: MCP_SERVER_VERSION,
       status: 'running',
       ...(scope && { scope: scope.ref }),
-      tools: scope ? getScopedBuiltInTools(scope) : [...globalBuiltInTools, ...extendedToolNames],
+      tools: scope
+        ? getScopedBuiltInTools(scope)
+        : [...globalBuiltInTools, ...(isCanvasEnabled() ? CANVAS_TOOL_NAMES : []), ...extendedToolNames],
       extendedTools: !scope && extendedToolNames.length > 0 ? extendedToolNames : undefined,
       resources: getMcpResourceUris(scope),
     });
@@ -983,7 +998,23 @@ const handleMcpRequest = async (c: Context, kind?: McpScopeKind) => {
     }
 
     const scope = await resolveRequestScope(c, kind);
-    const server = createMcpServer(scope, { catalogUrl: new URL(c.req.url).origin });
+    // Canvas tools work on Studio's canvases: started (storage loaded) before they're listed, and left out when
+    // Studio isn't available (the rest of the catalog's tools still work)
+    const canvases =
+      !scope &&
+      isCanvasEnabled() &&
+      (await startStudio().then(
+        () => true,
+        (error) => {
+          console.error(`[studio] Canvas tools are off: ${(error as Error).message}`);
+          return false;
+        }
+      ));
+    const server = createMcpServer(scope, {
+      catalogUrl: new URL(c.req.url).origin,
+      userAgent: c.req.header('user-agent'),
+      canvases,
+    });
     const transport = new WebStandardStreamableHTTPServerTransport({
       sessionIdGenerator: undefined,
     });
@@ -1023,7 +1054,7 @@ app.post('/', (c: Context) => handleMcpRequest(c));
 
 // Astro API route handler - delegates all requests to Hono
 // Note: SSR checks are handled at build time by the integration
-// This route is only injected when isEventCatalogMCPEnabled() returns true
+// This route is only injected when isEventCatalogMCPEnabled() or isCanvasEnabled() returns true
 export const ALL: APIRoute = async ({ request }) => {
   return app.fetch(request);
 };

package/eventcatalog/src/features/server/start.ts

@@ -0,0 +1,25 @@
+import type { APIRoute } from 'astro';
+import { isCanvasEnabled } from '@utils/feature';
+import { startStorage } from '../storage/database';
+import { startStudio } from '../studio/server/runtime';
+import { isSignedIn } from '../studio/server/sign-in';
+
+/**
+ * What the server starts before anyone asks for it: `eventcatalog start` calls this once the server listens. Each
+ * feature that needs starting has its own start function, called here in order: the storage configured is opened and
+ * migrated first (features keep their state in it), then Studio (so tabs reconnecting after a restart find it
+ * ready). Under /_eventcatalog, which sign-in lets through (the server calls it without a session); it says nothing
+ * about what's stored.
+ */
+export const GET: APIRoute = async () => {
+  try {
+    await startStorage();
+  } catch (error) {
+    console.error(`[eventcatalog] Could not open the database: ${(error as Error).message}`);
+  }
+  // Studio says why if it can't start
+  if (isCanvasEnabled()) await startStudio({ isSignedIn }).catch(() => {});
+  return new Response(null, { status: 204 });
+};
+
+export const prerender = false;

package/eventcatalog/src/features/storage/database.ts

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import config from '../../utils/eventcatalog-config/source';
+import type { Config } from '../../../../src/eventcatalog.config';
+import { migrate, type Database } from './migrations';
+import { namedStatements } from './sql';
+import databaseSql from './sql/database.sql?raw';
+
+/** `storage` in eventcatalog.config.js: memory (the default), or one SQLite database for the whole catalog */
+export type StorageConfig = NonNullable<Config['storage']>;
+export type StorageType = StorageConfig['type'];
+export type { Database };
+
+export const DEFAULT_STORAGE: StorageConfig = { type: 'memory' };
+const DEFAULT_DATABASE_PATH = '.eventcatalog/eventcatalog.db';
+
+const SQL = namedStatements(databaseSql, ['useWriteAheadLog']);
+
+/** The database file a config asks for (relative to the catalog), or undefined when state is kept in memory */
+export const getDatabasePath = (storage: StorageConfig | undefined, projectDirectory: string) => {
+  const chosen = storage ?? DEFAULT_STORAGE;
+  switch (chosen.type) {
+    case 'memory':
+      return undefined;
+    case 'sqlite':
+      return path.resolve(projectDirectory, chosen.path ?? DEFAULT_DATABASE_PATH);
+    default:
+      throw new Error(`Unknown storage type "${(chosen as { type?: string }).type}": use "memory" or "sqlite"`);
+  }
+};
+
+const open = async (file: string): Promise<Database> => {
+  // Node's built-in SQLite (no native package to install), asked of Node itself: the dev server loads this through
+  // Vite, which doesn't know node:sqlite and fails to import it
+  type Sqlite = { DatabaseSync: new (file: string) => Database };
+  const getBuiltinModule = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;
+  let sqlite: Sqlite | undefined;
+  try {
+    sqlite = getBuiltinModule
+      ? (getBuiltinModule('node:sqlite') as Sqlite | undefined)
+      : await import(/* @vite-ignore */ ['node', 'sqlite'].join(':'));
+  } catch (error) {
+    throw new Error(`Could not load node:sqlite (${(error as Error).message})`);
+  }
+  if (!sqlite?.DatabaseSync) {
+    throw new Error(
+      `SQLite storage needs Node.js 22.13 or later (it uses node:sqlite); this is Node.js ${process.versions.node}`
+    );
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const database = new sqlite.DatabaseSync(file);
+  database.exec(SQL.useWriteAheadLog);
+  migrate(database);
+  return database;
+};
+
+// Opened once per process, by file (kept on globalThis: the dev server's integrations and the app load this module
+// separately, and code reloads in dev keep globalThis)
+const DATABASES = Symbol.for('eventcatalog.databases');
+const store = globalThis as typeof globalThis & { [DATABASES]?: Map<string, Promise<Database>> };
+
+/**
+ * The database in `file`, brought up to date by the migrations: opened the first time it's asked for, then shared by
+ * every feature. Rejects (every time) if it can't be opened or migrated, e.g. when a newer EventCatalog updated it.
+ */
+export const openDatabase = (file: string): Promise<Database> => {
+  const databases = (store[DATABASES] ??= new Map());
+  let database = databases.get(file);
+  if (!database) {
+    database = open(file);
+    databases.set(file, database);
+  }
+  return database;
+};
+
+/**
+ * Opens the storage configured, running the migrations it needs. Called as the dev server and `eventcatalog start`
+ * start (not on build: builds often run somewhere other than where the database lives), so it's ready before any
+ * feature uses it. Returns the database file, or undefined when state is kept in memory.
+ */
+export const startStorage = async (projectDirectory = process.env.PROJECT_DIR || process.cwd()) => {
+  if ((config as { studio?: { storage?: unknown } }).studio?.storage) {
+    console.warn('[eventcatalog] studio.storage is no longer used: set storage in eventcatalog.config.js instead');
+  }
+  const file = getDatabasePath(config.storage, projectDirectory);
+  if (file) await openDatabase(file);
+  return file;
+};

package/eventcatalog/src/features/storage/migrations.ts

@@ -0,0 +1,85 @@
+import { namedStatements } from './sql';
+import runnerSql from './sql/migrations.sql?raw';
+
+/**
+ * Changes to the database's schema, for every feature that keeps state, as .sql files in ./sql/migrations named
+ * `NNNN-what-it-does.sql` (one numbered order for the whole catalog; tables are named for their feature, e.g.
+ * `studio_canvases`). They run in order when the database opens, each once, recorded in its `migrations` table. To
+ * change the schema, add a file with the next number: never change one that has shipped, since databases out there have
+ * already run it.
+ */
+export type Migration = { version: number; name: string; sql: string };
+
+/** The parts of node:sqlite's DatabaseSync EventCatalog uses */
+export type Database = {
+  exec: (sql: string) => void;
+  prepare: (sql: string) => { run: (...values: unknown[]) => unknown; all: () => unknown[] };
+};
+
+// Built into the server code (no files to find at runtime, wherever it's deployed)
+const files = import.meta.glob<string>('./sql/migrations/*.sql', { query: '?raw', import: 'default', eager: true });
+const SQL = namedStatements(runnerSql, ['createMigrationsTable', 'appliedVersions', 'recordMigration']);
+
+/** Migrations from their files, in order (an error if a file is misnamed or two have the same number) */
+export const toMigrations = (sources: Record<string, string>): Migration[] => {
+  const migrations = Object.entries(sources).map(([file, sql]) => {
+    const name = file
+      .split('/')
+      .pop()!
+      .replace(/\.sql$/, '');
+    const version = Number(/^(\d{4})-[a-z0-9-]+$/.exec(name)?.[1]);
+    if (!version) throw new Error(`Migration "${file}" should be named like 0003-what-it-does.sql`);
+    return { version, name, sql };
+  });
+  migrations.sort((a, b) => a.version - b.version);
+  migrations.forEach((migration, index) => {
+    if (migration.version !== index + 1) {
+      throw new Error(`Migrations should be numbered 1, 2, 3...: expected ${index + 1} before ${migration.name}`);
+    }
+  });
+  return migrations;
+};
+
+export const MIGRATIONS = toMigrations(files);
+
+/**
+ * The database was updated by a newer EventCatalog. Features don't fall back to memory for this (changes would quietly
+ * stop being saved): they aren't available until EventCatalog is updated. Told by its code, as the dev server's
+ * integrations and the app load this module separately.
+ */
+const DATABASE_TOO_NEW = 'EVENTCATALOG_DATABASE_TOO_NEW';
+export const isDatabaseTooNew = (error: unknown) => (error as { code?: unknown } | null)?.code === DATABASE_TOO_NEW;
+
+/**
+ * Brings a database up to date: runs the migrations it hasn't run yet, each in a transaction (all of it or none).
+ * Refuses a database that has run migrations this version doesn't know (made by a newer EventCatalog).
+ */
+export const migrate = (database: Database, migrations: Migration[] = MIGRATIONS) => {
+  database.exec(SQL.createMigrationsTable);
+  const applied = new Set(
+    (database.prepare(SQL.appliedVersions).all() as { version: number }[]).map((row) => Number(row.version))
+  );
+  const latest = migrations.at(-1)?.version ?? 0;
+  const newer = [...applied].filter((version) => version > latest);
+  if (newer.length) {
+    throw Object.assign(
+      new Error(
+        `The EventCatalog database has been updated by a newer EventCatalog (migration ${Math.max(...newer)}; this version knows up to ${latest}). Update EventCatalog to use it.`
+      ),
+      { code: DATABASE_TOO_NEW }
+    );
+  }
+  const record = database.prepare(SQL.recordMigration);
+  for (const migration of migrations) {
+    if (applied.has(migration.version)) continue;
+    database.exec('BEGIN');
+    try {
+      database.exec(migration.sql);
+      record.run(migration.version, migration.name, Date.now());
+      database.exec('COMMIT');
+    } catch (error) {
+      database.exec('ROLLBACK');
+      throw new Error(`Could not run migration ${migration.name}: ${(error as Error).message}`);
+    }
+  }
+};

package/eventcatalog/src/features/storage/sql/database.sql

@@ -0,0 +1,5 @@
+-- Statements run as the database opens (see database.ts), each named by the `-- name:` line above it.
+
+-- name: useWriteAheadLog
+-- Readers don't wait for writers (set as the database opens: it can't be changed inside a migration's transaction)
+PRAGMA journal_mode = WAL;

package/eventcatalog/src/features/storage/sql/migrations/0001-studio-canvases.sql

@@ -0,0 +1,12 @@
+-- Studio's canvases: each one's whole Yjs document (Y.encodeStateAsUpdate), and when it last changed.
+CREATE TABLE studio_canvases (
+  name TEXT PRIMARY KEY,
+  state BLOB NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+-- Studio canvases that were deleted, so a browser that still has one open can't bring it back.
+CREATE TABLE studio_deleted_canvases (
+  name TEXT PRIMARY KEY,
+  deleted_at INTEGER NOT NULL
+);

package/eventcatalog/src/features/storage/sql/migrations.sql

@@ -0,0 +1,15 @@
+-- The statements the migration runner runs (see migrations.ts), each named by the `-- name:` line above it. Its own
+-- table is made here rather than in a migration: it records which migrations have run, so it's needed before any do.
+
+-- name: createMigrationsTable
+CREATE TABLE IF NOT EXISTS migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at INTEGER NOT NULL
+);
+
+-- name: appliedVersions
+SELECT version FROM migrations;
+
+-- name: recordMigration
+INSERT INTO migrations (version, name, applied_at) VALUES (?, ?, ?);

package/eventcatalog/src/features/storage/sql.ts

@@ -0,0 +1,28 @@
+/**
+ * Statements kept in .sql files (./sql), each named by a `-- name: <name>` line above it. A file's statements are
+ * looked up by the names the code expects: a missing one is an error when the module loads, not when it's first run.
+ */
+export const namedStatements = <Name extends string>(source: string, names: readonly Name[]): Record<Name, string> => {
+  const statements = new Map<string, string>();
+  let current: { name: string; lines: string[] } | undefined;
+  const finish = () => {
+    if (current) statements.set(current.name, current.lines.join('\n').trim());
+  };
+  for (const line of source.split('\n')) {
+    const name = /^--\s*name:\s*(\S+)\s*$/.exec(line)?.[1];
+    if (name) {
+      finish();
+      current = { name, lines: [] };
+    } else {
+      current?.lines.push(line);
+    }
+  }
+  finish();
+  return Object.fromEntries(
+    names.map((name) => {
+      const statement = statements.get(name);
+      if (!statement) throw new Error(`No SQL statement named "${name}"`);
+      return [name, statement];
+    })
+  ) as Record<Name, string>;
+};