@eventcatalog/core 4.2.6 → 4.3.0

package/eventcatalog/src/enterprise/mcp/mcp-scope.ts

@@ -0,0 +1,159 @@
+/**
+ * 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';
+
+export const MCP_SCOPE_COLLECTIONS = [
+  'domains',
+  'systems',
+  'services',
+  'agents',
+  'events',
+  'commands',
+  'queries',
+  'flows',
+  'channels',
+  'entities',
+  'containers',
+  'data-products',
+  'adrs',
+  'diagrams',
+] as const;
+
+export type McpScopeCollection = (typeof MCP_SCOPE_COLLECTIONS)[number];
+export type McpScopeKind = 'domain' | 'system';
+
+export type McpScopeRef = {
+  kind: McpScopeKind;
+  id: string;
+  version?: string;
+};
+
+type CatalogEntry = {
+  collection: string;
+  data: {
+    id: string;
+    version: string;
+    name?: string;
+    summary?: string;
+    hidden?: boolean;
+    [key: string]: any;
+  };
+  [key: string]: any;
+};
+
+type CollectionLoader = (collection: McpScopeCollection) => Promise<CatalogEntry[]>;
+type GraphLoader = (root: CatalogGraphRoot, options: { flat: true }) => Promise<FlatCatalogGraph | undefined>;
+
+const graphTypeToCollection: Record<CatalogGraphResourceType, McpScopeCollection> = {
+  domain: 'domains',
+  system: 'systems',
+  service: 'services',
+  agent: 'agents',
+  event: 'events',
+  command: 'commands',
+  query: 'queries',
+  flow: 'flows',
+  channel: 'channels',
+  entity: 'entities',
+  container: 'containers',
+  'data-product': 'data-products',
+  adr: 'adrs',
+};
+
+const entryKey = (id: string, version: string) => `${id}@${version}`;
+const encodeUriPart = (value: string) => encodeURIComponent(value);
+
+export class McpScopeNotFoundError extends Error {}
+
+export class McpScope {
+  readonly entries = new Map<string, Map<string, CatalogEntry>>();
+  readonly ref: Required<McpScopeRef>;
+  readonly root: CatalogEntry;
+  readonly uriPrefix: string;
+
+  constructor(ref: McpScopeRef, root: CatalogEntry) {
+    this.ref = { ...ref, version: root.data.version } as Required<McpScopeRef>;
+    this.root = root;
+    this.uriPrefix = `eventcatalog://${ref.kind}s/${encodeUriPart(root.data.id)}/${encodeUriPart(root.data.version)}`;
+  }
+
+  add(entry: CatalogEntry | undefined) {
+    if (!entry || entry.data.hidden === true) return false;
+
+    const collectionEntries = this.entries.get(entry.collection) ?? new Map<string, CatalogEntry>();
+    const key = entryKey(entry.data.id, entry.data.version);
+    if (collectionEntries.has(key)) return false;
+
+    collectionEntries.set(key, entry);
+    this.entries.set(entry.collection, collectionEntries);
+    return true;
+  }
+
+  has(collection: string, id: string, version?: string) {
+    const entries = Array.from(this.entries.get(collection)?.values() ?? []);
+    return getItemsFromCollectionByIdAndSemverOrLatest(entries, id, version).length > 0;
+  }
+
+  list(collection: string) {
+    return Array.from(this.entries.get(collection)?.values() ?? []);
+  }
+
+  listAll() {
+    return Array.from(this.entries.values()).flatMap((entries) => Array.from(entries.values()));
+  }
+
+  get name() {
+    return this.root.data.name || this.root.data.id;
+  }
+}
+
+const defaultCollectionLoader: CollectionLoader = async (collection) => getCollection(collection as any) as any;
+const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
+const getCatalogGraph = utils(catalogDirectory).getGraph;
+const defaultGraphLoader: GraphLoader = (root, options) => getCatalogGraph(root, options);
+
+const scopeNotFound = (ref: McpScopeRef) =>
+  new McpScopeNotFoundError(
+    `${ref.kind === 'domain' ? 'Domain' : 'System'} not found: ${ref.id}${ref.version ? ` (${ref.version})` : ''}`
+  );
+
+export async function resolveMcpScope(
+  ref: McpScopeRef,
+  loadCollection: CollectionLoader = defaultCollectionLoader,
+  loadGraph: GraphLoader = defaultGraphLoader
+) {
+  const graph = await loadGraph({ type: ref.kind, id: ref.id, version: ref.version }, { flat: true });
+  if (!graph) throw scopeNotFound(ref);
+
+  const graphCollections = new Set(graph.resources.map((resource) => graphTypeToCollection[resource.type]));
+
+  const loadedCollections = await Promise.all(
+    Array.from(graphCollections).map(async (collection) => [collection, await loadCollection(collection)] as const)
+  );
+  const collections = new Map(
+    loadedCollections.map(([collection, entries]) => [
+      collection,
+      new Map(entries.map((entry) => [entryKey(entry.data.id, entry.data.version), entry])),
+    ])
+  );
+
+  const resolve = (collection: McpScopeCollection, id: string, version: string) =>
+    collections.get(collection)?.get(entryKey(id, version));
+
+  const rootCollection = graphTypeToCollection[graph.root.type];
+  const root = resolve(rootCollection, graph.root.id, graph.root.version);
+  if (!root || root.data.hidden === true) throw scopeNotFound(ref);
+
+  const scope = new McpScope(ref, root);
+  for (const resource of graph.resources) {
+    const collection = graphTypeToCollection[resource.type];
+    scope.add(resolve(collection, resource.id, resource.version));
+  }
+
+  return scope;
+}

package/eventcatalog/src/enterprise/mcp/mcp-scoped-tools.ts

@@ -0,0 +1,197 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import {
+  analyzeChangeImpact,
+  explainBusinessFlow,
+  explainUbiquitousLanguageTerms,
+  findMessageBySchemaId,
+  getConsumersOfMessage,
+  getMessagesProducedOrConsumedByResource,
+  getProducersOfMessage,
+  getResource,
+  getSchemaForResource,
+  paginate,
+} from '@enterprise/tools/catalog-tools';
+import type { McpScope } from './mcp-scope';
+
+const notFound = (collection: string, id: string, version?: string) => ({
+  error: `Resource not found: ${collection}/${id}${version ? ` (${version})` : ''}`,
+});
+
+const isScopedReference = (scope: McpScope, resource: any, defaultCollection?: string) => {
+  const collection = resource?.collection || defaultCollection;
+  return Boolean(collection && resource?.id && scope.has(collection, resource.id, resource.version));
+};
+
+const filterScopedReferences = (scope: McpScope, resources: any[] | undefined, defaultCollection?: string) =>
+  (resources || []).filter((resource) => isScopedReference(scope, resource, defaultCollection));
+
+export function createScopedCatalogTools(scope: McpScope) {
+  return {
+    async getResources(params: { collection: string; cursor?: string; search?: string }) {
+      let resources = scope.list(params.collection).map((resource) => ({
+        id: resource.data.id,
+        version: resource.data.version,
+        name: resource.data.name,
+        summary: resource.data.summary,
+      }));
+
+      if (params.search) {
+        const searchTerm = params.search.toLowerCase().trim();
+        resources = resources.filter(
+          (resource) =>
+            resource.id?.toLowerCase().includes(searchTerm) ||
+            resource.name?.toLowerCase().includes(searchTerm) ||
+            resource.summary?.toLowerCase().includes(searchTerm)
+        );
+      }
+
+      const result = paginate(resources, params.cursor);
+      if ('error' in result) return result;
+
+      return {
+        resources: result.items,
+        nextCursor: result.nextCursor,
+        totalCount: result.totalCount,
+        scope: scope.ref,
+      };
+    },
+
+    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 getMessagesProducedOrConsumedByResource(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 getMessagesProducedOrConsumedByResource(params);
+    },
+
+    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 findResourcesByOwner(params: { ownerId: string }) {
+      const resources = scope
+        .listAll()
+        .filter((resource) =>
+          (resource.data.owners || []).some((owner: string | { id: string }) =>
+            typeof owner === 'string' ? owner === params.ownerId : owner.id === params.ownerId
+          )
+        )
+        .map((resource) => ({
+          collection: resource.collection,
+          id: resource.data.id,
+          version: resource.data.version,
+          name: resource.data.name || resource.data.id,
+        }));
+
+      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);
+      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);
+      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);
+      if ('error' in result) return result;
+
+      const producers = filterScopedReferences(scope, result.producers);
+      const consumers = filterScopedReferences(scope, result.consumers);
+      const affected = [...producers, ...consumers];
+      const affectedOwners = new Set<string>();
+      affected.forEach((resource) =>
+        (resource.owners || []).forEach((owner: string | { id: string }) =>
+          affectedOwners.add(typeof owner === 'string' ? owner : owner.id)
+        )
+      );
+
+      return {
+        ...result,
+        scope: scope.ref,
+        impact: {
+          producerCount: producers.length,
+          consumerCount: consumers.length,
+          totalResourcesAffected: new Set(affected.map((resource) => `${resource.collection}:${resource.id}`)).size,
+          totalServicesAffected: new Set(
+            affected.filter((resource) => resource.collection === 'services').map((resource) => resource.id)
+          ).size,
+          totalAgentsAffected: new Set(
+            affected.filter((resource) => resource.collection === 'agents').map((resource) => resource.id)
+          ).size,
+          teamsAffected: Array.from(affectedOwners),
+        },
+        producers,
+        consumers,
+      };
+    },
+
+    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);
+      if ('error' in result) return result;
+      return {
+        ...result,
+        relatedServices: filterScopedReferences(scope, result.relatedServices, 'services'),
+        relatedAgents: filterScopedReferences(scope, result.relatedAgents, 'agents'),
+        scope: scope.ref,
+      };
+    },
+
+    async findMessageBySchemaId(params: {
+      messageId: string;
+      messageVersion?: string;
+      collection?: 'events' | 'commands' | 'queries';
+    }) {
+      const result = await findMessageBySchemaId(params);
+      if ('error' in result) return result;
+      if (!scope.has(result.resource.collection, result.resource.id, result.resource.version)) {
+        return notFound(result.resource.collection, params.messageId, params.messageVersion);
+      }
+      return {
+        ...result,
+        producers: filterScopedReferences(scope, result.producers),
+        consumers: filterScopedReferences(scope, result.consumers),
+        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);
+    },
+  };
+}