refactor(pluggable-widgets-mcp): extract shared sandbox utility and add project context to startup

Extracts duplicated path-allowlist logic into shared isPathAllowed() in
sandbox.ts. Adds project directory logging on HTTP/STDIO startup and
exposes projectDir in /health endpoint for observability.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rahmanunver

packages/pluggable-widgets-mcp/src/server/http.ts

@@ -1,9 +1,22 @@
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import cors from "cors";
-import { PORT } from "@/config";
+import { MENDIX_PROJECT_DIR, PORT, validateProjectDir } from "@/config";
 import { setupRoutes } from "./routes";
 import { sessionManager } from "./session";
 
+async function logProjectConfig(): Promise<void> {
+    if (MENDIX_PROJECT_DIR) {
+        const validation = await validateProjectDir(MENDIX_PROJECT_DIR);
+        if (validation.valid) {
+            console.log(`[HTTP] Project: ${validation.projectName} (${MENDIX_PROJECT_DIR})`);
+        } else {
+            console.warn(`[HTTP] Warning: MENDIX_PROJECT_DIR is set but invalid: ${validation.error}`);
+        }
+    } else {
+        console.log(`[HTTP] No project configured (set MENDIX_PROJECT_DIR to enable deploy support)`);
+    }
+}
+
 /**
  * Starts the MCP server with HTTP/Streamable transport.
  * Supports multiple concurrent sessions via Express.
@@ -26,6 +39,7 @@ export function startHttpServer(): void {
         console.log(`[HTTP] MCP Server started on port ${PORT}`);
         console.log(`[HTTP] Health check: http://localhost:${PORT}/health`);
         console.log(`[HTTP] MCP endpoint: http://localhost:${PORT}/mcp`);
+        logProjectConfig();
     });
 
     const shutdown = async (): Promise<void> => {

packages/pluggable-widgets-mcp/src/server/routes.ts

@@ -1,6 +1,6 @@
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import type { Express, Request, Response } from "express";
-import { SERVER_NAME, SERVER_VERSION } from "@/config";
+import { MENDIX_PROJECT_DIR, SERVER_NAME, SERVER_VERSION } from "@/config";
 import { createMcpServer } from "./server";
 import { sessionManager } from "./session";
 
@@ -17,11 +17,14 @@ export function setupRoutes(app: Express): void {
  */
 function setupHealthRoute(app: Express): void {
     app.get("/health", (_req: Request, res: Response) => {
+        const projectDir = MENDIX_PROJECT_DIR ?? null;
         res.json({
             status: "ok",
             server: SERVER_NAME,
             version: SERVER_VERSION,
-            sessions: sessionManager.sessionCount
+            sessions: sessionManager.sessionCount,
+            projectDir,
+            widgetsDir: projectDir ? `${projectDir}/widgets` : null
         });
     });
 }

packages/pluggable-widgets-mcp/src/server/stdio.ts

@@ -1,6 +1,20 @@
+import { MENDIX_PROJECT_DIR, validateProjectDir } from "@/config";
 import { createMcpServer } from "./server";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+async function logProjectConfig(): Promise<void> {
+    if (MENDIX_PROJECT_DIR) {
+        const validation = await validateProjectDir(MENDIX_PROJECT_DIR);
+        if (validation.valid) {
+            console.error(`[STDIO] Project: ${validation.projectName} (${MENDIX_PROJECT_DIR})`);
+        } else {
+            console.error(`[STDIO] Warning: MENDIX_PROJECT_DIR is set but invalid: ${validation.error}`);
+        }
+    } else {
+        console.error(`[STDIO] No project configured (set MENDIX_PROJECT_DIR to enable deploy support)`);
+    }
+}
+
 /**
  * Starts the MCP server with STDIO transport.
  * Communicates via stdin/stdout for CLI-based MCP clients.
@@ -11,6 +25,7 @@ export async function startStdioServer(): Promise<void> {
 
     // Log to stderr since stdout is used for MCP communication
     console.error("[STDIO] Starting MCP server...");
+    await logProjectConfig();
 
     await server.connect(transport);
 

packages/pluggable-widgets-mcp/src/tools/build.tools.ts

@@ -5,8 +5,8 @@
 
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { spawn } from "node:child_process";
-import { existsSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { z } from "zod";
 import { GENERATIONS_DIR } from "@/config";
 import type { ToolContext, ToolResponse } from "./types";
@@ -17,6 +17,9 @@ import {
     createToolResponse,
     type StructuredError
 } from "./utils/response";
+import { findMpkFile } from "./utils/mpk";
+import { isPathAllowed } from "./utils/sandbox";
+import type { SessionState } from "./session-state";
 
 /**
  * Input schema for build-widget tool.
@@ -306,38 +309,14 @@ function toStructuredError(error: ParsedError): StructuredError {
     });
 }
 
-/**
- * Finds the most recently created MPK file in the widget's dist directory.
- */
-function findMpkFile(widgetPath: string): string | undefined {
-    const distPath = join(widgetPath, "dist");
-    if (!existsSync(distPath)) return undefined;
-
-    try {
-        // Search for .mpk files recursively (usually in dist/x.x.x/)
-        const searchDir = (dir: string): string | undefined => {
-            const entries = readdirSync(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                const fullPath = join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    const found = searchDir(fullPath);
-                    if (found) return found;
-                } else if (entry.name.endsWith(".mpk")) {
-                    return fullPath;
-                }
-            }
-            return undefined;
-        };
-        return searchDir(distPath);
-    } catch {
-        return undefined;
-    }
-}
-
 /**
  * Handler for the build-widget tool.
  */
-async function handleBuildWidget(args: BuildWidgetInput, context: ToolContext): Promise<ToolResponse> {
+async function handleBuildWidget(
+    args: BuildWidgetInput,
+    context: ToolContext,
+    state: SessionState
+): Promise<ToolResponse> {
     const { widgetPath } = args;
 
     // Validate path exists
@@ -350,18 +329,7 @@ async function handleBuildWidget(args: BuildWidgetInput, context: ToolContext):
     }
 
     // Validate path is within allowed directories
-    const resolvedWidgetPath = resolve(widgetPath);
-    const allowedBuildPaths = [
-        resolve(GENERATIONS_DIR),
-        ...(process.env.MCP_ALLOWED_BUILD_PATHS ?? "")
-            .split(":")
-            .filter(Boolean)
-            .map(p => resolve(p))
-    ];
-    const isAllowedPath = allowedBuildPaths.some(
-        allowed => resolvedWidgetPath.startsWith(allowed + "/") || resolvedWidgetPath === allowed
-    );
-    if (!isAllowedPath) {
+    if (!isPathAllowed(widgetPath, state, "MCP_ALLOWED_BUILD_PATHS")) {
         return createStructuredErrorResponse(
             createStructuredError("ERR_NOT_FOUND", `Widget path is not within an allowed directory: ${widgetPath}`, {
                 suggestion: `Widget must be within ${GENERATIONS_DIR} or set MCP_ALLOWED_BUILD_PATHS env var (colon-separated paths).`
@@ -447,7 +415,7 @@ async function handleBuildWidget(args: BuildWidgetInput, context: ToolContext):
 /**
  * Registers the build tools with the MCP server.
  */
-export function registerBuildTools(server: McpServer): void {
+export function registerBuildTools(server: McpServer, state: SessionState): void {
     server.registerTool(
         "build-widget",
         {
@@ -458,6 +426,6 @@ export function registerBuildTools(server: McpServer): void {
                 "Returns build errors if any, which can be used to fix issues.",
             inputSchema: buildWidgetSchema
         },
-        handleBuildWidget
+        (args, context) => handleBuildWidget(args, context, state)
     );
 }

packages/pluggable-widgets-mcp/src/tools/scaffolding.tools.ts

@@ -10,8 +10,10 @@ import {
     type ErrorCode
 } from "@/tools/utils/response";
 import { access, mkdir } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname } from "node:path";
 import { z } from "zod";
+import { isPathAllowed } from "./utils/sandbox";
+import type { SessionState } from "./session-state";
 
 /**
  * Schema for create-widget tool input.
@@ -22,7 +24,7 @@ const createWidgetSchema = widgetOptionsSchema.extend({
         .string()
         .optional()
         .describe(
-            "[OPTIONAL] Directory where widget will be created. Defaults to ./generations/ in the current working directory. For desktop clients without a clear working directory, ask the user for their preferred location."
+            "[OPTIONAL] Directory where widget will be created. Defaults to ./generations/ in the current working directory. Leave unset in most cases — the server manages the output location."
         )
 });
 
@@ -45,9 +47,11 @@ OPTIONAL (with defaults):
   • programmingLanguage: "typescript" or "javascript" (default: "${DEFAULT_WIDGET_OPTIONS.programmingLanguage}")
   • unitTests: Include Jest test setup (default: ${DEFAULT_WIDGET_OPTIONS.unitTests})
   • e2eTests: Include Playwright E2E tests (default: ${DEFAULT_WIDGET_OPTIONS.e2eTests})
-  • outputPath: Directory where widget will be created (default: ./generations/)
+  • outputPath: Directory where widget will be created (default: ./generations/). Leave unset in most cases.
 
-Ask the user if they want to customize any options before proceeding.`;
+Ask the user if they want to customize any options before proceeding.
+
+After scaffolding, use build-widget to compile, then deploy-widget to copy the .mpk to the Mendix project.`;
 
 /**
  * Registers scaffolding-related tools for widget creation and management.
@@ -60,36 +64,29 @@ Ask the user if they want to customize any options before proceeding.`;
  *
  * @see AGENTS.md Roadmap Context section for planned additions
  */
-export function registerScaffoldingTools(server: McpServer): void {
+export function registerScaffoldingTools(server: McpServer, state: SessionState): void {
     server.registerTool(
         "create-widget",
         {
             title: "Create Widget",
             description: CREATE_WIDGET_DESCRIPTION,
             inputSchema: createWidgetSchema
         },
-        handleCreateWidget
+        (args, context) => handleCreateWidget(args, context, state)
     );
 }
 
-async function handleCreateWidget(args: CreateWidgetInput, context: ToolContext): Promise<ToolResponse> {
+async function handleCreateWidget(
+    args: CreateWidgetInput,
+    context: ToolContext,
+    state: SessionState
+): Promise<ToolResponse> {
     const options = buildWidgetOptions(args);
     const outputDir = args.outputPath ?? GENERATIONS_DIR;
 
     // Validate user-provided outputPath is within allowed directories
     if (args.outputPath) {
-        const resolvedOutputPath = resolve(args.outputPath);
-        const allowedOutputPaths = [
-            resolve(GENERATIONS_DIR),
-            ...(process.env.MCP_ALLOWED_OUTPUT_PATHS ?? "")
-                .split(":")
-                .filter(Boolean)
-                .map(p => resolve(p))
-        ];
-        const isAllowedPath = allowedOutputPaths.some(
-            allowed => resolvedOutputPath.startsWith(allowed + "/") || resolvedOutputPath === allowed
-        );
-        if (!isAllowedPath) {
+        if (!isPathAllowed(args.outputPath, state, "MCP_ALLOWED_OUTPUT_PATHS")) {
             return createStructuredErrorResponse(
                 createStructuredError(
                     "ERR_OUTPUT_PATH_INVALID",

packages/pluggable-widgets-mcp/src/tools/utils/sandbox.ts

@@ -0,0 +1,20 @@
+import { resolve } from "node:path";
+import { GENERATIONS_DIR } from "@/config";
+import type { SessionState } from "@/tools/session-state";
+
+/**
+ * Checks whether a resolved path is within the allowed directories.
+ * Allowed dirs: GENERATIONS_DIR, env-var paths (colon-separated), state.projectDir.
+ */
+export function isPathAllowed(targetPath: string, state: SessionState, envVar?: string): boolean {
+    const resolved = resolve(targetPath);
+    const allowed = [
+        resolve(GENERATIONS_DIR),
+        ...((envVar ? process.env[envVar] : undefined) ?? "")
+            .split(":")
+            .filter(Boolean)
+            .map(p => resolve(p)),
+        ...(state.projectDir ? [resolve(state.projectDir)] : [])
+    ];
+    return allowed.some(a => resolved.startsWith(a + "/") || resolved === a);
+}