@fre4x/jupyter 1.0.46 → 1.0.49

package/README.md

@@ -8,7 +8,7 @@ Jupyter Notebook MCP server for reading, writing, executing code in `.ipynb` fil
 - **Execute**: Run code cells in a real Jupyter kernel over the Jupyter WebSocket protocol.
 - **Control**: Launch or connect to a local Jupyter server, list kernels, and open notebooks in the browser.
 - **Mock Mode**: Development without a real Jupyter server using `MOCK=true`.
-- **Auto Start**: In non-mock mode the MCP process starts or connects to Jupyter before accepting requests.
+- **Auto Start**: In non-mock mode, the Jupyter server starts during MCP server startup.
 
 ## Tools
 
@@ -55,7 +55,8 @@ MOCK=true npx @fre4x/jupyter
 - `MOCK=true` keeps the old fixture-only behavior.
 - Without `MOCK=true`, the server first tries `JUPYTER_SERVER_URL` if provided.
 - Otherwise it launches a local Jupyter process (`jupyter lab`, then notebook fallbacks) with `--no-browser`.
-- After the server is ready, it opens the Jupyter UI in your default browser.
+- The Jupyter runtime is initialized before the MCP server finishes startup, so `list_tools` and later tool calls share the same ready runtime.
+- After the server is ready, it opens the Jupyter UI in your default browser (if `JUPYTER_AUTO_OPEN` is not `false`).
 - If `JUPYTER_START_NOTEBOOK_PATH` is set, that notebook is opened directly; otherwise the root Jupyter UI is opened.
 
 ## Environment Variables
@@ -63,6 +64,6 @@ MOCK=true npx @fre4x/jupyter
 - `JUPYTER_SERVER_URL`: Use an already-running Jupyter server instead of launching one.
 - `JUPYTER_TOKEN`: Optional token for an external Jupyter server.
 - `JUPYTER_ROOT_DIR`: Root directory for managed Jupyter startup. Defaults to the current working directory.
-- `JUPYTER_AUTO_OPEN`: Set to `false` to skip browser launch on MCP startup.
+- `JUPYTER_AUTO_OPEN`: Set to `false` to skip browser launch when the server starts.
 - `JUPYTER_START_NOTEBOOK_PATH`: Notebook to open automatically on startup.
 - `JUPYTER_KERNEL_NAME`: Kernel name used when code execution needs to create a kernel. Defaults to `python3`.

package/dist/index.js

@@ -49277,6 +49277,10 @@ var STARTUP_TIMEOUT_MS = Number.parseInt(
   process.env.JUPYTER_STARTUP_TIMEOUT_MS || "30000",
   10
 );
+var STARTUP_LOG_TAIL_MAX_CHARS = Number.parseInt(
+  process.env.JUPYTER_STARTUP_LOG_TAIL_MAX_CHARS || "16384",
+  10
+);
 var EXECUTION_TIMEOUT_MS = Number.parseInt(
   process.env.JUPYTER_EXECUTION_TIMEOUT_MS || "30000",
   10
@@ -49351,6 +49355,13 @@ function parseServerUrlFromOutput(output) {
   }
   return void 0;
 }
+function appendOutputTail(current, chunk, maxChars = STARTUP_LOG_TAIL_MAX_CHARS) {
+  if (maxChars <= 0) {
+    return "";
+  }
+  const next = current + chunk;
+  return next.length > maxChars ? next.slice(-maxChars) : next;
+}
 function buildLaunchCandidates(rootDir) {
   return [
     {
@@ -49425,11 +49436,17 @@ async function launchManagedServer() {
           });
           let output = "";
           let settled = false;
+          let readinessCheckInFlight = false;
+          const cleanupListeners = () => {
+            child.stdout?.off("data", handleChunk);
+            child.stderr?.off("data", handleChunk);
+          };
           const timeout = setTimeout(() => {
             if (settled) {
               return;
             }
             settled = true;
+            cleanupListeners();
             child.kill("SIGTERM");
             reject(
               new Error(
@@ -49444,15 +49461,21 @@ ${output.trim()}`
             }
             settled = true;
             clearTimeout(timeout);
+            cleanupListeners();
             reject(error48);
           };
           const maybeResolve = async () => {
+            if (settled || readinessCheckInFlight) {
+              return;
+            }
             const parsed = parseServerUrlFromOutput(output);
-            if (!parsed || settled) {
+            if (!parsed) {
               return;
             }
+            readinessCheckInFlight = true;
             settled = true;
             clearTimeout(timeout);
+            cleanupListeners();
             const runtime2 = {
               ...parsed,
               frontend: candidate.frontend,
@@ -49469,10 +49492,18 @@ ${output.trim()}`
             } catch (error48) {
               child.kill("SIGTERM");
               reject(error48);
+            } finally {
+              readinessCheckInFlight = false;
             }
           };
           const handleChunk = (chunk) => {
-            output += chunk.toString("utf8");
+            if (settled) {
+              return;
+            }
+            output = appendOutputTail(
+              output,
+              chunk.toString("utf8")
+            );
             void maybeResolve();
           };
           child.stdout.on("data", handleChunk);
@@ -49500,9 +49531,16 @@ ${output.trim()}`
       failures.push(`${candidate.label}: ${message}`);
     }
   }
-  throw new Error(
-    `Unable to start a local Jupyter server. Tried: ${failures.join(" | ")}`
-  );
+  const allMissing = failures.every((f) => f.includes("ENOENT"));
+  const combinedMessage = `Unable to start a local Jupyter server. Tried: ${failures.join(" | ")}`;
+  if (allMissing) {
+    throw new Error(
+      `${combinedMessage}
+
+[Hint] Jupyter seems to be missing. Please install it with: pip install jupyterlab`
+    );
+  }
+  throw new Error(combinedMessage);
 }
 async function connectToExternalServer() {
   const configuredUrl = process.env.JUPYTER_SERVER_URL?.trim();
@@ -49526,7 +49564,10 @@ async function connectToExternalServer() {
 async function ensureJupyterRuntime(options) {
   if (runtimeState.runtime) {
     if (options?.openBrowser && !runtimeState.startupBrowserOpened) {
-      await openJupyterInBrowser(options.notebookPath);
+      await openRuntimeInBrowser(
+        runtimeState.runtime,
+        options.notebookPath
+      );
       runtimeState.startupBrowserOpened = true;
     }
     return runtimeState.runtime;
@@ -49542,8 +49583,11 @@ async function ensureJupyterRuntime(options) {
   }
   const runtime = await runtimeState.startupPromise;
   runtimeState.startupPromise = void 0;
+  console.error(
+    `[jupyter] Connected to ${runtime.source} Jupyter server at ${runtime.baseUrl}`
+  );
   if (options?.openBrowser && !runtimeState.startupBrowserOpened) {
-    await openJupyterInBrowser(options.notebookPath);
+    await openRuntimeInBrowser(runtime, options.notebookPath);
     runtimeState.startupBrowserOpened = true;
   }
   return runtime;
@@ -49584,12 +49628,15 @@ function buildJupyterOpenUrl(runtime, notebookPath) {
   );
   return appendToken(url3, runtime.token);
 }
-async function openJupyterInBrowser(notebookPath, overrideUrl) {
-  const runtime = await ensureJupyterRuntime();
+async function openRuntimeInBrowser(runtime, notebookPath, overrideUrl) {
   const target = overrideUrl || buildJupyterOpenUrl(runtime, notebookPath);
   await openTarget(target);
   return target;
 }
+async function openJupyterInBrowser(notebookPath, overrideUrl) {
+  const runtime = await ensureJupyterRuntime();
+  return openRuntimeInBrowser(runtime, notebookPath, overrideUrl);
+}
 async function listJupyterKernels() {
   const runtime = await ensureJupyterRuntime();
   const response = await createHttpClient(runtime).get("/api/kernels");
@@ -49798,7 +49845,14 @@ async function executeCode(code, requestedKernelId) {
 
 // src/api.ts
 function createApiError(message, statusCode) {
-  const hint = statusCode === 404 ? "The requested resource was not found." : "Check your inputs and retry.";
+  let hint = statusCode === 404 ? "The requested resource was not found." : "Check your inputs and retry.";
+  if (message.includes("Unable to start a local Jupyter server")) {
+    hint = "Jupyter is not installed or not in your PATH. Please install it (e.g., pip install jupyterlab).";
+  } else if (message.includes("Timed out waiting for Jupyter server")) {
+    hint = "The Jupyter server started but is not responding. Check your firewall or resource usage.";
+  } else if (message.includes("ECONNREFUSED")) {
+    hint = "Connection refused. Ensure the Jupyter server is running and accessible.";
+  }
   const detail = statusCode ? ` (HTTP ${statusCode})` : "";
   return {
     isError: true,
@@ -50099,13 +50153,10 @@ async function main() {
       "[jupyter] Running in MOCK mode \u2014 no real local actions or API calls."
     );
   } else {
-    const runtime = await ensureJupyterRuntime({
+    await ensureJupyterRuntime({
       openBrowser: shouldAutoOpenOnStartup(),
       notebookPath: getStartupNotebookPath()
     });
-    console.error(
-      `[jupyter] Connected to ${runtime.source} Jupyter server at ${runtime.baseUrl}`
-    );
   }
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@fre4x/jupyter",
-  "version": "1.0.46",
+  "version": "1.0.49",
   "description": "Jupyter Notebook MCP server",
   "main": "dist/index.js",
   "bin": {
-    "jupyter": "dist/index.js"
+    "fre4x-jupyter": "dist/index.js"
   },
   "files": [
     "dist"
@@ -17,7 +17,7 @@
     "prepublishOnly": "npm run typecheck && npm run build",
     "test": "vitest run --exclude dist",
     "test:watch": "vitest",
-    "inspector": "cross-env MOCK=true npx @modelcontextprotocol/inspector node dist/index.js"
+    "inspector": "node ../scripts/run-official-inspector.mjs node dist/index.js"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",