@eventcatalog/core 4.12.3 → 5.0.0-beta.0

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

@@ -1,20 +1,42 @@
-/**
- * Licensed under the EventCatalog Commercial License.
- * See /packages/core/eventcatalog/src/enterprise/LICENSE
- */
-
 import type { APIRoute } from 'astro';
 import { Hono, type Context } from 'hono';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 import { z } from 'zod';
 import { join } from 'node:path';
-import { isEventCatalogScaleEnabled } from '@utils/feature';
-import * as catalogTools from '@enterprise/tools/catalog-tools';
+import * as catalogTools from '@features/tools/catalog-tools';
 import { getCollection } from 'astro:content';
 import { createMcpAuthErrorResponse, validateMcpRequest } from './mcp-auth';
 import { createScopedCatalogTools } from './mcp-scoped-tools';
 import { McpScopeNotFoundError, resolveMcpScope, type McpScope, type McpScopeKind } from './mcp-scope';
+import { getArchitectureDiagramView } from '@utils/node-graphs/architecture-diagram';
+import type {
+  ArchitectureDiagramCollection,
+  ArchitectureDiagramView,
+  Graph,
+} from '@utils/node-graphs/architecture-diagram-types';
+import { inlineNodeIcons } from './mcp-app-icons';
+import type { ArchitectureDiagramPayload } from './apps/architecture-diagram/shared';
+import type { SchemaViewerPayload } from './apps/schema-viewer/shared';
+import { RESOURCE_VIEWS, VIEWER_META_KEY, VIEWER_RESOURCE_URI, VIEWER_VIEW_TOOL, type ViewerPayload } from './apps/viewer/shared';
+import { toSchemaViewerSchemas } from './schema-viewer';
+import { getMcpAppViewLoader, mcpAppNote, registerMcpApp } from './mcp-apps';
+import { buildUrl } from '@utils/url-builder';
+
+const loadViewerView = getMcpAppViewLoader('viewer');
+
+const SHOW_RESOURCE_DESCRIPTION = [
+  "Show the user a resource in EventCatalog's interactive viewer. Pick what to show with view:",
+  '"architecture" shows an architecture diagram of a domain, system, service, agent, event, command, query, flow, data store or data product: what it connects to, what it publishes and consumes, and the systems and domains around it. Use it whenever the user wants to see or understand how something works or fits together, e.g. "show me how the Order Service works", "how does the Ordering domain fit together", "what does Payments talk to", or asks for a diagram, map or visual of something. Prefer it over drawing your own diagram. For domains and systems, pass detail "overview" for just the domains, systems and their relationships, or "full" (default) to include services, messages and channels.',
+  '"schema" shows the schema of a message (event, command or query) or other resource: its properties, types, descriptions and which ones are required. Use it whenever the user wants to see or understand a schema or payload, e.g. "show me the schema for OrderCreated", "what fields does PlaceOrder have", "what does the OrderShipped payload look like".',
+  'Clients that support MCP Apps show one viewer and switch it to each thing you show, so call this again to show the user something else. The result also contains what is shown (the diagram as Mermaid in mermaidCode, or the schema code) so you can understand it.',
+  'When the client shows the viewer, do not redraw the diagram or print the whole schema again in your reply: explain it and point out what matters. Otherwise, show the user the mermaidCode or the relevant parts of the schema code.',
+].join(' ');
+
+type McpServerOptions = {
+  /** Where this EventCatalog is served, for links from MCP App views back to it */
+  catalogUrl: string;
+};
 
 const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
 
@@ -50,7 +72,7 @@ let extendedToolNames: string[] = [];
 try {
   const providerConfiguration = await import(/* @vite-ignore */ join(catalogDirectory, 'eventcatalog.chat.js'));
 
-  if (isEventCatalogScaleEnabled() && providerConfiguration.tools) {
+  if (providerConfiguration.tools) {
     extendedTools = providerConfiguration.tools;
     extendedToolNames = Object.keys(extendedTools);
   }
@@ -58,12 +80,49 @@ try {
   // No chat configuration or tools defined - this is fine
 }
 
+const MCP_SERVER_VERSION = '1.3.0';
+
+// Every built-in tool only reads the catalog, so clients can safely auto-approve them
+const readOnlyAnnotations = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+const optionalVersion = (resource: string) =>
+  z.string().optional().describe(`The version of the ${resource}. Omit it (or pass "latest") to use the latest version.`);
+
+function getServerInstructions(scope?: McpScope) {
+  return [
+    'EventCatalog documents an event-driven architecture: domains, systems, services, agents, the messages they exchange (events, commands, queries), channels, flows, entities, data products, schemas, owners (teams and users) and custom documentation.',
+    ...(scope
+      ? [
+          `This server is scoped to the ${scope.name} ${scope.ref.kind} (version ${scope.ref.version}). Only resources inside this ${scope.ref.kind} are available.`,
+        ]
+      : []),
+    'Resources are identified by an id and a version. Versions are optional on every tool: omit the version to use the latest version.',
+    'To find something, call getResources with a collection and a search term, then fetch the details with getResource. Use getSchemaForResource when you need a schema or OpenAPI/AsyncAPI specification for yourself, not to show it to the user.',
+    'When the user wants to see or understand how something works or fits together (e.g. "show me how the Order Service works"), call showResource with view "architecture": it shows them an interactive diagram. Do not draw your own diagram of the architecture.',
+    'When the user wants to see a schema, payload or the fields of a message (e.g. "show me the schema for OrderCreated"), call showResource with view "schema", not getSchemaForResource: it shows them an interactive schema viewer. Do not print the schema yourself.',
+    'For relationships use getMessagesProducedOrConsumedByResource, getProducersOfMessage and getConsumersOfMessage. Before changing a message, call analyzeChangeImpact to find the affected services, agents and owning teams.',
+    ...(scope
+      ? []
+      : [
+          'Use findResourcesByOwner, getTeam and getUser to find who owns something and how to contact them. Guides, runbooks and architecture notes live in custom documentation: use searchCustomDocs, then getCustomDoc.',
+        ]),
+  ].join('\n');
+}
+
 // Create MCP Server with tools that access Astro collections
-function createMcpServer(scope?: McpScope) {
-  const server = new McpServer({
-    name: scope ? `EventCatalog MCP Server — ${scope.name} ${scope.ref.kind}` : 'EventCatalog MCP Server',
-    version: '1.0.0',
-  });
+function createMcpServer(scope: McpScope | undefined, { catalogUrl }: McpServerOptions) {
+  const server = new McpServer(
+    {
+      name: scope ? `EventCatalog MCP Server — ${scope.name} ${scope.ref.kind}` : 'EventCatalog MCP Server',
+      version: MCP_SERVER_VERSION,
+    },
+    { instructions: getServerInstructions(scope) }
+  );
 
   const tools = scope ? createScopedCatalogTools(scope) : catalogTools;
 
@@ -71,12 +130,14 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'getResources',
     {
+      title: 'List catalog resources',
       description: catalogTools.toolDescriptions.getResources,
       inputSchema: z.object({
         collection: catalogTools.collectionSchema.describe('The collection to get the resources from'),
         cursor: z.string().optional().describe('Pagination cursor from previous response'),
         search: z.string().optional().describe('Search term to filter resources by name, id, or summary (case-insensitive)'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.getResources, 'Failed to get resources')
   );
@@ -84,12 +145,14 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'getResource',
     {
+      title: 'Get a catalog resource',
       description: catalogTools.toolDescriptions.getResource,
       inputSchema: z.object({
         collection: catalogTools.collectionSchema.describe('The collection to get the resource from'),
         id: z.string().describe('The id of the resource to get'),
-        version: z.string().describe('The version of the resource to get'),
+        version: optionalVersion('resource'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.getResource, 'Failed to get resource')
   );
@@ -97,14 +160,16 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'getMessagesProducedOrConsumedByResource',
     {
+      title: 'Get messages a resource sends and receives',
       description: catalogTools.toolDescriptions.getMessagesProducedOrConsumedByResource,
       inputSchema: z.object({
         resourceId: z.string().describe('The id of the resource to get the messages produced or consumed for'),
-        resourceVersion: z.string().describe('The version of the resource to get the messages produced or consumed for'),
+        resourceVersion: optionalVersion('resource'),
         resourceCollection: catalogTools.resourceCollectionSchema
           .describe('The collection of the resource to get the messages produced or consumed for')
           .default('services'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.getMessagesProducedOrConsumedByResource, 'Failed to get messages')
   );
@@ -112,14 +177,16 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'getSchemaForResource',
     {
-      description: catalogTools.toolDescriptions.getSchemaForResource,
+      title: 'Get schemas and specifications',
+      description: `${catalogTools.toolDescriptions.getSchemaForResource}. To show the user a schema, use showResource with view "schema" instead: it shows them an interactive schema viewer.`,
       inputSchema: z.object({
         resourceId: z.string().describe('The id of the resource to get the schema for'),
-        resourceVersion: z.string().describe('The version of the resource to get the schema for'),
+        resourceVersion: optionalVersion('resource'),
         resourceCollection: catalogTools.resourceCollectionSchema
           .describe('The collection of the resource to get the schema for')
           .default('services'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.getSchemaForResource, 'Failed to get schema')
   );
@@ -127,10 +194,12 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'findResourcesByOwner',
     {
+      title: 'Find resources by owner',
       description: catalogTools.toolDescriptions.findResourcesByOwner,
       inputSchema: z.object({
         ownerId: z.string().describe('The id of the owner (team or user) to find resources for'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.findResourcesByOwner, 'Failed to find resources')
   );
@@ -138,14 +207,16 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'getProducersOfMessage',
     {
+      title: 'Find producers of a message',
       description: catalogTools.toolDescriptions.getProducersOfMessage,
       inputSchema: z.object({
         messageId: z.string().describe('The id of the message to find producers for'),
-        messageVersion: z.string().describe('The version of the message'),
+        messageVersion: optionalVersion('message'),
         messageCollection: catalogTools.messageCollectionSchema
           .describe('The collection type of the message (events, commands, or queries)')
           .default('events'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.getProducersOfMessage, 'Failed to get producers')
   );
@@ -153,14 +224,16 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'getConsumersOfMessage',
     {
+      title: 'Find consumers of a message',
       description: catalogTools.toolDescriptions.getConsumersOfMessage,
       inputSchema: z.object({
         messageId: z.string().describe('The id of the message to find consumers for'),
-        messageVersion: z.string().describe('The version of the message'),
+        messageVersion: optionalVersion('message'),
         messageCollection: catalogTools.messageCollectionSchema
           .describe('The collection type of the message (events, commands, or queries)')
           .default('events'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.getConsumersOfMessage, 'Failed to get consumers')
   );
@@ -169,10 +242,12 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       'getC4Diagram',
       {
+        title: 'Get C4 (LikeC4) diagrams',
         description: catalogTools.toolDescriptions.getC4Diagram,
         inputSchema: z.object({
           viewId: z.string().describe('The id of the LikeC4 view to return source files for').optional(),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(catalogTools.getC4Diagram, 'Failed to get c4 diagram')
     );
@@ -181,14 +256,16 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'analyzeChangeImpact',
     {
+      title: 'Analyze the impact of changing a message',
       description: catalogTools.toolDescriptions.analyzeChangeImpact,
       inputSchema: z.object({
         messageId: z.string().describe('The id of the message to analyze impact for'),
-        messageVersion: z.string().describe('The version of the message'),
+        messageVersion: optionalVersion('message'),
         messageCollection: catalogTools.messageCollectionSchema
           .describe('The collection type of the message (events, commands, or queries)')
           .default('events'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.analyzeChangeImpact, 'Failed to analyze impact')
   );
@@ -196,11 +273,13 @@ function createMcpServer(scope?: McpScope) {
   server.registerTool(
     'explainBusinessFlow',
     {
+      title: 'Explain a business flow',
       description: catalogTools.toolDescriptions.explainBusinessFlow,
       inputSchema: z.object({
         flowId: z.string().describe('The id of the flow to explain'),
-        flowVersion: z.string().describe('The version of the flow'),
+        flowVersion: optionalVersion('flow'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.explainBusinessFlow, 'Failed to explain flow')
   );
@@ -209,10 +288,12 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       'getTeams',
       {
+        title: 'List teams',
         description: catalogTools.toolDescriptions.getTeams,
         inputSchema: z.object({
           cursor: z.string().optional().describe('Pagination cursor from previous response'),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(catalogTools.getTeams, 'Failed to get teams')
     );
@@ -220,10 +301,12 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       'getTeam',
       {
+        title: 'Get a team',
         description: catalogTools.toolDescriptions.getTeam,
         inputSchema: z.object({
           id: z.string().describe('The id of the team to get'),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(catalogTools.getTeam, 'Failed to get team')
     );
@@ -231,10 +314,12 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       'getUsers',
       {
+        title: 'List users',
         description: catalogTools.toolDescriptions.getUsers,
         inputSchema: z.object({
           cursor: z.string().optional().describe('Pagination cursor from previous response'),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(catalogTools.getUsers, 'Failed to get users')
     );
@@ -242,18 +327,195 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       'getUser',
       {
+        title: 'Get a user',
         description: catalogTools.toolDescriptions.getUser,
         inputSchema: z.object({
           id: z.string().describe('The id of the user to get'),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(catalogTools.getUser, 'Failed to get user')
     );
   }
 
+  // Icons served by EventCatalog don't load in the host's sandbox, so they are embedded in the diagram
+  const withInlineIcons = async ({ overview, hiddenMessages, ...graph }: ArchitectureDiagramView) => {
+    const publicDirectory = join(catalogDirectory, 'public');
+    const inline = async (level: Graph) => ({ ...level, nodes: await inlineNodeIcons(level.nodes, publicDirectory) });
+    return {
+      ...(await inline(graph)),
+      ...(overview && { overview: await inline(overview) }),
+      ...(hiddenMessages && { hiddenMessages: await inline(hiddenMessages) }),
+    };
+  };
+
+  const getResourceName = async (diagram: { resourceCollection: string; resourceId: string; resourceVersion: string }) => {
+    const resource = await catalogTools.getResource({
+      collection: diagram.resourceCollection,
+      id: diagram.resourceId,
+      version: diagram.resourceVersion,
+    });
+    return ('data' in resource && resource.data.name) || diagram.resourceId;
+  };
+
+  // The diagram with its levels for the MCP App view, as the resource's Diagram page shows it
+  const getArchitectureDiagramPayload = async (diagram: {
+    resourceCollection: ArchitectureDiagramCollection;
+    resourceId: string;
+    resourceVersion: string;
+    visualiserUrl: string;
+  }): Promise<ArchitectureDiagramPayload> => ({
+    resource: {
+      collection: diagram.resourceCollection,
+      id: diagram.resourceId,
+      version: diagram.resourceVersion,
+      name: await getResourceName(diagram),
+    },
+    catalogUrl,
+    visualiserPath: diagram.visualiserUrl,
+    view: await withInlineIcons(
+      await getArchitectureDiagramView({
+        collection: diagram.resourceCollection,
+        id: diagram.resourceId,
+        version: diagram.resourceVersion,
+      })
+    ),
+  });
+
+  // The resource's schemas, parsed for the view's JSON Schema, Avro and Protobuf viewers
+  const getSchemaViewerPayload = async (params: {
+    resourceId: string;
+    resourceVersion?: string;
+    resourceCollection: string;
+  }): Promise<SchemaViewerPayload | { error: string }> => {
+    const resource = await tools.getResource({
+      collection: params.resourceCollection,
+      id: params.resourceId,
+      version: params.resourceVersion,
+    });
+    if (resource.error !== undefined) return { error: resource.error };
+
+    const schemas = await tools.getSchemaForResource({ ...params, resourceVersion: resource.version });
+    if ('error' in schemas) return schemas;
+
+    return {
+      resource: {
+        collection: params.resourceCollection,
+        id: resource.id,
+        version: resource.version,
+        name: resource.data.name || resource.id,
+      },
+      catalogUrl,
+      docsPath: buildUrl(`/docs/${params.resourceCollection}/${resource.id}/${resource.version}`),
+      schemas: Array.isArray(schemas) ? toSchemaViewerSchemas(schemas) : [],
+    };
+  };
+
+  // Every collection that has an architecture diagram or a schema
+  const viewCollectionSchema = z.enum([
+    ...new Set([...catalogTools.resourceCollectionSchema.options, ...catalogTools.visualiserCollectionSchema.options]),
+  ] as [string, ...string[]]);
+
+  const resourceViewInput = {
+    view: z
+      .enum(RESOURCE_VIEWS)
+      .describe('What to show: "architecture" for an architecture diagram, "schema" for the schema of a message'),
+    resourceId: z.string().describe('The id of the resource to show'),
+    resourceVersion: optionalVersion('resource'),
+    resourceCollection: viewCollectionSchema.describe('The collection of the resource (defaults to events)').default('events'),
+  };
+
+  type ResourceViewParams = {
+    view: (typeof RESOURCE_VIEWS)[number];
+    resourceId: string;
+    resourceVersion?: string;
+    resourceCollection: string;
+    detail?: 'overview' | 'full';
+  };
+
+  const loadArchitectureView = async ({ view, ...params }: ResourceViewParams) => {
+    const result = await tools.getArchitectureDiagramAsMermaid(params);
+    if (result.error !== undefined) return { error: result.error };
+    return {
+      forModel: {
+        note: mcpAppNote('diagram', 'redraw it as Mermaid or ASCII', 'show the user the mermaidCode'),
+        view,
+        ...result,
+      },
+      label: `the architecture diagram for ${result.resourceCollection}/${result.resourceId}`,
+      getPayload: async (): Promise<ViewerPayload> => ({
+        view: 'architecture',
+        diagram: await getArchitectureDiagramPayload(result),
+      }),
+    };
+  };
+
+  const loadSchemaView = async ({ view, ...params }: ResourceViewParams) => {
+    const payload = await getSchemaViewerPayload(params);
+    if ('error' in payload) return payload;
+    const { resource, schemas } = payload;
+    return {
+      // The model reads the schema code; the view gets it parsed for its Properties tab
+      forModel: {
+        note: mcpAppNote('schema', 'print the whole schema again', 'show the user the relevant parts of the code'),
+        view,
+        resourceId: resource.id,
+        resourceVersion: resource.version,
+        resourceCollection: resource.collection,
+        resource,
+        schemas: schemas.map(({ name, format, code }) => ({ name, format, code })),
+        ...(schemas.length === 0 && { message: `${resource.name} has no schema` }),
+      },
+      label: `the schema for ${resource.collection}/${resource.id}`,
+      getPayload: async (): Promise<ViewerPayload> => ({ view: 'schema', schema: payload }),
+    };
+  };
+
+  registerMcpApp(server, {
+    loadView: loadViewerView,
+    resource: {
+      name: 'EventCatalog viewer',
+      uri: VIEWER_RESOURCE_URI,
+      description:
+        'Interactive EventCatalog viewer (architecture diagrams and schemas), shown by MCP hosts that support MCP Apps',
+      // Diagram nodes show icons (languages, databases...) served by this EventCatalog
+      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'] },
+    },
+    // One viewer per server: each result updates the viewer the host already shows
+    sessionId: scope ? `eventcatalog:${scope.ref.kind}:${scope.ref.id}` : 'eventcatalog',
+    metaKey: VIEWER_META_KEY,
+    tool: {
+      name: 'showResource',
+      title: 'Show a resource',
+      description: SHOW_RESOURCE_DESCRIPTION,
+      input: {
+        ...resourceViewInput,
+        detail: z
+          .enum(['overview', 'full'])
+          .optional()
+          .describe(
+            'For view "architecture" of domains and systems: "overview" shows only domains, systems and their relationships; "full" (default) also shows services, messages and channels'
+          ),
+      },
+    },
+    viewTool: {
+      name: VIEWER_VIEW_TOOL,
+      title: 'Load a resource for the viewer',
+      description:
+        'Loads the architecture diagram or schema shown by the EventCatalog viewer. To show the user a resource, use showResource instead.',
+      input: resourceViewInput,
+    },
+    annotations: readOnlyAnnotations,
+    errorMessage: 'Failed to show resource',
+    load: (params) => (params.view === 'schema' ? loadSchemaView(params) : loadArchitectureView(params)),
+  });
+
   server.registerTool(
     'findMessageBySchemaId',
     {
+      title: 'Find a message from a schema',
       description: catalogTools.toolDescriptions.findMessageBySchemaId,
       inputSchema: z.object({
         messageId: z.string().describe('The message id (from x-eventcatalog-id in the schema)'),
@@ -267,6 +529,7 @@ function createMcpServer(scope?: McpScope) {
           .optional()
           .describe('Optional hint for which collection to search (events, commands, or queries)'),
       }),
+      annotations: readOnlyAnnotations,
     },
     createToolHandler(tools.findMessageBySchemaId, 'Failed to find message')
   );
@@ -275,25 +538,57 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       'explainUbiquitousLanguageTerms',
       {
+        title: 'Explain ubiquitous language terms',
         description: catalogTools.toolDescriptions.explainUbiquitousLanguageTerms,
         inputSchema: z.object({
           domainId: z.string().describe('The id of the domain to get ubiquitous language terms for'),
-          domainVersion: z.string().optional().describe('The version of the domain. If not provided, uses the latest version.'),
+          domainVersion: optionalVersion('domain'),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(tools.explainUbiquitousLanguageTerms, 'Failed to get ubiquitous language terms')
     );
   }
 
   if (!scope) {
+    server.registerTool(
+      'getDataProductInputs',
+      {
+        title: 'Get data product inputs',
+        description: catalogTools.toolDescriptions.getDataProductInputs,
+        inputSchema: z.object({
+          dataProductId: z.string().describe('The id of the data product'),
+          dataProductVersion: optionalVersion('data product'),
+        }),
+        annotations: readOnlyAnnotations,
+      },
+      createToolHandler(catalogTools.getDataProductInputs, 'Failed to get data product inputs')
+    );
+
+    server.registerTool(
+      'getDataProductOutputs',
+      {
+        title: 'Get data product outputs and contracts',
+        description: catalogTools.toolDescriptions.getDataProductOutputs,
+        inputSchema: z.object({
+          dataProductId: z.string().describe('The id of the data product'),
+          dataProductVersion: optionalVersion('data product'),
+        }),
+        annotations: readOnlyAnnotations,
+      },
+      createToolHandler(catalogTools.getDataProductOutputs, 'Failed to get data product outputs')
+    );
+
     server.registerTool(
       'getCustomDocs',
       {
+        title: 'List custom documentation',
         description: catalogTools.toolDescriptions.getCustomDocs,
         inputSchema: z.object({
           cursor: z.string().optional().describe('Pagination cursor from previous response'),
           search: z.string().optional().describe('Search term to filter docs by title, id, or summary (case-insensitive)'),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(catalogTools.getCustomDocs, 'Failed to get custom documentation pages')
     );
@@ -301,11 +596,13 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       'searchCustomDocs',
       {
+        title: 'Search custom documentation',
         description: catalogTools.toolDescriptions.searchCustomDocs,
         inputSchema: z.object({
           query: z.string().describe('Full-text search query, e.g. keywords describing the topic to find'),
           limit: z.number().optional().describe('Maximum number of results to return (default 10)'),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(catalogTools.searchCustomDocs, 'Failed to search custom documentation')
     );
@@ -313,11 +610,13 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       'getCustomDoc',
       {
+        title: 'Get a custom documentation page',
         description: catalogTools.toolDescriptions.getCustomDoc,
         inputSchema: z.object({
           id: z.string().describe('The id or slug of the custom documentation page'),
           section: z.string().optional().describe('Optional section heading to return only that section of the page'),
         }),
+        annotations: readOnlyAnnotations,
       },
       createToolHandler(catalogTools.getCustomDoc, 'Failed to get custom documentation page')
     );
@@ -329,7 +628,7 @@ function createMcpServer(scope?: McpScope) {
 
     // Extract tool properties (Vercel AI SDK format)
     // The AI SDK tool() helper uses "inputSchema" for Zod schemas
-    const { description, parameters, inputSchema, execute } = toolConfig;
+    const { title, description, parameters, inputSchema, annotations, execute } = toolConfig;
 
     if (!description || !execute) {
       console.warn(`[MCP] Skipping invalid extended tool: ${toolName}`);
@@ -339,8 +638,10 @@ function createMcpServer(scope?: McpScope) {
     server.registerTool(
       toolName,
       {
+        ...(title && { title }),
         description: description || `Custom tool: ${toolName}`,
         inputSchema: inputSchema || parameters || z.object({}),
+        ...(annotations && { annotations }),
       },
       async (params: any) => {
         try {
@@ -537,7 +838,8 @@ function createMcpServer(scope?: McpScope) {
 // "Stateless transport cannot be reused across requests" errors.
 
 // Create Hono app for MCP routes
-const app = new Hono().basePath('/docs/mcp');
+// Not strict, so /docs/mcp/ works too: MCP clients are often configured with a trailing slash
+const app = new Hono({ strict: false }).basePath('/docs/mcp');
 
 const globalBuiltInTools = [
   'getResources',
@@ -556,17 +858,28 @@ const globalBuiltInTools = [
   'getUser',
   'findMessageBySchemaId',
   'explainUbiquitousLanguageTerms',
+  'getDataProductInputs',
+  'getDataProductOutputs',
+  'showResource',
+  'getCustomDocs',
+  'searchCustomDocs',
+  'getCustomDoc',
+];
+
+const globalOnlyTools = [
+  'getC4Diagram',
+  'getTeams',
+  'getTeam',
+  'getUsers',
+  'getUser',
+  'getDataProductInputs',
+  'getDataProductOutputs',
   'getCustomDocs',
   'searchCustomDocs',
   'getCustomDoc',
 ];
 
-const scopedBuiltInTools = globalBuiltInTools.filter(
-  (tool) =>
-    !['getC4Diagram', 'getTeams', 'getTeam', 'getUsers', 'getUser', 'getCustomDocs', 'searchCustomDocs', 'getCustomDoc'].includes(
-      tool
-    )
-);
+const scopedBuiltInTools = globalBuiltInTools.filter((tool) => !globalOnlyTools.includes(tool));
 
 const getScopedBuiltInTools = (scope: McpScope) =>
   scope.ref.kind === 'system'
@@ -605,7 +918,7 @@ const getMcpResourceUris = (scope?: McpScope) =>
 
 const getScopeRef = (c: Context, kind: McpScopeKind) => ({
   kind,
-  id: c.req.param('id'),
+  id: c.req.param('id') ?? '',
   version: c.req.param('version') || 'latest',
 });
 
@@ -648,7 +961,7 @@ const handleGetRequest = async (c: Context, kind?: McpScopeKind) => {
     const scope = await resolveRequestScope(c, kind);
     return c.json({
       name: scope ? `EventCatalog MCP Server — ${scope.name} ${scope.ref.kind}` : 'EventCatalog MCP Server',
-      version: '1.2.0',
+      version: MCP_SERVER_VERSION,
       status: 'running',
       ...(scope && { scope: scope.ref }),
       tools: scope ? getScopedBuiltInTools(scope) : [...globalBuiltInTools, ...extendedToolNames],
@@ -670,7 +983,7 @@ const handleMcpRequest = async (c: Context, kind?: McpScopeKind) => {
     }
 
     const scope = await resolveRequestScope(c, kind);
-    const server = createMcpServer(scope);
+    const server = createMcpServer(scope, { catalogUrl: new URL(c.req.url).origin });
     const transport = new WebStandardStreamableHTTPServerTransport({
       sessionIdGenerator: undefined,
     });
@@ -709,7 +1022,7 @@ for (const kind of ['domain', 'system'] as const) {
 app.post('/', (c: Context) => handleMcpRequest(c));
 
 // Astro API route handler - delegates all requests to Hono
-// Note: SSR and Scale plan checks are handled at build time by the integration
+// Note: SSR checks are handled at build time by the integration
 // This route is only injected when isEventCatalogMCPEnabled() returns true
 export const ALL: APIRoute = async ({ request }) => {
   return app.fetch(request);