@mashroom/mashroom-mcp-server 3.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) nonblocking.at gmbh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+
+# Mashroom MCP Server
+
+Plugin for [Mashroom Server](https://www.mashroom-server.com), a **Microfrontend Integration Platform**.
+
+A minimal MCP plugin that allows agents to register new Portal Apps (Microfrontends) and to place them on pages.
+
+## Usage
+
+If *node_modules/@mashroom* is configured as a plugin path, add **@mashroom/mashroom-mcp-server** as *dependency*.
+
+The MCP server will be available under *http://localhost:5050/mcp*.
+
+> [!WARNING]
+> The MCP server currently has no security whatsoever, so don't install in on production servers.
+> Also, the route /mcp must be accessible without authentication.
+
+Check out the documentation of your coding agent how to register an MCP server:
+
+ * Claude Code: https://code.claude.com/docs/en/mcp-quickstart
+ * Codex: https://learn.chatgpt.com/docs/extend/mcp?surface=cli
+ * VSC: https://code.visualstudio.com/docs/agent-customization/mcp-servers
+ * JetBrains Junie: https://junie.jetbrains.com/docs/junie-plugin-mcp-settings.html
+
+Example conversations:
+
+![Example1](./examples/example1.png)
+
+![Example2](./examples/example2.png)
+

package/dist/dev-server.js

@@ -0,0 +1,45 @@
+"use strict";
+
+var _express = _interopRequireDefault(require("express"));
+var _mcpApi = _interopRequireDefault(require("./mcp-api"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const start = async () => {
+  const app = (0, _express.default)();
+
+  // Disable CORS
+  app.use((req, res, next) => {
+    res.header('Access-Control-Allow-Origin', '*');
+    res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept, MCP-Protocol-Version');
+    next();
+  });
+
+  // Dummy services
+  app.use((req, res, next) => {
+    const pluginContext = {
+      loggerFactory: () => console,
+      services: {
+        core: {},
+        portal: {
+          service: {
+            getSites: async () => {
+              return [];
+            },
+            getSite: async siteId => {
+              return null;
+            }
+          }
+        }
+      }
+    };
+    req.pluginContext = pluginContext;
+    next();
+  });
+  app.use('/mcp', _mcpApi.default);
+  app.listen(5099, () => {
+    console.log('MCP Server started on http://localhost:5099/mcp');
+  });
+  app.once('error', error => {
+    console.error('Failed to start server!', error);
+  });
+};
+start();

package/dist/mashroom-bootstrap.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _mcpApi = _interopRequireDefault(require("./mcp-api"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const bootstrap = async () => {
+  return _mcpApi.default;
+};
+var _default = exports.default = bootstrap;

package/dist/mcp-api.js

@@ -0,0 +1,63 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+var _express = require("express");
+var _bodyParser = _interopRequireDefault(require("body-parser"));
+var _mcpServer = _interopRequireDefault(require("./mcp-server"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const router = (0, _express.Router)();
+router.use(_bodyParser.default.json());
+router.post('/', async (req, res) => {
+  const logger = req.pluginContext.loggerFactory('mashroom.mcp');
+  logger.debug('Received MCP request:', req.body);
+  try {
+    const server = (0, _mcpServer.default)(req);
+    const transport = new _streamableHttp.StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+    res.on('close', () => {
+      logger.debug('Close MCP request');
+      transport.close();
+      server.close();
+    });
+  } catch (error) {
+    logger.error('Error handling MCP request:', error);
+    if (!res.headersSent) {
+      res.status(500).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32603,
+          message: 'Internal server error'
+        },
+        id: null
+      });
+    }
+  }
+});
+router.get('/', async (req, res) => {
+  res.writeHead(405).end(JSON.stringify({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not allowed.'
+    },
+    id: null
+  }));
+});
+router.delete('/', async (req, res) => {
+  res.writeHead(405).end(JSON.stringify({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not allowed.'
+    },
+    id: null
+  }));
+});
+var _default = exports.default = router;

package/dist/mcp-server.js

@@ -0,0 +1,108 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var z = _interopRequireWildcard(require("zod/v4"));
+var _listPortalSites = _interopRequireDefault(require("./tools/sites/list-portal-sites"));
+var _listPortalPages = _interopRequireDefault(require("./tools/pages/list-portal-pages"));
+var _serverInfo = _interopRequireDefault(require("./tools/server-info"));
+var _portalPageDetails = _interopRequireDefault(require("./tools/pages/portal-page-details"));
+var _listRegisteredPortalApps = _interopRequireDefault(require("./tools/apps/list-registered-portal-apps"));
+var _registerRemotePortalApp = _interopRequireDefault(require("./tools/apps/register-remote-portal-app"));
+var _unregisterRemotePortalApp = _interopRequireDefault(require("./tools/apps/unregister-remote-portal-app"));
+var _addPortalAppToPage = _interopRequireDefault(require("./tools/apps/add-portal-app-to-page"));
+var _removePortalAppFromPage = _interopRequireDefault(require("./tools/apps/remove-portal-app-from-page"));
+var _movePortalAppOnPage = _interopRequireDefault(require("./tools/apps/move-portal-app-on-page"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+var _default = req => {
+  const server = new _mcp.McpServer({
+    name: 'mashroom-mcp-server',
+    version: '1.0.0',
+    websiteUrl: 'https://www.mashroom-server.com'
+  }, {
+    capabilities: {
+      logging: {}
+    }
+  });
+  server.registerTool('server-info', {
+    title: 'Mashroom Server Info Tool',
+    description: 'Mashroom Server info such as version and default language',
+    inputSchema: {}
+  }, (0, _serverInfo.default)(req.pluginContext));
+  server.registerTool('list-portal-sites', {
+    title: 'List Portal Sites Tool',
+    description: 'List all sites configured in Mashroom Portal',
+    inputSchema: {}
+  }, (0, _listPortalSites.default)(req));
+  server.registerTool('list-portal-pages', {
+    title: 'List Portal Pages Tool',
+    description: 'List all configured pages in Mashroom Portal',
+    inputSchema: {
+      siteId: z.string().optional().describe('Filter pages by Site ID (optional)')
+    }
+  }, (0, _listPortalPages.default)(req));
+  server.registerTool('portal-page-details', {
+    title: 'Portal Page Details Tool',
+    description: 'Details for a given Page',
+    inputSchema: {
+      pageId: z.string().describe('The Page ID')
+    }
+  }, (0, _portalPageDetails.default)(req));
+  server.registerTool('list-registered-portal-apps', {
+    title: 'List Registered Portal Apps Tool',
+    description: 'List all Apps currently registered in Mashroom Portal',
+    inputSchema: {}
+  }, (0, _listRegisteredPortalApps.default)(req));
+  server.registerTool('register-remote-portal-app', {
+    title: 'Register Remote Portal App Tool',
+    description: 'Register a remote App running on some server with Mashroom Portal',
+    inputSchema: {
+      url: z.string().describe('The full URL of the remote App'),
+      waitFor: z.number().optional().describe('Number of seconds to wait for a successful registration (optional, default: 20)')
+    }
+  }, (0, _registerRemotePortalApp.default)(req));
+  server.registerTool('unregister-remote-portal-app', {
+    title: 'Unregister Remote Portal App Tool',
+    description: 'Unregister a remote App registered with Mashroom Portal',
+    inputSchema: {
+      url: z.string().describe('The full URL of the remote App')
+    }
+  }, (0, _unregisterRemotePortalApp.default)(req));
+  server.registerTool('add-portal-app-to-page', {
+    title: 'Add Portal App to Page Tool',
+    description: 'Add an already registered App to a specific Page and area',
+    inputSchema: {
+      appName: z.string().describe('The App name'),
+      pageId: z.string().describe('The Page ID'),
+      areaId: z.string().describe('The Area ID'),
+      position: z.number().optional().describe('The position within the Area (optional, default: 0)'),
+      overrideAppConfig: z.object({}).optional().describe('Override the App config (optional)')
+    }
+  }, (0, _addPortalAppToPage.default)(req));
+  server.registerTool('remove-portal-app-from-page', {
+    title: 'Remove Portal App from Page Tool',
+    description: 'Remove an existing App instance from a Page',
+    inputSchema: {
+      appName: z.string().describe('The App name'),
+      appInstanceId: z.string().describe('The App Instance ID'),
+      pageId: z.string().describe('The Page ID')
+    }
+  }, (0, _removePortalAppFromPage.default)(req));
+  server.registerTool('move-portal-app-on-page', {
+    title: 'Move Portal App on Page Tool',
+    description: 'Move an existing App instance to a different area or position on a Page',
+    inputSchema: {
+      appName: z.string().describe('The App name'),
+      appInstanceId: z.string().describe('The App Instance ID'),
+      pageId: z.string().describe('The Page ID'),
+      newAreaId: z.string().describe('The new Area ID'),
+      newPosition: z.number().optional().describe('The new position within the Area (optional, default: 0)')
+    }
+  }, (0, _movePortalAppOnPage.default)(req));
+  return server;
+};
+exports.default = _default;

package/dist/tools/apps/add-portal-app-to-page.js

@@ -0,0 +1,82 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("../utils");
+var _default = req => async ({
+  appName,
+  pageId,
+  areaId,
+  position = 0,
+  overrideAppConfig = {}
+}) => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const portalService = services.portal.service;
+  const securityService = services.security.service;
+  logger.info('Executing add-portal-app-to-page');
+  const page = await portalService.getPage(pageId);
+  if (!page) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: No page with ID "${pageId}" found.`
+      }]
+    };
+  }
+  const {
+    site,
+    pageRef
+  } = await (0, _utils.determineSiteAndPageRef)(pageId, pluginContext);
+  const serverUrl = (0, _utils.determineServerUrl)(req);
+  const pageUrl = `${serverUrl}${site?.path}${pageRef?.friendlyUrl}`;
+  const portalApp = portalService.getPortalApps().find(a => a.name === appName);
+  if (!portalApp) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: No Portal App with name "${appName}" found.`
+      }]
+    };
+  }
+  const portalAppInstance = {
+    pluginName: appName,
+    instanceId: crypto.randomUUID()
+  };
+  const actualPos = (0, _utils.insertAppInstance)(page, portalAppInstance, areaId, position);
+  await portalService.updatePage(page);
+  const appConfig = {
+    ...(portalApp.defaultAppConfig ?? {}),
+    ...(overrideAppConfig ?? {})
+  };
+  const appInstance = {
+    ...portalAppInstance,
+    appConfig
+  };
+  await portalService.insertPortalAppInstance(appInstance);
+  if (portalApp.defaultRestrictViewToRoles && Array.isArray(portalApp.defaultRestrictViewToRoles) && portalApp.defaultRestrictViewToRoles.length > 0) {
+    await securityService.updateResourcePermission(req, {
+      type: 'Portal-App',
+      key: (0, _utils.getPortalAppResourceKey)(appName, appInstance.instanceId),
+      permissions: [{
+        permissions: ['View'],
+        roles: portalApp.defaultRestrictViewToRoles || []
+      }]
+    });
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: `Success: Portal App "${appName}" added to page "${pageId}" at position ${actualPos} in area "${areaId}. App Instance ID: ${appInstance.instanceId}. Full page URL: ${pageUrl}`
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/apps/list-registered-portal-apps.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("../utils");
+var _default = req => async () => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const pluginService = services.core.pluginService;
+  logger.info('Executing list-registered-portal-apps');
+  const apps = pluginService.getPlugins().filter(p => p.type === 'portal-app2' || p.type === 'portal-app');
+  const pluginPackages = pluginService.getPotentialPluginPackages();
+  const lines = apps.map((a, idx) => {
+    const {
+      config,
+      type,
+      pluginDefinition
+    } = a;
+    const {
+      defaultConfig
+    } = a.pluginDefinition;
+    const fullConfig = {
+      ...defaultConfig,
+      ...config
+    };
+    const version = type === 'portal-app2' ? 2 : 1;
+    const title = version === 2 ? fullConfig.title : pluginDefinition.title;
+    const category = version === 2 ? fullConfig.category : pluginDefinition.category;
+    const description = fullConfig.description || pluginDefinition.description;
+    let source = a.pluginPackage.pluginPackageUrl.toString();
+    if (pluginPackages.find(pp => pp.url.toString() === source)?.scannerName === 'Mashroom Remote Package Scanner Kubernetes') {
+      source += ' (Kubernetes)';
+    }
+    return `${idx + 1}. Name: ${a.name}, Title: ${(0, _utils.serializeI18NString)(title, pluginContext)}, Description: ${(0, _utils.serializeI18NString)(description, pluginContext)}, Category: ${category}, Source: ${source}, Status: ${a.status}, config: ${JSON.stringify(fullConfig)}`;
+  });
+  return {
+    content: [{
+      type: 'text',
+      text: `
+Registered Portal Apps (${lines.length}):
+
+${lines.join('\n')}
+                `
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/apps/move-portal-app-on-page.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("../utils");
+var _default = req => async ({
+  appName,
+  appInstanceId,
+  pageId,
+  newAreaId,
+  newPosition = 0
+}) => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const portalService = services.portal.service;
+  logger.info('Executing move-portal-app-on-page');
+  const page = await portalService.getPage(pageId);
+  if (!page) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: No page with ID "${pageId}" found.`
+      }]
+    };
+  }
+  const areaId = Object.keys(page.portalApps ?? {}).find(areaId => page.portalApps?.[areaId]?.some(app => app.instanceId === appInstanceId));
+  let portalAppInstancePosition = -1;
+  if (areaId) {
+    portalAppInstancePosition = page.portalApps[areaId].findIndex(app => app.instanceId === appInstanceId);
+  }
+  if (portalAppInstancePosition === -1) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: No Instance of Portal App ${appName} IO "${appInstanceId}" found.`
+      }]
+    };
+  }
+  const portalAppInstance = page.portalApps[areaId].splice(portalAppInstancePosition, 1)[0];
+  const actualPos = (0, _utils.insertAppInstance)(page, portalAppInstance, newAreaId, newPosition);
+  await portalService.updatePage(page);
+  return {
+    content: [{
+      type: 'text',
+      text: `Success: Portal App "${appName}" with Instance ID ${appInstanceId} moved to position ${actualPos} in area "${newAreaId}"`
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/apps/register-remote-portal-app.js

@@ -0,0 +1,97 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("../utils");
+const WAIT_FOR_REGISTRATION_SUCCESS_SEC_DEFAULT = 20;
+var _default = req => async ({
+  url,
+  waitForSec = WAIT_FOR_REGISTRATION_SUCCESS_SEC_DEFAULT
+}) => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const remoteScannerService = services.remotePackageScanner?.service;
+  logger.info('Executing register-remote-portal-app');
+  if (!remoteScannerService) {
+    return {
+      content: [{
+        type: 'text',
+        text: 'Error: This tool only works if the plugin @mashroom/mashroom-remote-package-scanner is installed.'
+      }]
+    };
+  }
+  let targetURL;
+  try {
+    targetURL = new URL(url);
+  } catch (e) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: Invalid url ${url}. Error: ${e.message}.`
+      }]
+    };
+  }
+  if (!targetURL.protocol.startsWith('http')) {
+    return {
+      content: [{
+        type: 'text',
+        text: 'Error: Invalid protocol, only http and https supported!'
+      }]
+    };
+  }
+
+  // Check if the package is already registered
+  const alreadyRegisteredPackage = (0, _utils.findPluginPackage)(targetURL, pluginContext);
+  if (alreadyRegisteredPackage) {
+    let statusText = alreadyRegisteredPackage.foundPlugins?.length ? `the following Apps have been found: ${alreadyRegisteredPackage.foundPlugins.join(', ')}` : 'no Apps have been found';
+    if (alreadyRegisteredPackage.updateErrors?.length) {
+      statusText += ` and the following errors occurred: ${alreadyRegisteredPackage.updateErrors.join(', ')}`;
+    }
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: The URL ${url} is already registered and ${statusText}.`
+      }]
+    };
+  }
+  try {
+    const start = Date.now();
+    await remoteScannerService.addOrUpdatePackageUrl(req, new URL(url));
+    let newlyRegisteredPluginPackage;
+    while (!newlyRegisteredPluginPackage?.foundPlugins?.length && Date.now() - start < waitForSec * 1000) {
+      newlyRegisteredPluginPackage = (0, _utils.findPluginPackage)(targetURL, pluginContext);
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    if (newlyRegisteredPluginPackage?.foundPlugins?.length) {
+      return {
+        content: [{
+          type: 'text',
+          text: `Success. The following new Apps have been registered: ${newlyRegisteredPluginPackage.foundPlugins.join(', ')}`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: 'text',
+          text: `Error: No new Apps registered on URL ${url} after ${waitForSec} seconds!`
+        }]
+      };
+    }
+  } catch (e) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: Registering the URL failed with: ${e.message}`
+      }]
+    };
+  }
+};
+exports.default = _default;

package/dist/tools/apps/remove-portal-app-from-page.js

@@ -0,0 +1,54 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _default = req => async ({
+  appName,
+  appInstanceId,
+  pageId
+}) => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const portalService = services.portal.service;
+  logger.info('Executing remove-portal-app-from-page');
+  const page = await portalService.getPage(pageId);
+  if (!page) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: No page with ID "${pageId}" found.`
+      }]
+    };
+  }
+  const areaId = Object.keys(page.portalApps ?? {}).find(areaId => page.portalApps?.[areaId]?.some(app => app.instanceId === appInstanceId));
+  let portalAppInstancePosition = -1;
+  if (areaId) {
+    portalAppInstancePosition = page.portalApps[areaId].findIndex(app => app.instanceId === appInstanceId);
+  }
+  if (portalAppInstancePosition === -1) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: No Instance of Portal App ${appName} IO "${appInstanceId}" found.`
+      }]
+    };
+  }
+  page.portalApps[areaId].splice(portalAppInstancePosition, 1);
+  await portalService.updatePage(page);
+  await portalService.deletePortalAppInstance(req, appName, appInstanceId);
+  return {
+    content: [{
+      type: 'text',
+      text: `Success: Portal App Instance "${appInstanceId}" removed from page "${pageId}"`
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/apps/unregister-remote-portal-app.js

@@ -0,0 +1,67 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("../utils");
+var _default = req => async ({
+  url
+}) => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const remoteScannerService = services.remotePackageScanner?.service;
+  logger.info('Executing unregister-remote-portal-app');
+  if (!remoteScannerService) {
+    return {
+      content: [{
+        type: 'text',
+        text: 'Error: This tool only works if the plugin @mashroom/mashroom-remote-package-scanner is installed.'
+      }]
+    };
+  }
+  let targetURL;
+  try {
+    targetURL = new URL(url);
+  } catch (e) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: Invalid url ${url}. Error: ${e.message}.`
+      }]
+    };
+  }
+  if (!targetURL.protocol.startsWith('http')) {
+    return {
+      content: [{
+        type: 'text',
+        text: 'Error: Invalid protocol, only http and https supported!'
+      }]
+    };
+  }
+
+  // Check if the package is actually registered
+  const registeredPackage = (0, _utils.findPluginPackage)(targetURL, pluginContext);
+  if (!registeredPackage) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: The URL ${url} is not registered at the moment!`
+      }]
+    };
+  }
+  remoteScannerService.removePackageUrl(req, targetURL);
+  return {
+    content: [{
+      type: 'text',
+      text: `Success. The following Apps have been unregistered: ${registeredPackage.foundPlugins?.join(', ')}`
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/pages/list-portal-pages.js

@@ -0,0 +1,54 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("../utils");
+var _default = req => async ({
+  siteId
+}) => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const portalService = services.portal.service;
+  logger.info('Executing list-portal-pages with siteId:', siteId);
+  const serverUrl = (0, _utils.determineServerUrl)(req);
+  const sites = (await portalService.getSites()).filter(s => !siteId || s.siteId === siteId);
+  let lines = [];
+  for (const site of sites) {
+    const {
+      path: sitePath,
+      pages
+    } = site;
+    const allPages = [];
+    const addPages = async (page, parentPageId) => {
+      const fullUrl = `${serverUrl}${sitePath}${page.friendlyUrl}`;
+      allPages.push({
+        ...page,
+        parentPageId,
+        fullUrl
+      });
+      if (page.subPages) {
+        page.subPages.forEach(p => addPages(p, page.pageId));
+      }
+    };
+    pages.forEach(p => addPages(p, null));
+    const pageLines = allPages.map((p, idx) => `${idx + 1}. Page ID: ${p.pageId}, Parent Page ID: ${p.parentPageId ?? '(none)'}, Friendly URL: ${p.friendlyUrl}, Full URL: ${p.fullUrl}, Title: ${(0, _utils.serializeI18NString)(p.title, pluginContext)}, Number sub pages: ${p.subPages?.length ?? 0}, Hidden: ${p.hidden ? 'yes' : 'no'}`);
+    lines.push(`Site "${site.siteId}" pages (${allPages.length}):\n`);
+    lines.push(...pageLines);
+    lines.push('\n');
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: lines.join('\n')
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/pages/portal-page-details.js

@@ -0,0 +1,71 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _promises = require("fs/promises");
+var _utils = require("../utils");
+var _default = req => async ({
+  pageId
+}) => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const portalService = services.portal.service;
+  logger.info('Executing portal-page-details with pageId:', pageId);
+  const page = await portalService.getPage(pageId);
+  if (!page) {
+    return {
+      content: [{
+        type: 'text',
+        text: `No page with ID "${pageId}" found.`
+      }]
+    };
+  }
+  const {
+    site,
+    pageRef
+  } = await (0, _utils.determineSiteAndPageRef)(pageId, pluginContext);
+  const serverUrl = (0, _utils.determineServerUrl)(req);
+  const pageUrl = `${serverUrl}${site?.path}${pageRef?.friendlyUrl}`;
+  const layoutName = page.layout ?? site?.defaultLayout;
+  const layoutAreaIds = [];
+  if (layoutName) {
+    const layout = portalService.getLayouts().find(p => p.name === layoutName);
+    if (layout) {
+      try {
+        const layoutTemplate = await (0, _promises.readFile)(layout.layoutPath, {
+          encoding: 'utf-8'
+        });
+        Array.from(layoutTemplate.matchAll(/ id=["'](.+)["']/g)).forEach(match => layoutAreaIds.push(match[1]));
+      } catch (e) {
+        logger.warn(`Error reading layout file: ${layout.layoutPath}`, e);
+      }
+    }
+  }
+  const appLines = Object.keys(page.portalApps ?? {}).flatMap((areaCode, idx) => page.portalApps[areaCode].map(app => `${idx + 1}. Name: ${app.pluginName}, Instance ID: ${app.instanceId}, Area ID: ${areaCode}`));
+  return {
+    content: [{
+      type: 'text',
+      text: `
+Page "${pageId}" Details:
+
+Title: ${(0, _utils.serializeI18NString)(pageRef?.title, pluginContext)}
+Description: ${page.description}
+FriendlyUrl: ${pageRef?.friendlyUrl ?? '(none)'}
+Full URL: ${pageUrl}
+Layout: ${layoutName ?? '(none)'}
+Layout Area IDs: ${layoutAreaIds.join(', ')}
+Apps on the Page:
+    ${appLines.join('\n')}
+                `
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/server-info.js

@@ -0,0 +1,43 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _default = pluginContext => async () => {
+  const {
+    serverInfo,
+    serverConfig,
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const i18nService = services.i18n.service;
+  const defaultLanguage = i18nService.defaultLanguage;
+  const availableLanguages = i18nService.availableLanguages;
+  logger.info('Executing server-info');
+  return {
+    content: [{
+      type: 'text',
+      text: `
+                    Mashroom Server is a Microfrontend Integration Platform.
+
+                    Mashroom Portal is the component that can be used to build web pages consisting of multiple Microfrontends.
+
+                    The Microfrontends can be developed in any framework and can run remotely on a different server.
+
+                    Mashroom Portal is organized in Sites which can have multiple Pages which build a tree structure.
+
+                    Every Page has a configurable Layout with multiple areas where Microfrontends can be placed.
+
+                    Details about this Mashroom Server:
+
+                    Server Name: ${serverConfig.name}
+                    Server Version: ${serverInfo.version}
+                    Default language: ${defaultLanguage}
+                    Available languages: ${availableLanguages.join(', ')}
+                `
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/sites/list-portal-sites.js

@@ -0,0 +1,36 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("../utils");
+var _default = req => async () => {
+  const {
+    pluginContext
+  } = req;
+  const {
+    services,
+    loggerFactory
+  } = pluginContext;
+  const logger = loggerFactory('mashroom.mcp');
+  const portalService = services.portal.service;
+  logger.info('Executing list-portal-sites');
+  const sites = await portalService.getSites();
+  const serverUrl = (0, _utils.determineServerUrl)(req);
+  const lines = sites.map((s, idx) => {
+    const fullUrl = `${serverUrl}${s.path}`;
+    return `${idx + 1}. Site ID: ${s.siteId}, Path: ${s.path}, Full URL: ${fullUrl}, Title: ${(0, _utils.serializeI18NString)(s.title, pluginContext)}, Number pages: ${s.pages.length}, Default Theme: ${s.defaultTheme ?? '(none)'}, Default Layout: ${s.defaultLayout ?? '(none)'}`;
+  });
+  return {
+    content: [{
+      type: 'text',
+      text: `
+Sites (${sites.length}):
+
+${lines.join('\n')}
+                `
+    }]
+  };
+};
+exports.default = _default;

package/dist/tools/utils.js

@@ -0,0 +1,78 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.serializeI18NString = exports.insertAppInstance = exports.getPortalAppResourceKey = exports.findPluginPackage = exports.determineSiteAndPageRef = exports.determineServerUrl = void 0;
+const findPluginPackage = (url, pluginContext) => {
+  const pluginService = pluginContext.services.core.pluginService;
+  return pluginService.getPotentialPluginPackages().find(pp => pp.url.toString() === url.toString());
+};
+exports.findPluginPackage = findPluginPackage;
+const determinePortalBasePath = req => {
+  const portalPlugin = req.pluginContext.services.core.pluginService.getPlugins().find(p => p.name === 'Mashroom Portal WebApp');
+  if (portalPlugin) {
+    return portalPlugin.config?.path ?? '/portal';
+  }
+  return '/portal';
+};
+const determineServerUrl = req => {
+  const portalBasePath = determinePortalBasePath(req);
+  const forwardedHost = req.headers['x-forwarded-host'];
+  if (forwardedHost) {
+    const hostname = forwardedHost.split(',')[0];
+    const proto = req.headers['x-forwarded-proto']?.split(',')[0] ?? 'http';
+    const port = req.headers['x-forwarded-port']?.split(',')[0];
+    return `${proto}://${hostname}${port ? `:${port}` : ''}${portalBasePath}`;
+  }
+  return `http://${req.host}${portalBasePath}`;
+};
+exports.determineServerUrl = determineServerUrl;
+const determineSiteAndPageRef = async (pageId, pluginContext) => {
+  const portalService = pluginContext.services.portal.service;
+  const sites = await portalService.getSites();
+  let pageRef;
+  let site;
+  for (const s of sites) {
+    pageRef = await portalService.findPageRefByPageId(s, pageId);
+    if (pageRef) {
+      site = s;
+      break;
+    }
+  }
+  return {
+    site,
+    pageRef
+  };
+};
+exports.determineSiteAndPageRef = determineSiteAndPageRef;
+const insertAppInstance = (page, portalAppInstance, areaId, position) => {
+  page.portalApps = page.portalApps || {};
+  const areaAppInstances = page.portalApps[areaId] = page.portalApps[areaId] || [];
+  let actualPos = areaAppInstances.length;
+  if (typeof position === 'number' && position >= 0 && position < areaAppInstances.length) {
+    actualPos = position;
+  }
+  areaAppInstances.splice(actualPos, 0, portalAppInstance);
+  return actualPos;
+};
+exports.insertAppInstance = insertAppInstance;
+const getPortalAppResourceKey = (pluginName, instanceId) => {
+  return `${pluginName}_${instanceId || 'global'}`;
+};
+exports.getPortalAppResourceKey = getPortalAppResourceKey;
+const serializeI18NString = (i18nString, pluginContext) => {
+  if (!i18nString) {
+    return '';
+  }
+  if (typeof i18nString === 'string') {
+    return i18nString;
+  }
+  const i18nService = pluginContext.services.i18n.service;
+  const defaultLanguage = i18nService.defaultLanguage;
+  const defaultMessageKey = i18nString[defaultLanguage] ? defaultLanguage : Object.keys(i18nString)[0];
+  const defaultMessage = i18nString[defaultMessageKey];
+  const translations = Object.keys(i18nString).filter(lang => lang !== defaultLanguage).map(lang => `${lang}: ${i18nString[lang]}`).join(', ');
+  return `${defaultMessage} (Translations: ${translations})`;
+};
+exports.serializeI18NString = serializeI18NString;

package/mashroom.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "../../../node_modules/@mashroom/mashroom-json-schemas/schemas/mashroom-plugins.json",
+    "devModeBuildScript": "build",
+    "plugins": [
+        {
+            "name": "Mashroom MCP Server",
+            "type": "api",
+            "bootstrap": "./dist/mashroom-bootstrap.js",
+            "requires": [
+                "Mashroom Security Services",
+                "Mashroom Portal Services",
+                "Mashroom Internationalization Services"
+            ],
+            "defaultConfig": {
+                "path": "/mcp"
+            }
+        }
+    ]
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@mashroom/mashroom-mcp-server",
+    "description": "Mashroom MCP Server",
+    "homepage": "https://www.mashroom-server.com",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/nonblocking/mashroom.git"
+    },
+    "license": "MIT",
+    "version": "3.0.0-alpha.0",
+    "files": [
+        "dist/**",
+        "examples/**",
+        "mashroom.json"
+    ],
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "zod": "^4.4.3"
+    },
+    "devDependencies": {
+        "@mashroom/mashroom": "3.0.0-alpha.0",
+        "@mashroom/mashroom-i18n": "3.0.0-alpha.0",
+        "@mashroom/mashroom-portal": "3.0.0-alpha.0",
+        "@mashroom/mashroom-remote-package-scanner": "3.0.0-alpha.0"
+    },
+    "jest": {
+        "testEnvironment": "node",
+        "roots": [
+            "<rootDir>/test"
+        ],
+        "testRegex": "(\\.(test|spec))\\.ts",
+        "transform": {
+            "^.+\\.ts$": "ts-jest"
+        },
+        "reporters": [
+            "default",
+            "jest-junit"
+        ]
+    },
+    "jest-junit": {
+        "outputDirectory": "./test-reports"
+    },
+    "scripts": {
+        "lint": "eslint --fix",
+        "type-check": "tsc --noEmit",
+        "test": "jest",
+        "build": "babel src -d dist --extensions \".ts\"",
+        "dev": "nodemon --watch src --ext ts --exec \"npm run build && node dist/dev-server.js\"",
+        "inspector": "npx @modelcontextprotocol/inspector"
+    }
+}