@mcp-use/cli 3.1.0-canary.2 → 3.1.0-canary.3

package/dist/index.cjs

@@ -526,11 +526,11 @@ var source_default = chalk;
 var import_commander6 = require("commander");
 var import_config8 = require("dotenv/config");
 var import_node_child_process9 = require("child_process");
-var import_node_fs10 = require("fs");
+var import_node_fs11 = require("fs");
 var import_promises7 = require("fs/promises");
 var import_node_module2 = require("module");
-var import_node_path8 = __toESM(require("path"), 1);
-var import_node_url2 = require("url");
+var import_node_path9 = __toESM(require("path"), 1);
+var import_node_url3 = require("url");
 
 // ../../node_modules/.pnpm/open@11.0.0/node_modules/open/index.js
 var import_node_process8 = __toESM(require("process"), 1);
@@ -716,15 +716,15 @@ var wslDefaultBrowser = async () => {
   const { stdout } = await executePowerShell(command, { powerShellPath: psPath });
   return stdout.trim();
 };
-var convertWslPathToWindows = async (path7) => {
-  if (/^[a-z]+:\/\//i.test(path7)) {
-    return path7;
+var convertWslPathToWindows = async (path8) => {
+  if (/^[a-z]+:\/\//i.test(path8)) {
+    return path8;
   }
   try {
-    const { stdout } = await execFile2("wslpath", ["-aw", path7], { encoding: "utf8" });
+    const { stdout } = await execFile2("wslpath", ["-aw", path8], { encoding: "utf8" });
     return stdout.trim();
   } catch {
-    return path7;
+    return path8;
   }
 };
 
@@ -1374,8 +1374,8 @@ var McpUseAPI = class _McpUseAPI {
     return this.request(`/servers${q ? `?${q}` : ""}`);
   }
   async getServer(idOrSlug) {
-    const path7 = encodeURIComponent(idOrSlug);
-    return this.request(`/servers/${path7}`);
+    const path8 = encodeURIComponent(idOrSlug);
+    return this.request(`/servers/${path8}`);
   }
   async deleteServer(id) {
     await this.request(
@@ -5250,7 +5250,7 @@ async function addSkillsToProject(projectPath) {
       import_node_stream.Readable.fromWeb(response.body),
       (0, import_tar.extract)({
         cwd: tempDir,
-        filter: (path7) => path7.includes("/skills/"),
+        filter: (path8) => path8.includes("/skills/"),
         strip: 1
       })
     );
@@ -5315,14 +5315,114 @@ function createSkillsCommand() {
   return skills;
 }
 
-// src/utils/update-check.ts
+// src/utils/next-shims.ts
 var import_node_fs9 = require("fs");
+var import_node_path7 = __toESM(require("path"), 1);
+var import_node_url2 = require("url");
+async function detectNextJsProject(projectPath) {
+  try {
+    const pkgPath = import_node_path7.default.join(projectPath, "package.json");
+    const content = await import_node_fs9.promises.readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(content);
+    const deps = pkg.dependencies ?? {};
+    const devDeps = pkg.devDependencies ?? {};
+    return "next" in deps || "next" in devDeps;
+  } catch {
+    return false;
+  }
+}
+async function loadNextJsEnvFiles(projectPath) {
+  const files = [
+    ".env",
+    ".env.development",
+    ".env.local",
+    ".env.development.local"
+  ];
+  const dotenv = await import("dotenv");
+  for (const file of files) {
+    const abs = import_node_path7.default.join(projectPath, file);
+    try {
+      await import_node_fs9.promises.access(abs);
+    } catch {
+      continue;
+    }
+    dotenv.config({ path: abs, override: true, quiet: true });
+  }
+}
+function getThisDir() {
+  if (typeof __dirname === "string") return __dirname;
+  const url = importMetaUrl;
+  return import_node_path7.default.dirname((0, import_node_url2.fileURLToPath)(url));
+}
+function resolveShimPath(filename) {
+  const thisDir = getThisDir();
+  const candidates = [
+    // Production: `dist/` next to this module
+    import_node_path7.default.join(thisDir, "shims", filename),
+    // Test / dev: one level up (e.g., from `dist/utils/` back to `src/shims/`)
+    import_node_path7.default.join(thisDir, "..", "shims", filename),
+    import_node_path7.default.join(thisDir, "..", "..", "src", "shims", filename),
+    import_node_path7.default.join(thisDir, "..", "src", "shims", filename)
+  ];
+  for (const candidate of candidates) {
+    if ((0, import_node_fs9.existsSync)(candidate)) return candidate;
+  }
+  return void 0;
+}
+function getShimRegisterPath() {
+  return resolveShimPath("next-shims-register.mjs");
+}
+function getShimLoaderPath() {
+  return resolveShimPath("next-shims-loader.mjs");
+}
+function getShimCjsPreloadPath() {
+  return resolveShimPath("next-shims-cjs.cjs");
+}
+async function registerNextShimsInProcess() {
+  let anyRegistered = false;
+  const cjsPath = getShimCjsPreloadPath();
+  if (cjsPath) {
+    const { createRequire: createRequire3 } = await import("module");
+    const req = createRequire3((0, import_node_url2.pathToFileURL)(getThisDir() + import_node_path7.default.sep).href);
+    req(cjsPath);
+    anyRegistered = true;
+  }
+  const loaderPath = getShimLoaderPath();
+  if (loaderPath) {
+    const { register } = await import("module");
+    const loaderUrl = (0, import_node_url2.pathToFileURL)(loaderPath).href;
+    register(loaderUrl, (0, import_node_url2.pathToFileURL)(getThisDir() + import_node_path7.default.sep).href);
+    anyRegistered = true;
+  }
+  return anyRegistered;
+}
+function withNextShimsEnv(baseEnv) {
+  const additions = [];
+  const cjsPath = getShimCjsPreloadPath();
+  if (cjsPath) additions.push(`-r ${quoteNodeOption(cjsPath)}`);
+  const registerPath = getShimRegisterPath();
+  if (registerPath)
+    additions.push(`--import=${(0, import_node_url2.pathToFileURL)(registerPath).href}`);
+  if (additions.length === 0) return baseEnv;
+  const existing = baseEnv.NODE_OPTIONS ?? "";
+  const prepended = additions.join(" ");
+  return {
+    ...baseEnv,
+    NODE_OPTIONS: existing ? `${prepended} ${existing}` : prepended
+  };
+}
+function quoteNodeOption(value) {
+  return /\s/.test(value) ? `"${value}"` : value;
+}
+
+// src/utils/update-check.ts
+var import_node_fs10 = require("fs");
 var import_promises6 = require("fs/promises");
 var import_node_module = require("module");
 var import_node_os6 = __toESM(require("os"), 1);
-var import_node_path7 = __toESM(require("path"), 1);
-var CACHE_DIR = import_node_path7.default.join(import_node_os6.default.homedir(), ".mcp-use");
-var CACHE_FILE = import_node_path7.default.join(CACHE_DIR, "update-check.json");
+var import_node_path8 = __toESM(require("path"), 1);
+var CACHE_DIR = import_node_path8.default.join(import_node_os6.default.homedir(), ".mcp-use");
+var CACHE_FILE = import_node_path8.default.join(CACHE_DIR, "update-check.json");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 var FETCH_TIMEOUT_MS = 3e3;
 var PACKAGE_NAME = "mcp-use";
@@ -5405,16 +5505,16 @@ function resolveInstalledVersion(projectPath) {
   if (projectPath) {
     attempts.push(() => {
       const projectRequire = (0, import_node_module.createRequire)(
-        import_node_path7.default.join(projectPath, "package.json")
+        import_node_path8.default.join(projectPath, "package.json")
       );
       return projectRequire.resolve(`${PACKAGE_NAME}/package.json`);
     });
   }
-  attempts.push(() => import_node_path7.default.join(__dirname, "../../mcp-use/package.json"));
+  attempts.push(() => import_node_path8.default.join(__dirname, "../../mcp-use/package.json"));
   for (const attempt of attempts) {
     try {
       const pkgPath = attempt();
-      const json = JSON.parse((0, import_node_fs9.readFileSync)(pkgPath, "utf-8"));
+      const json = JSON.parse((0, import_node_fs10.readFileSync)(pkgPath, "utf-8"));
       if (typeof json.version === "string") return json.version;
     } catch {
     }
@@ -5447,8 +5547,8 @@ A new release of ${source_default.bold(PACKAGE_NAME)} is available: ${source_def
 
 // src/index.ts
 var program = new import_commander6.Command();
-var packageContent = (0, import_node_fs10.readFileSync)(
-  import_node_path8.default.join(__dirname, "../package.json"),
+var packageContent = (0, import_node_fs11.readFileSync)(
+  import_node_path9.default.join(__dirname, "../package.json"),
   "utf-8"
 );
 var packageJson = JSON.parse(packageContent);
@@ -5479,16 +5579,16 @@ function displayPackageVersions(projectPath) {
       if (projectPath) {
         try {
           const projectRequire = (0, import_node_module2.createRequire)(
-            import_node_path8.default.join(projectPath, "package.json")
+            import_node_path9.default.join(projectPath, "package.json")
           );
           pkgPath = projectRequire.resolve(`${pkg.name}/package.json`);
         } catch (resolveError) {
-          pkgPath = import_node_path8.default.join(__dirname, pkg.relativePath);
+          pkgPath = import_node_path9.default.join(__dirname, pkg.relativePath);
         }
       } else {
-        pkgPath = import_node_path8.default.join(__dirname, pkg.relativePath);
+        pkgPath = import_node_path9.default.join(__dirname, pkg.relativePath);
       }
-      const pkgContent = (0, import_node_fs10.readFileSync)(pkgPath, "utf-8");
+      const pkgContent = (0, import_node_fs11.readFileSync)(pkgPath, "utf-8");
       const pkgJson = JSON.parse(pkgContent);
       const version = pkgJson.version || "unknown";
       if (pkg.highlight) {
@@ -5638,20 +5738,92 @@ async function startTunnel(port, subdomain) {
     }, 3e4);
   });
 }
-async function findServerFile(projectPath) {
+async function resolveEntryFile(projectPath, cliEntry, mcpDir) {
+  if (cliEntry) {
+    await (0, import_promises7.access)(import_node_path9.default.join(projectPath, cliEntry)).catch(() => {
+      throw new Error(`File not found: ${cliEntry}`);
+    });
+    return cliEntry;
+  }
+  if (mcpDir) {
+    const mcpCandidates = [
+      import_node_path9.default.join(mcpDir, "index.ts"),
+      import_node_path9.default.join(mcpDir, "index.tsx"),
+      import_node_path9.default.join(mcpDir, "server.ts"),
+      import_node_path9.default.join(mcpDir, "server.tsx")
+    ];
+    for (const candidate of mcpCandidates) {
+      try {
+        await (0, import_promises7.access)(import_node_path9.default.join(projectPath, candidate));
+        return candidate;
+      } catch {
+        continue;
+      }
+    }
+    throw new Error(
+      `No entry file found inside ${mcpDir}.
+
+Expected one of: ${mcpCandidates.map((c) => import_node_path9.default.relative(projectPath, import_node_path9.default.join(projectPath, c))).join(", ")}
+
+Fix this by either:
+  1. Creating ${import_node_path9.default.join(mcpDir, "index.ts")}, or
+  2. Passing --entry <file> on the command line`
+    );
+  }
   const candidates = ["index.ts", "src/index.ts", "server.ts", "src/server.ts"];
   for (const candidate of candidates) {
     try {
-      await (0, import_promises7.access)(import_node_path8.default.join(projectPath, candidate));
+      await (0, import_promises7.access)(import_node_path9.default.join(projectPath, candidate));
       return candidate;
     } catch {
       continue;
     }
   }
-  throw new Error("No server file found");
+  throw new Error(
+    `No entry file found.
+
+Expected one of: ${candidates.join(", ")}
+
+Fix this by either:
+  1. Creating one of the default entry files above, or
+  2. Passing --entry <file> or --mcp-dir <dir> on the command line`
+  );
+}
+function resolveWidgetsDir(cliWidgetsDir, mcpDir) {
+  if (cliWidgetsDir) return cliWidgetsDir;
+  if (mcpDir) return import_node_path9.default.join(mcpDir, "resources");
+  return "resources";
+}
+function makeWidgetServerOnlyGuard(widgetName) {
+  const rejected = /* @__PURE__ */ new Set([
+    "server-only",
+    "client-only",
+    "next/cache",
+    "next/headers",
+    "next/navigation",
+    "next/server"
+  ]);
+  return {
+    name: "mcp-use-widget-server-only-guard",
+    enforce: "pre",
+    resolveId(id, importer) {
+      if (!rejected.has(id)) return null;
+      const from = importer ? ` (imported from ${importer})` : "";
+      throw new Error(
+        `Widget "${widgetName}" imports "${id}"${from}, which is a Next.js server-only module. Widgets run in a browser iframe and cannot use server APIs.
+
+To fix:
+  \u2022 Remove the import from the widget (or from any module the widget transitively imports)
+  \u2022 If the widget needs data from ${id}, read it inside an MCP tool in your server and pass the result through the widget's props`
+      );
+    }
+  };
+}
+async function findServerFile(projectPath, cliEntry, cliMcpDir) {
+  return resolveEntryFile(projectPath, cliEntry, cliMcpDir);
 }
 async function generateToolRegistryTypesForServer(projectPath, serverFileRelative) {
-  const serverFile = import_node_path8.default.join(projectPath, serverFileRelative);
+  const serverFile = import_node_path9.default.join(projectPath, serverFileRelative);
   const serverFileExists = await (0, import_promises7.access)(serverFile).then(() => true).catch(() => false);
   if (!serverFileExists) {
     throw new Error(`Server file not found: ${serverFile}`);
@@ -5660,19 +5832,48 @@ async function generateToolRegistryTypesForServer(projectPath, serverFileRelativ
   try {
     globalThis.__mcpUseHmrMode = true;
     globalThis.__mcpUseLastServer = void 0;
-    const { tsImport } = await import("tsx/esm/api");
-    await tsImport((0, import_node_url2.pathToFileURL)(serverFile).href, {
-      parentURL: importMetaUrl,
-      tsconfig: import_node_path8.default.join(projectPath, "tsconfig.json")
-    });
+    if (await detectNextJsProject(projectPath)) {
+      await loadNextJsEnvFiles(projectPath);
+      await registerNextShimsInProcess();
+    }
+    const projectTsconfigPath = import_node_path9.default.join(projectPath, "tsconfig.json");
+    const hasTsconfig = await (0, import_promises7.access)(projectTsconfigPath).then(() => true).catch(() => false);
+    if (hasTsconfig) {
+      process.env.TSX_TSCONFIG_PATH = projectTsconfigPath;
+    }
+    const previousCwd = process.cwd();
+    if (previousCwd !== projectPath) process.chdir(projectPath);
+    try {
+      const projectRequire = (0, import_node_module2.createRequire)(
+        import_node_path9.default.join(projectPath, "package.json")
+      );
+      const tsxEsmApiPath = projectRequire.resolve("tsx/esm/api");
+      const tsxEsmApi = await import((0, import_node_url3.pathToFileURL)(tsxEsmApiPath).href);
+      if (typeof tsxEsmApi.register === "function") {
+        tsxEsmApi.register({
+          tsconfig: hasTsconfig ? projectTsconfigPath : void 0
+        });
+      }
+      try {
+        const tsxCjsApiPath = projectRequire.resolve("tsx/cjs/api");
+        const tsxCjsApi = await import((0, import_node_url3.pathToFileURL)(tsxCjsApiPath).href);
+        if (typeof tsxCjsApi.register === "function") {
+          tsxCjsApi.register();
+        }
+      } catch {
+      }
+      await import(`${(0, import_node_url3.pathToFileURL)(serverFile).href}?t=${Date.now()}`);
+    } finally {
+      if (process.cwd() !== previousCwd) process.chdir(previousCwd);
+    }
     const server = globalThis.__mcpUseLastServer;
     if (!server) {
       throw new Error(
         "No MCPServer instance found. Make sure your server file creates an MCPServer instance."
       );
     }
-    const mcpUsePath = import_node_path8.default.join(projectPath, "node_modules", "mcp-use");
-    const { generateToolRegistryTypes } = await import((0, import_node_url2.pathToFileURL)(import_node_path8.default.join(mcpUsePath, "dist", "src", "server", "index.js")).href).then((mod) => mod);
+    const mcpUsePath = import_node_path9.default.join(projectPath, "node_modules", "mcp-use");
+    const { generateToolRegistryTypes } = await import((0, import_node_url3.pathToFileURL)(import_node_path9.default.join(mcpUsePath, "dist", "src", "server", "index.js")).href).then((mod) => mod);
     if (!generateToolRegistryTypes) {
       throw new Error("generateToolRegistryTypes not found in mcp-use package");
     }
@@ -5687,21 +5888,24 @@ async function generateToolRegistryTypesForServer(projectPath, serverFileRelativ
 }
 async function buildWidgets(projectPath, options = {}) {
   const { inline = true } = options;
-  const { promises: fs10 } = await import("fs");
+  const { promises: fs11 } = await import("fs");
   const { build } = await import("vite");
-  const resourcesDir = import_node_path8.default.join(projectPath, "resources");
+  const widgetsDirRelative = options.widgetsDir ?? "resources";
+  const resourcesDir = import_node_path9.default.resolve(projectPath, widgetsDirRelative);
   const mcpUrl = process.env.MCP_URL;
   try {
     await (0, import_promises7.access)(resourcesDir);
   } catch {
     console.log(
-      source_default.gray("No resources/ directory found - skipping widget build")
+      source_default.gray(
+        `No ${widgetsDirRelative}/ directory found - skipping widget build`
+      )
     );
     return [];
   }
   const entries = [];
   try {
-    const files = await fs10.readdir(resourcesDir, { withFileTypes: true });
+    const files = await fs11.readdir(resourcesDir, { withFileTypes: true });
     for (const dirent of files) {
       if (dirent.name.startsWith("._") || dirent.name.startsWith(".DS_Store")) {
         continue;
@@ -5709,12 +5913,12 @@ async function buildWidgets(projectPath, options = {}) {
       if (dirent.isFile() && (dirent.name.endsWith(".tsx") || dirent.name.endsWith(".ts"))) {
         entries.push({
           name: dirent.name.replace(/\.tsx?$/, ""),
-          path: import_node_path8.default.join(resourcesDir, dirent.name)
+          path: import_node_path9.default.join(resourcesDir, dirent.name)
         });
       } else if (dirent.isDirectory()) {
-        const widgetPath = import_node_path8.default.join(resourcesDir, dirent.name, "widget.tsx");
+        const widgetPath = import_node_path9.default.join(resourcesDir, dirent.name, "widget.tsx");
         try {
-          await fs10.access(widgetPath);
+          await fs11.access(widgetPath);
           entries.push({
             name: dirent.name,
             path: widgetPath
@@ -5724,11 +5928,15 @@ async function buildWidgets(projectPath, options = {}) {
       }
     }
   } catch (error) {
-    console.log(source_default.gray("No widgets found in resources/ directory"));
+    console.log(
+      source_default.gray(`No widgets found in ${widgetsDirRelative}/ directory`)
+    );
     return [];
   }
   if (entries.length === 0) {
-    console.log(source_default.gray("No widgets found in resources/ directory"));
+    console.log(
+      source_default.gray(`No widgets found in ${widgetsDirRelative}/ directory`)
+    );
     return [];
   }
   console.log(
@@ -5738,10 +5946,17 @@ async function buildWidgets(projectPath, options = {}) {
   );
   const react = (await import("@vitejs/plugin-react")).default;
   const tailwindcss = (await import("@tailwindcss/vite")).default;
-  const packageJsonPath = import_node_path8.default.join(projectPath, "package.json");
+  const projectTsconfigPath = import_node_path9.default.join(projectPath, "tsconfig.json");
+  let hasProjectTsconfig = false;
+  try {
+    await (0, import_promises7.access)(projectTsconfigPath);
+    hasProjectTsconfig = true;
+  } catch {
+  }
+  const packageJsonPath = import_node_path9.default.join(projectPath, "package.json");
   let favicon = "";
   try {
-    const pkgContent = await fs10.readFile(packageJsonPath, "utf-8");
+    const pkgContent = await fs11.readFile(packageJsonPath, "utf-8");
     const pkg = JSON.parse(pkgContent);
     favicon = pkg.mcpUse?.favicon || "";
   } catch {
@@ -5750,18 +5965,27 @@ async function buildWidgets(projectPath, options = {}) {
     const widgetName = entry.name;
     const entryPath = entry.path.replace(/\\/g, "/");
     console.log(source_default.gray(`  - Building ${widgetName}...`));
-    const tempDir = import_node_path8.default.join(projectPath, ".mcp-use", widgetName);
-    await fs10.mkdir(tempDir, { recursive: true });
-    const relativeResourcesPath = import_node_path8.default.relative(tempDir, resourcesDir).replace(/\\/g, "/");
-    const mcpUsePath = import_node_path8.default.join(projectPath, "node_modules", "mcp-use");
-    const relativeMcpUsePath = import_node_path8.default.relative(tempDir, mcpUsePath).replace(/\\/g, "/");
+    const tempDir = import_node_path9.default.join(projectPath, ".mcp-use", widgetName);
+    await fs11.mkdir(tempDir, { recursive: true });
+    const relativeResourcesPath = import_node_path9.default.relative(tempDir, resourcesDir).replace(/\\/g, "/");
+    const mcpUsePath = import_node_path9.default.join(projectPath, "node_modules", "mcp-use");
+    const relativeMcpUsePath = import_node_path9.default.relative(tempDir, mcpUsePath).replace(/\\/g, "/");
+    const projectSrcDir = import_node_path9.default.join(projectPath, "src");
+    let projectSrcSourceLine = "";
+    try {
+      await (0, import_promises7.access)(projectSrcDir);
+      const relativeProjectSrcPath = import_node_path9.default.relative(tempDir, projectSrcDir).replace(/\\/g, "/");
+      projectSrcSourceLine = `@source "${relativeProjectSrcPath}";
+`;
+    } catch {
+    }
     const cssContent = `@import "tailwindcss";
 
 /* Configure Tailwind to scan the resources directory and mcp-use package */
 @source "${relativeResourcesPath}";
 @source "${relativeMcpUsePath}/**/*.{ts,tsx,js,jsx}";
-`;
-    await fs10.writeFile(import_node_path8.default.join(tempDir, "styles.css"), cssContent, "utf8");
+${projectSrcSourceLine}`;
+    await fs11.writeFile(import_node_path9.default.join(tempDir, "styles.css"), cssContent, "utf8");
     const entryContent = `import React from 'react'
 import { createRoot } from 'react-dom/client'
 import './styles.css'
@@ -5786,9 +6010,9 @@ if (container && Component) {
     <script type="module" src="/entry.tsx"></script>
   </body>
 </html>`;
-    await fs10.writeFile(import_node_path8.default.join(tempDir, "entry.tsx"), entryContent, "utf8");
-    await fs10.writeFile(import_node_path8.default.join(tempDir, "index.html"), htmlContent, "utf8");
-    const outDir = import_node_path8.default.join(
+    await fs11.writeFile(import_node_path9.default.join(tempDir, "entry.tsx"), entryContent, "utf8");
+    await fs11.writeFile(import_node_path9.default.join(tempDir, "index.html"), htmlContent, "utf8");
+    const outDir = import_node_path9.default.join(
       projectPath,
       "dist",
       "resources",
@@ -5798,12 +6022,12 @@ if (container && Component) {
     const baseUrl = mcpUrl ? `${mcpUrl}/${widgetName}/` : `/mcp-use/widgets/${widgetName}/`;
     let widgetMetadata = {};
     try {
-      const metadataTempDir = import_node_path8.default.join(
+      const metadataTempDir = import_node_path9.default.join(
         projectPath,
         ".mcp-use",
         `${widgetName}-metadata`
       );
-      await fs10.mkdir(metadataTempDir, { recursive: true });
+      await fs11.mkdir(metadataTempDir, { recursive: true });
       const { createServer } = await import("vite");
       const nodeStubsPlugin = {
         name: "node-stubs",
@@ -5831,15 +6055,16 @@ export default PostHog;
           return null;
         }
       };
+      const serverOnlyGuard = makeWidgetServerOnlyGuard(widgetName);
       const metadataServer = await createServer({
         root: metadataTempDir,
-        cacheDir: import_node_path8.default.join(metadataTempDir, ".vite-cache"),
-        plugins: [nodeStubsPlugin, tailwindcss(), react()],
-        resolve: {
-          alias: {
-            "@": resourcesDir
-          }
-        },
+        cacheDir: import_node_path9.default.join(metadataTempDir, ".vite-cache"),
+        plugins: [serverOnlyGuard, nodeStubsPlugin, tailwindcss(), react()],
+        // When the project has a tsconfig, enable Vite's native tsconfig-paths
+        // resolver so `@/*` (or any custom alias) resolves through the
+        // project's own paths config. Without a tsconfig, fall back to the
+        // legacy hardcoded alias.
+        resolve: hasProjectTsconfig ? { tsconfigPaths: true } : { alias: { "@": resourcesDir } },
         server: {
           middlewareMode: true
         },
@@ -5918,7 +6143,7 @@ export default PostHog;
       } finally {
         await metadataServer.close();
         try {
-          await fs10.rm(metadataTempDir, { recursive: true, force: true });
+          await fs11.rm(metadataTempDir, { recursive: true, force: true });
         } catch {
         }
       }
@@ -6013,12 +6238,14 @@ export default {
           return null;
         }
       };
+      const buildServerOnlyGuard = makeWidgetServerOnlyGuard(widgetName);
       const buildPlugins = inline ? [
+        buildServerOnlyGuard,
         buildNodeStubsPlugin,
         tailwindcss(),
         react(),
         (0, import_vite_plugin_singlefile.viteSingleFile)({ removeViteModuleLoader: true })
-      ] : [buildNodeStubsPlugin, tailwindcss(), react()];
+      ] : [buildServerOnlyGuard, buildNodeStubsPlugin, tailwindcss(), react()];
       await build({
         root: tempDir,
         base: baseUrl,
@@ -6037,11 +6264,10 @@ export default {
             }
           }
         },
-        resolve: {
-          alias: {
-            "@": resourcesDir
-          }
-        },
+        // When a tsconfig exists, enable Vite's native `resolve.tsconfigPaths`
+        // so the project's path aliases resolve naturally. Otherwise fall
+        // back to the legacy `@` → resourcesDir alias.
+        resolve: hasProjectTsconfig ? { tsconfigPaths: true } : { alias: { "@": resourcesDir } },
         optimizeDeps: {
           // Exclude Node.js-only packages from browser bundling
           exclude: ["posthog-node"]
@@ -6063,7 +6289,7 @@ export default {
             // Inline all assets under 100MB (effectively all)
           } : {},
           rolldownOptions: {
-            input: import_node_path8.default.join(tempDir, "index.html"),
+            input: import_node_path9.default.join(tempDir, "index.html"),
             external: (id) => {
               return false;
             }
@@ -6071,12 +6297,12 @@ export default {
         }
       });
       try {
-        const assetsDir = import_node_path8.default.join(outDir, "assets");
-        const assetFiles = await fs10.readdir(assetsDir);
+        const assetsDir = import_node_path9.default.join(outDir, "assets");
+        const assetFiles = await fs11.readdir(assetsDir);
         const jsFiles = assetFiles.filter((f) => f.endsWith(".js"));
         for (const jsFile of jsFiles) {
-          const jsPath = import_node_path8.default.join(assetsDir, jsFile);
-          let content = await fs10.readFile(jsPath, "utf8");
+          const jsPath = import_node_path9.default.join(assetsDir, jsFile);
+          let content = await fs11.readFile(jsPath, "utf8");
           const zodConfigPatterns = [
             // Non-minified: export const globalConfig = {}
             /export\s+const\s+globalConfig\s*=\s*\{\s*\}/g,
@@ -6095,7 +6321,7 @@ export default {
             }
           }
           if (patched) {
-            await fs10.writeFile(jsPath, content, "utf8");
+            await fs11.writeFile(jsPath, content, "utf8");
             console.log(source_default.gray(`    \u2192 Patched Zod JIT in ${jsFile}`));
           }
         }
@@ -6107,8 +6333,8 @@ export default {
       const mcpServerUrl = process.env.MCP_SERVER_URL;
       if (mcpServerUrl) {
         try {
-          const htmlPath = import_node_path8.default.join(outDir, "index.html");
-          let html = await fs10.readFile(htmlPath, "utf8");
+          const htmlPath = import_node_path9.default.join(outDir, "index.html");
+          let html = await fs11.readFile(htmlPath, "utf8");
           const injectionScript = `<script>window.__getFile = (filename) => { return "${mcpUrl}/${widgetName}/"+filename }; window.__mcpPublicUrl = "${mcpServerUrl}/mcp-use/public"; window.__mcpPublicAssetsUrl = "${mcpUrl}/public";</script>`;
           if (!html.includes("window.__mcpPublicUrl")) {
             html = html.replace(
@@ -6129,7 +6355,7 @@ export default {
     <base href="${mcpServerUrl}">`
             );
           }
-          await fs10.writeFile(htmlPath, html, "utf8");
+          await fs11.writeFile(htmlPath, html, "utf8");
           console.log(
             source_default.gray(`    \u2192 Injected MCP_SERVER_URL into ${widgetName}`)
           );
@@ -6143,22 +6369,32 @@ export default {
         }
       }
       console.log(source_default.green(`    \u2713 Built ${widgetName}`));
-      return { name: widgetName, metadata: widgetMetadata };
+      return {
+        status: "built",
+        name: widgetName,
+        metadata: widgetMetadata
+      };
     } catch (error) {
       console.error(source_default.red(`    \u2717 Failed to build ${widgetName}:`), error);
-      return null;
+      return { status: "failed", name: widgetName };
     }
   };
   const buildResults = await Promise.all(
     entries.map((entry) => buildSingleWidget(entry))
   );
-  const builtWidgets = buildResults.filter(
-    (result) => result !== null
+  const failed = buildResults.filter((r) => r.status === "failed");
+  if (failed.length > 0) {
+    const names = failed.map((f) => f.name).join(", ");
+    throw new Error(
+      `${failed.length} widget(s) failed to build: ${names}. See errors above.`
+    );
+  }
+  return buildResults.flatMap(
+    (r) => r.status === "built" ? [{ name: r.name, metadata: r.metadata }] : []
   );
-  return builtWidgets;
 }
 async function collectTsFiles(projectPath, includePatterns, excludePatterns) {
-  const { promises: fs10 } = await import("fs");
+  const { promises: fs11 } = await import("fs");
   const literalFiles = [];
   const dirPrefixes = [];
   for (const pattern of includePatterns) {
@@ -6173,7 +6409,7 @@ async function collectTsFiles(projectPath, includePatterns, excludePatterns) {
   for (const file of literalFiles) {
     if (/\.tsx?$/.test(file) && !file.endsWith(".d.ts")) {
       try {
-        await (0, import_promises7.access)(import_node_path8.default.join(projectPath, file));
+        await (0, import_promises7.access)(import_node_path9.default.join(projectPath, file));
         files.push(file);
       } catch {
       }
@@ -6181,13 +6417,13 @@ async function collectTsFiles(projectPath, includePatterns, excludePatterns) {
   }
   const excludeSet = new Set(excludePatterns.map((e) => e.replace(/\*+/g, "")));
   for (const prefix of dirPrefixes) {
-    const dirPath = import_node_path8.default.join(projectPath, prefix);
+    const dirPath = import_node_path9.default.join(projectPath, prefix);
     try {
-      const entries = await fs10.readdir(dirPath, { recursive: true });
+      const entries = await fs11.readdir(dirPath, { recursive: true });
       for (const entry of entries) {
         const entryStr = String(entry);
-        const rel = import_node_path8.default.join(prefix, entryStr);
-        if (/\.tsx?$/.test(entryStr) && !entryStr.endsWith(".d.ts") && !excludeSet.has(rel.split(import_node_path8.default.sep)[0])) {
+        const rel = import_node_path9.default.join(prefix, entryStr);
+        if (/\.tsx?$/.test(entryStr) && !entryStr.endsWith(".d.ts") && !excludeSet.has(rel.split(import_node_path9.default.sep)[0])) {
           files.push(rel);
         }
       }
@@ -6198,11 +6434,11 @@ async function collectTsFiles(projectPath, includePatterns, excludePatterns) {
 }
 async function transpileWithEsbuild(projectPath) {
   const esbuild = await import("esbuild");
-  const { promises: fs10 } = await import("fs");
-  const tsconfigPath = import_node_path8.default.join(projectPath, "tsconfig.json");
+  const { promises: fs11 } = await import("fs");
+  const tsconfigPath = import_node_path9.default.join(projectPath, "tsconfig.json");
   let tsconfig = {};
   try {
-    const raw = await fs10.readFile(tsconfigPath, "utf-8");
+    const raw = await fs11.readFile(tsconfigPath, "utf-8");
     tsconfig = JSON.parse(raw);
   } catch {
   }
@@ -6229,10 +6465,10 @@ async function transpileWithEsbuild(projectPath) {
   const target = (compilerOptions.target || "ES2022").toLowerCase();
   const moduleStr = (compilerOptions.module || "ESNext").toLowerCase();
   const format = moduleStr.includes("commonjs") ? "cjs" : "esm";
-  const outbase = compilerOptions.rootDir ? import_node_path8.default.resolve(projectPath, compilerOptions.rootDir) : projectPath;
+  const outbase = compilerOptions.rootDir ? import_node_path9.default.resolve(projectPath, compilerOptions.rootDir) : projectPath;
   await esbuild.build({
-    entryPoints: files.map((f) => import_node_path8.default.join(projectPath, f)),
-    outdir: import_node_path8.default.join(projectPath, outDir),
+    entryPoints: files.map((f) => import_node_path9.default.join(projectPath, f)),
+    outdir: import_node_path9.default.join(projectPath, outDir),
     outbase,
     bundle: false,
     format,
@@ -6244,21 +6480,42 @@ async function transpileWithEsbuild(projectPath) {
     logLevel: "warning"
   });
 }
-program.command("build").description("Build TypeScript and MCP UI widgets").option("-p, --path <path>", "Path to project directory", process.cwd()).option("--with-inspector", "Include inspector in production build").option(
+program.command("build").description("Build TypeScript and MCP UI widgets").option("-p, --path <path>", "Path to project directory", process.cwd()).option(
+  "--entry <file>",
+  "Path to MCP server entry file (relative to project)"
+).option(
+  "--widgets-dir <dir>",
+  "Path to widgets directory (relative to project)"
+).option(
+  "--mcp-dir <dir>",
+  "Folder holding the MCP entry + resources (e.g. 'src/mcp' for Next.js apps)"
+).option("--with-inspector", "Include inspector in production build").option(
   "--inline",
   "Inline all JS/CSS into HTML (required for VS Code MCP Apps)"
 ).option("--no-inline", "Keep JS/CSS as separate files (default)").option("--no-typecheck", "Skip TypeScript type checking (faster builds)").action(async (options) => {
   try {
-    const projectPath = import_node_path8.default.resolve(options.path);
-    const { promises: fs10 } = await import("fs");
+    const projectPath = import_node_path9.default.resolve(options.path);
+    const { promises: fs11 } = await import("fs");
     displayPackageVersions(projectPath);
+    const mcpDir = options.mcpDir;
+    const widgetsDir = resolveWidgetsDir(options.widgetsDir, mcpDir);
     const builtWidgets = await buildWidgets(projectPath, {
-      inline: options.inline ?? false
+      inline: options.inline ?? false,
+      widgetsDir
     });
     let sourceServerFile;
     try {
-      sourceServerFile = await findServerFile(projectPath);
-    } catch {
+      sourceServerFile = await findServerFile(
+        projectPath,
+        options.entry,
+        options.mcpDir
+      );
+    } catch (err) {
+      console.log(
+        source_default.yellow(
+          `\u26A0 Could not locate a server entry file: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
     }
     if (sourceServerFile) {
       console.log(source_default.gray("Generating tool registry types..."));
@@ -6276,17 +6533,25 @@ program.command("build").description("Build TypeScript and MCP UI widgets").opti
         );
       }
     }
-    console.log(source_default.gray("Building TypeScript..."));
-    await transpileWithEsbuild(projectPath);
-    console.log(source_default.green("\u2713 TypeScript build complete!"));
-    if (options.typecheck !== false) {
+    if (!mcpDir) {
+      console.log(source_default.gray("Building TypeScript..."));
+      await transpileWithEsbuild(projectPath);
+      console.log(source_default.green("\u2713 TypeScript build complete!"));
+    } else {
+      console.log(
+        source_default.gray(
+          "Skipping TypeScript transpile (--mcp-dir mode runs source via tsx at start time)"
+        )
+      );
+    }
+    if (options.typecheck !== false && !mcpDir) {
       console.log(source_default.gray("Type checking..."));
       try {
         await runCommand(
           "node",
           [
             "--max-old-space-size=4096",
-            import_node_path8.default.join(
+            import_node_path9.default.join(
               projectPath,
               "node_modules",
               "typescript",
@@ -6307,39 +6572,43 @@ program.command("build").description("Build TypeScript and MCP UI widgets").opti
     }
     let entryPoint;
     if (sourceServerFile) {
-      const baseName = import_node_path8.default.basename(sourceServerFile, ".ts") + ".js";
-      const possibleOutputs = [
-        `dist/${baseName}`,
-        // rootDir set to project root or src
-        `dist/src/${baseName}`,
-        // no rootDir, source in src/
-        `dist/${sourceServerFile.replace(/\.ts$/, ".js")}`
-        // exact path preserved
-      ];
-      for (const candidate of possibleOutputs) {
-        try {
-          await (0, import_promises7.access)(import_node_path8.default.join(projectPath, candidate));
-          entryPoint = candidate;
-          break;
-        } catch {
-          continue;
+      if (mcpDir) {
+        entryPoint = sourceServerFile;
+      } else {
+        const baseName = import_node_path9.default.basename(sourceServerFile, ".ts") + ".js";
+        const possibleOutputs = [
+          `dist/${baseName}`,
+          // rootDir set to project root or src
+          `dist/src/${baseName}`,
+          // no rootDir, source in src/
+          `dist/${sourceServerFile.replace(/\.ts$/, ".js")}`
+          // exact path preserved
+        ];
+        for (const candidate of possibleOutputs) {
+          try {
+            await (0, import_promises7.access)(import_node_path9.default.join(projectPath, candidate));
+            entryPoint = candidate;
+            break;
+          } catch {
+            continue;
+          }
         }
       }
     }
-    const publicDir = import_node_path8.default.join(projectPath, "public");
+    const publicDir = import_node_path9.default.join(projectPath, "public");
     try {
-      await fs10.access(publicDir);
+      await fs11.access(publicDir);
       console.log(source_default.gray("Copying public assets..."));
-      await fs10.cp(publicDir, import_node_path8.default.join(projectPath, "dist", "public"), {
+      await fs11.cp(publicDir, import_node_path9.default.join(projectPath, "dist", "public"), {
         recursive: true
       });
       console.log(source_default.green("\u2713 Public assets copied"));
     } catch {
     }
-    const manifestPath = import_node_path8.default.join(projectPath, "dist", "mcp-use.json");
+    const manifestPath = import_node_path9.default.join(projectPath, "dist", "mcp-use.json");
     let existingManifest = {};
     try {
-      const existingContent = await fs10.readFile(manifestPath, "utf-8");
+      const existingContent = await fs11.readFile(manifestPath, "utf-8");
       existingManifest = JSON.parse(existingContent);
     } catch {
     }
@@ -6361,8 +6630,8 @@ program.command("build").description("Build TypeScript and MCP UI widgets").opti
       // Server entry point for `mcp-use start`
       widgets: widgetsData
     };
-    await fs10.mkdir(import_node_path8.default.dirname(manifestPath), { recursive: true });
-    await fs10.writeFile(
+    await fs11.mkdir(import_node_path9.default.dirname(manifestPath), { recursive: true });
+    await fs11.writeFile(
       manifestPath,
       JSON.stringify(manifest, null, 2),
       "utf8"
@@ -6382,14 +6651,23 @@ program.command("build").description("Build TypeScript and MCP UI widgets").opti
     process.exit(1);
   }
 });
-program.command("dev").description("Run development server with auto-reload and inspector").option("-p, --path <path>", "Path to project directory", process.cwd()).option("--port <port>", "Server port", "3000").option(
+program.command("dev").description("Run development server with auto-reload and inspector").option("-p, --path <path>", "Path to project directory", process.cwd()).option(
+  "--entry <file>",
+  "Path to MCP server entry file (relative to project)"
+).option(
+  "--widgets-dir <dir>",
+  "Path to widgets directory (relative to project)"
+).option(
+  "--mcp-dir <dir>",
+  "Folder holding the MCP entry + resources (e.g. 'src/mcp' for Next.js apps)"
+).option("--port <port>", "Server port", "3000").option(
   "--host <host>",
   "Server host (use 0.0.0.0 to listen on all interfaces)",
   "0.0.0.0"
 ).option("--no-open", "Do not auto-open inspector").option("--no-hmr", "Disable hot module reloading (use tsx watch instead)").option("--tunnel", "Expose server through a tunnel").action(async (options) => {
   try {
     process.env.MCP_USE_CLI_DEV = "1";
-    const projectPath = import_node_path8.default.resolve(options.path);
+    const projectPath = import_node_path9.default.resolve(options.path);
     let port = parseInt(options.port, 10);
     const host = options.host;
     const useHmr = options.hmr !== false;
@@ -6400,13 +6678,24 @@ program.command("dev").description("Run development server with auto-reload and
       console.log(source_default.green.bold(`\u2713 Using port ${availablePort} instead`));
       port = availablePort;
     }
-    const serverFile = await findServerFile(projectPath);
+    const serverFile = await findServerFile(
+      projectPath,
+      options.entry,
+      options.mcpDir
+    );
+    {
+      const devMcpDir = options.mcpDir;
+      const devWidgetsDir = resolveWidgetsDir(options.widgetsDir, devMcpDir);
+      if (devWidgetsDir !== "resources") {
+        process.env.MCP_USE_WIDGETS_DIR = devWidgetsDir;
+      }
+    }
     let tunnelProcess = void 0;
     let tunnelSubdomain = void 0;
     let tunnelUrl = void 0;
     if (options.tunnel) {
       try {
-        const manifestPath = import_node_path8.default.join(projectPath, "dist", "mcp-use.json");
+        const manifestPath = import_node_path9.default.join(projectPath, "dist", "mcp-use.json");
         let existingSubdomain;
         try {
           const manifestContent = await (0, import_promises7.readFile)(manifestPath, "utf-8");
@@ -6455,7 +6744,7 @@ program.command("dev").description("Run development server with auto-reload and
             manifest.tunnel = {};
           }
           manifest.tunnel.subdomain = tunnelSubdomain;
-          await (0, import_promises7.mkdir)(import_node_path8.default.dirname(manifestPath), { recursive: true });
+          await (0, import_promises7.mkdir)(import_node_path9.default.dirname(manifestPath), { recursive: true });
           await (0, import_promises7.writeFile)(
             manifestPath,
             JSON.stringify(manifest, null, 2),
@@ -6482,22 +6771,35 @@ program.command("dev").description("Run development server with auto-reload and
     } else if (!process.env.MCP_URL) {
       process.env.MCP_URL = mcpUrl;
     }
+    const isNextJsProject = await detectNextJsProject(projectPath);
+    if (isNextJsProject) {
+      console.log(
+        source_default.gray(
+          "Next.js detected \u2014 installing server-runtime shims (server-only, next/cache, next/headers, next/navigation, next/server)"
+        )
+      );
+      await loadNextJsEnvFiles(projectPath);
+    }
     if (!useHmr) {
       console.log(source_default.gray("HMR disabled, using tsx watch (full restart)"));
       const processes = [];
-      const env2 = {
+      const baseEnv = {
+        // Inherit parent env (PATH, HOME, etc.) — without it, tsx can't
+        // resolve its own tooling in some setups.
+        ...process.env,
         PORT: String(port),
         HOST: host,
         NODE_ENV: "development",
         // Preserve user-provided MCP_URL (e.g., for reverse proxy setups)
         MCP_URL: process.env.MCP_URL || mcpUrl
       };
+      const env2 = isNextJsProject ? withNextShimsEnv(baseEnv) : baseEnv;
       const { createRequire: createRequire4 } = await import("module");
       let cmd;
       let args;
       try {
         const projectRequire = createRequire4(
-          import_node_path8.default.join(projectPath, "package.json")
+          import_node_path9.default.join(projectPath, "package.json")
         );
         const tsxPkgPath = projectRequire.resolve("tsx/package.json");
         const tsxPkg = JSON.parse(await (0, import_promises7.readFile)(tsxPkgPath, "utf-8"));
@@ -6509,7 +6811,7 @@ program.command("dev").description("Run development server with auto-reload and
         } else {
           throw new Error("No bin field found in tsx package.json");
         }
-        const tsxBin = import_node_path8.default.resolve(import_node_path8.default.dirname(tsxPkgPath), binPath);
+        const tsxBin = import_node_path9.default.resolve(import_node_path9.default.dirname(tsxPkgPath), binPath);
         cmd = "node";
         args = [tsxBin, "watch", serverFile];
       } catch (error) {
@@ -6584,18 +6886,56 @@ program.command("dev").description("Run development server with auto-reload and
         "HMR enabled - changes will hot reload without dropping connections"
       )
     );
+    if (isNextJsProject) {
+      const registered = await registerNextShimsInProcess();
+      if (!registered) {
+        console.warn(
+          source_default.yellow(
+            "[HMR] Warning: Next.js shim loader could not be found on disk. Importing server-only / next/cache / etc. will throw. Reinstall @mcp-use/cli to fix."
+          )
+        );
+      }
+    }
     const chokidarModule = await import("chokidar");
     const chokidar = chokidarModule.default || chokidarModule;
-    const { fileURLToPath: fileURLToPath2 } = await import("url");
+    const { fileURLToPath: fileURLToPath3 } = await import("url");
     const { createRequire: createRequire3 } = await import("module");
-    let tsImport = null;
+    const projectTsconfigPath = import_node_path9.default.join(projectPath, "tsconfig.json");
+    let tsconfigAvailable = false;
+    try {
+      await (0, import_promises7.access)(projectTsconfigPath);
+      tsconfigAvailable = true;
+      process.env.TSX_TSCONFIG_PATH = projectTsconfigPath;
+      if (process.cwd() !== projectPath) process.chdir(projectPath);
+    } catch {
+    }
+    let tsxLoaderActive = false;
     try {
       const projectRequire = createRequire3(
-        import_node_path8.default.join(projectPath, "package.json")
+        import_node_path9.default.join(projectPath, "package.json")
       );
-      const tsxApiPath = projectRequire.resolve("tsx/esm/api");
-      const tsxApi = await import((0, import_node_url2.pathToFileURL)(tsxApiPath).href);
-      tsImport = tsxApi.tsImport;
+      const tsxEsmApiPath = projectRequire.resolve("tsx/esm/api");
+      const tsxEsmApi = await import((0, import_node_url3.pathToFileURL)(tsxEsmApiPath).href);
+      if (typeof tsxEsmApi.register === "function") {
+        tsxEsmApi.register({
+          tsconfig: tsconfigAvailable ? projectTsconfigPath : void 0,
+          onImport: (url) => {
+            const filePath = url.startsWith("file://") ? fileURLToPath3(url) : url;
+            if (!filePath.includes("node_modules") && filePath.startsWith(projectPath)) {
+              console.debug(`[HMR] Loaded: ${url}`);
+            }
+          }
+        });
+        tsxLoaderActive = true;
+      }
+      try {
+        const tsxCjsApiPath = projectRequire.resolve("tsx/cjs/api");
+        const tsxCjsApi = await import((0, import_node_url3.pathToFileURL)(tsxCjsApiPath).href);
+        if (typeof tsxCjsApi.register === "function") {
+          tsxCjsApi.register();
+        }
+      } catch {
+      }
     } catch {
       console.log(
         source_default.yellow(
@@ -6603,25 +6943,15 @@ program.command("dev").description("Run development server with auto-reload and
         )
       );
     }
-    const serverFilePath = import_node_path8.default.join(projectPath, serverFile);
-    const serverFileUrl = (0, import_node_url2.pathToFileURL)(serverFilePath).href;
+    const serverFilePath = import_node_path9.default.join(projectPath, serverFile);
+    const serverFileUrl = (0, import_node_url3.pathToFileURL)(serverFilePath).href;
     globalThis.__mcpUseHmrMode = true;
     const importServerModule = async () => {
       const previousServer = globalThis.__mcpUseLastServer;
       globalThis.__mcpUseLastServer = null;
-      if (tsImport) {
-        await tsImport(`${serverFileUrl}?t=${Date.now()}`, {
-          parentURL: importMetaUrl,
-          onImport: (file) => {
-            const filePath = file.startsWith("file://") ? fileURLToPath2(file) : file;
-            if (!filePath.includes("node_modules") && filePath.startsWith(projectPath)) {
-              console.debug(`[HMR] Loaded: ${file}`);
-            }
-          }
-        });
-      } else {
-        await import(`${serverFileUrl}?t=${Date.now()}`);
+      if (!tsxLoaderActive) {
       }
+      await import(`${serverFileUrl}?t=${Date.now()}`);
       const instance = globalThis.__mcpUseLastServer;
       if (!instance) {
         globalThis.__mcpUseLastServer = previousServer;
@@ -6635,7 +6965,7 @@ program.command("dev").description("Run development server with auto-reload and
       if (instance === previousServer) {
         console.warn(
           source_default.yellow(
-            "[HMR] Warning: Module re-import returned the same server instance. The module may not have been re-evaluated. " + (!tsImport ? "Install tsx as a devDependency for reliable TypeScript HMR." : "This may be a tsx caching issue.")
+            "[HMR] Warning: Module re-import returned the same server instance. The module may not have been re-evaluated. " + (!tsxLoaderActive ? "Install tsx as a devDependency for reliable TypeScript HMR." : "This may be a module cache issue.")
           )
         );
         return null;
@@ -6710,8 +7040,8 @@ program.command("dev").description("Run development server with auto-reload and
     }
     let watcher = chokidar.watch(".", {
       cwd: projectPath,
-      ignored: (path7, stats) => {
-        const normalizedPath = path7.replace(/\\/g, "/");
+      ignored: (path8, stats) => {
+        const normalizedPath = path8.replace(/\\/g, "/");
         if (/(^|\/)\.[^/]/.test(normalizedPath)) {
           return true;
         }
@@ -6885,7 +7215,7 @@ program.command("dev").description("Run development server with auto-reload and
       }
       tunnelUrl = void 0;
       if (withTunnel) {
-        const manifestPath = import_node_path8.default.join(projectPath, "dist", "mcp-use.json");
+        const manifestPath = import_node_path9.default.join(projectPath, "dist", "mcp-use.json");
         let existingSubdomain;
         try {
           const manifestContent = await (0, import_promises7.readFile)(manifestPath, "utf-8");
@@ -6922,7 +7252,7 @@ program.command("dev").description("Run development server with auto-reload and
         tunnelSubdomain = tunnelInfo.subdomain;
         process.env.MCP_URL = tunnelUrl;
         try {
-          const mPath = import_node_path8.default.join(projectPath, "dist", "mcp-use.json");
+          const mPath = import_node_path9.default.join(projectPath, "dist", "mcp-use.json");
           let manifest = {};
           try {
             manifest = JSON.parse(await (0, import_promises7.readFile)(mPath, "utf-8"));
@@ -6930,7 +7260,7 @@ program.command("dev").description("Run development server with auto-reload and
           }
           if (!manifest.tunnel) manifest.tunnel = {};
           manifest.tunnel.subdomain = tunnelSubdomain;
-          await (0, import_promises7.mkdir)(import_node_path8.default.dirname(mPath), { recursive: true });
+          await (0, import_promises7.mkdir)(import_node_path9.default.dirname(mPath), { recursive: true });
           await (0, import_promises7.writeFile)(mPath, JSON.stringify(manifest, null, 2), "utf-8");
         } catch {
         }
@@ -7026,9 +7356,15 @@ program.command("dev").description("Run development server with auto-reload and
     process.exit(1);
   }
 });
-program.command("start").description("Start production server").option("-p, --path <path>", "Path to project directory", process.cwd()).option("--port <port>", "Server port", "3000").option("--tunnel", "Expose server through a tunnel").action(async (options) => {
+program.command("start").description("Start production server").option("-p, --path <path>", "Path to project directory", process.cwd()).option(
+  "--entry <file>",
+  "Path to MCP server entry file (relative to project)"
+).option(
+  "--mcp-dir <dir>",
+  "Folder holding the MCP entry + resources (e.g. 'src/mcp' for Next.js apps)"
+).option("--port <port>", "Server port", "3000").option("--tunnel", "Expose server through a tunnel").action(async (options) => {
   try {
-    const projectPath = import_node_path8.default.resolve(options.path);
+    const projectPath = import_node_path9.default.resolve(options.path);
     const portFlagProvided = process.argv.includes("--port") || process.argv.includes("-p") || process.argv.some((arg) => arg.startsWith("--port=")) || process.argv.some((arg) => arg.startsWith("-p="));
     let port = portFlagProvided ? parseInt(options.port, 10) : parseInt(process.env.PORT || options.port || "3000", 10);
     if (!await isPortAvailable(port)) {
@@ -7046,7 +7382,7 @@ program.command("start").description("Start production server").option("-p, --pa
     let tunnelSubdomain = void 0;
     if (options.tunnel) {
       try {
-        const manifestPath2 = import_node_path8.default.join(projectPath, "dist", "mcp-use.json");
+        const manifestPath2 = import_node_path9.default.join(projectPath, "dist", "mcp-use.json");
         let existingSubdomain;
         try {
           const manifestContent = await (0, import_promises7.readFile)(manifestPath2, "utf-8");
@@ -7101,7 +7437,7 @@ program.command("start").description("Start production server").option("-p, --pa
             manifest.tunnel = {};
           }
           manifest.tunnel.subdomain = subdomain;
-          await (0, import_promises7.mkdir)(import_node_path8.default.dirname(manifestPath2), { recursive: true });
+          await (0, import_promises7.mkdir)(import_node_path9.default.dirname(manifestPath2), { recursive: true });
           await (0, import_promises7.writeFile)(
             manifestPath2,
             JSON.stringify(manifest, null, 2),
@@ -7120,18 +7456,25 @@ program.command("start").description("Start production server").option("-p, --pa
       }
     }
     let serverFile;
-    const manifestPath = import_node_path8.default.join(projectPath, "dist", "mcp-use.json");
+    const manifestPath = import_node_path9.default.join(projectPath, "dist", "mcp-use.json");
     try {
       const manifestContent = await (0, import_promises7.readFile)(manifestPath, "utf-8");
       const manifest = JSON.parse(manifestContent);
       if (manifest.entryPoint) {
-        await (0, import_promises7.access)(import_node_path8.default.join(projectPath, manifest.entryPoint));
+        await (0, import_promises7.access)(import_node_path9.default.join(projectPath, manifest.entryPoint));
         serverFile = manifest.entryPoint;
       }
     } catch {
     }
     if (!serverFile) {
+      const startMcpDir = options.mcpDir;
       const serverCandidates = [
+        ...startMcpDir ? [
+          `${startMcpDir}/index.ts`,
+          `${startMcpDir}/index.tsx`,
+          `dist/${startMcpDir}/index.js`,
+          `dist/${startMcpDir}/server.js`
+        ] : [],
         "dist/index.js",
         "dist/server.js",
         "dist/src/index.js",
@@ -7139,7 +7482,7 @@ program.command("start").description("Start production server").option("-p, --pa
       ];
       for (const candidate of serverCandidates) {
         try {
-          await (0, import_promises7.access)(import_node_path8.default.join(projectPath, candidate));
+          await (0, import_promises7.access)(import_node_path9.default.join(projectPath, candidate));
           serverFile = candidate;
           break;
         } catch {
@@ -7163,18 +7506,53 @@ Looked for:
       process.exit(1);
     }
     console.log("Starting production server...");
-    const env2 = {
+    const isNextJsProject = await detectNextJsProject(projectPath);
+    if (isNextJsProject) {
+      console.log(
+        source_default.gray(
+          "Next.js detected \u2014 installing server-runtime shims for the production server"
+        )
+      );
+      await loadNextJsEnvFiles(projectPath);
+    }
+    const baseEnv = {
       ...process.env,
       PORT: String(port),
       NODE_ENV: "production"
     };
     if (mcpUrl) {
-      env2.MCP_URL = mcpUrl;
+      baseEnv.MCP_URL = mcpUrl;
       console.log(source_default.whiteBright(`Tunnel:   ${mcpUrl}/mcp`));
-    } else if (!env2.MCP_URL) {
-      env2.MCP_URL = `http://localhost:${port}`;
+    } else if (!baseEnv.MCP_URL) {
+      baseEnv.MCP_URL = `http://localhost:${port}`;
+    }
+    const env2 = isNextJsProject ? withNextShimsEnv(baseEnv) : baseEnv;
+    const isTsEntry = /\.(ts|tsx|mts|cts)$/.test(serverFile);
+    let spawnCmd = "node";
+    let spawnArgs = [serverFile];
+    if (isTsEntry) {
+      try {
+        const projectRequire = (0, import_node_module2.createRequire)(
+          import_node_path9.default.join(projectPath, "package.json")
+        );
+        const tsxPkgPath = projectRequire.resolve("tsx/package.json");
+        const tsxPkg = JSON.parse(await (0, import_promises7.readFile)(tsxPkgPath, "utf-8"));
+        const binField = typeof tsxPkg.bin === "string" ? tsxPkg.bin : tsxPkg.bin?.tsx ?? Object.values(tsxPkg.bin ?? {})[0];
+        if (!binField) throw new Error("tsx bin entry not found");
+        const tsxBin = import_node_path9.default.resolve(import_node_path9.default.dirname(tsxPkgPath), binField);
+        spawnCmd = "node";
+        spawnArgs = [tsxBin, serverFile];
+      } catch (error) {
+        console.log(
+          source_default.yellow(
+            `Could not resolve local tsx (${error instanceof Error ? error.message : String(error)}); falling back to npx`
+          )
+        );
+        spawnCmd = "npx";
+        spawnArgs = ["tsx", serverFile];
+      }
     }
-    const serverProc = (0, import_node_child_process9.spawn)("node", [serverFile], {
+    const serverProc = (0, import_node_child_process9.spawn)(spawnCmd, spawnArgs, {
       cwd: projectPath,
       stdio: "inherit",
       env: env2
@@ -7310,7 +7688,7 @@ program.addCommand(createSkillsCommand());
 program.command("generate-types").description(
   "Generate TypeScript type definitions for tools (writes .mcp-use/tool-registry.d.ts)"
 ).option("-p, --path <path>", "Path to project directory", process.cwd()).option("--server <file>", "Server entry file", "index.ts").action(async (options) => {
-  const projectPath = import_node_path8.default.resolve(options.path);
+  const projectPath = import_node_path9.default.resolve(options.path);
   try {
     console.log(source_default.blue("Generating tool registry types..."));
     const success = await generateToolRegistryTypesForServer(