@sap-ux/fiori-mcp-server 0.0.1

package/dist/page-editor-api/sapuxFtfsFileIO.d.ts

@@ -0,0 +1,84 @@
+import type { v4, ExportResults, PageConfig, File, GenerateCustomExtensionParams, Application, PageType } from '@sap/ux-specification/dist/types/src';
+import type { ApplicationAccess } from '@sap-ux/project-access';
+export interface PageData {
+    pageId: string;
+    config: PageConfig;
+    pageType: PageType;
+    schema: string;
+    entitySet?: string;
+    entityType?: string;
+    contextPath?: string;
+    page: v4.Page;
+}
+export interface AppData {
+    config: Application;
+    schema: string;
+}
+/**
+ * Class for handling file I/O operations for page editor.
+ * Mainly it uses specification to import(manifest->config/schema) or export(config->manifest).
+ */
+export declare class SapuxFtfsFileIO {
+    private readonly appAccess;
+    /**
+     * Creates an instance of SapuxFtfsFileIO.
+     *
+     * @param appAccess - The application access object
+     */
+    constructor(appAccess: ApplicationAccess);
+    /**
+     * Retrieves the Specification object.
+     *
+     * @returns A promise that resolves to a Specification object
+     */
+    private getSpecification;
+    /**
+     * Extracts the application ID from the manifest.
+     *
+     * @param manifest - The Manifest object
+     * @returns The application ID as a string
+     */
+    private getAppId;
+    /**
+     * Retrieves virtual files for the project.
+     *
+     * @returns A promise that resolves to an array of File objects
+     */
+    private getVirtualFiles;
+    /**
+     * Reads the application data.
+     *
+     * @param files - Optional array of File objects
+     * @returns A promise that resolves to an AppData object
+     */
+    readApp(files?: File[]): Promise<AppData>;
+    /**
+     * Get page data object using Project Provider.
+     *
+     * @param pageId - page id.
+     * @returns Promise to page data.
+     */
+    readPageData(pageId: string): Promise<PageData | undefined>;
+    /**
+     * Update content of the passed page.
+     *
+     * @param pageData Page data.
+     * @returns Result of export operation.
+     */
+    writePage(pageData: PageData): Promise<ExportResults | undefined>;
+    /**
+     * Writes the application data.
+     *
+     * @param appData - The AppData object to write
+     * @returns A promise that resolves to ExportResults or undefined
+     */
+    writeApp(appData: AppData): Promise<ExportResults | undefined>;
+    /**
+     * Writes FPM (Flexible Programming Model) data.
+     *
+     * @param params - The GenerateCustomExtensionParams object
+     * @returns A promise that resolves to an array of strings
+     */
+    writeFPM(params: GenerateCustomExtensionParams): Promise<string[]>;
+}
+//# sourceMappingURL=sapuxFtfsFileIO.d.ts.map

package/dist/page-editor-api/sapuxFtfsFileIO.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapuxFtfsFileIO = void 0;
+const src_1 = require("@sap/ux-specification/dist/types/src");
+const path_1 = require("path");
+const project_1 = require("./project");
+/**
+ * Class for handling file I/O operations for page editor.
+ * Mainly it uses specification to import(manifest->config/schema) or export(config->manifest).
+ */
+class SapuxFtfsFileIO {
+    appAccess;
+    /**
+     * Creates an instance of SapuxFtfsFileIO.
+     *
+     * @param appAccess - The application access object
+     */
+    constructor(appAccess) {
+        this.appAccess = appAccess;
+    }
+    /**
+     * Retrieves the Specification object.
+     *
+     * @returns A promise that resolves to a Specification object
+     */
+    async getSpecification() {
+        return this.appAccess.getSpecification();
+    }
+    /**
+     * Extracts the application ID from the manifest.
+     *
+     * @param manifest - The Manifest object
+     * @returns The application ID as a string
+     */
+    getAppId(manifest) {
+        return manifest['sap.app']?.id ?? '';
+    }
+    /**
+     * Retrieves virtual files for the project.
+     *
+     * @returns A promise that resolves to an array of File objects
+     */
+    async getVirtualFiles() {
+        const manifest = await (0, project_1.getManifest)(this.appAccess);
+        if (!manifest) {
+            return [];
+        }
+        const specification = await this.getSpecification();
+        const annotationData = await (0, project_1.readAnnotationFiles)(this.appAccess);
+        // Import project using specification API
+        return specification.importProject({
+            manifest: manifest,
+            annotations: annotationData
+        });
+    }
+    /**
+     * Reads the application data.
+     *
+     * @param files - Optional array of File objects
+     * @returns A promise that resolves to an AppData object
+     */
+    async readApp(files) {
+        files ??= await this.getVirtualFiles();
+        const appJson = files.find((file) => file.dataSourceUri === src_1.FileName.App);
+        const appConfig = JSON.parse(appJson?.fileContent ?? '{}');
+        const schemaPath = (0, path_1.join)('.schemas', (0, path_1.basename)((0, path_1.join)(appConfig?.$schema ?? '')));
+        const schemaFile = files.find((file) => (0, path_1.join)(file.dataSourceUri) === schemaPath);
+        if (schemaFile) {
+            const schema = JSON.parse(schemaFile.fileContent);
+            if (schema.properties?.settings) {
+                schema.properties.settings.isViewNode = true;
+            }
+            schemaFile.fileContent = JSON.stringify(schema);
+        }
+        return {
+            config: appConfig,
+            schema: schemaFile?.fileContent ?? '{}'
+        };
+    }
+    /**
+     * Get page data object using Project Provider.
+     *
+     * @param pageId - page id.
+     * @returns Promise to page data.
+     */
+    async readPageData(pageId) {
+        try {
+            const files = await this.getVirtualFiles();
+            const pagePath = (0, path_1.join)(src_1.DirName.Pages, `${pageId}.json`);
+            const pageFile = files.find((file) => (0, path_1.join)(file.dataSourceUri) === pagePath);
+            const pageConfig = pageFile?.fileContent ? JSON.parse(pageFile.fileContent) : undefined;
+            const schemaPath = (0, path_1.join)('.schemas', (0, path_1.basename)((0, path_1.join)(pageConfig?.$schema ?? '')));
+            const schema = files.find((file) => (0, path_1.join)(file.dataSourceUri) === schemaPath);
+            if (pageConfig && schema) {
+                const application = await this.readApp(files);
+                const page = application.config.pages?.[pageId];
+                if (page) {
+                    const pageType = page.pageType;
+                    return {
+                        pageId,
+                        pageType: pageType ?? src_1.PageTypeV4.ListReport,
+                        config: pageConfig,
+                        page: page,
+                        schema: schema.fileContent,
+                        entitySet: page.entitySet,
+                        entityType: 'entityType' in page && typeof page.entityType === 'string' ? page.entityType : undefined,
+                        contextPath: page.contextPath
+                    };
+                }
+            }
+        }
+        catch (error) {
+            console.log(String(error));
+        }
+        return undefined;
+    }
+    /**
+     * Update content of the passed page.
+     *
+     * @param pageData Page data.
+     * @returns Result of export operation.
+     */
+    async writePage(pageData) {
+        const manifest = await (0, project_1.getManifest)(this.appAccess);
+        if (!manifest) {
+            return;
+        }
+        const specification = await this.getSpecification();
+        const schemaType = pageData.pageType === src_1.PageTypeV4.ObjectPage ? src_1.SchemaType.ObjectPage : src_1.SchemaType.ListReport;
+        const params = {
+            [schemaType]: {
+                appId: this.getAppId(manifest),
+                jsonSchema: JSON.parse(pageData.schema),
+                manifest,
+                page: {
+                    ...pageData.page,
+                    name: pageData.pageId,
+                    config: pageData.config
+                }
+            }
+        };
+        const result = specification.exportConfig({
+            v4: params
+        });
+        if (result.manifestChangeIndicator === 'Updated') {
+            await this.appAccess.updateManifestJSON(result.manifest);
+        }
+        return result;
+    }
+    /**
+     * Writes the application data.
+     *
+     * @param appData - The AppData object to write
+     * @returns A promise that resolves to ExportResults or undefined
+     */
+    async writeApp(appData) {
+        const { config, schema } = appData;
+        const manifest = await (0, project_1.getManifest)(this.appAccess);
+        if (!manifest) {
+            return;
+        }
+        const specification = await this.getSpecification();
+        const params = {
+            [src_1.SchemaType.Application]: {
+                application: config,
+                manifest,
+                jsonSchema: JSON.parse(schema)
+            }
+        };
+        const result = specification.exportConfig({
+            v4: params
+        });
+        await this.appAccess.updateManifestJSON(result.manifest);
+        return result;
+    }
+    /**
+     * Writes FPM (Flexible Programming Model) data.
+     *
+     * @param params - The GenerateCustomExtensionParams object
+     * @returns A promise that resolves to an array of strings
+     */
+    async writeFPM(params) {
+        if (params.data) {
+            params.data.minUI5Version = await (0, project_1.getUI5Version)(this.appAccess);
+        }
+        const specification = await this.getSpecification();
+        const fsEditor = (await specification.generateCustomExtension(params));
+        await fsEditor.commit(() => {
+            //empty callback, do nothing.
+        });
+        return Object.keys(fsEditor.dump());
+    }
+}
+exports.SapuxFtfsFileIO = SapuxFtfsFileIO;
+//# sourceMappingURL=sapuxFtfsFileIO.js.map

package/dist/server.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Sets up and manages an MCP (Model Context Protocol) server that provides Fiori-related tools.
+ */
+export declare class FioriFunctionalityServer {
+    private readonly server;
+    /**
+     * Initializes a new instance of the FioriFunctionalityServer.
+     * Sets up the MCP server with Fiori functionality tools and error handling.
+     */
+    constructor();
+    /**
+     * Sets up error handling for the server.
+     * Logs MCP errors and handles the SIGINT signal for graceful shutdown.
+     */
+    private setupErrorHandling;
+    /**
+     * Sets up handlers for various MCP tools.
+     * Configures handlers for listing tools, and calling specific Fiori functionality tools.
+     */
+    private setupToolHandlers;
+    /**
+     * Converts the result of a tool execution to the CallToolResult format.
+     *
+     * @param result - The result to be converted.
+     * @returns The converted result in CallToolResult format.
+     */
+    private convertResultToCallToolResult;
+    /**
+     * Starts the FioriFunctionalityServer.
+     * Connects the server to a StdioServerTransport and begins listening for requests.
+     */
+    run(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FioriFunctionalityServer = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+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");
+/**
+ * Sets up and manages an MCP (Model Context Protocol) server that provides Fiori-related tools.
+ */
+class FioriFunctionalityServer {
+    server;
+    /**
+     * Initializes a new instance of the FioriFunctionalityServer.
+     * Sets up the MCP server with Fiori functionality tools and error handling.
+     */
+    constructor() {
+        this.server = new index_js_1.Server({
+            name: 'fiori-mcp',
+            version: package_json_1.default.version
+        }, {
+            capabilities: {
+                tools: {}
+            }
+        });
+        this.setupToolHandlers();
+        this.setupErrorHandling();
+    }
+    /**
+     * Sets up error handling for the server.
+     * Logs MCP errors and handles the SIGINT signal for graceful shutdown.
+     */
+    setupErrorHandling() {
+        this.server.onerror = (error) => console.error('[MCP Error]', error);
+        process.on('SIGINT', async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    /**
+     * Sets up handlers for various MCP tools.
+     * Configures handlers for listing tools, and calling specific Fiori functionality tools.
+     */
+    setupToolHandlers() {
+        this.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+            return {
+                tools: tools_1.tools
+            };
+        });
+        this.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                let result;
+                switch (name) {
+                    case 'list-fiori-apps':
+                        result = await (0, tools_1.listFioriApps)(args);
+                        return this.convertResultToCallToolResult(result);
+                    case 'list-functionality':
+                        result = await (0, tools_1.listFunctionalities)(args);
+                        return this.convertResultToCallToolResult(result);
+                    case 'get-functionality-details':
+                        result = await (0, tools_1.getFunctionalityDetails)(args);
+                        return this.convertResultToCallToolResult(result);
+                    case 'execute-functionality':
+                        result = await (0, tools_1.executeFunctionality)(args);
+                        return this.convertResultToCallToolResult(result);
+                    default:
+                        throw new Error(`Unknown tool: ${name}. Try one of: list-fiori-apps, list-functionality, get-functionality-details, execute-functionality.`);
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${errorMessage}`
+                        }
+                    ]
+                };
+            }
+        });
+    }
+    /**
+     * Converts the result of a tool execution to the CallToolResult format.
+     *
+     * @param result - The result to be converted.
+     * @returns The converted result in CallToolResult format.
+     */
+    convertResultToCallToolResult(result) {
+        const convertedResult = {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result)
+                }
+            ]
+        };
+        if (!Array.isArray(result)) {
+            convertedResult.structuredContent = result;
+        }
+        return convertedResult;
+    }
+    /**
+     * Starts the FioriFunctionalityServer.
+     * Connects the server to a StdioServerTransport and begins listening for requests.
+     */
+    async run() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Fiori Functionality MCP Server running on stdio');
+    }
+}
+exports.FioriFunctionalityServer = FioriFunctionalityServer;
+//# sourceMappingURL=server.js.map

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

@@ -0,0 +1,19 @@
+import type { ExecuteFunctionalitiesInput, ExecuteFunctionalityOutput } from '../types';
+import { PageEditorApi } from '../page-editor-api';
+/**
+ * Executes a functionality based on the provided parameters.
+ *
+ * @param params - Input parameters for executing the functionality
+ * @returns A promise that resolves to the execution output
+ * @throws Error if required parameters are missing
+ */
+export declare function executeFunctionality(params: ExecuteFunctionalitiesInput): Promise<ExecuteFunctionalityOutput>;
+/**
+ * Retrieves the PageEditorApi instance for the given application path and page name.
+ *
+ * @param appPath - Path to the application
+ * @param pageName - Optional name of the page
+ * @returns A promise that resolves to a PageEditorApi instance or undefined
+ */
+export declare function getEditorApi(appPath: string, pageName?: string): Promise<PageEditorApi | undefined>;
+//# sourceMappingURL=execute-functionality.d.ts.map

package/dist/tools/execute-functionality.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeFunctionality = executeFunctionality;
+exports.getEditorApi = getEditorApi;
+const get_functionality_details_1 = require("./get-functionality-details");
+const page_editor_api_1 = require("../page-editor-api");
+const functionalities_1 = require("./functionalities");
+const utils_1 = require("./utils");
+/**
+ * Executes a functionality based on the provided parameters.
+ *
+ * @param params - Input parameters for executing the functionality
+ * @returns A promise that resolves to the execution output
+ * @throws Error if required parameters are missing
+ */
+async function executeFunctionality(params) {
+    const { functionalityId, parameters, appPath } = params;
+    if (!functionalityId) {
+        throw new Error('functionalityId parameter is required');
+    }
+    if (!appPath) {
+        throw new Error('appPath parameter is required');
+    }
+    // Custom/external functionalities
+    const externalFunctionality = typeof functionalityId === 'string' ? functionalities_1.FUNCTIONALITIES_HANDLERS.get(functionalityId) : undefined;
+    if (externalFunctionality) {
+        return externalFunctionality.executeFunctionality(params);
+    }
+    // Get functionality details to validate parameters
+    const functionality = await (0, get_functionality_details_1.getFunctionalityDetails)({
+        appPath,
+        functionalityId
+    });
+    // Validate required parameters
+    const missingParams = functionality.parameters
+        .filter((param) => param.required && !(param.id in parameters))
+        .map((param) => param.name);
+    if (missingParams.length > 0) {
+        throw new Error(`Missing required parameters: ${missingParams.join(', ')}`);
+    }
+    const changes = await generateChanges(functionality, functionalityId, parameters, appPath, functionality.pageName);
+    let executionResult;
+    if (changes.length) {
+        // Mock execution - in a real implementation, this would modify the actual files
+        executionResult = {
+            functionalityId,
+            status: 'success',
+            message: `Successfully executed '${functionality.name}'`,
+            parameters,
+            appPath,
+            changes,
+            timestamp: new Date().toISOString()
+        };
+    }
+    else {
+        // No changes register
+        executionResult = {
+            functionalityId,
+            status: 'skipped',
+            message: `Execution of '${functionality.name}' did not trigger any change in files`,
+            parameters,
+            appPath,
+            changes,
+            timestamp: new Date().toISOString()
+        };
+    }
+    return executionResult;
+}
+/**
+ * Generates changes based on the functionality and parameters.
+ *
+ * @param functionality - Details of the functionality to be executed
+ * @param functionalityId - ID of the functionality
+ * @param parametersValue - Values for the parameters
+ * @param appPath - Path to the application
+ * @param pageName - Optional name of the page
+ * @returns A promise that resolves to an array of change descriptions
+ */
+async function generateChanges(functionality, functionalityId, parametersValue, appPath, pageName) {
+    const changes = [];
+    const editor = await getEditorApi(appPath, pageName);
+    if (!editor) {
+        return [];
+    }
+    const { propertyPath } = (0, get_functionality_details_1.resolveFunctionality)(functionalityId);
+    const changedParameterInfo = findParameterById(functionality, propertyPath[propertyPath.length - 1]);
+    let changed = false;
+    if (!changedParameterInfo && typeof parametersValue === 'object') {
+        // Parameters most likely in node parameters - edge case
+        for (const parameterValue in parametersValue) {
+            const paramPropertyPath = [...propertyPath, parameterValue];
+            const parameterInfo = findParameterById(functionality, parameterValue);
+            if (parameterInfo) {
+                await editor.changeProperty(paramPropertyPath, resolveParameterValue(paramPropertyPath, parametersValue, parameterInfo));
+                changed = true;
+                if (changes.length === 0) {
+                    changes.push('Modified webapp/manifest.json');
+                }
+            }
+        }
+    }
+    if (!changed) {
+        // Common way to change property - AI passes precise property id and parameters
+        await editor.changeProperty(propertyPath, resolveParameterValue(propertyPath, parametersValue, changedParameterInfo));
+        // problem -> result?.manifestChangeIndicator does not return changed indicator when we change fcl
+        changes.push('Modified webapp/manifest.json');
+    }
+    return changes;
+}
+/**
+ * Retrieves the PageEditorApi instance for the given application path and page name.
+ *
+ * @param appPath - Path to the application
+ * @param pageName - Optional name of the page
+ * @returns A promise that resolves to a PageEditorApi instance or undefined
+ */
+async function getEditorApi(appPath, pageName) {
+    const project = await (0, utils_1.resolveApplication)(appPath);
+    if (project?.applicationAccess) {
+        return new page_editor_api_1.PageEditorApi(project.applicationAccess, pageName);
+    }
+    return undefined;
+}
+/**
+ * Currently resolved values through params passed differently time to time by AI.
+ * This method tries to resolve value before applying/saving it.
+ *
+ * @param propertyPath - Path to the property
+ * @param parametersValue - Object containing parameter values
+ * @param parameterInfo - Optional information about the parameter
+ * @returns The resolved parameter value
+ */
+function resolveParameterValue(propertyPath, parametersValue, parameterInfo) {
+    const propertyName = propertyPath[propertyPath.length - 1];
+    if (parameterInfo?.type === 'object') {
+        let value = parametersValue;
+        if (propertyName in parametersValue) {
+            // Change property is part of parameters object
+            value = parametersValue[propertyName];
+        }
+        if (value === null || (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0)) {
+            // AI fails to pass undefined value, it is more stablew with null - currently workaround is to convert it to 'undefined'
+            // So far there is no valid property with value null - such transformation seems ok
+            value = undefined;
+        }
+        // Whole object is received as parameters
+        return value;
+    }
+    let value;
+    if (propertyName in parametersValue) {
+        // Change property is part of parameters object
+        value = parametersValue[propertyName];
+    }
+    else if ('value' in parametersValue) {
+        // Seems generic approach from AI - property named 'value' contains new value
+        value = parametersValue.value;
+    }
+    if (value === null) {
+        // AI fails to pass undefined value, it is more stablew with null - currently workaround is to convert it to 'undefined'
+        // So far there is no valid property with value null - such transformation seems ok
+        value = undefined;
+    }
+    return value;
+}
+/**
+ * Finds a parameter in the functionality details by its ID.
+ *
+ * @param functionality - Details of the functionality
+ * @param id - ID of the parameter to find
+ * @returns The found Parameter object or undefined if not found
+ */
+function findParameterById(functionality, id) {
+    return functionality.parameters.find((parameter) => parameter.id === id);
+}
+//# sourceMappingURL=execute-functionality.js.map

package/dist/tools/functionalities/controller-extension/index.d.ts

@@ -0,0 +1,4 @@
+import type { FunctionalityHandlers, GetFunctionalityDetailsOutput } from '../../../types';
+export declare const CREATE_CONTROLLER_EXTENSION_FUNCTIONALITY: GetFunctionalityDetailsOutput;
+export declare const createControllerExtensionHandlers: FunctionalityHandlers;
+//# sourceMappingURL=index.d.ts.map