@eventcatalog/core 4.3.2 → 4.3.3

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.3.2";
+var version = "4.3.3";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-BYH34SOZ.js";
-import "../chunk-W4UBACYZ.js";
+} from "../chunk-UW52WRSH.js";
+import "../chunk-PXBG5QKU.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -140,7 +140,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.3.2";
+var version = "4.3.3";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-25RQCO2H.js";
+} from "../chunk-OWE74ZHY.js";
+import "../chunk-UW52WRSH.js";
 import "../chunk-K2XIENVT.js";
-import "../chunk-BYH34SOZ.js";
-import "../chunk-W4UBACYZ.js";
+import "../chunk-PXBG5QKU.js";
 import "../chunk-6QENHZZP.js";
 export {
   log_build_default as default

package/dist/{chunk-T6UEDS2J.js → chunk-2IGBU3PN.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-W4UBACYZ.js";
+} from "./chunk-PXBG5QKU.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-YBNWZEFQ.js → chunk-HR6KK56F.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-T6UEDS2J.js";
+} from "./chunk-2IGBU3PN.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-25RQCO2H.js → chunk-OWE74ZHY.js}

@@ -1,10 +1,10 @@
+import {
+  raiseEvent
+} from "./chunk-UW52WRSH.js";
 import {
   countResources,
   serializeCounts
 } from "./chunk-K2XIENVT.js";
-import {
-  raiseEvent
-} from "./chunk-BYH34SOZ.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/{chunk-W4UBACYZ.js → chunk-PXBG5QKU.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "4.3.2";
+var version = "4.3.3";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-BYH34SOZ.js → chunk-UW52WRSH.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-W4UBACYZ.js";
+} from "./chunk-PXBG5QKU.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "4.3.2";
+var version = "4.3.3";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-W4UBACYZ.js";
+} from "./chunk-PXBG5QKU.js";
 export {
   VERSION
 };

package/dist/docs/api/02-config.md

@@ -550,6 +550,30 @@ module.exports = {
 | ------ | ---- | ------- | ----------- |
 | `chat.enabled` | `boolean` | `true` | Enables or disables the AI chat feature. Set to `false` to hide the chat UI and prevent chat requests even when all other prerequisites are met. |
 
+### `mcp` {#mcp}
+
+Configuration for the built-in EventCatalog MCP server.
+
+The MCP server requires a Scale plan and `output: 'server'`. When those prerequisites are met, it is enabled by default. Set
+`mcp.enabled` to `false` to prevent the MCP routes from being registered and hide the MCP connection actions on domain and
+system pages.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  output: 'server',
+  mcp: {
+    enabled: false,
+  },
+};
+```
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `mcp.enabled` | `boolean` | `true` | Enables or disables the built-in MCP server when its SSR and Scale prerequisites are met. |
+
+See the [MCP server guide](/docs/development/ask-your-architecture/mcp-server/getting-started) for scoped domain and system
+endpoints, client setup, and OAuth configuration.
+
 ### `search` {#search}
 
 <AddedIn version="3.36.0" />

package/dist/docs/cli/governance.md

@@ -2,7 +2,7 @@
 id: cli-governance
 title: Governance
 sidebar_label: Governance
-sidebar_position: 20
+sidebar_position: 19
 ---
 
 # Governance CLI Commands

package/dist/docs/cli/snapshots.md

@@ -2,7 +2,7 @@
 id: cli-snapshots
 title: Snapshots
 sidebar_label: Snapshots
-sidebar_position: 19
+sidebar_position: 18
 ---
 
 # Snapshots CLI Commands

package/dist/docs/development/ask-your-architecture/03-mcp-server/getting-started.md

@@ -19,7 +19,7 @@ import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 ### Quick start
 
-Your MCP server is available at:
+The MCP server for your whole catalog is available at:
 
 ```
 https://your-eventcatalog.com/docs/mcp/
@@ -31,8 +31,41 @@ For local development:
 http://localhost:3000/docs/mcp/
 ```
 
-The MCP server is enabled by default when EventCatalog is running in server mode with a Scale license. To disable it, set
-`mcp.enabled` to `false`:
+### Connect to a domain or system
+
+Domain and system pages include a **Connect to MCP server** action when the built-in MCP server is available. Select it to see
+and copy the scoped server URL for that resource.
+
+Scoped MCP servers expose the selected domain or system and resources reachable from it through supported catalog
+relationships. EventCatalog follows those relationships recursively, giving the MCP client the full reachable graph without
+including unrelated catalog resources. Scoped MCP URLs do not take a depth parameter.
+
+| Scope | Latest version | Specific version |
+|---|---|---|
+| Domain | `/docs/mcp/domains/{domain-id}` | `/docs/mcp/domains/{domain-id}/{version}` |
+| System | `/docs/mcp/systems/{system-id}` | `/docs/mcp/systems/{system-id}/{version}` |
+
+For example:
+
+```text
+https://your-eventcatalog.com/docs/mcp/domains/payments
+https://your-eventcatalog.com/docs/mcp/systems/payment-processing/1.2.0
+```
+
+The unversioned URL follows the latest version of the domain or system. When you view a historical version in EventCatalog, the
+connection action uses the versioned URL instead.
+
+You can use a scoped URL anywhere the client examples below use the whole-catalog `/docs/mcp/` URL.
+
+:::note Scoped tool availability
+Scoped servers omit C4, team and user directory, custom documentation, and user-defined extended tools. System-scoped servers
+also omit the domain-specific ubiquitous-language tool.
+:::
+
+### Disable the MCP server
+
+The built-in MCP server is enabled by default when EventCatalog is running in server mode with a Scale license. To disable the
+whole-catalog endpoint, scoped endpoints, and MCP connection actions, set `mcp.enabled` to `false`:
 
 ```js title="eventcatalog.config.js"
 module.exports = {
@@ -50,13 +83,17 @@ Visit the endpoint in your browser to verify. It returns available tools and res
 ```json
 {
   "name": "EventCatalog MCP Server",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "status": "running",
   "tools": ["getResources", "getResource", ...],
   "resources": ["eventcatalog://all", "eventcatalog://events", ...]
 }
 ```
 
+The MCP server uses stateless Streamable HTTP. MCP protocol requests use `POST`; an ordinary browser `GET` returns the health
+response above. A client requesting a server-sent events stream with `GET` receives `405 Method Not Allowed` because this
+stateless server does not provide the optional SSE channel.
+
 ### Protect with OAuth
 
 <AddedIn version="3.40.0" />
@@ -65,6 +102,10 @@ The built-in MCP server can be protected with OAuth Bearer tokens, following the
 
 EventCatalog acts as the OAuth protected resource server for `/docs/mcp`. Your identity provider or authorization server remains responsible for user login, consent, client registration, `/authorize`, `/oauth/token`, and token refresh.
 
+The same authorization configuration protects the whole-catalog endpoint and every scoped domain and system endpoint. Configure
+`resource` and `audience` for the catalog MCP resource at `/docs/mcp`; you do not need separate OAuth configuration for each
+scope.
+
 Configure MCP authorization in `eventcatalog.config.js`:
 
 ```js title="eventcatalog.config.js"
@@ -187,7 +228,7 @@ claude mcp add --transport http <name> <url>
 
 ## Available tools
 
-### 15 built-in tools
+### 19 built-in tools
 
 - `getResources` - Get events, services, commands, queries, flows, domains
 - `getResource` - Get a specific resource by id and version
@@ -196,25 +237,34 @@ claude mcp add --transport http <name> <url>
 - `findResourcesByOwner` - Resources owned by a team or user
 - `getProducersOfMessage` - Services that produce a message
 - `getConsumersOfMessage` - Services that consume a message
+- `getC4Diagram` - Get the source for a C4 diagram
 - `analyzeChangeImpact` - Impact of changing a message
 - `explainBusinessFlow` - Detailed flow information
 - `getTeams` / `getTeam` - Query teams
 - `getUsers` / `getUser` - Query users
 - `findMessageBySchemaId` - Find messages by schema identifiers
 - `explainUbiquitousLanguageTerms` - DDD ubiquitous language from domains
+- `getCustomDocs` - List and search custom documentation pages
+- `searchCustomDocs` - Full-text search custom documentation
+- `getCustomDoc` - Get a custom documentation page or section
 
 [See full API documentation →](/docs/development/ask-your-architecture/mcp-server/getting-started)
 
-### 12 resources
+### 17 resources
 
 - `eventcatalog://all` - All resources
 - `eventcatalog://events` - All events
 - `eventcatalog://commands` - All commands
 - `eventcatalog://queries` - All queries
+- `eventcatalog://agents` - All agents
+- `eventcatalog://adrs` - All architecture decision records
 - `eventcatalog://services` - All services
+- `eventcatalog://systems` - All systems
 - `eventcatalog://channels` - All channels
+- `eventcatalog://entities` - All entities
 - `eventcatalog://diagrams` - All diagrams
 - `eventcatalog://containers` - All containers
+- `eventcatalog://data-products` - All data products
 - `eventcatalog://domains` - All domains
 - `eventcatalog://flows` - All flows
 - `eventcatalog://teams` - All teams
@@ -296,4 +346,3 @@ See [instructions on the GitHub repository](https://github.com/event-catalog/mcp
 
 
 
-

package/dist/docs/development/ask-your-architecture/03-mcp-server/introduction.md

@@ -13,11 +13,16 @@ import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 <PlanBanner plan="Scale" />
 
-EventCatalog exposes an MCP server. This allows you to connect any MCP client to your catalog to fetch the relevant information about your architecture when you need it.
-
-EventCatalog MCP server has out the box tools, that helps your AI agents and LLMs query the correct information based on the task it is trying to do.
+EventCatalog exposes a built-in MCP server that lets AI agents and other MCP clients query your architecture catalog. Its
+built-in tools can find resources, inspect schemas and ownership, follow message producers and consumers, and analyze change
+impact.
 
+You can connect a client to the whole catalog, or limit it to the graph of a particular domain or system. Scoped connections
+give an agent the selected resource and resources recursively reachable through its supported relationships, without exposing
+unrelated parts of the catalog.
 
+On a domain or system page, select **Connect to MCP server** to copy the appropriate scoped server URL. EventCatalog uses the
+unversioned URL for the latest resource version and includes the version when you are viewing historical documentation.
 
 
 

package/dist/docs/development/deployment/build-ssr-mode.md

@@ -47,12 +47,4 @@ This will output one directory
 
 You will need to deploy your EventCatalog to a server that can run Node.js.
 
-The easiest way to do this is to use [a docker container](/docs/development/deployment/hosting-options#hosting-static-website-with-docker).
-
-## Loading indicator
-
-<AddedIn version="4.2.5" />
-
-Server-side rendering means a page's render time depends on your server, so navigations can occasionally take longer than a static build.
-
-EventCatalog shows a thin progress bar at the top of the page during navigations that take longer than 200ms, so the catalog never looks unresponsive. It works automatically and needs no configuration.
+The easiest way to do this is to use [a docker container](/docs/development/deployment/hosting-options#hosting-static-website-with-docker).

package/dist/docs/development/developer-tools/api-catalog.md

@@ -105,7 +105,7 @@ Content-Type: application/yaml
 
 ### MCP server entry
 
-When the EventCatalog MCP server is enabled, an additional entry pointing at `/docs/mcp` is appended to the linkset. This lets MCP-aware agents discover the catalog's machine interface alongside its API specifications.
+When the EventCatalog MCP server is enabled, an additional entry pointing at `/docs/mcp` is appended to the linkset. This lets MCP-aware agents discover the catalog's machine interface alongside its API specifications. The entry is omitted when `mcp.enabled` is set to `false`.
 
 ### What is included
 

package/dist/docs/development/guides/98-versioning-resources.md

@@ -10,6 +10,7 @@ description: Learn how versioning works for EventCatalog resources.
 ---
 
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
+import AddedIn from '@site/src/components/MDX/AddedIn';
 
 EventCatalog resources can be versioned when you want to preserve how a resource looked at a point in time.
 
@@ -110,6 +111,20 @@ For example:
 
 This lets users compare the current resource with previous versions when they need historical context.
 
+### Stable URLs for the latest version
+
+<AddedIn version="4.3.3" />
+
+For services, the URLs for the latest version and its sub-pages (changelog, specifications, and attached documentation) stay versionless and never change as the service is versioned up.
+
+| Page | URL |
+|------|-----|
+| Overview | `/docs/services/Orders` |
+| Changelog | `/docs/services/Orders/changelog` |
+| OpenAPI spec | `/docs/services/Orders/spec/openapi` |
+
+Share these links freely. When `Orders` moves from `1.0.0` to `2.0.0`, the versionless URLs keep resolving to whatever is latest, so the link never rots. Historical versions keep their versioned URLs, for example `/docs/services/Orders/1.0.0/changelog`.
+
 ## Referencing versions
 
 When one resource references another resource, you can include a `version` field when you want to point to a specific version.

package/dist/docs/development/guides/resources/entities/03-model-entity-relationships.md

@@ -88,27 +88,28 @@ This tells EventCatalog that `order.customerId` references the `customer.custome
 
 ## Reference a whole entity
 
-Use `referenceTarget: entity` when the relationship is to the entity rather than one of its properties.
+Use `referenceTarget: entity` when a property relates to the referenced entity as a whole rather than one of its properties.
 
-```yaml
+```yaml title="/entities/order/index.mdx"
 properties:
   - name: customer
-    type: object
+    type: Customer
     references: customer
     referenceTarget: entity
     relationType: placedBy
 ```
 
-This renders the relationship against the `Customer` entity header. Existing relationships that omit `referenceTarget` continue to use property-level targeting.
+This renders the relationship against the `Customer` entity header in entity maps. Existing relationships that omit `referenceTarget` continue to use property-level targeting.
 
 ## Model embedded objects
 
-Use nested `properties` for a value object that only exists as part of its parent entity. Embedded objects have no entity id and cannot be referenced independently from elsewhere in the catalog.
+Use nested `properties` for a value object that exists only as part of its parent entity. Property definitions are recursive, so embedded objects can contain other embedded objects.
 
-```yaml
+```yaml title="/entities/order/index.mdx"
 properties:
   - name: deliveryAddress
     type: object
+    required: true
     properties:
       - name: line1
         type: string
@@ -116,8 +117,26 @@ properties:
       - name: city
         type: string
         required: true
+      - name: coordinates
+        type: object
+        properties:
+          - name: latitude
+            type: number
+          - name: longitude
+            type: number
+```
+
+Embedded objects are owned by their parent entity. They have no entity id and cannot be referenced independently elsewhere in the catalog.
+
+### Model arrays of embedded objects
+
+Define nested `properties` inside `items` when an array contains embedded objects.
+
+```yaml title="/entities/order/index.mdx"
+properties:
   - name: adjustments
     type: array
+    description: Discounts and credits applied to the order.
     items:
       type: object
       properties:
@@ -125,6 +144,7 @@ properties:
           type: string
         - name: amount
           type: decimal
+          required: true
 ```
 
 Embedded properties appear inside their parent entity rather than as separate nodes in entity maps.

package/dist/docs/development/guides/resources/entities/05-entity-maps.md

@@ -17,6 +17,8 @@ When entities are assigned to a domain or service, EventCatalog can create an en
 - Entities referenced from outside the current resource.
 - Which entities are owned by the current domain or service context.
 
+Entity properties that contain embedded objects can be expanded directly in the map. Relationships configured with `referenceTarget: entity` connect to the entity header, while existing property-level relationships continue to connect to the referenced identifier or property.
+
 ![Entity Map](./img/entity-map.png)
 
 ## Open an entity map in the visualizer

package/dist/docs/development/guides/resources/entities/06-reference.md

@@ -96,6 +96,27 @@ properties:
       - pending
       - confirmed
       - cancelled
+  # Delivery address captured as part of the order.
+  - name: deliveryAddress
+    type: object
+    required: true
+    properties:
+      - name: line1
+        type: string
+        required: true
+      - name: city
+        type: string
+        required: true
+  # Discounts and credits embedded in the order.
+  - name: adjustments
+    type: array
+    items:
+      type: object
+      properties:
+        - name: description
+          type: string
+        - name: amount
+          type: decimal
 ---
 ```
 
@@ -264,7 +285,9 @@ attachments:
 | `properties` | `array` | Nested properties for an embedded object. |
 | `items` | `object` | Item type and optional nested properties for array properties. |
 
-Property definitions are recursive, so embedded objects and arrays of embedded objects can contain their own `properties`. Embedded objects are owned by their parent entity and are not independently referenceable catalog resources.
+Property definitions are recursive. Embedded objects and arrays of embedded objects can contain their own `properties`. Embedded objects belong to their parent entity and are not independently referenceable catalog resources.
+
+Use `referenceTarget: entity` with `references` when a relationship should connect to the referenced entity as a whole. If `referenceTarget` is omitted, EventCatalog targets `referencesIdentifier`, the referenced entity's `identifier`, or its first property.
 
 ## EntityPropertiesTable component
 
@@ -274,7 +297,7 @@ Use `<EntityPropertiesTable />` in the entity Markdown body to render the entity
 <EntityPropertiesTable />
 ```
 
-This is useful when you want the documentation page to show the same properties defined in frontmatter.
+This is useful when you want the documentation page to show the same properties defined in frontmatter. Embedded properties are displayed beneath their parent property, and references identify whether they target a whole entity or one of its properties.
 
 ## Custom properties
 

package/dist/docs/development/guides/resources/services/07-versioning-and-lifecycle/01-version-services.md

@@ -8,6 +8,8 @@ title: Version services
 description: Learn how to version services
 ---
 
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
 All content in EventCatalog can be versioned. This allows you to keep historic versions of content which can give context to users why things are changing.
 
 ## How to version a service

package/dist/docs/plugins/asyncapi/02-plugin-configuration.md

@@ -57,6 +57,7 @@ Each service in the `services` array requires the following properties:
 | `messages.id.separator` | string | `-` | The separator to use between the prefix and the message id. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/plugin-configuration#adding-prefix-to-all-messages) |
 | `messages.id.prefixWithServiceId` | boolean | | If true, the service id will be added to the id of the messages that are generated. For example a message with the id `orderPlaced` and the service id `orders-service` will be `orders-service-orderPlaced`. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/plugin-configuration#adding-prefix-to-all-messages) |
 | `messages.id.lowerCase` | boolean | false | If true, the message id will be stored in lowercase and the folder will also be lowercased. (e.g `/events/orderplaced/index.mdx) _(Added in v5.0.0)_ |
+| `preserveExistingMessages` | boolean | `true` | Preserve existing message Markdown when the generator runs again. Set to `false` to replace existing Markdown with content generated from the AsyncAPI specification and `messages.generateMarkdown` template. Referenced and external messages are never overwritten. |
 | `saveParsedSpecFile` | boolean | `false` | Parse and save expanded AsyncAPI spec (helpful for files with $refs) |
 | `parseSchemas` | boolean | `true` | If you choose to parse your specification file using the [saveParsedSpecFile](#saveparsedspecfile-saveparsedspecfile) field, you can also opt in or out to have your ,message schemas parsed using the `parseSchemas` field. By default message schemas are parsed, if you want to keep your original schemas you have to set `parseSchemas` to false. | | `parseChannels` | boolean | `false` | Parse and save channels. If you set to true the AsyncAPI channels will also be documented in the catalog. |
 | `parseChannels` | boolean | `false` | When setting the value to true the generator will parse and write channels to your EventCatalog. |
@@ -66,6 +67,35 @@ Each service in the `services` array requires the following properties:
 | `parseExamples` | boolean | `true` | Parse message examples from AsyncAPI files and write each payload as a `.json` file to the message's `examples` folder. Named examples use `{name}.json`; unnamed examples fall back to `example-{index}.json`. Set to `false` to disable. _(Added in v6.1.0)_ [(Read more)](/docs/plugins/asyncapi/features#parse-message-examples) |
 | `debug` | boolean | `false` | Enable debug mode |
 
+## Regenerating existing message Markdown
+
+<AddedIn version="7.0.1" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+By default, the generator preserves the Markdown already stored for an existing message. This allows you to manually enrich generated message pages without losing those changes the next time the generator runs.
+
+Set `preserveExistingMessages` to `false` when your AsyncAPI specification or `messages.generateMarkdown` template should be the source of truth:
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        preserveExistingMessages: false,
+        services: [
+          {
+            path: './asyncapi.yml',
+            id: 'orders-service',
+          },
+        ],
+      },
+    ],
+  ],
+};
+```
+
+This option only controls message Markdown. Message metadata and schemas can still be updated, while existing badges and attachments are preserved. A service that only references or receives an existing message cannot overwrite the message, even when `preserveExistingMessages` is `false`.
+
 ## Example Configuration
 
 ```js title="eventcatalog.config.js"
@@ -308,5 +338,3 @@ or refer to the [AsyncAPI examples on GitHub](https://github.com/event-catalog/g
 
 
 
-
-