@eventcatalog/core 5.5.0 → 5.5.2

package/eventcatalog/src/features/mcp/apps/schema-viewer/view.tsx

@@ -12,6 +12,7 @@ import AvroSchemaViewer from '../../../../components/SchemaExplorer/AvroSchemaVi
 import ProtobufSchemaViewer from '../../../../components/SchemaExplorer/ProtobufSchemaViewer';
 import { SchemaCode } from './schema-code';
 import { RESOURCE_TYPE_LABELS } from '../shared/resource-types';
+import { fullscreenStyle } from '../shared/app-view';
 import type { SchemaViewerPayload, SchemaViewerSchema } from './shared';
 
 const INLINE_MAX_HEIGHT = '560px';
@@ -75,7 +76,7 @@ export function SchemaViewerView({ app, payload, hostContext }: SchemaViewerView
     'inline-flex h-7 items-center gap-1.5 rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg))] px-2.5 text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:border-[rgb(var(--ec-accent))] hover:text-[rgb(var(--ec-accent))]';
 
   return (
-    <div className={`flex flex-col ${isFullscreen ? 'h-screen' : ''}`}>
+    <div className="flex flex-col" style={isFullscreen ? fullscreenStyle(hostContext) : undefined}>
       <div className="flex items-center justify-between gap-3 border-b border-[rgb(var(--ec-page-border))] px-3 py-2">
         <div className="flex min-w-0 items-center gap-2 text-[13px]">
           <span className="shrink-0 rounded bg-[rgb(var(--ec-accent-subtle))] px-1.5 py-px text-[10px] font-semibold uppercase tracking-wide text-[rgb(var(--ec-accent))]">

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

@@ -2,7 +2,7 @@
  * Connecting the EventCatalog viewer MCP App to the host, loading the tool result's payload, following the
  * host's theme and display mode, and mounting the view.
  */
-import { useEffect, useState, type ComponentType } from 'react';
+import { useEffect, useState, type ComponentType, type CSSProperties } from 'react';
 import { config as configureZod } from 'zod';
 import { createRoot } from 'react-dom/client';
 import type { App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
@@ -20,6 +20,24 @@ const applyTheme = (context?: McpUiHostContext) => {
   if (context?.theme) document.documentElement.setAttribute('data-theme', context.theme);
 };
 
+/**
+ * The view full screen: the height of the frame, kept clear of what the host draws over it on phones (the notch,
+ * the home indicator, the message box), which it reports as safe area insets
+ */
+export const fullscreenStyle = (context?: McpUiHostContext): CSSProperties => {
+  const insets = context?.safeAreaInsets;
+  return {
+    height: '100vh',
+    boxSizing: 'border-box',
+    ...(insets && {
+      paddingTop: insets.top,
+      paddingRight: insets.right,
+      paddingBottom: insets.bottom,
+      paddingLeft: insets.left,
+    }),
+  };
+};
+
 type McpAppViewOptions<Payload> = {
   name: string;
   /** Key of the payload in the model-facing tool result's `_meta` */
@@ -61,8 +79,9 @@ export function useMcpAppView<Payload>(options: McpAppViewOptions<Payload>) {
     appInfo: { name: options.name, version: '1.0.0' },
     // The views fit inline and have a full screen button (the server asks hosts to open them full screen)
     capabilities: { availableDisplayModes: ['inline', 'fullscreen'] },
+    // Listeners go on before the view connects: hosts send the tool's result as soon as it has
     onAppCreated: (createdApp) => {
-      createdApp.ontoolresult = (result) => {
+      createdApp.addEventListener('toolresult', (result) => {
         if (result.isError) {
           setError(result.content?.find((item) => item.type === 'text')?.text ?? options.loadErrorMessage);
           return;
@@ -70,11 +89,11 @@ export function useMcpAppView<Payload>(options: McpAppViewOptions<Payload>) {
         loadPayload(createdApp, result, options)
           .then(setPayload)
           .catch((loadError) => setError(String(loadError?.message ?? loadError)));
-      };
-      createdApp.onhostcontextchanged = (context) => {
+      });
+      createdApp.addEventListener('hostcontextchanged', (context) => {
         applyTheme(context);
         setHostContext((previous) => ({ ...previous, ...context }));
-      };
+      });
     },
   });
 

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

@@ -54,6 +54,8 @@ export type McpAppDefinition<Shape extends z.ZodRawShape, ViewShape extends z.Zo
     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[] };
+    /** Whether the host frames the view with a border and background (hosts' defaults differ, e.g. Claude's web and mobile apps) */
+    prefersBorder?: boolean;
   };
   /**
    * Ties every result to one view (ChatGPT's `openai/widgetSessionId`): the host updates the view it already
@@ -93,7 +95,7 @@ export function registerMcpApp<Shape extends z.ZodRawShape, ViewShape extends z.
       if ('error' in result) return errorResult(result);
       return {
         // The model reads the text; hosts that support MCP Apps show the view from `_meta`
-        content: [{ type: 'text' as const, text: JSON.stringify(result.forModel, null, 2) }],
+        content: [{ type: 'text' as const, text: JSON.stringify(result.forModel) }],
         ...(loadView && {
           _meta: {
             [app.metaKey]: await result.getPayload(),
@@ -151,7 +153,10 @@ export function registerMcpApp<Shape extends z.ZodRawShape, ViewShape extends z.
         mimeType: RESOURCE_MIME_TYPE,
         text: await loadView(),
         _meta: {
-          ...(app.resource.csp && { ui: { csp: app.resource.csp } }),
+          ui: {
+            ...(app.resource.csp && { csp: app.resource.csp }),
+            ...(app.resource.prefersBorder !== undefined && { prefersBorder: app.resource.prefersBorder }),
+          },
           ...(app.resource.displayModes && {
             'openai/ui': {
               preferredDisplayMode: app.resource.displayModes.preferred,

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

@@ -48,7 +48,8 @@ type McpServerOptions = {
 
 const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
 
-// Helper to create consistent MCP tool handlers with error handling
+// Helper to create consistent MCP tool handlers with error handling. Results are compact JSON: indenting them costs
+// the model about a fifth more tokens for nothing
 function createToolHandler<T>(fn: (params: T) => Promise<any>, errorMessage: string) {
   return async (params: T) => {
     try {
@@ -62,7 +63,7 @@ function createToolHandler<T>(fn: (params: T) => Promise<any>, errorMessage: str
       }
 
       return {
-        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+        content: [{ type: 'text' as const, text: JSON.stringify(result) }],
       };
     } catch (error) {
       return {
@@ -511,6 +512,8 @@ function createMcpServer(
       csp: { resourceDomains: [catalogUrl] },
       // Diagrams and schemas need the room, so hosts that can open the viewer full screen straight away
       displayModes: { preferred: 'fullscreen', available: ['inline', 'fullscreen'] },
+      // The viewer has its own background: no frame around it, on the web and on phones alike
+      prefersBorder: false,
     },
     // One viewer per server: each result updates the viewer the host already shows
     sessionId: scope ? `eventcatalog:${scope.ref.kind}:${scope.ref.id}` : 'eventcatalog',
@@ -665,7 +668,7 @@ function createMcpServer(
         try {
           const result = await execute(params);
           return {
-            content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+            content: [{ type: 'text' as const, text: JSON.stringify(result) }],
           };
         } catch (error) {
           return {
@@ -840,7 +843,7 @@ function createMcpServer(
           contents: [
             {
               uri: uri.href,
-              text: JSON.stringify({ ...(scope && { scope: scope.ref }), resources: allResources }, null, 2),
+              text: JSON.stringify({ ...(scope && { scope: scope.ref }), resources: allResources }),
               mimeType: 'application/json',
             },
           ],

package/eventcatalog/src/features/mcp/schema-viewer.ts

@@ -3,7 +3,7 @@ import { getLanguageForHighlight } from '@components/SchemaExplorer/utils';
 import { getSchemaExtensionForFormat } from '@utils/collections/schemas';
 import type { SchemaViewerSchema } from './apps/schema-viewer/shared';
 
-type SchemaToolResult = { name?: string; format?: string; url?: string; code: string };
+type SchemaToolResult = { name?: string; format?: string; path?: string; code: string };
 
 /**
  * The schemas returned by getSchemaForResource, ready for the schema viewer: parsed for its Properties tab
@@ -12,11 +12,11 @@ type SchemaToolResult = { name?: string; format?: string; url?: string; code: st
 export const toSchemaViewerSchemas = (schemas: SchemaToolResult[]): SchemaViewerSchema[] =>
   schemas.map((schema) => {
     // Schemas in the schemas collection have a format (jsonschema, avro, protobuf), others a file extension
-    const format = schema.format ?? schema.url?.split('.').pop() ?? '';
+    const format = schema.format ?? schema.path?.split('.').pop() ?? '';
     const extension = getSchemaExtensionForFormat(format);
     return {
       ...parseSchemaForViewer(extension, schema.code),
-      ...(schemas.length > 1 && { name: schema.name ?? schema.url?.split('/').pop() ?? format }),
+      ...(schemas.length > 1 && { name: schema.name ?? schema.path?.split('/').pop() ?? format }),
       format,
       language: getLanguageForHighlight(extension),
       code: schema.code,

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

@@ -52,7 +52,7 @@ const CANVAS_ICON_SVG =
 const CANVAS_ICON = { src: `data:image/svg+xml;base64,${btoa(CANVAS_ICON_SVG)}`, mimeType: 'image/svg+xml', sizes: ['20x20'] };
 
 const text = (value: unknown, isError = false) => ({
-  content: [{ type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
+  content: [{ type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value) }],
   ...(isError && { isError }),
 });
 
@@ -124,6 +124,8 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
       // The view joins the canvas over the collaboration WebSocket, and shows icons served by this EventCatalog
       csp: { connectDomains: [new URL(socketUrl).origin, catalogUrl], resourceDomains: [catalogUrl] },
       displayModes: { preferred: 'fullscreen', available: ['inline', 'fullscreen'] },
+      // The canvas has its own background: no frame around it, on the web and on phones alike
+      prefersBorder: false,
     },
     metaKey: CANVAS_META_KEY,
     tool: {

package/eventcatalog/src/features/studio/tool-sync.ts

@@ -6,7 +6,8 @@ import type { Status } from './hooks/use-studio-flow';
  * Syncing a canvas through MCP tool calls, for when a view can't open the collaboration WebSocket
  * (e.g. an MCP App inside a chat whose sandbox blocks it). Each call sends the server what it doesn't have
  * yet (by its state vector) and our presence, and gets back what we don't have and everyone's presence.
- * Slower than the WebSocket (it polls), but works wherever the chat can call the MCP server's tools.
+ * Slower than the WebSocket (it polls), but works wherever the chat can call the MCP server's tools. It polls less
+ * while nothing changes, and rarely while the view is out of sight (chats keep every view they showed running).
  */
 
 export type SyncRequest = {
@@ -33,6 +34,11 @@ export const fromBase64 = (text: string) => Uint8Array.from(atob(text), (char) =
 /** Applied with this origin, so undo (which tracks local changes) leaves other people's changes alone */
 const REMOTE = Symbol('tool-sync');
 
+/** Waiting longest between syncs while nothing changes on either side */
+const IDLE_INTERVAL_MS = 5000;
+/** Between syncs while the view is out of sight (slowed, not stopped: a host that wrongly reports it hidden still syncs) */
+const OUT_OF_SIGHT_INTERVAL_MS = 15_000;
+
 export function startToolSync(
   doc: Y.Doc,
   awareness: Awareness,
@@ -44,32 +50,90 @@ export function startToolSync(
   }: { canvasId: string; sync: ToolSync; onStatus: (status: Status) => void; intervalMs?: number }
 ) {
   let serverVector: Uint8Array | undefined;
+  let lastServerVector: string | undefined;
+  let lastAwareness: string | undefined;
   let stopped = false;
+  let syncing = false;
   let timer: ReturnType<typeof setTimeout> | undefined;
+  let dueAt = 0;
+  // Slower while nothing changes (a chat keeps every view it showed running, each polling), back to quick on a change
+  let delay = intervalMs;
+  // Hosts keep a chat's earlier views running: one scrolled out of sight, or in a hidden tab, syncs rarely
+  let inView = true;
+  const isShown = () => inView && document.visibilityState !== 'hidden';
+
+  const schedule = (ms: number) => {
+    clearTimeout(timer);
+    dueAt = Date.now() + ms;
+    timer = setTimeout(tick, ms);
+  };
 
   const tick = async () => {
+    timer = undefined;
+    if (stopped || syncing) return;
+    syncing = true;
     try {
+      const update = Y.encodeStateAsUpdate(doc, serverVector);
       const response = await sync({
         canvasId,
         clientId: doc.clientID,
         stateVector: toBase64(Y.encodeStateVector(doc)),
-        update: toBase64(Y.encodeStateAsUpdate(doc, serverVector)),
+        update: toBase64(update),
         awareness: toBase64(encodeAwarenessUpdate(awareness, [doc.clientID])),
       });
       if (stopped) return;
       Y.applyUpdate(doc, fromBase64(response.update), REMOTE);
       serverVector = fromBase64(response.stateVector);
       if (response.awareness) applyAwarenessUpdate(awareness, fromBase64(response.awareness), REMOTE);
+      // Anything new either way (the canvas, or anyone's presence) keeps it quick
+      const changed = response.stateVector !== lastServerVector || response.awareness !== lastAwareness;
+      lastServerVector = response.stateVector;
+      lastAwareness = response.awareness;
+      delay = changed ? intervalMs : Math.min(delay * 1.5, IDLE_INTERVAL_MS);
       onStatus('connected');
     } catch {
       if (!stopped) onStatus('disconnected');
+    } finally {
+      syncing = false;
     }
-    if (!stopped) timer = setTimeout(tick, intervalMs);
+    // Out of sight: rarely, and straight away again once it's shown (see show)
+    if (!stopped) schedule(isShown() ? delay : Math.max(delay, OUT_OF_SIGHT_INTERVAL_MS));
+  };
+
+  // Our own changes and presence go out within the quick interval, however long it's been waiting
+  const wake = (_update: unknown, origin: unknown) => {
+    if (origin === REMOTE || stopped) return;
+    delay = intervalMs;
+    if (timer && dueAt > Date.now() + intervalMs) schedule(intervalMs);
   };
+  doc.on('update', wake);
+  awareness.on('update', wake);
+
+  const show = () => {
+    if (stopped || !isShown() || syncing || dueAt <= Date.now() + intervalMs) return;
+    clearTimeout(timer);
+    delay = intervalMs;
+    void tick();
+  };
+  document.addEventListener('visibilitychange', show);
+  // Seen from inside the chat's frame: whether the view is on the screen at all
+  const observer =
+    typeof IntersectionObserver === 'undefined'
+      ? undefined
+      : new IntersectionObserver(([entry]) => {
+          inView = entry?.isIntersecting ?? true;
+          show();
+        });
+  observer?.observe(document.documentElement);
+
   void tick();
 
   return () => {
     stopped = true;
     clearTimeout(timer);
+    doc.off('update', wake);
+    awareness.off('update', wake);
+    document.removeEventListener('visibilitychange', show);
+    observer?.disconnect();
   };
 }

package/eventcatalog/src/features/tools/catalog-tools.ts

@@ -4,8 +4,8 @@
  */
 import { getCollection } from 'astro:content';
 import { z } from 'zod';
-import { getSchemasFromResource, getSchemaFormatFromURL } from '@utils/collections/schemas';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
+import { getSchemaFormatFromURL } from '@utils/collections/schemas';
+import { getItemsFromCollectionByIdAndSemverOrLatest, processSpecifications, versionMatches } from '@utils/collections/util';
 import { getUbiquitousLanguageWithSubdomains } from '@utils/collections/domains';
 import { getAbsoluteFilePathForAstroFile } from '@utils/files';
 import fs from 'node:fs';
@@ -280,6 +280,74 @@ export async function getResource(params: { collection: string; id: string; vers
 
 type MessagePointer = { id: string; version?: string };
 
+type MessageEntry = { collection: string; data: { id: string; version: string } };
+
+/** Resources that send and receive messages, and the collections that hold them */
+const MESSAGING_COLLECTIONS = ['services', 'agents', 'domains'] as const;
+
+/** Old versions live in a versioned folder: what they send and receive is history, not the catalog today */
+const isLatestVersion = (entry: { filePath?: string }) => !entry.filePath?.includes('versioned');
+
+/**
+ * Whether a sends/receives pointer points at this version of a message, as on the message's pages: one without a
+ * version (or "latest") points at the latest version only; others match exactly, by semver range or by x-pattern (1.x)
+ */
+const pointsAtMessage = (pointer: MessagePointer, message: MessageEntry, latestVersion: string) => {
+  if (pointer.id !== message.data.id) return false;
+  if (!pointer.version || pointer.version === 'latest') return message.data.version === latestVersion;
+  return versionMatches(message.data.version, pointer.version);
+};
+
+/** The services, agents and domains (latest versions) that send (or receive) this version of a message */
+const getResourcesThat = async (direction: 'sends' | 'receives', message: MessageEntry) => {
+  const [latestMessage, ...collections] = await Promise.all([
+    findEntry(message.collection, message.data.id),
+    ...MESSAGING_COLLECTIONS.map((collection) => getCollection(collection)),
+  ]);
+  const latestVersion = latestMessage?.data.version ?? message.data.version;
+
+  return collections
+    .flat()
+    .filter(isLatestVersion)
+    .filter((resource) =>
+      ((resource.data as any)[direction] || []).some((pointer: MessagePointer) =>
+        pointsAtMessage(pointer, message, latestVersion)
+      )
+    );
+};
+
+/**
+ * The resources a domain or system is made of, with it: its services and agents, and for a domain its systems and
+ * subdomains (and everything inside them)
+ */
+const getResourcesInside = async (container: any) => {
+  const [domains, systems, services, agents] = await Promise.all(
+    (['domains', 'systems', 'services', 'agents'] as const).map((collection) => getCollection(collection))
+  );
+  const resolve = (entries: any[], pointers: MessagePointer[] = []) =>
+    pointers
+      .map((pointer) => getItemsFromCollectionByIdAndSemverOrLatest(entries, pointer.id, pointer.version)[0])
+      .filter(Boolean);
+
+  const found = new Map<string, any>();
+  const visit = (entry: any) => {
+    const key = `${entry.collection}/${entry.data.id}`;
+    if (found.has(key)) return;
+    found.set(key, entry);
+    if (entry.collection !== 'domains' && entry.collection !== 'systems') return;
+    [
+      ...resolve(services, entry.data.services),
+      ...resolve(agents, entry.data.agents),
+      ...(entry.collection === 'domains'
+        ? [...resolve(systems, entry.data.systems), ...resolve(domains, entry.data.domains)]
+        : []),
+    ].forEach(visit);
+  };
+  visit(container);
+
+  return [...found.values()];
+};
+
 /**
  * Resolve a sends/receives pointer to the documented message it points at
  */
@@ -321,17 +389,39 @@ export async function getMessagesProducedOrConsumedByResource(params: {
     getCollection('queries'),
   ]);
   const messages = [...events, ...commands, ...queries];
+  const summary = {
+    id: resource.data.id,
+    version: resource.data.version,
+    name: resource.data.name || resource.data.id,
+    collection: params.resourceCollection,
+  };
 
-  return {
-    resource: {
-      id: resource.data.id,
-      version: resource.data.version,
-      name: resource.data.name || resource.data.id,
-      collection: params.resourceCollection,
-    },
-    sends: (resource.data.sends || []).map((pointer: MessagePointer) => resolveMessagePointer(messages, pointer)),
-    receives: (resource.data.receives || []).map((pointer: MessagePointer) => resolveMessagePointer(messages, pointer)),
+  if (params.resourceCollection !== 'domains' && params.resourceCollection !== 'systems') {
+    return {
+      resource: summary,
+      sends: (resource.data.sends || []).map((pointer: MessagePointer) => resolveMessagePointer(messages, pointer)),
+      receives: (resource.data.receives || []).map((pointer: MessagePointer) => resolveMessagePointer(messages, pointer)),
+    };
+  }
+
+  // A domain or system sends and receives what it and everything inside it does: `by` names who, e.g. services/orders
+  const members = await getResourcesInside(resource);
+  const collect = (direction: 'sends' | 'receives') => {
+    const found = new Map<string, ReturnType<typeof resolveMessagePointer> & { by: string[] }>();
+    for (const member of members) {
+      for (const pointer of (member.data[direction] || []) as MessagePointer[]) {
+        const message = resolveMessagePointer(messages, pointer);
+        const key = `${message.collection ?? ''}/${message.id}@${message.version}`;
+        const entry = found.get(key) ?? { ...message, by: [] };
+        const by = `${member.collection}/${member.data.id}`;
+        if (!entry.by.includes(by)) entry.by.push(by);
+        found.set(key, entry);
+      }
+    }
+    return [...found.values()];
   };
+
+  return { resource: summary, sends: collect('sends'), receives: collect('receives') };
 }
 
 /**
@@ -367,15 +457,27 @@ export async function getSchemaForResource(params: { resourceId: string; resourc
     }
   }
 
-  const schema = await getSchemasFromResource(resource);
+  const files = [
+    ...(resource.data.schemaPath
+      ? [{ path: resource.data.schemaPath, format: getSchemaFormatFromURL(resource.data.schemaPath) }]
+      : []),
+    ...processSpecifications(resource.data.specifications).map((spec) => ({
+      name: spec.name,
+      path: spec.path,
+      format: spec.type,
+    })),
+  ];
+
+  // Read from beside the resource's own file (paths are relative to it); files that can't be read are left out
+  const schemas = files.flatMap((file) => {
+    try {
+      return [{ ...file, code: fs.readFileSync(getAbsoluteFilePathForAstroFile(resource.filePath ?? '', file.path), 'utf-8') }];
+    } catch {
+      return [];
+    }
+  });
 
-  if (schema.length > 0) {
-    return schema.map((schemaItem) => ({
-      url: schemaItem.url,
-      format: schemaItem.format,
-      code: fs.readFileSync(schemaItem.url, 'utf-8'),
-    }));
-  }
+  if (schemas.length > 0) return schemas;
 
   return { message: 'No schemas found for this resource' };
 }
@@ -431,8 +533,6 @@ export async function findResourcesByOwner(params: { ownerId: string }) {
  * Get resources that produce (send) a specific message
  */
 export async function getProducersOfMessage(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
-  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
-  const routableResources = [...services, ...agents];
   const message = await findEntry(params.messageCollection, params.messageId, params.messageVersion);
 
   if (!message) {
@@ -440,21 +540,13 @@ export async function getProducersOfMessage(params: { messageId: string; message
       error: `Message not found: ${params.messageId} (${describeVersion(params.messageVersion)}) in ${params.messageCollection}`,
     };
   }
-  const messageVersion = message.data.version;
 
-  const producers = routableResources.filter((resource) => {
-    const sends = (resource.data as any).sends || [];
-    return sends.some((send: any) => {
-      const idMatch = send.id === params.messageId;
-      if (!send.version || send.version === 'latest') return idMatch;
-      return idMatch && send.version === messageVersion;
-    });
-  });
+  const producers = await getResourcesThat('sends', message);
 
   return {
     message: {
       id: params.messageId,
-      version: messageVersion,
+      version: message.data.version,
       collection: params.messageCollection,
     },
     producers: producers.map((s) => ({
@@ -511,8 +603,6 @@ export async function getC4Diagram(params: { viewId?: string }) {
  * Get resources that consume (receive) a specific message
  */
 export async function getConsumersOfMessage(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
-  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
-  const routableResources = [...services, ...agents];
   const message = await findEntry(params.messageCollection, params.messageId, params.messageVersion);
 
   if (!message) {
@@ -520,21 +610,13 @@ export async function getConsumersOfMessage(params: { messageId: string; message
       error: `Message not found: ${params.messageId} (${describeVersion(params.messageVersion)}) in ${params.messageCollection}`,
     };
   }
-  const messageVersion = message.data.version;
 
-  const consumers = routableResources.filter((resource) => {
-    const receives = (resource.data as any).receives || [];
-    return receives.some((receive: any) => {
-      const idMatch = receive.id === params.messageId;
-      if (!receive.version || receive.version === 'latest') return idMatch;
-      return idMatch && receive.version === messageVersion;
-    });
-  });
+  const consumers = await getResourcesThat('receives', message);
 
   return {
     message: {
       id: params.messageId,
-      version: messageVersion,
+      version: message.data.version,
       collection: params.messageCollection,
     },
     consumers: consumers.map((s) => ({
@@ -552,8 +634,6 @@ export async function getConsumersOfMessage(params: { messageId: string; message
  * Returns all affected services (producers and consumers) and their owners
  */
 export async function analyzeChangeImpact(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
-  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
-  const routableResources = [...services, ...agents];
   const message = await findEntry(params.messageCollection, params.messageId, params.messageVersion);
 
   if (!message) {
@@ -563,17 +643,7 @@ export async function analyzeChangeImpact(params: { messageId: string; messageVe
   }
   const messageVersion = message.data.version;
 
-  // Find producers
-  const producers = routableResources.filter((resource) => {
-    const sends = (resource.data as any).sends || [];
-    return sends.some((send: any) => send.id === params.messageId);
-  });
-
-  // Find consumers
-  const consumers = routableResources.filter((resource) => {
-    const receives = (resource.data as any).receives || [];
-    return receives.some((receive: any) => receive.id === params.messageId);
-  });
+  const [producers, consumers] = await Promise.all([getResourcesThat('sends', message), getResourcesThat('receives', message)]);
 
   // Collect all affected teams/owners
   const affectedOwners = new Set<string>();
@@ -796,19 +866,10 @@ export async function findMessageBySchemaId(params: {
     const matches = getItemsFromCollectionByIdAndSemverOrLatest(collection, params.messageId, params.messageVersion);
     const resource = matches[0];
     if (resource) {
-      // Get producers and consumers
-      const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
-      const routableResources = [...services, ...agents];
-
-      const producers = routableResources.filter((resource) => {
-        const sends = (resource.data as any).sends || [];
-        return sends.some((send: any) => send.id === params.messageId);
-      });
-
-      const consumers = routableResources.filter((resource) => {
-        const receives = (resource.data as any).receives || [];
-        return receives.some((receive: any) => receive.id === params.messageId);
-      });
+      const [producers, consumers] = await Promise.all([
+        getResourcesThat('sends', resource),
+        getResourcesThat('receives', resource),
+      ]);
 
       return {
         resource: {
@@ -1265,23 +1326,23 @@ export async function getCustomDoc(params: { id: string; section?: string }) {
 
 export const toolDescriptions = {
   getResources:
-    'Use this tool to get events, agents, services, commands, queries, flows, domains, channels, entities from EventCatalog. Supports pagination via cursor and filtering by search term (searches name, id, and summary).',
+    'Use this tool to list the resources in a collection of EventCatalog (events, commands, queries, services, agents, domains, systems, flows, channels, entities, containers, data products, diagrams or ADRs). Supports pagination via cursor and filtering by search term (searches name, id, and summary).',
   getResource:
     'Use this tool to get a specific resource from EventCatalog by its id. Returns the frontmatter and markdown documentation. Omit the version to get the latest version.',
   getMessagesProducedOrConsumedByResource:
-    'Use this tool to get the messages (events, commands, queries) a service, agent or domain sends and receives. Each message is resolved to its catalog id, version, name and summary; messages that are referenced but not documented in the catalog are marked notFound. Omit the version to use the latest version of the resource.',
+    'Use this tool to get the messages (events, commands, queries) a service, agent, domain or system sends and receives. Each message is resolved to its catalog id, version, name and summary; messages that are referenced but not documented in the catalog are marked notFound. For a domain or system, this includes what the services, agents, systems and subdomains inside it send and receive, and each message lists `by`: the resources that send or receive it (e.g. services/order-service). Omit the version to use the latest version of the resource.',
   getSchemaForResource:
     'Use this tool to get the schema or specifications (openapi or asyncapi or graphql) for a resource by its id and version',
   findResourcesByOwner:
     'Use this tool to find all resources (agents, services, events, commands, etc.) owned by a specific team or user',
   getProducersOfMessage:
-    'Use this tool to find which agents or services produce (send) a specific message (event, command, or query)',
+    'Use this tool to find which services, agents or domains produce (send) a specific message (event, command, or query). Only the latest versions of those resources are included.',
   getConsumersOfMessage:
-    'Use this tool to find which agents or services consume (receive) a specific message (event, command, or query)',
+    'Use this tool to find which services, agents or domains consume (receive) a specific message (event, command, or query). Only the latest versions of those resources are included.',
   getC4Diagram:
     'Use this tool to get the C4 diagram (or likeC4) in EventCatalog. These files usually have a .c4 extension on them',
   analyzeChangeImpact:
-    'Use this tool to analyze the impact of changing a message. Returns all affected agents and services (producers and consumers), the teams that own them, and the blast radius of the change',
+    'Use this tool to analyze the impact of changing a message. Returns all affected services, agents and domains (producers and consumers), the teams that own them, and the blast radius of the change',
   explainBusinessFlow:
     'Use this tool to get detailed information about a business flow (state machine). Returns the flow definition, steps, mermaid diagram if available, and related agents and services',
   getTeams: