@akram1110/notebook-mcp 1.0.3 → 1.5.1

package/README.md

@@ -1,27 +1,94 @@
-# notebook-mcp (NPM)
+# Notebook MCP
 
-This is an NPM wrapper for the **Python** package `notebook-mcp`.
+![Notebook MCP](../docs/notebook-mcp-pproduct-img.png)
 
-## Install
+AI-Native Intelligence Layer for Jupyter Notebooks using the Model Context Protocol (MCP)
 
-```bash
-npm i -g @akram1110/notebook-mcp
+Notebook MCP enables AI assistants (Cursor, Windsurf, Claude Desktop, etc.) to properly understand, analyze, and interact with `.ipynb` notebooks.
+
+---
+
+## ✨ Features
+
+* Builds dependency graphs across notebook cells
+* Detects stale and unexecuted cells
+* Generates rerun plans automatically
+* Provides focused context slices for LLM reasoning
+* Converts notebooks into deterministic Python scripts
+* Integrates with live Jupyter kernels
+* Allows runtime execution and variable inspection
+
+---
+
+## 📦 Installation
+
+```
+npm install -g @akram1110/notebook-mcp
 ```
 
-## Run
+This CLI automatically installs the Python backend via PyPI.
 
-```bash
+---
+
+## ⚙️ Requirements
+
+* Python 3.10+
+* pip
+* Node.js 18+
+
+---
+
+## 🚀 Usage
+
+Run MCP server:
+
+```
 notebook-mcp
 ```
 
-## Configuration
+---
+
+## 🧠 MCP Tools Provided
+
+### Notebook Analysis
+
+* notebook_analyze
+* notebook_context
+* notebook_export_script
+* notebook_state
+* notebook_rerun_plan
+
+### Jupyter Runtime
+
+* jupyter_list_sessions
+* jupyter_get_kernel
+* jupyter_execute
+* jupyter_inspect
+
+---
+
+## 🔌 Cursor MCP Configuration
+
+```
+{
+  "mcpServers": {
+    "notebook": {
+      "command": "notebook-mcp"
+    }
+  }
+}
+```
+
+---
+
+## 🌍 Python Backend
+
+Python package is available at:
+
+[https://pypi.org/project/notebook-mcp/](https://pypi.org/project/notebook-mcp/)
 
-- `NOTEBOOK_MCP_PYTHON`: path to the Python executable to use
-- `NOTEBOOK_MCP_PIP_SPEC`: pip spec to install (default: `notebook-mcp`)
-- `NOTEBOOK_MCP_PIP_ARGS`: extra args passed to `pip install` (space-separated)
+---
 
-Environment variables used by the server:
+## 💬 Feedback
 
-- `MCP_TRANSPORT`: `stdio` (default) or `streamable-http`
-- `MCP_HOST`, `MCP_PORT`
-- `JUPYTER_BASE_URL`, `JUPYTER_TOKEN`
+Issues and contributions welcome on GitHub.

package/lib/launcher.js

@@ -2,6 +2,14 @@ const { spawnSync, spawn } = require("node:child_process");
 const process = require("node:process");
 const which = require("which");
 
+function ok(msg) {
+  process.stdout.write(`✔ ${msg}\n`);
+  // Force flush for immediate visibility
+  if (process.stdout && typeof process.stdout.flush === 'function') {
+    process.stdout.flush();
+  }
+}
+
 function findPython() {
   const explicit = process.env.NOTEBOOK_MCP_PYTHON;
   if (explicit) return explicit;
@@ -34,7 +42,7 @@ function canImportNotebookMcp(python) {
 }
 
 function ensureInstalled(python) {
-  if (canImportNotebookMcp(python)) return;
+  if (canImportNotebookMcp(python)) return false;
 
   const spec = process.env.NOTEBOOK_MCP_PIP_SPEC || "notebook-mcp";
   const extraArgs = (process.env.NOTEBOOK_MCP_PIP_ARGS || "").split(" ").filter(Boolean);
@@ -48,6 +56,8 @@ function ensureInstalled(python) {
         "Check that your Python environment is the one you expect (NOTEBOOK_MCP_PYTHON)."
     );
   }
+
+  return true;
 }
 
 async function launch(argv) {
@@ -59,7 +69,11 @@ async function launch(argv) {
     );
   }
 
-  ensureInstalled(python);
+  ok(`Python detected (${python})`);
+
+  const installed = ensureInstalled(python);
+  if (installed) ok("Backend installed (notebook-mcp)");
+  else ok("Backend already installed (notebook-mcp)");
 
   // Run as module so this works even if Scripts/ is not on PATH.
   const child = spawn(python, ["-m", "notebook_mcp.server", ...argv], {
@@ -67,6 +81,8 @@ async function launch(argv) {
     env: process.env,
   });
 
+  ok("MCP server running");
+
   return new Promise((resolve, reject) => {
     child.on("error", reject);
     child.on("exit", (code, signal) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akram1110/notebook-mcp",
-  "version": "1.0.3",
+  "version": "1.5.1",
   "description": "NPM wrapper that launches the notebook-mcp Python MCP server",
   "license": "MIT",
   "main": "lib/launcher.js",
@@ -26,12 +26,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/your-org/notebook-mcp"
+    "url": "git+https://github.com/akram-side-projects/notebook-mcp.git"
   },
   "bugs": {
-    "url": "https://github.com/your-org/notebook-mcp/issues"
+    "url": "https://github.com/akram-side-projects/notebook-mcp/issues"
   },
-  "homepage": "https://github.com/your-org/notebook-mcp#readme",
+  "homepage": "https://github.com/akram-side-projects/notebook-mcp#readme",
   "engines": {
     "node": ">=18"
   },