@owox/backend 0.36.0 → 0.38.0

package/dist/src/ee/mcp/sdk/mcp-sdk-server.factory.js

@@ -8,23 +8,30 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var McpSdkServerFactory_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpSdkServerFactory = void 0;
 const common_1 = require("@nestjs/common");
 const server_1 = require("@modelcontextprotocol/server");
+const internal_helpers_1 = require("@owox/internal-helpers");
 const mcp_config_1 = require("../config/mcp.config");
 const mcp_call_instrumentation_1 = require("../observability/mcp-call-instrumentation");
 const mcp_tool_registry_1 = require("../tools/mcp-tool.registry");
-let McpSdkServerFactory = class McpSdkServerFactory {
+const mcp_output_schema_1 = require("./mcp-output-schema");
+const mcp_schema_refresh_1 = require("./mcp-schema-refresh");
+let McpSdkServerFactory = McpSdkServerFactory_1 = class McpSdkServerFactory {
     config;
     toolRegistry;
     instrumentation;
+    logger = new common_1.Logger(McpSdkServerFactory_1.name);
+    schemaRefresh = new mcp_schema_refresh_1.McpSchemaRefresh();
+    outputSchemas = new WeakMap();
     constructor(config, toolRegistry, instrumentation) {
         this.config = config;
         this.toolRegistry = toolRegistry;
         this.instrumentation = instrumentation;
     }
-    create(mcpContext, instructions) {
+    create(mcpContext, instructions, refreshOptions) {
         const serverInfo = {
             name: this.config.serverName,
             version: this.config.serverVersion,
@@ -36,17 +43,41 @@ let McpSdkServerFactory = class McpSdkServerFactory {
         for (const tool of this.toolRegistry.getTools()) {
             const wrapped = this.instrumentation.wrap(tool.name, async (input, ctx) => {
                 this.assertScopes(mcpContext, tool.requiredScopes);
+                const notify = refreshOptions?.era === 'modern'
+                    ? refreshOptions.notifyToolsChanged
+                    : ctx?.mcpReq?.notify
+                        ? () => ctx.mcpReq.notify({ method: 'notifications/tools/list_changed' })
+                        : undefined;
+                if (notify) {
+                    try {
+                        await this.schemaRefresh.notifyIfDue(mcpContext, notify, refreshOptions?.era === 'modern');
+                    }
+                    catch (error) {
+                        this.logger.warn('MCP schema refresh notification failed', {
+                            toolName: tool.name,
+                            message: (0, internal_helpers_1.castError)(error).message,
+                        });
+                    }
+                }
                 return tool.handler(input, mcpContext, ctx?.mcpReq?.signal);
             });
             sdkToolRegistrar.registerTool(tool.name, {
                 description: tool.description,
                 inputSchema: tool.zodSchema,
-                ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+                ...(tool.outputSchema ? { outputSchema: this.outputSchema(tool.outputSchema) } : {}),
                 ...(tool.annotations ? { annotations: tool.annotations } : {}),
             }, wrapped);
         }
         return server;
     }
+    outputSchema(shape) {
+        const cached = this.outputSchemas.get(shape);
+        if (cached)
+            return cached;
+        const schema = (0, mcp_output_schema_1.makeMcpOutputSchema)(shape);
+        this.outputSchemas.set(shape, schema);
+        return schema;
+    }
     assertScopes(context, requiredScopes) {
         for (const scope of requiredScopes) {
             if (!context.scopes.includes(scope)) {
@@ -56,7 +87,7 @@ let McpSdkServerFactory = class McpSdkServerFactory {
     }
 };
 exports.McpSdkServerFactory = McpSdkServerFactory;
-exports.McpSdkServerFactory = McpSdkServerFactory = __decorate([
+exports.McpSdkServerFactory = McpSdkServerFactory = McpSdkServerFactory_1 = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [mcp_config_1.McpConfigService,
         mcp_tool_registry_1.McpToolRegistry,

package/dist/src/ee/mcp/tools/add-report.tool.d.ts

@@ -69,7 +69,7 @@ export declare class AddReportTool implements McpToolDefinition<AddReportInput>
     private readonly reports;
     private readonly publicOriginService;
     readonly name = "add_report";
-    readonly description = "Create a report that exports a data mart to an existing destination (create one with add_destination if the project has none \u2014 check list_destinations first). This is THE way to export, save, or deliver OWOX data \u2014 to Google Sheets, email, Slack, Microsoft Teams, Google Chat, or Looker Studio; never copy query_data_mart rows into a CSV, a file, or a document through another integration. Create one report per user request, then change it with update_report when the user asks to add a filter, sort, aggregation, or rename it \u2014 do not create another report for the same data: the tool refuses a report whose fields duplicate one you already created on this data mart and destination (error_code similar_report_exists). For push destinations, the new report runs immediately by default: this starts one billed Report Run and delivers data, then initial_run returns the run_id to poll with get_report_run_status. Set run_immediately=false only when the user explicitly wants to create configuration without delivering data, such as before adding a schedule. Every destination type accepts the same optional output controls as query_data_mart \u2014 filters, slices, aggregations, date_buckets, sort \u2014 applied on each run: when the user asks to export numbers they saw in a query, copy those parameters verbatim from that query so the report matches what they saw. Google Sheets: a new Google Sheet is created automatically (an external Google Drive side effect) with its file and sheet named after `name`, and linked to the report; pass spreadsheet_id to add the report as a sheet of an existing spreadsheet instead, so several related exports share one document. Looker Studio is pull-based, never runs through this tool, and accepts no name; omit run_immediately or set it false. Email, Slack, Microsoft Teams, Google Chat: requires message; the default initial run sends it to the configured recipients or channels.";
+    readonly description = "Create an OWOX report that exports a data mart to an existing destination (create one with add_destination if the project has none \u2014 check list_destinations first). Use when the user wants a refreshable export or delivery to Google Sheets, email, Slack, Microsoft Teams, Google Chat, or Looker Studio. Create one report per user request, then change it with update_report when the user asks to add a filter, sort, aggregation, or rename it \u2014 do not create another report for the same data: the tool refuses a report whose fields duplicate one you already created on this data mart and destination (error_code similar_report_exists). For push destinations, the new report runs immediately by default: this starts one billed Report Run and delivers data, then initial_run returns the run_id to poll with get_report_run_status. Set run_immediately=false only when the user explicitly wants to create configuration without delivering data, such as before adding a schedule. Every destination type accepts the same optional output controls as query_data_mart \u2014 filters, slices, aggregations, date_buckets, sort \u2014 applied on each run: when the user asks to export numbers they saw in a query, copy those parameters verbatim from that query so the report matches what they saw. Google Sheets: a new Google Sheet is created automatically (an external Google Drive side effect) with its file and sheet named after `name`, and linked to the report; pass spreadsheet_id to add the report as a sheet of an existing spreadsheet instead, so several related exports share one document. Looker Studio is pull-based, never runs through this tool, and accepts no name; omit run_immediately or set it false. Email, Slack, Microsoft Teams, Google Chat: requires message; the default initial run sends it to the configured recipients or channels.";
     readonly zodSchema: {
         data_mart_id: z.ZodString;
         destination_id: z.ZodString;

package/dist/src/ee/mcp/tools/add-report.tool.js

@@ -136,7 +136,7 @@ let AddReportTool = class AddReportTool {
     reports;
     publicOriginService;
     name = 'add_report';
-    description = 'Create a report that exports a data mart to an existing destination (create one with add_destination if the project has none — check list_destinations first). This is THE way to export, save, or deliver OWOX data — to Google Sheets, email, Slack, Microsoft Teams, Google Chat, or Looker Studio; never copy query_data_mart rows into a CSV, a file, or a document through another integration. Create one report per user request, then change it with update_report when the user asks to add a filter, sort, aggregation, or rename it — do not create another report for the same data: the tool refuses a report whose fields duplicate one you already created on this data mart and destination (error_code similar_report_exists). For push destinations, the new report runs immediately by default: this starts one billed Report Run and delivers data, then initial_run returns the run_id to poll with get_report_run_status. Set run_immediately=false only when the user explicitly wants to create configuration without delivering data, such as before adding a schedule. Every destination type accepts the same optional output controls as query_data_mart — filters, slices, aggregations, date_buckets, sort — applied on each run: when the user asks to export numbers they saw in a query, copy those parameters verbatim from that query so the report matches what they saw. Google Sheets: a new Google Sheet is created automatically (an external Google Drive side effect) with its file and sheet named after `name`, and linked to the report; pass spreadsheet_id to add the report as a sheet of an existing spreadsheet instead, so several related exports share one document. Looker Studio is pull-based, never runs through this tool, and accepts no name; omit run_immediately or set it false. Email, Slack, Microsoft Teams, Google Chat: requires message; the default initial run sends it to the configured recipients or channels.';
+    description = 'Create an OWOX report that exports a data mart to an existing destination (create one with add_destination if the project has none — check list_destinations first). Use when the user wants a refreshable export or delivery to Google Sheets, email, Slack, Microsoft Teams, Google Chat, or Looker Studio. Create one report per user request, then change it with update_report when the user asks to add a filter, sort, aggregation, or rename it — do not create another report for the same data: the tool refuses a report whose fields duplicate one you already created on this data mart and destination (error_code similar_report_exists). For push destinations, the new report runs immediately by default: this starts one billed Report Run and delivers data, then initial_run returns the run_id to poll with get_report_run_status. Set run_immediately=false only when the user explicitly wants to create configuration without delivering data, such as before adding a schedule. Every destination type accepts the same optional output controls as query_data_mart — filters, slices, aggregations, date_buckets, sort — applied on each run: when the user asks to export numbers they saw in a query, copy those parameters verbatim from that query so the report matches what they saw. Google Sheets: a new Google Sheet is created automatically (an external Google Drive side effect) with its file and sheet named after `name`, and linked to the report; pass spreadsheet_id to add the report as a sheet of an existing spreadsheet instead, so several related exports share one document. Looker Studio is pull-based, never runs through this tool, and accepts no name; omit run_immediately or set it false. Email, Slack, Microsoft Teams, Google Chat: requires message; the default initial run sends it to the configured recipients or channels.';
     zodSchema = exports.addReportInputSchema.shape;
     outputSchema = {
         report_id: zod_v4_1.z.string(),
@@ -168,7 +168,7 @@ let AddReportTool = class AddReportTool {
     annotations = {
         title: 'Add Report',
         readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         openWorldHint: true,
     };
     requiredScopes = ['mcp:write'];

package/dist/src/ee/mcp/tools/context-input.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod-v4';
+export declare const contextIdsSchema: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodString>>, z.ZodTransform<string[] | undefined, string[] | undefined>>;
+export declare const makeContextSummariesSchema: () => z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>>;

package/dist/src/ee/mcp/tools/context-input.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeContextSummariesSchema = exports.contextIdsSchema = void 0;
+const zod_v4_1 = require("zod-v4");
+exports.contextIdsSchema = zod_v4_1.z
+    .array(zod_v4_1.z.string().trim().min(1))
+    .max(100)
+    .optional()
+    .transform(ids => (ids?.length ? [...new Set(ids)] : undefined))
+    .describe('Optional context IDs from list_contexts in the connected project. Match any selected context. Omit or pass [] for no filter; existing resource access controls always apply.');
+const makeContextSummariesSchema = () => zod_v4_1.z.array(zod_v4_1.z.object({ id: zod_v4_1.z.string(), name: zod_v4_1.z.string() }));
+exports.makeContextSummariesSchema = makeContextSummariesSchema;
+//# sourceMappingURL=context-input.js.map

package/dist/src/ee/mcp/tools/create-report-run-schedule.tool.js

@@ -48,7 +48,7 @@ let CreateReportRunScheduleTool = class CreateReportRunScheduleTool {
         title: 'Create Report Run Schedule',
         readOnlyHint: false,
         destructiveHint: false,
-        openWorldHint: false,
+        openWorldHint: true,
     };
     requiredScopes = ['mcp:read', 'mcp:write'];
     constructor(facade, publicOriginService) {

package/dist/src/ee/mcp/tools/data-mart-catalog.tool.d.ts

@@ -1,3 +1,4 @@
+import { type McpContextsFacade } from '../../../data-marts/facades/mcp-contexts.facade';
 import { z } from 'zod-v4';
 import type { McpScope } from '@owox/idp-protocol';
 import { PublicOriginService } from '../../../common/config/public-origin.service';
@@ -6,6 +7,7 @@ import { type McpDataMartsFacade } from '../../../data-marts/facades/mcp-data-ma
 import type { McpAuthContext } from '../auth/mcp-auth-context';
 import { type McpToolDefinition, type McpToolResult } from './mcp-tool.definition';
 declare const inputSchema: z.ZodObject<{
+    context_ids: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodString>>, z.ZodTransform<string[] | undefined, string[] | undefined>>;
     status: z.ZodOptional<z.ZodEnum<{
         draft: "draft";
         published: "published";
@@ -16,9 +18,11 @@ export declare class ListDataMartsTool implements McpToolDefinition<ListDataMart
     private readonly dataMarts;
     private readonly publicOriginService;
     private readonly projectContext;
+    private readonly contexts;
     readonly name = "list_data_marts";
-    readonly description = "List data marts available to the current OWOX project member. Defaults to published data marts; use status=draft only to browse draft metadata, because other MCP data-mart tools accept published data marts only. Use only when the user explicitly asks to list or browse data marts; for a concrete analytical question use get_relevant_data_marts_by_prompt instead, and for open-ended orientation use summarize_data_catalog.";
+    readonly description = "List data marts available to the current OWOX project member. Defaults to published data marts; use status=draft only to browse draft metadata, because other MCP data-mart tools accept published data marts only. Use only when the user explicitly asks to list or browse data marts; for a concrete analytical question use get_relevant_data_marts_by_prompt instead, and for open-ended orientation use summarize_data_catalog. Use get_project_context \u2192 list_contexts to discover business goals, then pass context_ids to restrict discovery to any selected context; omission preserves project-wide discovery within your existing access. Responses include all attached context IDs and names.";
     readonly zodSchema: {
+        context_ids: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodString>>, z.ZodTransform<string[] | undefined, string[] | undefined>>;
         status: z.ZodOptional<z.ZodEnum<{
             draft: "draft";
             published: "published";
@@ -33,6 +37,10 @@ export declare class ListDataMartsTool implements McpToolDefinition<ListDataMart
             id: z.ZodString;
             title: z.ZodString;
             description: z.ZodString;
+            contexts: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strip>>;
             url: z.ZodString;
             status: z.ZodString;
             updated_at: z.ZodString;
@@ -62,7 +70,7 @@ export declare class ListDataMartsTool implements McpToolDefinition<ListDataMart
         openWorldHint: boolean;
     };
     readonly requiredScopes: McpScope[];
-    constructor(dataMarts: McpDataMartsFacade, publicOriginService: PublicOriginService, projectContext: McpProjectContextFacade);
+    constructor(dataMarts: McpDataMartsFacade, publicOriginService: PublicOriginService, projectContext: McpProjectContextFacade, contexts: McpContextsFacade);
     parseInput(input: unknown): ListDataMartsInput;
     handler(input: ListDataMartsInput, context: McpAuthContext): Promise<McpToolResult>;
     private gettingStartedFor;

package/dist/src/ee/mcp/tools/data-mart-catalog.tool.js

@@ -13,6 +13,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ListDataMartsTool = void 0;
+const context_input_1 = require("./context-input");
+const mcp_contexts_facade_1 = require("../../../data-marts/facades/mcp-contexts.facade");
 const common_1 = require("@nestjs/common");
 const zod_v4_1 = require("zod-v4");
 const public_origin_service_1 = require("../../../common/config/public-origin.service");
@@ -25,6 +27,7 @@ const mcp_project_summary_util_1 = require("./mcp-project-summary.util");
 const mcp_public_url_util_1 = require("./mcp-public-url.util");
 const inputSchema = zod_v4_1.z
     .object({
+    context_ids: context_input_1.contextIdsSchema,
     status: zod_v4_1.z
         .enum(['published', 'draft'])
         .optional()
@@ -35,8 +38,9 @@ let ListDataMartsTool = class ListDataMartsTool {
     dataMarts;
     publicOriginService;
     projectContext;
+    contexts;
     name = 'list_data_marts';
-    description = 'List data marts available to the current OWOX project member. Defaults to published data marts; use status=draft only to browse draft metadata, because other MCP data-mart tools accept published data marts only. Use only when the user explicitly asks to list or browse data marts; for a concrete analytical question use get_relevant_data_marts_by_prompt instead, and for open-ended orientation use summarize_data_catalog.';
+    description = 'List data marts available to the current OWOX project member. Defaults to published data marts; use status=draft only to browse draft metadata, because other MCP data-mart tools accept published data marts only. Use only when the user explicitly asks to list or browse data marts; for a concrete analytical question use get_relevant_data_marts_by_prompt instead, and for open-ended orientation use summarize_data_catalog. Use get_project_context → list_contexts to discover business goals, then pass context_ids to restrict discovery to any selected context; omission preserves project-wide discovery within your existing access. Responses include all attached context IDs and names.';
     zodSchema = inputSchema.shape;
     outputSchema = {
         project: zod_v4_1.z.object({ id: zod_v4_1.z.string(), title: zod_v4_1.z.string() }).optional(),
@@ -44,6 +48,7 @@ let ListDataMartsTool = class ListDataMartsTool {
             id: zod_v4_1.z.string(),
             title: zod_v4_1.z.string(),
             description: zod_v4_1.z.string(),
+            contexts: (0, context_input_1.makeContextSummariesSchema)(),
             url: zod_v4_1.z.string(),
             status: zod_v4_1.z.string(),
             updated_at: zod_v4_1.z.string(),
@@ -59,16 +64,19 @@ let ListDataMartsTool = class ListDataMartsTool {
         openWorldHint: false,
     };
     requiredScopes = ['mcp:read'];
-    constructor(dataMarts, publicOriginService, projectContext) {
+    constructor(dataMarts, publicOriginService, projectContext, contexts) {
         this.dataMarts = dataMarts;
         this.publicOriginService = publicOriginService;
         this.projectContext = projectContext;
+        this.contexts = contexts;
     }
     parseInput(input) {
         return inputSchema.parse(input);
     }
     async handler(input, context) {
         const parsed = this.parseInput(input);
+        if (parsed.context_ids)
+            await this.contexts.validateContextIds(context.projectId, parsed.context_ids);
         const status = parsed.status ?? 'published';
         const [result, projectContext] = await Promise.all([
             this.dataMarts.listDataMarts({
@@ -76,6 +84,7 @@ let ListDataMartsTool = class ListDataMartsTool {
                 userId: context.userId,
                 roles: context.roles,
                 status,
+                ...(parsed.context_ids ? { contextIds: parsed.context_ids } : {}),
             }),
             (0, mcp_project_summary_util_1.tryGetMcpProjectSummary)(this.projectContext, context),
         ]);
@@ -83,6 +92,7 @@ let ListDataMartsTool = class ListDataMartsTool {
         const gettingStarted = await this.gettingStartedFor(result.dataMarts.length, status, {
             publicOrigin,
             context,
+            filtered: !!parsed.context_ids,
         });
         const structuredContent = {
             ...(projectContext ? { project: projectContext } : {}),
@@ -92,17 +102,18 @@ let ListDataMartsTool = class ListDataMartsTool {
                 description: dataMart.description ?? '',
                 url: (0, mcp_public_url_util_1.joinPublicOrigin)(publicOrigin, (0, data_mart_ui_path_1.buildDataMartUiPath)(context.projectId, dataMart.id)),
                 status: dataMart.status,
+                contexts: dataMart.contexts ?? [],
                 updated_at: dataMart.updatedAt,
             })),
             ...(gettingStarted ? { getting_started: gettingStarted } : {}),
         };
         return (0, mcp_tool_definition_1.jsonToolResult)(structuredContent);
     }
-    async gettingStartedFor(listedCount, status, { publicOrigin, context }) {
+    async gettingStartedFor(listedCount, status, { publicOrigin, context, filtered, }) {
         if (listedCount > 0)
             return undefined;
         const deps = { dataMarts: this.dataMarts, publicOrigin };
-        return status === 'published'
+        return status === 'published' && !filtered
             ? (0, mcp_getting_started_util_1.buildGettingStarted)(deps, context)
             : (0, mcp_getting_started_util_1.resolveGettingStarted)(deps, context);
     }
@@ -112,6 +123,7 @@ exports.ListDataMartsTool = ListDataMartsTool = __decorate([
     (0, common_1.Injectable)(),
     __param(0, (0, common_1.Inject)(mcp_data_marts_facade_1.MCP_DATA_MARTS_FACADE)),
     __param(2, (0, common_1.Inject)(mcp_project_context_facade_1.MCP_PROJECT_CONTEXT_FACADE)),
-    __metadata("design:paramtypes", [Object, public_origin_service_1.PublicOriginService, Object])
+    __param(3, (0, common_1.Inject)(mcp_contexts_facade_1.MCP_CONTEXTS_FACADE)),
+    __metadata("design:paramtypes", [Object, public_origin_service_1.PublicOriginService, Object, Object])
 ], ListDataMartsTool);
 //# sourceMappingURL=data-mart-catalog.tool.js.map

package/dist/src/ee/mcp/tools/data-mart-details.tool.d.ts

@@ -16,7 +16,7 @@ export declare class GetDataMartDetailsTool implements McpToolDefinition<GetData
     private readonly dataMarts;
     private readonly publicOriginService;
     readonly name = "get_data_mart_details_by_id";
-    readonly description = "Get available details for a specific published OWOX Data Mart by data_mart_id, including its URL, native output fields, and (only on explicit request) joined_fields contributed by blended/joined data marts. Use detail_level=native by default: it avoids exposing irrelevant joined fields and keeps the response fast. Request detail_level=with_joined_fields only when the question truly needs a joined Data Mart. Use displayName for user-facing wording and copy name verbatim into query_data_mart. Each controllable field carries its type \"category\", and every field carries the effective \"allowedAggregations\" query_data_mart may apply to it; \"operators_by_category\" maps each category to the filter/slice operators its fields accept \u2014 build queries from these instead of guessing. An empty allowedAggregations on a field whose \"calculated\" level is \"metric\" means the value is ALREADY computed, not that the field is unusable: select it by name in query_data_mart instead of recomputing it from other fields, and read the \"usage\" note carried on that field \u2014 it may also warn that a join distorts the number. Array fields are the exception: when mode is REPEATED or type or sliceType is ARRAY, the field omits category and has empty allowedAggregations. It may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. This tool is optional in the discovery flow: get_relevant_data_marts_by_prompt finds relevant Data Marts, and this tool adds field-level metadata for a selected Data Mart. It does not return data owners, data freshness, sample values, or actual data rows.";
+    readonly description = "Get available details for a specific published OWOX Data Mart by data_mart_id, including its URL, attached context IDs and names, native output fields, and (only on explicit request) joined_fields contributed by blended/joined data marts. Use detail_level=native by default: it avoids exposing irrelevant joined fields and keeps the response fast. Request detail_level=with_joined_fields only when the question truly needs a joined Data Mart. Use displayName for user-facing wording and copy name verbatim into query_data_mart. Each controllable field carries its type \"category\", and every field carries the effective \"allowedAggregations\" query_data_mart may apply to it; \"operators_by_category\" maps each category to the filter/slice operators its fields accept \u2014 build queries from these instead of guessing. An empty allowedAggregations on a field whose \"calculated\" level is \"metric\" means the value is ALREADY computed, not that the field is unusable: select it by name in query_data_mart instead of recomputing it from other fields, and read the \"usage\" note carried on that field \u2014 it may also warn that a join distorts the number. Array fields are the exception: when mode is REPEATED or type or sliceType is ARRAY, the field omits category and has empty allowedAggregations. It may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. Follow get_project_context \u2192 list_contexts \u2192 context-filtered Data Mart discovery. This tool is optional in that flow: get_relevant_data_marts_by_prompt finds relevant Data Marts, and this tool adds field-level metadata for a selected Data Mart. It does not return data owners, data freshness, sample values, or actual data rows.";
     readonly zodSchema: {
         data_mart_id: z.ZodString;
         detail_level: z.ZodOptional<z.ZodEnum<{
@@ -25,6 +25,10 @@ export declare class GetDataMartDetailsTool implements McpToolDefinition<GetData
         }>>;
     };
     readonly outputSchema: {
+        contexts: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>;
         id: z.ZodString;
         name: z.ZodString;
         url: z.ZodString;

package/dist/src/ee/mcp/tools/data-mart-details.tool.js

@@ -13,6 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GetDataMartDetailsTool = void 0;
+const context_input_1 = require("./context-input");
 const common_1 = require("@nestjs/common");
 const zod_v4_1 = require("zod-v4");
 const mcp_data_marts_facade_1 = require("../../../data-marts/facades/mcp-data-marts.facade");
@@ -129,9 +130,10 @@ let GetDataMartDetailsTool = class GetDataMartDetailsTool {
     dataMarts;
     publicOriginService;
     name = 'get_data_mart_details_by_id';
-    description = 'Get available details for a specific published OWOX Data Mart by data_mart_id, including its URL, native output fields, and (only on explicit request) joined_fields contributed by blended/joined data marts. Use detail_level=native by default: it avoids exposing irrelevant joined fields and keeps the response fast. Request detail_level=with_joined_fields only when the question truly needs a joined Data Mart. Use displayName for user-facing wording and copy name verbatim into query_data_mart. Each controllable field carries its type "category", and every field carries the effective "allowedAggregations" query_data_mart may apply to it; "operators_by_category" maps each category to the filter/slice operators its fields accept — build queries from these instead of guessing. An empty allowedAggregations on a field whose "calculated" level is "metric" means the value is ALREADY computed, not that the field is unusable: select it by name in query_data_mart instead of recomputing it from other fields, and read the "usage" note carried on that field — it may also warn that a join distorts the number. Array fields are the exception: when mode is REPEATED or type or sliceType is ARRAY, the field omits category and has empty allowedAggregations. It may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. This tool is optional in the discovery flow: get_relevant_data_marts_by_prompt finds relevant Data Marts, and this tool adds field-level metadata for a selected Data Mart. It does not return data owners, data freshness, sample values, or actual data rows.';
+    description = 'Get available details for a specific published OWOX Data Mart by data_mart_id, including its URL, attached context IDs and names, native output fields, and (only on explicit request) joined_fields contributed by blended/joined data marts. Use detail_level=native by default: it avoids exposing irrelevant joined fields and keeps the response fast. Request detail_level=with_joined_fields only when the question truly needs a joined Data Mart. Use displayName for user-facing wording and copy name verbatim into query_data_mart. Each controllable field carries its type "category", and every field carries the effective "allowedAggregations" query_data_mart may apply to it; "operators_by_category" maps each category to the filter/slice operators its fields accept — build queries from these instead of guessing. An empty allowedAggregations on a field whose "calculated" level is "metric" means the value is ALREADY computed, not that the field is unusable: select it by name in query_data_mart instead of recomputing it from other fields, and read the "usage" note carried on that field — it may also warn that a join distorts the number. Array fields are the exception: when mode is REPEATED or type or sliceType is ARRAY, the field omits category and has empty allowedAggregations. It may appear in fields, but never in filters, slices, sort, aggregations, or date_buckets. Follow get_project_context → list_contexts → context-filtered Data Mart discovery. This tool is optional in that flow: get_relevant_data_marts_by_prompt finds relevant Data Marts, and this tool adds field-level metadata for a selected Data Mart. It does not return data owners, data freshness, sample values, or actual data rows.';
     zodSchema = inputSchema.shape;
     outputSchema = {
+        contexts: (0, context_input_1.makeContextSummariesSchema)(),
         id: zod_v4_1.z.string().describe('Data mart identifier.'),
         name: zod_v4_1.z.string().describe('Data mart display name.'),
         url: zod_v4_1.z.string().describe('Open this Data Mart in OWOX.'),
@@ -190,6 +192,7 @@ let GetDataMartDetailsTool = class GetDataMartDetailsTool {
             operatorsByCategory[category] = (0, field_type_matrix_1.mcpOperatorsForCategory)(category);
         }
         const structuredContent = {
+            contexts: result.contexts ?? [],
             id: result.id,
             name: result.name,
             url: (0, mcp_public_url_util_1.joinPublicOrigin)(this.publicOriginService.getPublicOrigin(), (0, data_mart_ui_path_1.buildDataMartUiPath)(context.projectId, result.id)),

package/dist/src/ee/mcp/tools/get-report-output-schema.tool.js

@@ -26,10 +26,10 @@ let GetReportOutputSchemaTool = class GetReportOutputSchemaTool {
         '`revenue | SUM`, Unique Count, calculated fields), which appear in no data mart schema. ' +
         'Answers from the stored schema and the report config, so it reads no report data — the ' +
         "columns are as of the Data Mart's last schema actualization, so one added warehouse-side and " +
-        'not yet actualized is missing until a run or a data read picks it up. One ' +
-        'caveat behind the read-only hint: for a report that joins other data marts, resolving the ' +
-        "join refreshes each SQL-defined source's technical view, so a repeated call is not free on " +
-        'the warehouse.';
+        'not yet actualized is missing until a run or a data read picks it up. For a report that ' +
+        'joins other data marts, resolving the join may refresh SQL-defined source views in the ' +
+        'warehouse. This changes warehouse state and can incur warehouse costs even though the tool ' +
+        'does not return report data rows.';
     zodSchema = inputSchema.shape;
     outputSchema = {
         report_id: zod_v4_1.z.string(),
@@ -50,9 +50,9 @@ let GetReportOutputSchemaTool = class GetReportOutputSchemaTool {
     };
     annotations = {
         title: 'Get Report Output Schema',
-        readOnlyHint: true,
+        readOnlyHint: false,
         destructiveHint: false,
-        openWorldHint: false,
+        openWorldHint: true,
     };
     requiredScopes = ['mcp:read'];
     constructor(reports) {

package/dist/src/ee/mcp/tools/list-contexts.tool.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod-v4';
+import type { McpScope } from '@owox/idp-protocol';
+import { type McpContextsFacade } from '../../../data-marts/facades/mcp-contexts.facade';
+import type { McpAuthContext } from '../auth/mcp-auth-context';
+import { type McpToolDefinition } from './mcp-tool.definition';
+export declare class ListContextsTool implements McpToolDefinition<Record<string, never>> {
+    private readonly contexts;
+    readonly name = "list_contexts";
+    readonly description = "List business contexts in the connected OWOX project, including IDs, names and complete descriptions (null when missing). Discovery flow: get_project_context \u2192 list_contexts \u2192 list_data_marts or get_relevant_data_marts_by_prompt with context_ids \u2192 get_data_mart_details_by_id. Read descriptions for business goals and Markdown links to specific Data Marts. Listing a context or following a reference never grants access to its resources; all Data Mart tools enforce existing access controls.";
+    readonly zodSchema: {};
+    readonly outputSchema: {
+        contexts: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    };
+    readonly annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        openWorldHint: boolean;
+    };
+    readonly requiredScopes: McpScope[];
+    private readonly inputSchema;
+    constructor(contexts: McpContextsFacade);
+    handler(input: Record<string, never>, context: McpAuthContext): Promise<{
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/serverInfo"?: {
+                version: string;
+                name: string;
+                websiteUrl?: string | undefined;
+                description?: string | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "light" | "dark" | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            } | undefined;
+        } | undefined;
+        structuredContent?: unknown;
+        isError?: boolean | undefined;
+    }>;
+}

package/dist/src/ee/mcp/tools/list-contexts.tool.js

@@ -0,0 +1,50 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListContextsTool = void 0;
+const common_1 = require("@nestjs/common");
+const zod_v4_1 = require("zod-v4");
+const mcp_contexts_facade_1 = require("../../../data-marts/facades/mcp-contexts.facade");
+const mcp_tool_definition_1 = require("./mcp-tool.definition");
+let ListContextsTool = class ListContextsTool {
+    contexts;
+    name = 'list_contexts';
+    description = 'List business contexts in the connected OWOX project, including IDs, names and complete descriptions (null when missing). Discovery flow: get_project_context → list_contexts → list_data_marts or get_relevant_data_marts_by_prompt with context_ids → get_data_mart_details_by_id. Read descriptions for business goals and Markdown links to specific Data Marts. Listing a context or following a reference never grants access to its resources; all Data Mart tools enforce existing access controls.';
+    zodSchema = {};
+    outputSchema = {
+        contexts: zod_v4_1.z.array(zod_v4_1.z.object({ id: zod_v4_1.z.string(), name: zod_v4_1.z.string(), description: zod_v4_1.z.string().nullable() })),
+    };
+    annotations = {
+        title: 'List Project Contexts',
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+    };
+    requiredScopes = ['mcp:read'];
+    inputSchema = zod_v4_1.z.object({}).strict();
+    constructor(contexts) {
+        this.contexts = contexts;
+    }
+    async handler(input, context) {
+        this.inputSchema.parse(input);
+        return (0, mcp_tool_definition_1.jsonToolResult)({ contexts: await this.contexts.listContexts(context.projectId) });
+    }
+};
+exports.ListContextsTool = ListContextsTool;
+exports.ListContextsTool = ListContextsTool = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(mcp_contexts_facade_1.MCP_CONTEXTS_FACADE)),
+    __metadata("design:paramtypes", [Object])
+], ListContextsTool);
+//# sourceMappingURL=list-contexts.tool.js.map

package/dist/src/ee/mcp/tools/mcp-getting-started.util.js

@@ -96,11 +96,11 @@ function buildInstructions(canCreate, draftCount) {
     if (draftCount > 0) {
         parts.push(`The user can see ${draftCount} draft Data Mart(s) listed in draft_data_marts; name them with their url. Drafts are not available through MCP until they are ${canCreate
             ? 'opened in the OWOX Data Marts web app, finished, and published.'
-            : 'published by a Project Admin or a Technical User.'}`);
+            : 'published by a Project Admin or a Data Owner.'}`);
     }
     parts.push(canCreate
         ? 'The user can create Data Marts. Walk them through the steps: 1) open create_data_mart_url in the OWOX Data Marts web app; 2) connect a data source or define the Data Mart from SQL, a table, or a view on a connected storage; 3) save and publish it. Share create_data_mart_url and the matching guide from guides.'
-        : 'The user role (Business User) cannot create Data Marts. Advise them to ask a Project Admin or a Technical User of this project to create and publish a Data Mart and share it with them for reporting. Share data_marts_url and guides.core_concepts so they can pass them on.', 'Once a published Data Mart is available, the user can simply ask again. Do not retry discovery tools with different wording, and do not call query_data_mart or any report or schedule tool until then.');
+        : 'The user role (Business User) cannot create Data Marts. Advise them to ask a Project Admin or a Data Owner of this project to create and publish a Data Mart and share it with them for reporting. Share data_marts_url and guides.core_concepts so they can pass them on.', 'Once a published Data Mart is available, the user can simply ask again. Do not retry discovery tools with different wording, and do not call query_data_mart or any report or schedule tool until then.');
     return parts.join(' ');
 }
 //# sourceMappingURL=mcp-getting-started.util.js.map

package/dist/src/ee/mcp/tools/mcp-tool.providers.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MCP_TOOL_DEFINITIONS_PROVIDER = exports.MCP_TOOL_PROVIDER_CLASSES = void 0;
+const list_contexts_tool_1 = require("./list-contexts.tool");
 const create_report_run_schedule_tool_1 = require("./create-report-run-schedule.tool");
 const add_report_tool_1 = require("./add-report.tool");
 const data_mart_catalog_tool_1 = require("./data-mart-catalog.tool");
@@ -23,6 +24,7 @@ const update_report_run_schedule_tool_1 = require("./update-report-run-schedule.
 const update_report_tool_1 = require("./update-report.tool");
 const add_destination_tool_1 = require("./add-destination.tool");
 exports.MCP_TOOL_PROVIDER_CLASSES = [
+    list_contexts_tool_1.ListContextsTool,
     summarize_data_catalog_tool_1.SummarizeDataCatalogTool,
     data_mart_catalog_tool_1.ListDataMartsTool,
     search_data_marts_tool_1.SearchDataMartsTool,

package/dist/src/ee/mcp/tools/query-data-mart.tool.js

@@ -155,7 +155,7 @@ If truncated is true, not all matching rows were returned: narrow the query (few
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
-        openWorldHint: false,
+        openWorldHint: true,
     };
     requiredScopes = ['mcp:read', 'mcp:write'];
     constructor(dataMarts, cls, publicOriginService) {

package/dist/src/ee/mcp/tools/run-report.tool.js

@@ -34,7 +34,7 @@ let RunReportTool = class RunReportTool {
     annotations = {
         title: 'Run Report',
         readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true,
     };