feat(pluggable-widgets-mcp): wip

Author: rahmanunver

packages/pluggable-widgets-mcp/package.json

@@ -29,7 +29,7 @@
     },
     "devDependencies": {
         "@types/cors": "^2.8.19",
-        "@types/express": "^5.0.2",
+        "@types/express": "^5.0.6",
         "@types/node": "^24.10.1",
         "tsc-alias": "^1.8.16",
         "typescript": "^5.9.3"

packages/pluggable-widgets-mcp/src/config.ts

@@ -21,5 +21,11 @@ const __dirname = import.meta.dirname ?? dirname(fileURLToPath(import.meta.url))
 export const PACKAGE_ROOT = join(__dirname, "../");
 export const GENERATIONS_DIR = join(PACKAGE_ROOT, "generations");
 
+// Path to docs/requirements (relative to monorepo root)
+export const DOCS_DIR = join(PACKAGE_ROOT, "../../docs/requirements");
+
+// Allowed file extensions for widget file operations
+export const ALLOWED_EXTENSIONS = [".tsx", ".ts", ".xml", ".scss", ".css", ".json", ".md", ".editorConfig.ts"];
+
 // Timeouts
 export const SCAFFOLD_TIMEOUT_MS = 300000; // 5 minutes

packages/pluggable-widgets-mcp/src/index.ts

@@ -5,19 +5,15 @@ type TransportMode = "http" | "stdio";
 
 const mode = (process.argv[2] as TransportMode) || "http";
 
-async function main(): Promise<void> {
-    switch (mode) {
-        case "stdio":
-            await startStdioServer();
-            break;
-        case "http":
-        default:
-            await startHttpServer();
-            break;
-    }
+switch (mode) {
+    case "stdio":
+        startStdioServer().catch(err => {
+            console.error("Fatal error:", err);
+            process.exit(1);
+        });
+        break;
+    case "http":
+    default:
+        startHttpServer();
+        break;
 }
-
-main().catch(err => {
-    console.error("Fatal error:", err);
-    process.exit(1);
-});

packages/pluggable-widgets-mcp/src/resources/guidelines.ts

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DOCS_DIR } from "@/config";
+
+/**
+ * Definition for a guideline resource.
+ */
+export interface GuidelineResource {
+    /** Unique resource name */
+    name: string;
+    /** Resource URI (e.g., mendix://guidelines/frontend) */
+    uri: string;
+    /** Human-readable title */
+    title: string;
+    /** Description of what this guideline covers */
+    description: string;
+    /** Source markdown file name */
+    filename: string;
+}
+
+/**
+ * All available guideline resources.
+ */
+export const GUIDELINE_RESOURCES: GuidelineResource[] = [
+    {
+        name: "frontend-guidelines",
+        uri: "mendix://guidelines/frontend",
+        title: "Frontend Guidelines",
+        description: "CSS/SCSS styling, naming conventions, component best practices, and Atlas UI integration",
+        filename: "frontend-guidelines.md"
+    },
+    {
+        name: "implementation-plan",
+        uri: "mendix://guidelines/implementation",
+        title: "Implementation Plan",
+        description: "Step-by-step guide for creating new widgets, including PR templates and testing requirements",
+        filename: "implementation-plan.md"
+    },
+    {
+        name: "app-flow",
+        uri: "mendix://guidelines/app-flow",
+        title: "Application Flow",
+        description: "Complete widget development lifecycle from scaffolding to Studio Pro integration",
+        filename: "app-flow.md"
+    },
+    {
+        name: "backend-structure",
+        uri: "mendix://guidelines/backend-structure",
+        title: "Backend Structure",
+        description:
+            "Widget-to-Mendix runtime integration, data handling with EditableValue/ActionValue, and event management",
+        filename: "backend-structure.md"
+    },
+    {
+        name: "tech-stack",
+        uri: "mendix://guidelines/tech-stack",
+        title: "Technology Stack",
+        description: "Core technologies (TypeScript, React, SCSS), monorepo structure, and development tools",
+        filename: "tech-stack.md"
+    }
+];
+
+/**
+ * Cache for loaded guideline content to avoid repeated file reads.
+ */
+const guidelineCache = new Map<string, string>();
+
+/**
+ * Loads the content of a guideline file.
+ * Caches content after first load for performance.
+ *
+ * @param filename - The markdown filename to load
+ * @returns The file content as a string
+ */
+export async function loadGuidelineContent(filename: string): Promise<string> {
+    // Check cache first
+    if (guidelineCache.has(filename)) {
+        return guidelineCache.get(filename)!;
+    }
+
+    const filePath = join(DOCS_DIR, filename);
+
+    try {
+        const content = await readFile(filePath, "utf-8");
+        guidelineCache.set(filename, content);
+        return content;
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load guideline ${filename}: ${message}`);
+    }
+}
+
+/**
+ * Clears the guideline cache. Useful for testing or hot-reloading.
+ */
+export function clearGuidelineCache(): void {
+    guidelineCache.clear();
+}

packages/pluggable-widgets-mcp/src/resources/index.ts

@@ -0,0 +1,44 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { GUIDELINE_RESOURCES, loadGuidelineContent } from "./guidelines";
+
+/**
+ * Registers all MCP resources with the server.
+ *
+ * Resources are read-only data sources that clients can fetch on-demand.
+ * We expose the Mendix widget development guidelines as resources so LLMs
+ * can access them when implementing widget functionality.
+ */
+export function registerResources(server: McpServer): void {
+    registerGuidelineResources(server);
+}
+
+/**
+ * Registers guideline documentation as MCP resources.
+ */
+function registerGuidelineResources(server: McpServer): void {
+    for (const resource of GUIDELINE_RESOURCES) {
+        server.registerResource(
+            resource.name,
+            resource.uri,
+            {
+                title: resource.title,
+                description: resource.description,
+                mimeType: "text/markdown"
+            },
+            async uri => {
+                const content = await loadGuidelineContent(resource.filename);
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            mimeType: "text/markdown",
+                            text: content
+                        }
+                    ]
+                };
+            }
+        );
+    }
+
+    console.error(`[resources] Registered ${GUIDELINE_RESOURCES.length} guideline resources`);
+}

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

@@ -8,26 +8,22 @@ import { sessionManager } from "./session";
  * Starts the MCP server with HTTP/Streamable transport.
  * Supports multiple concurrent sessions via Express.
  */
-export async function startHttpServer(): Promise<void> {
+export function startHttpServer(): void {
     const app = createMcpExpressApp();
     app.use(cors());
 
     setupRoutes(app);
 
-    app.listen(PORT, () => {
+    const server = app.listen(PORT, () => {
         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`);
     });
 
-    setupGracefulShutdown();
-}
-
-function setupGracefulShutdown(): void {
     const shutdown = async (): Promise<void> => {
         console.log("\n[HTTP] Shutting down server...");
         await sessionManager.closeAll();
-        process.exit(0);
+        server.close(() => process.exit(0));
     };
 
     process.on("SIGINT", shutdown);

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

@@ -1,9 +1,10 @@
 import { SERVER_ICON, SERVER_INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, SERVER_WEBSITE_URL } from "@/config";
+import { registerResources } from "@/resources";
 import { getAllTools } from "@/tools";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 /**
- * Creates and configures a new MCP server instance with all registered tools.
+ * Creates and configures a new MCP server instance with all registered tools and resources.
  */
 export function createMcpServer(): McpServer {
     const server = new McpServer(
@@ -25,6 +26,7 @@ export function createMcpServer(): McpServer {
     );
 
     registerTools(server);
+    registerResources(server);
 
     return server;
 }