@mctx-ai/mcp-dev 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mctx
+
+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/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mctx-ai/mcp-dev",
+  "version": "0.3.0",
+  "description": "Local development server for @mctx-ai/mcp-server with hot reload",
+  "type": "module",
+  "main": "./src/cli.js",
+  "bin": {
+    "mctx-dev": "./src/cli.js"
+  },
+  "exports": {
+    ".": "./src/cli.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "development",
+    "hot-reload",
+    "dev-server"
+  ],
+  "author": "mctx, Inc.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mctx-ai/mcp-server.git",
+    "directory": "packages/dev"
+  },
+  "bugs": {
+    "url": "https://github.com/mctx-ai/mcp-server/issues"
+  },
+  "homepage": "https://docs.mctx.ai",
+  "peerDependencies": {
+    "@mctx-ai/mcp-server": "^0.3.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "echo 'Linting not configured yet'"
+  }
+}

package/src/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+/**
+ * @mctx-ai/mcp-dev CLI Entry Point
+ *
+ * Usage: npx mctx-dev <entry-file>
+ * Example: npx mctx-dev index.js
+ */
+
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { pathToFileURL } from "url";
+import { startDevServer } from "./server.js";
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+
+// Check for --help flag
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`
+mctx-dev - Local development server for MCP servers
+
+Usage:
+  npx mctx-dev <entry-file> [options]
+
+Options:
+  --port <number>    Port to listen on (default: 3000)
+  -h, --help         Show this help message
+
+Examples:
+  npx mctx-dev index.js
+  npx mctx-dev index.js --port 8080
+
+Environment Variables:
+  PORT              Port to listen on (overridden by --port flag)
+`);
+  process.exit(0);
+}
+
+// Parse entry file
+const entryFile = args.find((arg) => !arg.startsWith("--"));
+
+if (!entryFile) {
+  console.error("Error: Entry file is required");
+  console.error("Usage: npx mctx-dev <entry-file>");
+  console.error('Run "npx mctx-dev --help" for more information');
+  process.exit(1);
+}
+
+// Parse port from flags or environment
+const portFlagIndex = args.indexOf("--port");
+const port =
+  portFlagIndex !== -1 && args[portFlagIndex + 1]
+    ? parseInt(args[portFlagIndex + 1], 10)
+    : parseInt(process.env.PORT || "3000", 10);
+
+if (isNaN(port) || port < 1 || port > 65535) {
+  console.error(
+    `Error: Invalid port "${args[portFlagIndex + 1] || process.env.PORT}"`,
+  );
+  process.exit(1);
+}
+
+// Resolve entry file to absolute path
+const entryPath = resolve(process.cwd(), entryFile);
+
+// Check if file exists (Fix #4)
+if (!existsSync(entryPath)) {
+  console.error(`Error: File not found: ${entryFile}`);
+  console.error(`Resolved path: ${entryPath}`);
+  process.exit(1);
+}
+
+// Convert to file URL for dynamic import
+const entryUrl = pathToFileURL(entryPath).href;
+
+// Start dev server
+try {
+  await startDevServer(entryUrl, port);
+} catch (error) {
+  // Handle EADDRINUSE port conflicts (Fix #1)
+  if (error.code === "EADDRINUSE") {
+    console.error(`\nError: Port ${port} is already in use.`);
+    console.error(
+      `Try a different port: npx mctx-dev ${entryFile} --port ${port + 1}`,
+    );
+    process.exit(1);
+  }
+
+  console.error("Failed to start dev server:", error.message);
+
+  if (error.code === "ERR_MODULE_NOT_FOUND") {
+    console.error(`\nCould not find module: ${entryFile}`);
+    console.error("Make sure the file exists and the path is correct.");
+  } else if (error.message.includes("default export")) {
+    console.error("\nMake sure your entry file has a default export.");
+    console.error("Example: export default app;");
+  } else {
+    console.error("\nStack trace:");
+    console.error(error.stack);
+  }
+
+  process.exit(1);
+}

package/src/server.js

@@ -0,0 +1,548 @@
+/**
+ * @mctx-ai/mcp-dev Server
+ *
+ * HTTP server that wraps the app's fetch handler with developer-friendly features:
+ * - Initialize handshake handling
+ * - Request/response logging with timing
+ * - Rich error messages with stack traces
+ * - Hot reload support
+ */
+
+import { createServer } from "http";
+import { watch } from "./watcher.js";
+
+// ANSI color codes for logging
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+};
+
+/**
+ * Format timestamp for logs
+ */
+function timestamp() {
+  return new Date().toISOString().split("T")[1].split(".")[0];
+}
+
+/**
+ * Log with timestamp and color (Fix #8: separated framework vs request logs)
+ */
+function log(message, color = colors.reset) {
+  console.log(
+    `${colors.gray}[${timestamp()}]${colors.reset} ${color}${message}${colors.reset}`,
+  );
+}
+
+/**
+ * Log framework events (startup, reload, errors)
+ */
+function logFramework(message, color = colors.reset) {
+  console.log(
+    `${colors.gray}[${timestamp()}]${colors.reset} ${colors.bright}[mctx-dev]${colors.reset} ${color}${message}${colors.reset}`,
+  );
+}
+
+/**
+ * Handle MCP initialize handshake
+ * This is normally handled by the MCP client (Claude Desktop), but we need to
+ * handle it locally for development.
+ */
+function handleInitialize(rpcRequest) {
+  const { method, params = {} } = rpcRequest;
+
+  if (method === "initialize") {
+    // Respond with server capabilities
+    return {
+      jsonrpc: "2.0",
+      id: rpcRequest.id,
+      result: {
+        protocolVersion: "2024-11-05",
+        capabilities: {
+          tools: {},
+          resources: {},
+          prompts: {},
+          logging: {},
+        },
+        serverInfo: {
+          name: "mctx-dev",
+          version: "0.1.0",
+        },
+      },
+    };
+  }
+
+  if (method === "initialized") {
+    // Fix #3: Return special marker for notifications (no response per JSON-RPC 2.0)
+    return { _notification: true };
+  }
+
+  if (method === "ping") {
+    // Respond to ping
+    return {
+      jsonrpc: "2.0",
+      id: rpcRequest.id,
+      result: {},
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Extract method name and arguments for logging
+ */
+function formatMethod(rpcRequest) {
+  const { method, params } = rpcRequest;
+
+  // For tools/call, show tool name
+  if (method === "tools/call" && params?.name) {
+    return `${method} (${params.name})`;
+  }
+
+  // For resources/read, show URI
+  if (method === "resources/read" && params?.uri) {
+    return `${method} (${params.uri})`;
+  }
+
+  // For prompts/get, show prompt name
+  if (method === "prompts/get" && params?.name) {
+    return `${method} (${params.name})`;
+  }
+
+  return method;
+}
+
+/**
+ * Format error for display with helpful hints
+ */
+function formatError(error, rpcRequest) {
+  let formatted = `${colors.red}${colors.bright}Error:${colors.reset} ${error.message}\n`;
+
+  // Add stack trace if available
+  if (error.stack) {
+    const stack = error.stack
+      .split("\n")
+      .slice(1) // Skip first line (error message)
+      .map((line) => `  ${colors.dim}${line.trim()}${colors.reset}`)
+      .join("\n");
+    formatted += `${stack}\n`;
+  }
+
+  // Add helpful hints for common errors
+  if (error.message.includes("not found")) {
+    formatted += `\n${colors.yellow}Hint:${colors.reset} Check if the ${rpcRequest.method.split("/")[0]} is registered in your server.\n`;
+  } else if (error.message.includes("required")) {
+    formatted += `\n${colors.yellow}Hint:${colors.reset} Check your request parameters. Some fields might be missing.\n`;
+  } else if (error.message.includes("undefined")) {
+    formatted += `\n${colors.yellow}Hint:${colors.reset} Did you forget to return a value from your handler?\n`;
+  }
+
+  return formatted;
+}
+
+/**
+ * Create Request-like object compatible with app's fetch handler
+ */
+function createRequest(body) {
+  return {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+    },
+    async json() {
+      return body;
+    },
+  };
+}
+
+/**
+ * Start the development server
+ */
+export async function startDevServer(entryUrl, port) {
+  let app = null;
+  let appModule = null;
+
+  // Check if verbose logging is enabled
+  const isVerbose = process.env.MCTX_VERBOSE === "true";
+
+  // Load the user's app
+  async function loadApp() {
+    try {
+      // Clear module from cache for hot reload
+      if (entryUrl.startsWith("file://")) {
+        const modulePath = entryUrl;
+        // Add cache-busting query parameter for ES modules
+        const cacheBustedUrl = `${modulePath}?t=${Date.now()}`;
+        appModule = await import(cacheBustedUrl);
+      } else {
+        appModule = await import(entryUrl);
+      }
+
+      app = appModule.default;
+
+      if (!app) {
+        throw new Error(
+          "Entry file must have a default export (the app instance)",
+        );
+      }
+
+      if (typeof app.fetch !== "function") {
+        throw new Error(
+          "App must have a fetch method (created via createServer())",
+        );
+      }
+
+      return true;
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  // Initial load (Fix #2: handle syntax errors gracefully)
+  try {
+    await loadApp();
+  } catch (error) {
+    // Show error and continue - watcher will retry on file changes
+    logFramework(`Failed to load ${entryUrl.split("/").pop()}`, colors.red);
+
+    if (error instanceof SyntaxError) {
+      console.error(
+        `${colors.red}${colors.bright}SyntaxError:${colors.reset} ${error.message}`,
+      );
+      if (error.stack) {
+        const stackLines = error.stack.split("\n").slice(1, 4);
+        console.error(colors.dim + stackLines.join("\n") + colors.reset);
+      }
+      logFramework(
+        "Watching for changes... fix the error and save to retry.",
+        colors.yellow,
+      );
+    } else {
+      console.error(formatError(error, { method: "initial-load" }));
+    }
+  }
+
+  // Start file watcher for hot reload
+  const entryPath = new URL(entryUrl).pathname;
+  const watcherInfo = watch(entryPath, async () => {
+    try {
+      await loadApp();
+      logFramework("Reload successful", colors.green);
+    } catch (error) {
+      logFramework("Reload failed", colors.red);
+
+      if (error instanceof SyntaxError) {
+        console.error(
+          `${colors.red}${colors.bright}SyntaxError:${colors.reset} ${error.message}`,
+        );
+        if (error.stack) {
+          const stackLines = error.stack.split("\n").slice(1, 4);
+          console.error(colors.dim + stackLines.join("\n") + colors.reset);
+        }
+      } else {
+        console.error(formatError(error, { method: "reload" }));
+      }
+    }
+  });
+
+  // Create HTTP server
+  const server = createServer(async (req, res) => {
+    // Fix #2: If app failed to load initially, return error
+    if (!app) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message:
+              "Server initialization failed - fix syntax errors and save to retry",
+          },
+          id: null,
+        }),
+      );
+      return;
+    }
+
+    // Only accept POST requests
+    if (req.method !== "POST") {
+      res.writeHead(405, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32600,
+            message: "Invalid Request - Only POST method is supported",
+          },
+          id: null,
+        }),
+      );
+      return;
+    }
+
+    // Read request body (Fix #6: add timeout protection)
+    let body = "";
+    let timedOut = false;
+
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      req.destroy();
+      res.writeHead(408, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message: "Request timeout - body not received within 30s",
+          },
+          id: null,
+        }),
+      );
+      logFramework("Request timeout", colors.red);
+    }, 30000);
+
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+
+    req.on("end", async () => {
+      clearTimeout(timeout);
+
+      if (timedOut) {
+        return;
+      }
+
+      let rpcRequest;
+      const startTime = Date.now();
+
+      try {
+        // Parse JSON body
+        rpcRequest = JSON.parse(body);
+      } catch (error) {
+        // Fix #9: include body snippet in parse error
+        const bodySnippet =
+          body.length > 100 ? body.substring(0, 100) + "..." : body;
+
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+              code: -32700,
+              message: `Parse error - Invalid JSON: ${error.message}`,
+              data: { bodySnippet },
+            },
+            id: null,
+          }),
+        );
+
+        log(`${colors.red}✗${colors.reset} Parse error`, colors.red);
+        console.error(
+          `${colors.dim}Body snippet: ${bodySnippet}${colors.reset}`,
+        );
+        return;
+      }
+
+      // Log incoming request
+      const methodDisplay = formatMethod(rpcRequest);
+      log(`${colors.cyan}→${colors.reset} ${methodDisplay}`, colors.dim);
+
+      // Verbose logging: log full request body (skip initialize/initialized)
+      if (
+        isVerbose &&
+        rpcRequest.method !== "initialize" &&
+        rpcRequest.method !== "initialized"
+      ) {
+        console.log(`${colors.dim}[verbose] Request:${colors.reset}`);
+        console.log(JSON.stringify(rpcRequest, null, 2));
+      }
+
+      try {
+        // Handle initialize handshake locally
+        const initResponse = handleInitialize(rpcRequest);
+        if (initResponse !== null) {
+          const elapsed = Date.now() - startTime;
+
+          // Fix #3: For notifications (initialized), send 204 No Content
+          if (initResponse._notification === true) {
+            res.writeHead(204);
+            res.end();
+            log(
+              `${colors.green}←${colors.reset} 204 (${elapsed}ms)`,
+              colors.dim,
+            );
+            return;
+          }
+
+          // Fix #5: Include app capabilities if available
+          if (rpcRequest.method === "initialize" && app) {
+            const capabilities = initResponse.result.capabilities;
+
+            // Merge app capabilities if exposed
+            if (app.tools && typeof app.tools.list === "function") {
+              capabilities.tools = app.tools.capabilities || {};
+            }
+            if (app.resources && typeof app.resources.list === "function") {
+              capabilities.resources = app.resources.capabilities || {};
+            }
+            if (app.prompts && typeof app.prompts.list === "function") {
+              capabilities.prompts = app.prompts.capabilities || {};
+            }
+          }
+
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(initResponse));
+          log(`${colors.green}←${colors.reset} 200 (${elapsed}ms)`, colors.dim);
+          return;
+        }
+
+        // Delegate to app's fetch handler
+        const request = createRequest(rpcRequest);
+        const response = await app.fetch(request, {}, {});
+
+        const elapsed = Date.now() - startTime;
+
+        // Read response
+        const responseText = await response.text();
+        const statusCode = response.status;
+
+        // Send response
+        res.writeHead(statusCode, { "Content-Type": "application/json" });
+        res.end(responseText);
+
+        // Log response
+        const statusColor =
+          statusCode >= 200 && statusCode < 300 ? colors.green : colors.red;
+        log(
+          `${statusColor}←${colors.reset} ${statusCode} (${elapsed}ms)`,
+          colors.dim,
+        );
+
+        // Verbose logging: log full response body (skip initialize/initialized)
+        if (
+          isVerbose &&
+          rpcRequest.method !== "initialize" &&
+          rpcRequest.method !== "initialized"
+        ) {
+          console.log(`${colors.dim}[verbose] Response:${colors.reset}`);
+          try {
+            const responseJson = JSON.parse(responseText);
+            console.log(JSON.stringify(responseJson, null, 2));
+          } catch {
+            console.log(responseText);
+          }
+        }
+
+        // Slow tool warning: if tools/call took >1000ms
+        if (rpcRequest.method === "tools/call" && elapsed > 1000) {
+          const toolName = rpcRequest.params?.name || "unknown";
+          log(
+            `${colors.yellow}⚠️  Slow tool: ${toolName} took ${elapsed}ms${colors.reset}`,
+            colors.yellow,
+          );
+        }
+
+        // If error, show details
+        if (statusCode >= 400) {
+          try {
+            const errorResponse = JSON.parse(responseText);
+            if (errorResponse.error) {
+              console.error(
+                formatError(
+                  new Error(errorResponse.error.message || "Unknown error"),
+                  rpcRequest,
+                ),
+              );
+            }
+          } catch {
+            // Ignore parse errors
+          }
+        }
+      } catch (error) {
+        const elapsed = Date.now() - startTime;
+
+        // Return error response
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+              code: -32603,
+              message: error.message || "Internal error",
+            },
+            id: rpcRequest.id || null,
+          }),
+        );
+
+        log(`${colors.red}←${colors.reset} error (${elapsed}ms)`, colors.red);
+        console.error(formatError(error, rpcRequest));
+      }
+    });
+  });
+
+  // Fix #1: Handle EADDRINUSE port conflicts
+  server.on("error", (error) => {
+    if (error.code === "EADDRINUSE") {
+      // Propagate to CLI for proper error handling
+      throw error;
+    } else {
+      logFramework(`Server error: ${error.message}`, colors.red);
+      throw error;
+    }
+  });
+
+  // Start listening
+  server.listen(port, () => {
+    logFramework(`Server running at http://localhost:${port}`, colors.cyan);
+
+    // Format watched directories for display
+    const watchedDirsDisplay = watcherInfo.watchedDirs
+      .map(
+        ({ path, recursive }) =>
+          `  ${colors.dim}${path}${recursive ? " (recursive)" : ""}${colors.reset}`,
+      )
+      .join("\n");
+
+    console.log(`
+${colors.bright}${colors.cyan}🔧 mctx dev server running at http://localhost:${port}${colors.reset}
+
+${colors.bright}Test with curl:${colors.reset}
+  ${colors.dim}curl -X POST http://localhost:${port} \\
+    -H "Content-Type: application/json" \\
+    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'${colors.reset}
+
+${colors.bright}Claude Desktop config${colors.reset} ${colors.dim}(~/.config/claude/claude_desktop_config.json):${colors.reset}
+  ${colors.dim}{
+    "mcpServers": {
+      "my-server": {
+        "command": "npx",
+        "args": ["mctx-dev", "${entryPath}"]
+      }
+    }
+  }${colors.reset}
+
+${colors.bright}Watching for changes:${colors.reset}
+${watchedDirsDisplay}
+`);
+  });
+
+  // Handle graceful shutdown
+  process.on("SIGINT", () => {
+    console.log(`\n${colors.dim}Shutting down...${colors.reset}`);
+    server.close(() => {
+      process.exit(0);
+    });
+  });
+
+  process.on("SIGTERM", () => {
+    server.close(() => {
+      process.exit(0);
+    });
+  });
+}

package/src/watcher.js

@@ -0,0 +1,139 @@
+/**
+ * @mctx-ai/mcp-dev File Watcher
+ *
+ * Watches project files for changes and triggers hot reload.
+ * Uses Node's built-in fs.watch with debouncing to avoid rapid reloads.
+ *
+ * Watches:
+ * - Project root (if package.json found)
+ * - Common directories: src/, lib/, utils/ (recursively)
+ * - Falls back to entry file directory if no package.json found
+ */
+
+import { watch as fsWatch, existsSync } from "fs";
+import { dirname, basename, join } from "path";
+
+// ANSI color codes
+const colors = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  gray: "\x1b[90m",
+};
+
+/**
+ * Format timestamp for logs
+ */
+function timestamp() {
+  return new Date().toISOString().split("T")[1].split(".")[0];
+}
+
+/**
+ * Log with timestamp
+ */
+function log(message) {
+  console.log(`${colors.gray}[${timestamp()}]${colors.reset} ${message}`);
+}
+
+/**
+ * Find project root by walking up to find package.json
+ */
+function findProjectRoot(startPath) {
+  let currentPath = startPath;
+
+  // Walk up until we find package.json or reach root
+  while (currentPath !== dirname(currentPath)) {
+    const packageJsonPath = join(currentPath, "package.json");
+    if (existsSync(packageJsonPath)) {
+      return currentPath;
+    }
+    currentPath = dirname(currentPath);
+  }
+
+  return null;
+}
+
+/**
+ * Get directories to watch
+ */
+function getWatchDirs(entryFilePath) {
+  const entryDir = dirname(entryFilePath);
+  const projectRoot = findProjectRoot(entryDir);
+
+  if (!projectRoot) {
+    // No package.json found, fall back to entry file directory
+    return [{ path: entryDir, recursive: false }];
+  }
+
+  const watchDirs = [];
+
+  // Watch common directories recursively if they exist
+  const commonDirs = ["src", "lib", "utils"];
+  for (const dir of commonDirs) {
+    const dirPath = join(projectRoot, dir);
+    if (existsSync(dirPath)) {
+      watchDirs.push({ path: dirPath, recursive: true });
+    }
+  }
+
+  // If no common dirs found, watch project root non-recursively
+  if (watchDirs.length === 0) {
+    watchDirs.push({ path: projectRoot, recursive: false });
+  }
+
+  return watchDirs;
+}
+
+/**
+ * Watch file and directories for changes
+ *
+ * @param {string} filePath - Absolute path to file to watch
+ * @param {Function} onChange - Callback when file changes
+ * @returns {Object} Object with watchers array and watchedDirs info
+ *
+ * Watches project root and common directories (src/, lib/, utils/) recursively.
+ * Falls back to entry file directory if no package.json found.
+ */
+export function watch(filePath, onChange) {
+  let debounceTimer = null;
+  const DEBOUNCE_MS = 100;
+
+  const watchDirs = getWatchDirs(filePath);
+  const watchers = [];
+
+  // Watch each directory
+  for (const { path, recursive } of watchDirs) {
+    const watcher = fsWatch(path, { recursive }, (eventType, changedFile) => {
+      // Only watch .js files
+      if (changedFile && !changedFile.endsWith(".js")) {
+        return;
+      }
+
+      // Debounce rapid changes (editors often write multiple times)
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+      }
+
+      debounceTimer = setTimeout(() => {
+        log(
+          `${colors.green}Reloaded:${colors.reset} ${colors.dim}${changedFile || "file"}${colors.reset}`,
+        );
+        onChange();
+      }, DEBOUNCE_MS);
+    });
+
+    // Handle watcher errors
+    watcher.on("error", (error) => {
+      console.error(`Watcher error: ${error.message}`);
+    });
+
+    watchers.push(watcher);
+  }
+
+  // Clean up on process exit
+  process.on("exit", () => {
+    watchers.forEach((w) => w.close());
+  });
+
+  return { watchers, watchedDirs: watchDirs };
+}