@eventcatalog/core 4.12.3 → 5.0.0-beta.0

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

@@ -0,0 +1,160 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import type { McpUiDisplayMode } from '@modelcontextprotocol/ext-apps';
+import { registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from '@modelcontextprotocol/ext-apps/server';
+import { z } from 'zod';
+
+// MCP App views (built by scripts/build-mcp-apps.mjs). Without a build, tools return text only.
+// Loaded when a host reads the view, not up front: each view's HTML is up to a few MB
+const mcpAppViews = import.meta.glob<string>('./apps/generated/*.html', { query: '?raw', import: 'default' });
+
+/** Loads a built MCP App view's HTML, or undefined when the views weren't built */
+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'>) => ({
+  ui: { resourceUri, ...(visibility && { visibility }) },
+  [RESOURCE_URI_META_KEY]: resourceUri,
+});
+
+/** Told to the model with every result shown in a view, so it doesn't repeat what the user can already see */
+export const mcpAppNote = (subject: string, avoid: string, otherwise: string) =>
+  `Clients that support MCP Apps are showing the user this ${subject} interactively. If so, do not ${avoid}: explain it instead. Otherwise, ${otherwise}.`;
+
+/** What a tool shows: text for the model, and the payload for the view (built only when there is a view to show it) */
+export type McpAppResult<Payload> =
+  | { error: string }
+  | {
+      /** What the model reads, including a note (see mcpAppNote) on what the view already shows the user */
+      forModel: Record<string, unknown>;
+      /** What was loaded, e.g. "the schema for events/OrderCreated", for the app-only tool's text */
+      label: string;
+      getPayload: () => Promise<Payload>;
+    };
+
+type ToolDefinition<Shape extends z.ZodRawShape> = {
+  name: string;
+  title: string;
+  description: string;
+  /** The tool's arguments, as a Zod shape */
+  input: Shape;
+};
+
+export type McpAppDefinition<Shape extends z.ZodRawShape, ViewShape extends z.ZodRawShape, Payload> = {
+  /** Loads the view's HTML; undefined when the views weren't built, so only the text result is returned */
+  loadView?: () => Promise<string>;
+  resource: {
+    name: string;
+    uri: string;
+    description: string;
+    csp?: { resourceDomains: 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[] };
+  };
+  /**
+   * Ties every result to one view (ChatGPT's `openai/widgetSessionId`): the host updates the view it already
+   * shows with each new result, instead of showing another one
+   */
+  sessionId?: string;
+  /** Key of the payload in the model-facing tool result's `_meta` */
+  metaKey: string;
+  /** The tool the model calls to show the user something */
+  tool: ToolDefinition<Shape>;
+  /** App-only tool the view calls to load its payload when the host doesn't pass the result's `_meta` */
+  viewTool: ToolDefinition<ViewShape>;
+  annotations: ToolAnnotations;
+  load: (params: z.output<z.ZodObject<Shape>> | z.output<z.ZodObject<ViewShape>>) => Promise<McpAppResult<Payload>>;
+  /** Prefix of the error returned when loading fails */
+  errorMessage: string;
+};
+
+const errorResult = (error: { error: string }) => ({
+  content: [{ type: 'text' as const, text: JSON.stringify(error) }],
+  isError: true,
+});
+
+/**
+ * Registers a tool whose result MCP hosts that support MCP Apps show in a view (e.g. an interactive diagram),
+ * with the app-only tool the view loads from and the view itself. Other hosts get the tool's text.
+ */
+export function registerMcpApp<Shape extends z.ZodRawShape, ViewShape extends z.ZodRawShape, Payload>(
+  server: McpServer,
+  app: McpAppDefinition<Shape, ViewShape, Payload>
+) {
+  const { loadView } = app;
+
+  const showInView = async (params: z.output<z.ZodObject<Shape>>) => {
+    try {
+      const result = await app.load(params);
+      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) }],
+        ...(loadView && {
+          _meta: {
+            [app.metaKey]: await result.getPayload(),
+            ...(app.sessionId && { 'openai/widgetSessionId': app.sessionId }),
+          },
+        }),
+      };
+    } catch (error) {
+      return errorResult({ error: `${app.errorMessage}: ${error}` });
+    }
+  };
+
+  const toolInput = z.object(app.tool.input);
+  server.registerTool<z.ZodRawShape, typeof toolInput>(
+    app.tool.name,
+    {
+      title: app.tool.title,
+      description: app.tool.description,
+      inputSchema: toolInput,
+      annotations: app.annotations,
+      _meta: loadView ? appViewMeta(app.resource.uri) : undefined,
+    },
+    showInView
+  );
+
+  if (!loadView) return;
+
+  const loadForView = async (params: z.output<z.ZodObject<ViewShape>>) => {
+    const result = await app.load(params);
+    if ('error' in result) return errorResult(result);
+    return {
+      content: [{ type: 'text' as const, text: `Loaded ${result.label}` }],
+      structuredContent: (await result.getPayload()) as Record<string, unknown>,
+    };
+  };
+
+  const viewToolInput = z.object(app.viewTool.input);
+  server.registerTool<z.ZodRawShape, typeof viewToolInput>(
+    app.viewTool.name,
+    {
+      title: app.viewTool.title,
+      description: app.viewTool.description,
+      inputSchema: viewToolInput,
+      annotations: app.annotations,
+      _meta: appViewMeta(app.resource.uri, ['app']),
+    },
+    loadForView
+  );
+
+  registerAppResource(server, app.resource.name, app.resource.uri, { description: app.resource.description }, async () => ({
+    contents: [
+      {
+        uri: app.resource.uri,
+        mimeType: RESOURCE_MIME_TYPE,
+        text: await loadView(),
+        _meta: {
+          ...(app.resource.csp && { ui: { csp: app.resource.csp } }),
+          ...(app.resource.displayModes && {
+            'openai/ui': {
+              preferredDisplayMode: app.resource.displayModes.preferred,
+              availableDisplayModes: app.resource.displayModes.available,
+            },
+          }),
+        },
+      },
+    ],
+  }));
+}

package/eventcatalog/src/{enterprise → features}/mcp/mcp-auth.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import jwt, { type Algorithm, type JwtPayload } from 'jsonwebtoken';
 import { createPublicKey, type JsonWebKey, type KeyObject } from 'node:crypto';
 import config from '@config';

package/eventcatalog/src/{enterprise → features}/mcp/mcp-scope.ts

@@ -1,8 +1,3 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import utils, { type CatalogGraphResourceType, type CatalogGraphRoot, type FlatCatalogGraph } from '@eventcatalog/sdk';
 import { getCollection } from 'astro:content';
 import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
@@ -94,9 +89,14 @@ export class McpScope {
     return true;
   }
 
-  has(collection: string, id: string, version?: string) {
+  /** Find an entry in the scope. When no version (or 'latest') is given, the latest version in the scope is returned. */
+  find(collection: string, id: string, version?: string): CatalogEntry | undefined {
     const entries = Array.from(this.entries.get(collection)?.values() ?? []);
-    return getItemsFromCollectionByIdAndSemverOrLatest(entries, id, version).length > 0;
+    return getItemsFromCollectionByIdAndSemverOrLatest(entries, id, version)[0];
+  }
+
+  has(collection: string, id: string, version?: string) {
+    return this.find(collection, id, version) !== undefined;
   }
 
   list(collection: string) {

package/eventcatalog/src/{enterprise → features}/mcp/mcp-scoped-tools.ts

@@ -1,20 +1,16 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import {
   analyzeChangeImpact,
   explainBusinessFlow,
   explainUbiquitousLanguageTerms,
   findMessageBySchemaId,
+  getArchitectureDiagramAsMermaid,
   getConsumersOfMessage,
   getMessagesProducedOrConsumedByResource,
   getProducersOfMessage,
   getResource,
   getSchemaForResource,
   paginate,
-} from '@enterprise/tools/catalog-tools';
+} from '@features/tools/catalog-tools';
 import type { McpScope } from './mcp-scope';
 
 const notFound = (collection: string, id: string, version?: string) => ({
@@ -60,27 +56,26 @@ export function createScopedCatalogTools(scope: McpScope) {
       };
     },
 
-    async getResource(params: { collection: string; id: string; version: string }) {
-      if (!scope.has(params.collection, params.id, params.version)) return notFound(params.collection, params.id, params.version);
-      return getResource(params);
+    async getResource(params: { collection: string; id: string; version?: string }) {
+      const entry = scope.find(params.collection, params.id, params.version);
+      if (!entry) return notFound(params.collection, params.id, params.version);
+      return getResource({ ...params, version: entry.data.version });
     },
 
     async getMessagesProducedOrConsumedByResource(params: {
       resourceId: string;
-      resourceVersion: string;
+      resourceVersion?: string;
       resourceCollection: string;
     }) {
-      if (!scope.has(params.resourceCollection, params.resourceId, params.resourceVersion)) {
-        return notFound(params.resourceCollection, params.resourceId, params.resourceVersion);
-      }
-      return getMessagesProducedOrConsumedByResource(params);
+      const entry = scope.find(params.resourceCollection, params.resourceId, params.resourceVersion);
+      if (!entry) return notFound(params.resourceCollection, params.resourceId, params.resourceVersion);
+      return getMessagesProducedOrConsumedByResource({ ...params, resourceVersion: entry.data.version });
     },
 
-    async getSchemaForResource(params: { resourceId: string; resourceVersion: string; resourceCollection: string }) {
-      if (!scope.has(params.resourceCollection, params.resourceId, params.resourceVersion)) {
-        return notFound(params.resourceCollection, params.resourceId, params.resourceVersion);
-      }
-      return getSchemaForResource(params);
+    async getSchemaForResource(params: { resourceId: string; resourceVersion?: string; resourceCollection: string }) {
+      const entry = scope.find(params.resourceCollection, params.resourceId, params.resourceVersion);
+      if (!entry) return notFound(params.resourceCollection, params.resourceId, params.resourceVersion);
+      return getSchemaForResource({ ...params, resourceVersion: entry.data.version });
     },
 
     async findResourcesByOwner(params: { ownerId: string }) {
@@ -101,31 +96,28 @@ export function createScopedCatalogTools(scope: McpScope) {
       return { ownerId: params.ownerId, totalCount: resources.length, resources, scope: scope.ref };
     },
 
-    async getProducersOfMessage(params: { messageId: string; messageVersion: string; messageCollection: string }) {
-      if (!scope.has(params.messageCollection, params.messageId, params.messageVersion)) {
-        return notFound(params.messageCollection, params.messageId, params.messageVersion);
-      }
-      const result = await getProducersOfMessage(params);
+    async getProducersOfMessage(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
+      const entry = scope.find(params.messageCollection, params.messageId, params.messageVersion);
+      if (!entry) return notFound(params.messageCollection, params.messageId, params.messageVersion);
+      const result = await getProducersOfMessage({ ...params, messageVersion: entry.data.version });
       if ('error' in result) return result;
       const producers = filterScopedReferences(scope, result.producers);
       return { ...result, producers, count: producers.length, scope: scope.ref };
     },
 
-    async getConsumersOfMessage(params: { messageId: string; messageVersion: string; messageCollection: string }) {
-      if (!scope.has(params.messageCollection, params.messageId, params.messageVersion)) {
-        return notFound(params.messageCollection, params.messageId, params.messageVersion);
-      }
-      const result = await getConsumersOfMessage(params);
+    async getConsumersOfMessage(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
+      const entry = scope.find(params.messageCollection, params.messageId, params.messageVersion);
+      if (!entry) return notFound(params.messageCollection, params.messageId, params.messageVersion);
+      const result = await getConsumersOfMessage({ ...params, messageVersion: entry.data.version });
       if ('error' in result) return result;
       const consumers = filterScopedReferences(scope, result.consumers);
       return { ...result, consumers, count: consumers.length, scope: scope.ref };
     },
 
-    async analyzeChangeImpact(params: { messageId: string; messageVersion: string; messageCollection: string }) {
-      if (!scope.has(params.messageCollection, params.messageId, params.messageVersion)) {
-        return notFound(params.messageCollection, params.messageId, params.messageVersion);
-      }
-      const result = await analyzeChangeImpact(params);
+    async analyzeChangeImpact(params: { messageId: string; messageVersion?: string; messageCollection: string }) {
+      const entry = scope.find(params.messageCollection, params.messageId, params.messageVersion);
+      if (!entry) return notFound(params.messageCollection, params.messageId, params.messageVersion);
+      const result = await analyzeChangeImpact({ ...params, messageVersion: entry.data.version });
       if ('error' in result) return result;
 
       const producers = filterScopedReferences(scope, result.producers);
@@ -158,9 +150,10 @@ export function createScopedCatalogTools(scope: McpScope) {
       };
     },
 
-    async explainBusinessFlow(params: { flowId: string; flowVersion: string }) {
-      if (!scope.has('flows', params.flowId, params.flowVersion)) return notFound('flows', params.flowId, params.flowVersion);
-      const result = await explainBusinessFlow(params);
+    async explainBusinessFlow(params: { flowId: string; flowVersion?: string }) {
+      const entry = scope.find('flows', params.flowId, params.flowVersion);
+      if (!entry) return notFound('flows', params.flowId, params.flowVersion);
+      const result = await explainBusinessFlow({ ...params, flowVersion: entry.data.version });
       if ('error' in result) return result;
       return {
         ...result,
@@ -188,10 +181,24 @@ export function createScopedCatalogTools(scope: McpScope) {
       };
     },
 
+    // The diagram shows the resource with what it connects to, as on its Diagram page, which can include resources outside the scope
+    async getArchitectureDiagramAsMermaid(params: {
+      resourceId: string;
+      resourceVersion?: string;
+      resourceCollection: string;
+      detail?: 'overview' | 'full';
+    }) {
+      const entry = scope.find(params.resourceCollection, params.resourceId, params.resourceVersion);
+      if (!entry) return notFound(params.resourceCollection, params.resourceId, params.resourceVersion);
+      const result = await getArchitectureDiagramAsMermaid({ ...params, resourceVersion: entry.data.version });
+      if ('error' in result) return result;
+      return { ...result, scope: scope.ref };
+    },
+
     async explainUbiquitousLanguageTerms(params: { domainId: string; domainVersion?: string }) {
-      if (!scope.has('domains', params.domainId, params.domainVersion))
-        return notFound('domains', params.domainId, params.domainVersion);
-      return explainUbiquitousLanguageTerms(params);
+      const entry = scope.find('domains', params.domainId, params.domainVersion);
+      if (!entry) return notFound('domains', params.domainId, params.domainVersion);
+      return explainUbiquitousLanguageTerms({ ...params, domainVersion: entry.data.version });
     },
   };
 }