Support devcontainer_workspace_folders

Author: aiqlcom

README.md

@@ -30,7 +30,7 @@ npx -y mcp-devcontainers
 - Run ESLint: `npm run lint` - Executes ESLint for code validation
 - Fix ESLint issues: `npm run lint:fix` - Automatically fixes ESLint errors
 
-## MCP Transport
+## ✨ MCP Transport
 
 ### Option 1 - Start STDIO server
 
@@ -128,6 +128,58 @@ Initializes and starts a devcontainer environment in the specified workspace fol
 
   Text content with the current devcontainer Docker process status
 
+### `devcontainer_workspace_folders`
+
+  Runs find command to get all workspace folders with devcontainer config.
+
+- #### Input Parameters
+  | Name | Required | Type | Description |
+  | -------- | -------- | -------- | -------- |
+  | rootPath | ⚪ | string | A path used to search its subdirectories for all workspace folders containing a devcontainer configuration. |
+
+- #### Returns
+
+  Text content with all workspace folders under the specified root path.
+
+
+## 🧑‍💻 Quick Experience / Trial
+
+For developers who want to quickly try this project without a local Docker setup, we recommend using GitHub Codespaces:
+
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/AI-QL/mcp-devcontainers?quickstart=1)
+
+Then follow these steps to set up a trial environment:
+
+- Wait for the environment to initialize in your browser
+
+- Install dependencies: `npm install`
+
+- Launch the service: `npm start http`
+
+  > The codespace will automatically provide a forwarded port (e.g., https://ominous-halibut-7vvq7v56vgq6hr5p9-3001.app.github.dev/)
+
+- Make the `forwarded port` publicly accessible (located on the right side of the VSCode `Terminal` tab)
+
+- Connect using [mcp-inspector](https://github.com/modelcontextprotocol/inspector) via Streamable HTTP
+
+  ```bash
+  npx -y @modelcontextprotocol/inspector
+  ```
+  > For a streamable HTTP connection, remember to append `/mcp` to the URL
+
+For MCP Clients that don't support remote URLs, use this alternative configuration:
+
+```json
+{
+  "mcpServers": {
+    "Devcontainer": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://ominous-halibut-7vvq7v56vgq6hr5p9-3001.app.github.dev/mcp"]
+    }
+  }
+}
+```
 
 ## 🤝 Contributing
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-devcontainers",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "MCP Server for devcontainers management",
   "private": false,
   "license": "MIT",

package.json

@@ -1,7 +1,9 @@
 import { spawn, SpawnOptions, exec } from "child_process";
+import { promises } from "fs";
 import fs from "fs";
+import path from "path";
 import { z } from "zod";
-import { promisify } from 'util';
+import { promisify } from "util";
 
 const execAsync = promisify(exec);
 
@@ -11,14 +13,23 @@ const COMMAND = "docker";
 
 type CommandResult = Promise<string>;
 
-const PS_PATTERN = "\"{psID: {{.ID}}, psName: {{.Names}}, workspaceFolder: {{.Label \"devcontainer.local_folder\"}}, container: {{.Label \"dev.containers.id\"}}}\""
+const PS_PATTERN =
+  '{psID: {{.ID}}, psName: {{.Names}}, workspaceFolder: {{.Label "devcontainer.local_folder"}}, container: {{.Label "dev.containers.id"}}}';
+
+const WS_FOLDER_DESC =
+  "A path used to search its subdirectories for all workspace folders containing a devcontainer configuration.";
 
 export const DevCleanupSchema = z.object({});
 
 export const DevListSchema = z.object({});
 
+export const DevWsFolderSchema = z.object({
+  rootPath: z.string().describe(WS_FOLDER_DESC).optional(),
+});
+
 type DevCleanupArgs = z.infer<typeof DevCleanupSchema>;
 type DevListArgs = z.infer<typeof DevListSchema>;
+type DevWsFolderArgs = z.infer<typeof DevWsFolderSchema>;
 
 function createOutputStream(
   stdioFilePath: string = NULL_DEVICE
@@ -99,11 +110,15 @@ export async function devCleanup(options: DevCleanupArgs): CommandResult {
   let ids: string[];
 
   try {
-    const { stdout } = await execAsync("docker ps -aq -f label=dev.containers.id")
+    const { stdout } = await execAsync(
+      "docker ps -aq -f label=dev.containers.id"
+    );
     const raw = stdout.toString().trim();
     ids = raw ? raw.split("\n") : [];
   } catch (error) {
-    return Promise.reject(`Cannot list all docker ps: ${(error as Error).message}`);
+    return Promise.reject(
+      `Cannot list all docker ps: ${(error as Error).message}`
+    );
   }
 
   if (ids.length === 0) {
@@ -124,3 +139,67 @@ export async function devList(options: DevListArgs): CommandResult {
     stream
   );
 }
+
+// Optionally skip well-known heavy directories to improve performance
+function shouldSkipDirectory(name: string): boolean {
+  const skipDirs = ["node_modules", ".git", "dist", "build", ".next"];
+  return skipDirs.includes(name);
+}
+
+export async function devWsFolder(
+  options: DevWsFolderArgs
+): Promise<CommandResult> {
+  const rootPath = options.rootPath;
+  const searchRoot = rootPath ? path.resolve(rootPath) : process.cwd();
+  const results: string[] = [];
+
+  // Use concurrency to speed up directory traversal
+  async function scanDirectory(dir: string): Promise<void> {
+    let entries: fs.Dirent[];
+
+    try {
+      entries = await promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      // Skip directories that cannot be read (permissions, transient I/O errors, etc.)
+      return;
+    }
+
+    // Collect subdirectories and schedule checks separately to maximize parallelism
+    const subDirs: string[] = [];
+    const checkTasks: Promise<void>[] = [];
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (entry.name === ".devcontainer") {
+          checkTasks.push(
+            promises
+              .access(path.join(fullPath, "devcontainer.json"))
+              .then(() => void results.push(fullPath))
+              .catch(() => {
+                /* file not found; ignore */
+              })
+          );
+        }
+        else if (!shouldSkipDirectory(entry.name)) {
+          subDirs.push(fullPath);
+        }
+      }
+    }
+
+    // Wait for all devcontainer.json checks to complete
+    await Promise.all(checkTasks);
+
+    // Recursively scan subdirectories in parallel
+    await Promise.all(subDirs.map(scanDirectory));
+  }
+
+  await scanDirectory(searchRoot);
+
+  if (results.length === 0) {
+    throw new Error(`No Workspace Folders found in ${searchRoot}`);
+  }
+
+  return "\n" + results.join("\n");
+}

src/docker.ts

@@ -10,8 +10,12 @@ import { devUp, devRunUserCommands, devExec } from "./devcontainer.js";
 
 import { DevUpSchema, DevRunSchema, DevExecSchema } from "./devcontainer.js";
 
-import { devCleanup, devList } from "./docker.js";
-import { DevCleanupSchema, DevListSchema } from "./docker.js";
+import { devCleanup, devList, devWsFolder } from "./docker.js";
+import {
+  DevCleanupSchema,
+  DevListSchema,
+  DevWsFolderSchema,
+} from "./docker.js";
 
 type ToolInput = Tool["inputSchema"];
 type ToolName = keyof typeof ToolMap;
@@ -55,14 +59,22 @@ const ToolMap = {
     label: "Devcontainer Cleanup",
   },
   devcontainer_list: {
-    description:
-      "Runs docker command to list all devcontainer environments.",
+    description: "Runs docker command to list all devcontainer environments.",
     schema: DevListSchema,
     execute: async (args: ToolArgs) => {
       return devList(DevListSchema.parse(args));
     },
     label: "Devcontainer List",
   },
+  devcontainer_workspace_folders: {
+    description:
+      "Runs find command to get all workspace folders with devcontainer config.",
+    schema: DevWsFolderSchema,
+    execute: async (args: ToolArgs) => {
+      return devWsFolder(DevWsFolderSchema.parse(args));
+    },
+    label: "Devcontainer Workspace Folders",
+  },
 };
 
 export const createServer = () => {
@@ -103,34 +115,34 @@ export const createServer = () => {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const Tool = ToolMap[name as ToolName];
-    try {
-      switch (name) {
-        case "devcontainer_up":
-        case "devcontainer_run_user_commands":
-        case "devcontainer_exec":
-        case "devcontainer_cleanup":
-        case "devcontainer_list":
-          {
-            const result = await Tool.execute(args);
-            return {
-              content: [
-                { type: "text", text: `${Tool.label} result: ${result}` },
-              ],
-            };
-          }
-        default:
+
+    switch (name) {
+      case "devcontainer_up":
+      case "devcontainer_run_user_commands":
+      case "devcontainer_exec":
+      case "devcontainer_cleanup":
+      case "devcontainer_list":
+      case "devcontainer_workspace_folders":
+      {
+        try {
+          const result = await Tool.execute(args);
+          return {
+            content: [
+              { type: "text", text: `${Tool.label} result: ${result}` },
+            ],
+          };
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
           return {
-            error: {
-              code: -32602,
-              message: `Undefined tool: ${name}`,
-            },
+            content: [
+              { type: "text", text: `${Tool.label} failure: ${message}` },
+            ],
+            isError: true,
           };
+        }
       }
-    } catch (error) {
-      return {
-        content: [{ type: "text", text: `${Tool.label} failure: ${error}` }],
-        isError: true,
-      };
+      default:
+        throw new Error(`Undefined tool: ${name}`);
     }
   });