@sap-ux/fiori-mcp-server 0.0.4 → 0.0.6

package/dist/server.d.ts

@@ -14,6 +14,10 @@ export declare class FioriFunctionalityServer {
      * Logs MCP errors and handles the SIGINT signal for graceful shutdown.
      */
     private setupErrorHandling;
+    /**
+     * Sets up telemetry.
+     */
+    private setupTelemetry;
     /**
      * Sets up handlers for various MCP tools.
      * Configures handlers for listing tools, and calling specific Fiori functionality tools.

package/dist/server.js

@@ -10,6 +10,7 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const package_json_1 = __importDefault(require("../package.json"));
 const tools_1 = require("./tools");
+const telemetry_1 = require("./telemetry");
 /**
  * Sets up and manages an MCP (Model Context Protocol) server that provides Fiori-related tools.
  */
@@ -42,6 +43,12 @@ class FioriFunctionalityServer {
             process.exit(0);
         });
     }
+    /**
+     * Sets up telemetry.
+     */
+    async setupTelemetry() {
+        await telemetry_1.TelemetryHelper.initTelemetrySettings();
+    }
     /**
      * Sets up handlers for various MCP tools.
      * Configures handlers for listing tools, and calling specific Fiori functionality tools.
@@ -56,22 +63,30 @@ class FioriFunctionalityServer {
             const { name, arguments: args } = request.params;
             try {
                 let result;
+                telemetry_1.TelemetryHelper.markToolStartTime();
+                const telemetryProperties = {
+                    tool: name,
+                    functionalityId: args?.functionalityId
+                };
                 switch (name) {
                     case 'list-fiori-apps':
                         result = await (0, tools_1.listFioriApps)(args);
-                        return this.convertResultToCallToolResult(result);
+                        break;
                     case 'list-functionality':
                         result = await (0, tools_1.listFunctionalities)(args);
-                        return this.convertResultToCallToolResult(result);
+                        break;
                     case 'get-functionality-details':
                         result = await (0, tools_1.getFunctionalityDetails)(args);
-                        return this.convertResultToCallToolResult(result);
+                        break;
                     case 'execute-functionality':
                         result = await (0, tools_1.executeFunctionality)(args);
-                        return this.convertResultToCallToolResult(result);
+                        break;
                     default:
+                        await telemetry_1.TelemetryHelper.sendTelemetry(telemetry_1.unknownTool, telemetryProperties, args?.appPath);
                         throw new Error(`Unknown tool: ${name}. Try one of: list-fiori-apps, list-functionality, get-functionality-details, execute-functionality.`);
                 }
+                await telemetry_1.TelemetryHelper.sendTelemetry(name, telemetryProperties, args?.appPath);
+                return this.convertResultToCallToolResult(result);
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
@@ -113,6 +128,7 @@ class FioriFunctionalityServer {
     async run() {
         const transport = new stdio_js_1.StdioServerTransport();
         await this.server.connect(transport);
+        await this.setupTelemetry();
         console.error('Fiori Functionality MCP Server running on stdio');
     }
 }

package/dist/telemetry/index.d.ts

@@ -0,0 +1,68 @@
+import { type TelemetryProperties, type ToolsSuiteTelemetryInitSettings } from '@sap-ux/telemetry';
+export declare const mcpServerName = "@sap-ux/fiori-mcp-server";
+export declare const unknownTool = "unknown-tool";
+export interface TelemetryData {
+    [key: string]: string;
+}
+/**
+ * Helper class for intialising and preparing event data for telemetry.
+ */
+export declare abstract class TelemetryHelper {
+    private static _telemetryData;
+    private static _previousEventTimestamp;
+    /**
+     * Returns the telemetry data.
+     *
+     * @returns telemetry data
+     */
+    static get telemetryData(): TelemetryData;
+    /**
+     * Load telemetry settings.
+     *
+     * @param options - tools suite telemetry init settings
+     */
+    static initTelemetrySettings(options?: ToolsSuiteTelemetryInitSettings): Promise<void>;
+    /**
+     * Creates telemetry data and adds default telemetry props.
+     *
+     * @param additionalData - set additional properties to be reported by telemetry
+     * @param filterDups - filters duplicates by returning undefined if it's suspected to be a repeated event based on previous telemetry data & timestamp (1 second)
+     * @returns telemetry data
+     */
+    static createTelemetryData<T extends TelemetryProperties>(additionalData?: Partial<T>, filterDups?: boolean): TelemetryData | undefined;
+    /**
+     * Prepares the telemetry event by calculating the generation time if a mark name is provided.
+     *
+     * @param telemetryEventName - The name of the telemetry event
+     * @param telemetryData - The telemetry data
+     * @returns The prepared telemetry event
+     */
+    private static prepareTelemetryEvent;
+    /**
+     * Marks the start time. Example usage:
+     * At the start of the MCP tool calling phase.
+     * It should not be updated everytime calling createTelemetryData().
+     */
+    static markToolStartTime(): void;
+    /**
+     * Marks the end time. Example usage:
+     * At the end of the writing phase of the MCP tool calling phase.
+     */
+    static markToolsEndTime(): void;
+    /**
+     * Sends the telemetry event to the telemetry client.
+     *
+     * @param telemetryEventName - the event name to be reported
+     * @param telemetryData - the telemetry data
+     * @param appPath - the path of the application
+     * @returns - a promise that resolves when the event is sent
+     */
+    static sendTelemetry(telemetryEventName: string, telemetryData: TelemetryData, appPath?: string): Promise<void>;
+    /**
+     * Gets the telemetry name of the module.
+     *
+     * @returns The module telemetry name.
+     */
+    static getTelemetryName(): string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -0,0 +1,146 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryHelper = exports.unknownTool = exports.mcpServerName = void 0;
+const telemetry_1 = require("@sap-ux/telemetry");
+const feature_toggle_1 = require("@sap-ux/feature-toggle");
+const btp_utils_1 = require("@sap-ux/btp-utils");
+const os_name_1 = __importDefault(require("os-name"));
+const i18next_1 = __importDefault(require("i18next"));
+const package_json_1 = require("../../package.json");
+exports.mcpServerName = '@sap-ux/fiori-mcp-server';
+exports.unknownTool = 'unknown-tool';
+const resourceId = '0a65e45d-6bf4-421d-b845-61e888c50e9e';
+/**
+ * Helper class for intialising and preparing event data for telemetry.
+ */
+class TelemetryHelper {
+    static _telemetryData;
+    static _previousEventTimestamp;
+    /**
+     * Returns the telemetry data.
+     *
+     * @returns telemetry data
+     */
+    static get telemetryData() {
+        return this._telemetryData;
+    }
+    /**
+     * Load telemetry settings.
+     *
+     * @param options - tools suite telemetry init settings
+     */
+    static async initTelemetrySettings(options) {
+        const telemetryOptions = {
+            consumerModule: {
+                name: exports.mcpServerName,
+                version: package_json_1.version
+            },
+            watchTelemetrySettingStore: false,
+            internalFeature: (0, feature_toggle_1.isInternalFeaturesSettingEnabled)(),
+            resourceId,
+            ...options
+        };
+        await (0, telemetry_1.initTelemetrySettings)(telemetryOptions);
+    }
+    /**
+     * Creates telemetry data and adds default telemetry props.
+     *
+     * @param additionalData - set additional properties to be reported by telemetry
+     * @param filterDups - filters duplicates by returning undefined if it's suspected to be a repeated event based on previous telemetry data & timestamp (1 second)
+     * @returns telemetry data
+     */
+    static createTelemetryData(additionalData, filterDups = false) {
+        const currentTimestamp = new Date().getTime();
+        if (!this._previousEventTimestamp) {
+            filterDups = false; // can't filter duplicates if no previous event timestamp
+            this._previousEventTimestamp = currentTimestamp;
+        }
+        if (!this._telemetryData) {
+            let osVersionName = i18next_1.default.t('telemetry.unknownOs');
+            try {
+                osVersionName = (0, os_name_1.default)();
+            }
+            catch {
+                // no matched os name, possible beta or unreleased version
+            }
+            this._telemetryData = {
+                Platform: (0, btp_utils_1.isAppStudio)() ? 'SBAS' : 'VSCode',
+                OperatingSystem: osVersionName
+            };
+        }
+        if (filterDups) {
+            const newTelemData = { ...this._telemetryData, ...additionalData };
+            if (Math.abs(this._previousEventTimestamp - currentTimestamp) < 1000 &&
+                JSON.stringify(newTelemData) === JSON.stringify(this._telemetryData)) {
+                return undefined;
+            }
+        }
+        this._previousEventTimestamp = currentTimestamp;
+        this._telemetryData = Object.assign(this._telemetryData, additionalData);
+        return this._telemetryData;
+    }
+    /**
+     * Prepares the telemetry event by calculating the generation time if a mark name is provided.
+     *
+     * @param telemetryEventName - The name of the telemetry event
+     * @param telemetryData - The telemetry data
+     * @returns The prepared telemetry event
+     */
+    static prepareTelemetryEvent(telemetryEventName, telemetryData) {
+        // Make sure performance measurement end is called
+        this.markToolsEndTime();
+        const requestTime = telemetryData.markName
+            ? telemetry_1.PerformanceMeasurementAPI.getMeasurementDuration(telemetryData.markName)
+            : undefined;
+        return {
+            eventName: telemetryEventName,
+            properties: telemetryData,
+            measurements: requestTime ? { RequestTime: requestTime } : {}
+        };
+    }
+    /**
+     * Marks the start time. Example usage:
+     * At the start of the MCP tool calling phase.
+     * It should not be updated everytime calling createTelemetryData().
+     */
+    static markToolStartTime() {
+        this.createTelemetryData({
+            markName: telemetry_1.PerformanceMeasurementAPI.startMark('MCP_LOADING_TIME')
+        });
+    }
+    /**
+     * Marks the end time. Example usage:
+     * At the end of the writing phase of the MCP tool calling phase.
+     */
+    static markToolsEndTime() {
+        if (this._telemetryData?.markName) {
+            telemetry_1.PerformanceMeasurementAPI.endMark(this._telemetryData.markName);
+            telemetry_1.PerformanceMeasurementAPI.measure(this._telemetryData.markName);
+        }
+    }
+    /**
+     * Sends the telemetry event to the telemetry client.
+     *
+     * @param telemetryEventName - the event name to be reported
+     * @param telemetryData - the telemetry data
+     * @param appPath - the path of the application
+     * @returns - a promise that resolves when the event is sent
+     */
+    static async sendTelemetry(telemetryEventName, telemetryData, appPath) {
+        const telemetryEvent = this.prepareTelemetryEvent(telemetryEventName, telemetryData);
+        await telemetry_1.ClientFactory.getTelemetryClient().reportEvent(telemetryEvent, telemetry_1.SampleRate.NoSampling, appPath ? { appPath } : undefined);
+    }
+    /**
+     * Gets the telemetry name of the module.
+     *
+     * @returns The module telemetry name.
+     */
+    static getTelemetryName() {
+        return exports.mcpServerName;
+    }
+}
+exports.TelemetryHelper = TelemetryHelper;
+//# sourceMappingURL=index.js.map

package/dist/tools/execute-functionality.d.ts

@@ -1,4 +1,4 @@
-import type { ExecuteFunctionalitiesInput, ExecuteFunctionalityOutput } from '../types';
+import type { ExecuteFunctionalityInput, ExecuteFunctionalityOutput } from '../types';
 import { PageEditorApi } from '../page-editor-api';
 /**
  * Executes a functionality based on the provided parameters.
@@ -7,7 +7,7 @@ import { PageEditorApi } from '../page-editor-api';
  * @returns A promise that resolves to the execution output
  * @throws Error if required parameters are missing
  */
-export declare function executeFunctionality(params: ExecuteFunctionalitiesInput): Promise<ExecuteFunctionalityOutput>;
+export declare function executeFunctionality(params: ExecuteFunctionalityInput): Promise<ExecuteFunctionalityOutput>;
 /**
  * Retrieves the PageEditorApi instance for the given application path and page name.
  *

package/dist/tools/functionalities/functionalities.d.ts

@@ -1,4 +1,61 @@
 import type { FunctionalityHandlers } from '../../types';
-export declare const FUNCTIONALITIES_DETAILS: import("../../types").GetFunctionalityDetailsOutput[];
+export declare const FUNCTIONALITIES_DETAILS: {
+    functionalityId: string | (string | number)[];
+    name: string;
+    description: string;
+    parameters: {
+        id: string;
+        type: "string" | "number" | "boolean" | "object" | "array";
+        name?: string | undefined;
+        required?: boolean | undefined;
+        description?: string | undefined;
+        defaultValue?: unknown;
+        options?: (string | number | boolean | null)[] | undefined;
+        currentValue?: unknown;
+        examples?: string[] | undefined;
+        pattern?: string | undefined;
+        parameters?: {
+            id: string;
+            type: "string" | "number" | "boolean" | "object" | "array";
+            name?: string | undefined;
+            required?: boolean | undefined;
+            description?: string | undefined;
+            defaultValue?: unknown;
+            options?: (string | number | boolean | null)[] | undefined;
+            currentValue?: unknown;
+            examples?: string[] | undefined;
+            pattern?: string | undefined;
+            parameters?: {
+                id: string;
+                type: "string" | "number" | "boolean" | "object" | "array";
+                name?: string | undefined;
+                required?: boolean | undefined;
+                description?: string | undefined;
+                defaultValue?: unknown;
+                options?: (string | number | boolean | null)[] | undefined;
+                currentValue?: unknown;
+                examples?: string[] | undefined;
+                pattern?: string | undefined;
+                parameters?: {
+                    id: string;
+                    type: "string" | "number" | "boolean" | "object" | "array";
+                    name?: string | undefined;
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    defaultValue?: unknown;
+                    options?: (string | number | boolean | null)[] | undefined;
+                    currentValue?: unknown;
+                    examples?: string[] | undefined;
+                    pattern?: string | undefined;
+                }[] | undefined;
+            }[] | undefined;
+        }[] | undefined;
+    }[];
+    technicalDescription?: string | undefined;
+    prerequisites?: string[] | undefined;
+    impact?: string | undefined;
+    examples?: string[] | undefined;
+    pageName?: string | undefined;
+}[];
 export declare const FUNCTIONALITIES_HANDLERS: Map<string, FunctionalityHandlers>;
 //# sourceMappingURL=functionalities.d.ts.map

package/dist/tools/functionalities/generate-fiori-ui-app/command.d.ts

@@ -1,9 +1,9 @@
-import type { ExecuteFunctionalitiesInput, ExecuteFunctionalityOutput } from '../../../types';
+import type { ExecuteFunctionalityInput, ExecuteFunctionalityOutput } from '../../../types';
 /**
  * Method to generate fiori app.
  *
  * @param params Input parameters for application generation.
  * @returns Application generation execution output.
  */
-export declare function command(params: ExecuteFunctionalitiesInput): Promise<ExecuteFunctionalityOutput>;
+export declare function command(params: ExecuteFunctionalityInput): Promise<ExecuteFunctionalityOutput>;
 //# sourceMappingURL=command.d.ts.map

package/dist/tools/get-functionality-details.js

@@ -54,7 +54,7 @@ function getParameters(properties) {
             currentValue: property.value
         };
         if (property.options) {
-            parameter.options = property.options.map((option) => option.key);
+            parameter.options = property.options.map((option) => option.key ?? null);
         }
         if (property.properties) {
             parameter.parameters = getParameters(property.properties);

package/dist/tools/index.js

@@ -1,8 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tools = exports.executeFunctionality = exports.getFunctionalityDetails = exports.listFunctionalities = exports.listFioriApps = void 0;
-const output_schema_1 = require("./output-schema");
-const input_schema_1 = require("./input-schema");
+const Input = __importStar(require("../types/input"));
+const Output = __importStar(require("../types/output"));
+const utils_1 = require("./utils");
 var list_fiori_apps_1 = require("./list-fiori-apps");
 Object.defineProperty(exports, "listFioriApps", { enumerable: true, get: function () { return list_fiori_apps_1.listFioriApps; } });
 var list_functionalities_1 = require("./list-functionalities");
@@ -18,8 +52,8 @@ exports.tools = [
                     This is an optional, preliminary tool.
                     **Use this first ONLY if the target application's name or path is not already known.**
                     The output can be used to ask the user for clarification before starting the main 3-step workflow.`,
-        inputSchema: input_schema_1.listFioriAppsInputSchema,
-        outputSchema: output_schema_1.listFioriAppsOutputSchema
+        inputSchema: (0, utils_1.convertToSchema)(Input.ListFioriAppsInputSchema),
+        outputSchema: (0, utils_1.convertToSchema)(Output.ListFioriAppsOutputSchema)
     },
     {
         name: 'list-functionality',
@@ -30,8 +64,8 @@ exports.tools = [
                     You MUST not use a functionalityId as name of a tool.
                     Do not guess, assume, or use any functionality not present in this list, as it is invalid and will cause the operation to fail.
                     **Note: If the target application is not known, use the list-fiori-apps tool first to identify it.**`,
-        inputSchema: input_schema_1.listFunctionalityInputSchema,
-        outputSchema: output_schema_1.listFunctionalityOutputSchema
+        inputSchema: (0, utils_1.convertToSchema)(Input.ListFunctionalitiesInputSchema),
+        outputSchema: (0, utils_1.convertToSchema)(Output.ListFunctionalitiesOutputSchema)
     },
     {
         name: 'get-functionality-details',
@@ -39,8 +73,8 @@ exports.tools = [
                     Gets the required parameters and detailed information for a specific functionality to create a new or modify an existing SAP Fiori application.
                     You MUST provide a functionalityId obtained from 'list-functionality' (Step 1).
                     The output of this tool is required for the final step 'execute-functionality' (Step 3).`,
-        inputSchema: input_schema_1.getFunctionalityDetailsInputSchema,
-        outputSchema: output_schema_1.getFunctionalityDetailsOutputSchema
+        inputSchema: (0, utils_1.convertToSchema)(Input.GetFunctionalityDetailsInputSchema),
+        outputSchema: (0, utils_1.convertToSchema)(Output.GetFunctionalityDetailsOutputSchema)
     },
     {
         name: 'execute-functionality',
@@ -48,8 +82,8 @@ exports.tools = [
                     Executes a specific functionality to create a new or modify an existing SAP Fiori application with provided parameters.
                     This is the **final step** of the workflow and performs the actual creation or modification.
                     You MUST provide the exact parameter information obtained from get-functionality-details (Step 2).`,
-        inputSchema: input_schema_1.executeFunctionalityInputSchema,
-        outputSchema: output_schema_1.executeFunctionalityOutputSchema
+        inputSchema: (0, utils_1.convertToSchema)(Input.ExecuteFunctionalityInputSchema),
+        outputSchema: (0, utils_1.convertToSchema)(Output.ExecuteFunctionalityOutputSchema)
     }
 ];
 //# sourceMappingURL=index.js.map

package/dist/tools/utils.d.ts

@@ -1,3 +1,4 @@
+import * as zod from 'zod';
 import type { Appdetails } from '../types';
 /**
  * Resolves the application details from a given path.
@@ -13,4 +14,13 @@ export declare function resolveApplication(path: string): Promise<Appdetails | u
  * @returns The relative path for the extension folder, or undefined if the directory type is not recognized.
  */
 export declare const getDefaultExtensionFolder: (directory: string) => string | undefined;
+/**
+ * Converts a Zod schema into a JSON Schema object.
+ * Additionally function removes the `$schema` property (if present),
+ * since it is unnecessary for mcp server.
+ *
+ * @param schema - A Zod schema instance to be converted.
+ * @returns A JSON Schema object representing the given Zod schema.
+ */
+export declare const convertToSchema: (schema: zod.ZodType) => zod.core.JSONSchema.JSONSchema;
 //# sourceMappingURL=utils.d.ts.map

package/dist/tools/utils.js

@@ -1,9 +1,43 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDefaultExtensionFolder = void 0;
+exports.convertToSchema = exports.getDefaultExtensionFolder = void 0;
 exports.resolveApplication = resolveApplication;
 const project_access_1 = require("@sap-ux/project-access");
 const path_1 = require("path");
+const zod = __importStar(require("zod"));
 /**
  * Resolves the application details from a given path.
  *
@@ -71,4 +105,18 @@ const getDefaultExtensionFolder = (directory) => {
     return subFolder;
 };
 exports.getDefaultExtensionFolder = getDefaultExtensionFolder;
+/**
+ * Converts a Zod schema into a JSON Schema object.
+ * Additionally function removes the `$schema` property (if present),
+ * since it is unnecessary for mcp server.
+ *
+ * @param schema - A Zod schema instance to be converted.
+ * @returns A JSON Schema object representing the given Zod schema.
+ */
+const convertToSchema = (schema) => {
+    const jsonSchema = zod.toJSONSchema(schema);
+    delete jsonSchema.$schema;
+    return jsonSchema;
+};
+exports.convertToSchema = convertToSchema;
 //# sourceMappingURL=utils.js.map