@plutojl/mcp 0.2.0 → 0.4.0

package/dist/cli.cjs

@@ -31779,7 +31779,7 @@ var require_cookie = __commonJS({
   "../../node_modules/cookie/index.js"(exports2) {
     "use strict";
     exports2.parse = parse6;
-    exports2.serialize = serialize;
+    exports2.serialize = serialize2;
     var __toString = Object.prototype.toString;
     var __hasOwnProperty = Object.prototype.hasOwnProperty;
     var cookieNameRegExp = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
@@ -31838,7 +31838,7 @@ var require_cookie = __commonJS({
       }
       return min;
     }
-    function serialize(name, val, opt) {
+    function serialize2(name, val, opt) {
       var enc = opt && opt.encode || encodeURIComponent;
       if (typeof enc !== "function") {
         throw new TypeError("option encode is invalid");
@@ -33743,7 +33743,7 @@ var require_uri_all = __commonJS({
         }
         return output.join("");
       }
-      function serialize(components) {
+      function serialize2(components) {
         var options = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
         var protocol = options.iri ? IRI_PROTOCOL : URI_PROTOCOL;
         var uriTokens = [];
@@ -33799,8 +33799,8 @@ var require_uri_all = __commonJS({
         var skipNormalization = arguments[3];
         var target = {};
         if (!skipNormalization) {
-          base2 = parse6(serialize(base2, options), options);
-          relative = parse6(serialize(relative, options), options);
+          base2 = parse6(serialize2(base2, options), options);
+          relative = parse6(serialize2(relative, options), options);
         }
         options = options || {};
         if (!options.tolerant && relative.scheme) {
@@ -33851,26 +33851,26 @@ var require_uri_all = __commonJS({
       }
       function resolve(baseURI, relativeURI, options) {
         var schemelessOptions = assign2({ scheme: "null" }, options);
-        return serialize(resolveComponents(parse6(baseURI, schemelessOptions), parse6(relativeURI, schemelessOptions), schemelessOptions, true), schemelessOptions);
+        return serialize2(resolveComponents(parse6(baseURI, schemelessOptions), parse6(relativeURI, schemelessOptions), schemelessOptions, true), schemelessOptions);
       }
       function normalize(uri, options) {
         if (typeof uri === "string") {
-          uri = serialize(parse6(uri, options), options);
+          uri = serialize2(parse6(uri, options), options);
         } else if (typeOf(uri) === "object") {
-          uri = parse6(serialize(uri, options), options);
+          uri = parse6(serialize2(uri, options), options);
         }
         return uri;
       }
       function equal(uriA, uriB, options) {
         if (typeof uriA === "string") {
-          uriA = serialize(parse6(uriA, options), options);
+          uriA = serialize2(parse6(uriA, options), options);
         } else if (typeOf(uriA) === "object") {
-          uriA = serialize(uriA, options);
+          uriA = serialize2(uriA, options);
         }
         if (typeof uriB === "string") {
-          uriB = serialize(parse6(uriB, options), options);
+          uriB = serialize2(parse6(uriB, options), options);
         } else if (typeOf(uriB) === "object") {
-          uriB = serialize(uriB, options);
+          uriB = serialize2(uriB, options);
         }
         return uriA === uriB;
       }
@@ -33889,7 +33889,7 @@ var require_uri_all = __commonJS({
           }
           return components;
         },
-        serialize: function serialize2(components, options) {
+        serialize: function serialize3(components, options) {
           var secure = String(components.scheme).toLowerCase() === "https";
           if (components.port === (secure ? 443 : 80) || components.port === "") {
             components.port = void 0;
@@ -33920,7 +33920,7 @@ var require_uri_all = __commonJS({
           wsComponents.query = void 0;
           return wsComponents;
         },
-        serialize: function serialize2(wsComponents, options) {
+        serialize: function serialize3(wsComponents, options) {
           if (wsComponents.port === (isSecure(wsComponents) ? 443 : 80) || wsComponents.port === "") {
             wsComponents.port = void 0;
           }
@@ -34094,7 +34094,7 @@ var require_uri_all = __commonJS({
           }
           return uuidComponents;
         },
-        serialize: function serialize2(uuidComponents, options) {
+        serialize: function serialize3(uuidComponents, options) {
           var urnComponents = uuidComponents;
           urnComponents.nss = (uuidComponents.uuid || "").toLowerCase();
           return urnComponents;
@@ -34112,7 +34112,7 @@ var require_uri_all = __commonJS({
       exports3.pctDecChars = pctDecChars;
       exports3.parse = parse6;
       exports3.removeDotSegments = removeDotSegments;
-      exports3.serialize = serialize;
+      exports3.serialize = serialize2;
       exports3.resolveComponents = resolveComponents;
       exports3.resolve = resolve;
       exports3.normalize = normalize;
@@ -39140,8 +39140,8 @@ var require_ajv = __commonJS({
           delete this._refs[schemaKeyRef];
           return this;
         case "object":
-          var serialize = this._opts.serialize;
-          var cacheKey = serialize ? serialize(schemaKeyRef) : schemaKeyRef;
+          var serialize2 = this._opts.serialize;
+          var cacheKey = serialize2 ? serialize2(schemaKeyRef) : schemaKeyRef;
           this._cache.del(cacheKey);
           var id = this._getId(schemaKeyRef);
           if (id) {
@@ -39164,8 +39164,8 @@ var require_ajv = __commonJS({
     function _addSchema(schema, skipValidation, meta, shouldAddSchema) {
       if (typeof schema != "object" && typeof schema != "boolean")
         throw new Error("schema should be object or boolean");
-      var serialize = this._opts.serialize;
-      var cacheKey = serialize ? serialize(schema) : schema;
+      var serialize2 = this._opts.serialize;
+      var cacheKey = serialize2 ? serialize2(schema) : schema;
       var cached = this._cache.get(cacheKey);
       if (cached) return cached;
       shouldAddSchema = shouldAddSchema || this._opts.addUsedSchema !== false;
@@ -39349,6 +39349,7 @@ Run options:
   --pluto-port <port>      Pluto server port (default: ${DEFAULTS.plutoPort})
   --pluto-url <url>        Connect to existing Pluto server (skip starting one)
   --julia-version <ver>    Julia version via juliaup (default: ${DEFAULTS.juliaVersion})
+  --no-pluto               Start MCP server only, without starting Pluto
 
 Install options:
   --target <target>        Config target: claude-code, copilot, all (default: claude-code)
@@ -39440,6 +39441,8 @@ function parseArgs(argv) {
       args.force = true;
     } else if (flag === "--raw") {
       args.raw = true;
+    } else if (flag === "--no-pluto") {
+      args.noPluto = true;
     } else {
       console.warn(`Unknown flag: ${flag}`);
     }
@@ -39478,7 +39481,8 @@ function resolveRunConfig(args) {
     plutoPort: args.plutoPort ?? envInt("PLUTO_PORT") ?? file.plutoPort ?? DEFAULTS.plutoPort,
     plutoUrl: args.plutoUrl ?? process.env.PLUTO_SERVER_URL ?? file.serverUrl ?? void 0,
     juliaVersion: args.juliaVersion ?? process.env.JULIA_VERSION ?? file.juliaVersion ?? DEFAULTS.juliaVersion,
-    workDir
+    workDir,
+    noPluto: args.noPluto ?? false
   };
 }
 function resolveInstallArgs(args) {
@@ -54678,6 +54682,116 @@ end`,
     });
   }
 };
+var NOTEBOOK_HEADER = "### A Pluto.jl notebook ###";
+var CELL_ID_DELIMITER = "# \u2554\u2550\u2561 ";
+var CELL_METADATA_PREFIX = "# \u2560\u2550\u2561 ";
+var ORDER_DELIMITER = "# \u2560\u2550";
+var ORDER_DELIMITER_FOLDED = "# \u255F\u2500";
+var DISABLED_PREFIX = "#=\u2560\u2550\u2561\n";
+var DISABLED_SUFFIX = "\n  \u2560\u2550\u2561 =#";
+var PTOML_CELL_ID = "00000000-0000-0000-0000-000000000001";
+var MTOML_CELL_ID$1 = "00000000-0000-0000-0000-000000000002";
+var DEFAULT_CELL_METADATA = {
+  disabled: false,
+  show_logs: true,
+  skip_as_script: false
+};
+function generateBindMacro() {
+  return [
+    "",
+    "# This Pluto notebook uses @bind for interactivity. When running this notebook outside of Pluto, the following 'mock version' of @bind gives bound variables a default value (instead of an error).",
+    "macro bind(def, element)",
+    "    quote",
+    '        local iv = try Base.loaded_modules[Base.PkgId(Base.UUID("6e696c72-6542-2067-7265-42206c756150"), "AbstractPlutoDingetjes")].Bonds.initial_value catch; b -> missing; end',
+    "        local el = $(esc(element))",
+    "        global $(esc(def)) = Core.applicable(Base.get, el) ? Base.get(el) : iv(el)",
+    "        el",
+    "    end",
+    "end"
+  ];
+}
+function serializeCellMetadata(metadata) {
+  const lines = [];
+  if (metadata.disabled && !metadata._implicit_disabled) {
+    lines.push(CELL_METADATA_PREFIX + "disabled = true");
+  }
+  if (metadata.show_logs !== void 0 && metadata.show_logs !== DEFAULT_CELL_METADATA.show_logs) {
+    lines.push(CELL_METADATA_PREFIX + `show_logs = ${metadata.show_logs}`);
+  }
+  if (metadata.skip_as_script !== void 0 && metadata.skip_as_script !== DEFAULT_CELL_METADATA.skip_as_script) {
+    lines.push(
+      CELL_METADATA_PREFIX + `skip_as_script = ${metadata.skip_as_script}`
+    );
+  }
+  return [
+    ...lines,
+    ...Object.entries(metadata).filter(([name, entry]) => {
+      return !["skip_as_script", "show_logs", "disabled"].includes(name);
+    }).map(
+      ([name, entry]) => `${CELL_METADATA_PREFIX}${name} = ${JSON.stringify(entry)}`
+    )
+  ];
+}
+function serialize(notebookData) {
+  const lines = [];
+  lines.push(NOTEBOOK_HEADER);
+  lines.push(`# ${notebookData.pluto_version || "v0.20.10"}`);
+  lines.push("");
+  if (notebookData.metadata && notebookData.metadata._raw_metadata_lines) {
+    for (const metadataLine of notebookData.metadata._raw_metadata_lines) {
+      lines.push("#> " + metadataLine);
+    }
+    lines.push("");
+  }
+  lines.push("using Markdown");
+  lines.push("using InteractiveUtils");
+  if (notebookData._has_bind_macro) {
+    lines.push(...generateBindMacro());
+  }
+  lines.push("");
+  const topologicalOrder = notebookData._topological_order || notebookData.cell_order || [];
+  const cellInputs = notebookData.cell_inputs || {};
+  for (const cellId of topologicalOrder) {
+    const cellInput = cellInputs[cellId];
+    if (!cellInput) continue;
+    lines.push(CELL_ID_DELIMITER + cellId);
+    const metadata = cellInput.metadata || {};
+    const metadataLines = serializeCellMetadata(metadata);
+    lines.push(...metadataLines);
+    let code = cellInput.code || "";
+    if (metadata.disabled && !code.startsWith(DISABLED_PREFIX)) {
+      code = DISABLED_PREFIX + code + DISABLED_SUFFIX;
+    }
+    lines.push(code);
+    lines.push("");
+  }
+  const packageCells = notebookData._package_cells || {};
+  if (packageCells[PTOML_CELL_ID]) {
+    lines.push(CELL_ID_DELIMITER + PTOML_CELL_ID);
+    lines.push(packageCells[PTOML_CELL_ID]);
+    lines.push("");
+  }
+  if (packageCells[MTOML_CELL_ID$1]) {
+    lines.push(CELL_ID_DELIMITER + MTOML_CELL_ID$1);
+    lines.push(packageCells[MTOML_CELL_ID$1]);
+    lines.push("");
+  }
+  lines.push(CELL_ID_DELIMITER + "Cell order:");
+  const cellOrder = notebookData.cell_order || [];
+  for (const cellId of cellOrder) {
+    const cellInput = cellInputs[cellId];
+    if (!cellInput) continue;
+    const delimiter = cellInput.code_folded ? ORDER_DELIMITER_FOLDED : ORDER_DELIMITER;
+    lines.push(delimiter + cellId);
+  }
+  if (packageCells[PTOML_CELL_ID]) {
+    lines.push(ORDER_DELIMITER_FOLDED + PTOML_CELL_ID);
+  }
+  if (packageCells[MTOML_CELL_ID$1]) {
+    lines.push(ORDER_DELIMITER_FOLDED + MTOML_CELL_ID$1);
+  }
+  return lines.join("\n") + "\n";
+}
 
 // ../../src/plutoManager.ts
 var import_events = require("events");
@@ -54949,6 +55063,16 @@ var PlutoManager = class {
     await worker2.deleteSnippets([result.cell_id]);
     return result;
   }
+  /**
+   * Get the serialized notebook content (.jl format) for saving to disk
+   */
+  getNotebookContent(worker2) {
+    const state = worker2.getState();
+    if (!state) {
+      throw new Error("Notebook state not available");
+    }
+    return serialize(state);
+  }
   /**
    * Close all notebook connections
    */
@@ -54984,6 +55108,7 @@ var PlutoManager = class {
 
 // ../../src/mcp-server-http.ts
 var import_express = __toESM(require_express2(), 1);
+var import_promises = require("fs/promises");
 
 // ../../node_modules/zod/v3/external.js
 var external_exports = {};
@@ -62666,7 +62791,7 @@ data: ${JSON.stringify(message)}
 };
 
 // ../../src/PLUTO_GUIDE.md
-var PLUTO_GUIDE_default = '# Pluto.jl Notebook Guide for AI Tools\n\nThis guide explains how to work with Pluto.jl notebooks, including cell structure, reactivity rules, PlutoUI components, and best practices.\n\n## Table of Contents\n\n- [Notebook Structure](#notebook-structure)\n- [Cell Rules and Reactivity](#cell-rules-and-reactivity)\n- [Markdown Cells](#markdown-cells)\n- [PlutoUI Components](#plutoui-components)\n- [Combining Markdown and PlutoUI](#combining-markdown-and-plutoui)\n- [Best Practices](#best-practices)\n- [Common Patterns](#common-patterns)\n\n---\n\n## Notebook Structure\n\n### File Format\n\nA Pluto notebook is a Julia file (`.jl`) with a specific structure:\n\n```julia\n### A Pluto.jl notebook ###\n# v0.20.19\n\nusing Markdown\nusing InteractiveUtils\n\n# \u2554\u2550\u2561 cell-uuid-1\n# \u2560\u2550\u2561 disabled = false\n# \u2560\u2550\u2561 show_logs = true\n# \u2560\u2550\u2561 skip_as_script = false\nmd"""\n# Your content here\n"""\n\n# \u2554\u2550\u2561 cell-uuid-2\nx = 10\n\n# \u2554\u2550\u2561 Cell order:\n# \u2560\u2550cell-uuid-1\n# \u2560\u2550cell-uuid-2\n```\n\n### Cell Markers\n\nEach cell starts with a unique identifier:\n\n- `# \u2554\u2550\u2561 <uuid>` - Cell boundary marker\n- Cell UUIDs are automatically generated\n- Cells contain Julia code, markdown, or expressions\n\n### Cell Metadata\n\nCells can have metadata comments:\n\n- `# \u2560\u2550\u2561 disabled = false` - Cell execution state\n- `# \u2560\u2550\u2561 show_logs = true` - Show cell output logs\n- `# \u2560\u2550\u2561 skip_as_script = false` - Include cell when exporting as script\n\n### Cell Order Section\n\nAt the end of the notebook:\n\n```julia\n# \u2554\u2550\u2561 Cell order:\n# \u2560\u2550cell-uuid-1\n# \u2560\u2550cell-uuid-2\n# \u2560\u2550cell-uuid-3\n```\n\nThis defines the display order of cells (not execution order).\n\n---\n\n## Cell Rules and Reactivity\n\n### Reactive Execution Model\n\n**Key Principle**: Pluto automatically determines execution order based on variable dependencies.\n\n#### Rules\n\n1. **One Variable per Cell (Assignment)**\n\n   ```julia\n   # \u2705 CORRECT\n   x = 10\n\n   # \u274C WRONG - Cannot assign same variable in another cell\n   x = 20  # Error: Multiple definitions of x\n   ```\n\n2. **Use `begin...end` for Multiple Statements**\n\n   ```julia\n   # \u2705 CORRECT\n   begin\n       x = 10\n       y = 20\n       z = x + y\n   end\n   ```\n\n3. **Automatic Dependency Tracking**\n\n   ```julia\n   # Cell 1\n   a = 5\n\n   # Cell 2 (depends on Cell 1)\n   b = a * 2  # Automatically re-runs when \'a\' changes\n\n   # Cell 3 (depends on Cell 2)\n   c = b + 10  # Automatically re-runs when \'b\' changes\n   ```\n\n4. **No Hidden State**\n   - Every variable is defined exactly once\n   - Execution order is determined by dependencies, not cell order\n   - Deleting a cell removes its variables completely\n\n5. **Import/Package Management**\n\n   ```julia\n   begin\n       import Pkg\n       Pkg.activate(; temp=true)\n       Pkg.add(["Plots", "DataFrames", "PlutoUI"])\n       using Plots\n       using PlutoUI\n   end\n   ```\n\n---\n\n## Markdown Cells\n\n### Basic Markdown Syntax\n\nMarkdown cells use triple-quote syntax:\n\n```julia\nmd"""\n# Heading 1\n## Heading 2\n### Heading 3\n\n**Bold text**\n*Italic text*\n\n- Bullet point 1\n- Bullet point 2\n\n1. Numbered item 1\n2. Numbered item 2\n\n[Link text](https://example.com)\n"""\n```\n\n### LaTeX Math\n\n```julia\nmd"""\nInline math: $E = mc^2$\n\nDisplay math:\n$$\n\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}\n$$\n"""\n```\n\n### Interpolating Variables\n\nUse `$()` to embed Julia expressions:\n\n```julia\nx = 42\n\nmd"""\nThe value of x is $(x).\n\nComputed value: $(x * 2)\n"""\n```\n\n### Tables in Markdown\n\n```julia\nmd"""\n| Column 1 | Column 2 | Column 3 |\n| -------- | -------- | -------- |\n| Value A  | Value B  | Value C  |\n| Value D  | Value E  | Value F  |\n"""\n```\n\n---\n\n## PlutoUI Components\n\nPlutoUI provides interactive widgets using the `@bind` macro.\n\n### Installation\n\n```julia\nbegin\n    import Pkg\n    Pkg.add("PlutoUI")\n    using PlutoUI\nend\n```\n\n### @bind Macro\n\nThe `@bind` macro connects a UI element to a variable:\n\n```julia\n@bind variable_name Widget(options...)\n```\n\n### Available Components\n\n#### 1. Slider\n\nCreates a slider for numeric input.\n\n```julia\n# Basic slider\n@bind x Slider(1:100)\n\n# Slider with default value and display\n@bind temperature Slider(0:0.1:100, default=25, show_value=true)\n\n# Slider with custom range\n@bind alpha Slider(0.0:0.01:1.0, default=0.5)\n```\n\n**Parameters:**\n\n- `range` - Range of values (e.g., `1:10` or `0.0:0.1:1.0`)\n- `default` - Initial value\n- `show_value` - Display current value (true/false)\n\n#### 2. TextField\n\nText input field.\n\n```julia\n# Single-line text field\n@bind name TextField()\n\n# Text field with default value\n@bind description TextField(default="Enter description")\n\n# Multi-line textarea\n@bind notes TextField((50, 10))  # (cols, rows)\n```\n\n**Parameters:**\n\n- `default` - Initial text value\n- `dims=(cols, rows)` - For multi-line textarea\n\n#### 3. NumberField\n\nNumeric input field.\n\n```julia\n# Number field with range\n@bind count NumberField(1:100, default=10)\n\n# Float number field\n@bind value NumberField(0.0:0.1:10.0, default=5.0)\n```\n\n**Parameters:**\n\n- `range` - Valid number range\n- `default` - Initial value\n\n#### 4. CheckBox\n\nBoolean checkbox.\n\n```julia\n# Simple checkbox\n@bind enabled CheckBox()\n\n# Checkbox with default value\n@bind show_details CheckBox(default=true)\n```\n\n**Parameters:**\n\n- `default` - Initial state (true/false)\n\n#### 5. Select\n\nDropdown selection.\n\n```julia\n# Select from array\n@bind color Select(["red", "green", "blue"])\n\n# Select with default\n@bind option Select(["Option A", "Option B", "Option C"], default="Option B")\n\n# Select from pairs (value => label)\n@bind choice Select([1 => "First", 2 => "Second", 3 => "Third"])\n```\n\n**Parameters:**\n\n- `options` - Array of options or pairs\n- `default` - Initially selected value\n\n#### 6. MultiSelect\n\nMultiple selection dropdown.\n\n```julia\n# Multi-select\n@bind colors MultiSelect(["red", "green", "blue", "yellow"])\n\n# Multi-select with defaults\n@bind selected MultiSelect(\n    ["A", "B", "C", "D"],\n    default=["A", "C"]\n)\n```\n\n#### 7. Button\n\nClickable button.\n\n```julia\n# Simple button\n@bind clicked Button("Click me!")\n\n# Button that increments on each click\n@bind click_count Button("Increment")\n```\n\n**Note**: Button sends the same value each time clicked, triggering reactive cells.\n\n#### 8. Radio\n\nRadio button group (single selection).\n\n```julia\n@bind choice Radio(["Option 1", "Option 2", "Option 3"])\n\n@bind size Radio(["Small", "Medium", "Large"], default="Medium")\n```\n\n#### 9. FilePicker\n\nFile upload widget.\n\n```julia\n@bind uploaded_file FilePicker()\n\n# Access file content\nfile_data = uploaded_file["data"]\nfile_name = uploaded_file["name"]\n```\n\n#### 10. Clock\n\nTimer that ticks at regular intervals.\n\n```julia\n# Tick every second\n@bind tick Clock()\n\n# Tick every 0.5 seconds\n@bind tick Clock(0.5)\n```\n\n#### 11. DateField\n\nDate picker.\n\n```julia\n@bind selected_date DateField()\n\n@bind start_date DateField(default=Dates.today())\n```\n\n---\n\n## Combining Markdown and PlutoUI\n\n### Inline Widgets in Tables\n\nYou can embed PlutoUI widgets directly in markdown tables:\n\n```julia\nmd"""\n| Parameter | Description | Units | Value |\n| --------- | ----------- | ----- | ----- |\n| `T_inf` | Ambient temperature | K | $(@bind T_inf NumberField(0:500, default=300)) |\n| `h` | Heat transfer coefficient | W/(m\xB2\xB7K) | $(@bind h Slider(0.0:0.1:1.0, default=0.7)) |\n| `mass` | Mass | kg | $(@bind m NumberField(0.0:0.1:10.0, default=1.0)) |\n"""\n```\n\n### Using Widget Values in Markdown\n\n```julia\n@bind speed Slider(1:100, default=50, show_value=true)\n\nmd"""\n## Speed Control\n\nCurrent speed: $(speed) km/h\n\nStatus: $(speed > 80 ? "\u{1F534} Fast" : "\u{1F7E2} Normal")\n"""\n```\n\n### Embedded Plots and Computations\n\n```julia\nmd"""\n# Wave Parameters\n\n| Parameter | Value |\n| --------- | ----- |\n| Amplitude | $(@bind amplitude Slider(0.1:0.1:5.0, default=1.0, show_value=true)) |\n| Frequency | $(@bind frequency Slider(0.1:0.1:10.0, default=1.0, show_value=true)) |\n\n## Waveform\n\n$(begin\n    x = 0:0.01:2\u03C0\n    y = amplitude .* sin.(frequency .* x)\n    plot(x, y, label="sin wave", xlabel="x", ylabel="y")\nend)\n"""\n```\n\n### Dynamic Content Generation\n\n```julia\nbegin\n    @bind param1 NumberField(0:100, default=50)\n    @bind param2 Slider(0.0:0.1:1.0, default=0.5)\n\n    result = param1 * param2\n\n    md"""\n    # Interactive Calculator\n\n    | Input | Value |\n    | ----- | ----- |\n    | Parameter 1 | $(param1) |\n    | Parameter 2 | $(param2) |\n    | **Result** | **$(result)** |\n\n    The computation shows: $(param1) \xD7 $(param2) = $(result)\n    """\nend\n```\n\n---\n\n## Best Practices\n\n### 1. Package Management\n\nAlways use a cell at the beginning for package management:\n\n```julia\nbegin\n    import Pkg\n    Pkg.activate(; temp=true)\n    Pkg.add(["Plots", "DataFrames", "PlutoUI"])\n    using Plots\n    using DataFrames\n    using PlutoUI\nend\n```\n\n### 2. Organize with Markdown Headers\n\n```julia\nmd"""\n# Section 1: Data Loading\n\nLoad and prepare the data.\n"""\n\n# ... code cells ...\n\nmd"""\n# Section 2: Analysis\n\nPerform the analysis.\n"""\n\n# ... code cells ...\n```\n\n### 3. Use `begin...end` for Complex Logic\n\n```julia\nbegin\n    # Multiple related computations\n    data = load_data()\n    cleaned = clean_data(data)\n    result = analyze(cleaned)\n    result\nend\n```\n\n### 4. Display the Last Expression\n\nThe last expression in a cell is automatically displayed:\n\n```julia\nbegin\n    x = 10\n    y = 20\n    x + y  # This value is displayed\nend\n```\n\n### 5. Suppress Output with Semicolon\n\n```julia\n# Suppress display\nlarge_data = load_large_dataset();\n\n# Show specific output\nprintln("Data loaded successfully")\n```\n\n### 6. Use @doc for Documentation\n\n```julia\nmd"""\n## Function Documentation\n\n$(@doc my_function)\n"""\n```\n\n### 7. Bind Multiple Related Widgets\n\n```julia\nmd"""\n## Configuration\n\n| Parameter | Value |\n| --------- | ----- |\n| X | $(@bind x Slider(1:10, default=5)) |\n| Y | $(@bind y Slider(1:10, default=5)) |\n\nSum: $(x + y)\nProduct: $(x * y)\n"""\n```\n\n---\n\n## Common Patterns\n\n### Pattern 1: Interactive Parameter Sweep\n\n```julia\n# Define parameters with widgets\n@bind param Slider(1:100, default=50, show_value=true)\n\n# Compute based on parameter\nresult = expensive_computation(param)\n\n# Display results\nplot(result)\n```\n\n### Pattern 2: Conditional Display\n\n```julia\n@bind show_advanced CheckBox(default=false)\n```\n\n```julia\n\nmd"""\nShow advanced options: $(show_advanced ? "\u2705 Enabled" : "\u274C Disabled")\n\n$(if show_advanced\n    md"## Advanced Settings\n\n    Configure advanced parameters here."\nelse\n    md""\nend)\n"""\n```\n\n### Pattern 3: Multi-Step Workflow\n\n```julia\nmd"""\n# Step 1: Select Dataset\n$(@bind dataset Select(["Dataset A", "Dataset B", "Dataset C"]))\n"""\n\n# Load selected dataset\ndata = load_dataset(dataset)\n\nmd"""\n# Step 2: Configure Analysis\n$(@bind threshold Slider(0:0.1:1, default=0.5, show_value=true))\n"""\n\n# Perform analysis\nresults = analyze(data, threshold)\n\nmd"""\n# Step 3: Results\n\n$(plot(results))\n"""\n```\n\n### Pattern 4: Table with Embedded Widgets\n\n```julia\nmd"""\n# Parameter Configuration\n\n| Parameter | Description | Units | Value |\n| --------- | ----------- | ----- | ----- |\n| `temperature` | Operating temperature | \xB0C | $(@bind temp NumberField(0:200, default=25)) |\n| `pressure` | Operating pressure | bar | $(@bind pres NumberField(0:100, default=1)) |\n| `enabled` | Enable feature | - | $(@bind enabled CheckBox(default=true)) |\n"""\n```\n\n```julia\n# Use the bound values\nconfig = (temperature=temp, pressure=pres, enabled=enabled)\n```\n\n### Pattern 5: Real-time Visualization\n\n```julia\n@bind time Clock(0.1)  # Update every 0.1 seconds\n\nbegin\n    # Generate time-varying data\n    t = time\n    x = 0:0.1:2\u03C0\n    y = sin.(x .+ t)\n\n    plot(x, y, label="sin(x + t)", ylims=(-1.5, 1.5))\nend\n```\n\n### Pattern 6: Form-like Interface\n\n```julia\nmd"""\n# User Profile\n\n| Field | Input |\n| ----- | ----- |\n| Name | $(@bind user_name TextField(default="")) |\n| Age | $(@bind user_age NumberField(1:120, default=25)) |\n| Country | $(@bind country Select(["USA", "UK", "Canada", "Other"])) |\n| Subscribe | $(@bind subscribe CheckBox(default=false)) |\n\n$(@bind submit_button Button("Submit"))\n"""\n```\n\n```julia\nbegin\n    profile = (\n        name = user_name,\n        age = user_age,\n        country = country,\n        subscribe = subscribe\n    )\n\n    md"""\n    ## Submitted Profile\n\n    - **Name**: $(profile.name)\n    - **Age**: $(profile.age)\n    - **Country**: $(profile.country)\n    - **Newsletter**: $(profile.subscribe ? "\u2705 Yes" : "\u274C No")\n    """\nend\n```\n\n---\n\n## Summary\n\n### Key Takeaways\n\n1. **Reactivity**: Cells automatically re-run based on dependencies\n2. **One Variable Rule**: Each variable can only be defined once across all cells\n3. **`@bind` Macro**: Connects UI widgets to variables\n4. **Markdown Integration**: Use `$()` to embed Julia expressions in markdown\n5. **Tables + Widgets**: Combine markdown tables with PlutoUI for interactive forms\n6. **No Hidden State**: All variables are explicit and traceable\n\n### Quick Reference\n\n**Slider**: `@bind x Slider(1:100, default=50, show_value=true)`\n\n**TextField**: `@bind text TextField(default="")`\n\n**NumberField**: `@bind n NumberField(0:100, default=10)`\n\n**CheckBox**: `@bind checked CheckBox(default=false)`\n\n**Select**: `@bind choice Select(["A", "B", "C"])`\n\n**Button**: `@bind clicked Button("Click")`\n\n**Markdown + Widget**: `$(@bind x Slider(1:10))`\n\n**Markdown + Variable**: `The value is $(x)`\n\n---\n\n## Additional Resources\n\n- Official Pluto.jl: <https://plutojl.org/>\n- PlutoUI Documentation: <https://github.com/JuliaPluto/PlutoUI.jl>\n- Featured Examples: <https://featured.plutojl.org/>\n\n---\n\n**Note for AI Tools**: When creating or modifying Pluto notebooks:\n\n- Always respect the one-variable-per-cell rule\n- Use `begin...end` blocks for multiple statements\n- Ensure cell UUIDs are unique\n- Maintain the cell order section at the end\n- Use `@bind` for all interactive widgets\n- Test reactivity by changing dependent variables\n';
+var PLUTO_GUIDE_default = '# Pluto.jl Notebook Guide for AI Tools\n\nThis guide explains how to work with Pluto.jl notebooks, including cell structure, reactivity rules, PlutoUI components, and best practices.\n\n## Important: Server Startup Times\n\nStarting a Pluto server involves installing Julia packages and precompiling them. **The first run can take several minutes** (2-10 minutes depending on the system). If `start_pluto_server` or `open_notebook` appears to hang or times out:\n\n1. **Do not retry immediately** \u2014 the server is likely still starting up.\n2. **Wait 30-60 seconds**, then call `get_notebook_status` to check progress.\n3. **Subsequent runs are much faster** since packages are cached.\n\nIf a tool call times out, that does NOT mean it failed \u2014 the server may still be starting in the background. Check `get_notebook_status` before retrying.\n\n## Working with Notebooks via MCP\n\nThese rules are critical when interacting with Pluto notebooks through the MCP API:\n\n### File Ownership\n\n- **Never edit the `.pluto.jl` file on disk while the notebook is open** \u2014 Pluto owns that file. Changes made outside the MCP API will be ignored or overwritten.\n- All cell mutations (create, edit, delete) must go through the MCP tools.\n- To persist changes to disk, call `save_notebook` explicitly. **Notebooks are NOT auto-saved.**\n\n### Handling Timeouts\n\n- If `create_cell` times out, the cell was likely still created in Pluto. Use `list_cells` to check before retrying \u2014 creating the same cell twice causes "Multiple definitions" errors.\n- For slow operations (e.g. `import Pkg; Pkg.add(...)`), prefer: (1) `edit_cell` with `run=false` to set the code, then (2) `execute_cell` to run it. This avoids timeout-induced phantom cells.\n- Use `delete_cell` to remove any accidental duplicate cells.\n\n### Pluto Reactivity Rules\n\n- **Each variable can only be defined in one cell.** If you get a "Multiple definitions" error, use `list_cells` to find the duplicate, then `delete_cell` to remove it.\n- When you edit a cell, Pluto automatically re-runs all cells that depend on the changed variables.\n- Prefer creating package cells with `import Pkg; Pkg.activate(; temp=true); Pkg.add([...])` in one cell, and `using PackageName` in a separate cell.\n\n### Recommended Workflow\n\n1. `open_notebook` (file must exist on disk first)\n2. `list_cells` to see current state\n3. `create_cell` / `edit_cell` / `delete_cell` to make changes\n4. `read_cell` to inspect outputs\n5. `save_notebook` to persist to disk when done\n6. `get_notebook_url` to give the user a browser link\n\n## Table of Contents\n\n- [Notebook Structure](#notebook-structure)\n- [Cell Rules and Reactivity](#cell-rules-and-reactivity)\n- [Markdown Cells](#markdown-cells)\n- [PlutoUI Components](#plutoui-components)\n- [Combining Markdown and PlutoUI](#combining-markdown-and-plutoui)\n- [Best Practices](#best-practices)\n- [Common Patterns](#common-patterns)\n\n---\n\n## Notebook Structure\n\n### File Format\n\nA Pluto notebook is a Julia file (`.jl`) with a specific structure:\n\n```julia\n### A Pluto.jl notebook ###\n# v0.20.19\n\nusing Markdown\nusing InteractiveUtils\n\n# \u2554\u2550\u2561 cell-uuid-1\n# \u2560\u2550\u2561 disabled = false\n# \u2560\u2550\u2561 show_logs = true\n# \u2560\u2550\u2561 skip_as_script = false\nmd"""\n# Your content here\n"""\n\n# \u2554\u2550\u2561 cell-uuid-2\nx = 10\n\n# \u2554\u2550\u2561 Cell order:\n# \u2560\u2550cell-uuid-1\n# \u2560\u2550cell-uuid-2\n```\n\n### Cell Markers\n\nEach cell starts with a unique identifier:\n\n- `# \u2554\u2550\u2561 <uuid>` - Cell boundary marker\n- Cell UUIDs are automatically generated\n- Cells contain Julia code, markdown, or expressions\n\n### Cell Metadata\n\nCells can have metadata comments:\n\n- `# \u2560\u2550\u2561 disabled = false` - Cell execution state\n- `# \u2560\u2550\u2561 show_logs = true` - Show cell output logs\n- `# \u2560\u2550\u2561 skip_as_script = false` - Include cell when exporting as script\n\n### Cell Order Section\n\nAt the end of the notebook:\n\n```julia\n# \u2554\u2550\u2561 Cell order:\n# \u2560\u2550cell-uuid-1\n# \u2560\u2550cell-uuid-2\n# \u2560\u2550cell-uuid-3\n```\n\nThis defines the display order of cells (not execution order).\n\n---\n\n## Cell Rules and Reactivity\n\n### Reactive Execution Model\n\n**Key Principle**: Pluto automatically determines execution order based on variable dependencies.\n\n#### Rules\n\n1. **One Variable per Cell (Assignment)**\n\n   ```julia\n   # \u2705 CORRECT\n   x = 10\n\n   # \u274C WRONG - Cannot assign same variable in another cell\n   x = 20  # Error: Multiple definitions of x\n   ```\n\n2. **Use `begin...end` for Multiple Statements**\n\n   ```julia\n   # \u2705 CORRECT\n   begin\n       x = 10\n       y = 20\n       z = x + y\n   end\n   ```\n\n3. **Automatic Dependency Tracking**\n\n   ```julia\n   # Cell 1\n   a = 5\n\n   # Cell 2 (depends on Cell 1)\n   b = a * 2  # Automatically re-runs when \'a\' changes\n\n   # Cell 3 (depends on Cell 2)\n   c = b + 10  # Automatically re-runs when \'b\' changes\n   ```\n\n4. **No Hidden State**\n   - Every variable is defined exactly once\n   - Execution order is determined by dependencies, not cell order\n   - Deleting a cell removes its variables completely\n\n5. **Import/Package Management**\n\n   ```julia\n   begin\n       import Pkg\n       Pkg.activate(; temp=true)\n       Pkg.add(["Plots", "DataFrames", "PlutoUI"])\n       using Plots\n       using PlutoUI\n   end\n   ```\n\n---\n\n## Markdown Cells\n\n### Basic Markdown Syntax\n\nMarkdown cells use triple-quote syntax:\n\n```julia\nmd"""\n# Heading 1\n## Heading 2\n### Heading 3\n\n**Bold text**\n*Italic text*\n\n- Bullet point 1\n- Bullet point 2\n\n1. Numbered item 1\n2. Numbered item 2\n\n[Link text](https://example.com)\n"""\n```\n\n### LaTeX Math\n\n```julia\nmd"""\nInline math: $E = mc^2$\n\nDisplay math:\n$$\n\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}\n$$\n"""\n```\n\n### Interpolating Variables\n\nUse `$()` to embed Julia expressions:\n\n```julia\nx = 42\n\nmd"""\nThe value of x is $(x).\n\nComputed value: $(x * 2)\n"""\n```\n\n### Tables in Markdown\n\n```julia\nmd"""\n| Column 1 | Column 2 | Column 3 |\n| -------- | -------- | -------- |\n| Value A  | Value B  | Value C  |\n| Value D  | Value E  | Value F  |\n"""\n```\n\n---\n\n## PlutoUI Components\n\nPlutoUI provides interactive widgets using the `@bind` macro.\n\n### Installation\n\n```julia\nbegin\n    import Pkg\n    Pkg.add("PlutoUI")\n    using PlutoUI\nend\n```\n\n### @bind Macro\n\nThe `@bind` macro connects a UI element to a variable:\n\n```julia\n@bind variable_name Widget(options...)\n```\n\n### Available Components\n\n#### 1. Slider\n\nCreates a slider for numeric input.\n\n```julia\n# Basic slider\n@bind x Slider(1:100)\n\n# Slider with default value and display\n@bind temperature Slider(0:0.1:100, default=25, show_value=true)\n\n# Slider with custom range\n@bind alpha Slider(0.0:0.01:1.0, default=0.5)\n```\n\n**Parameters:**\n\n- `range` - Range of values (e.g., `1:10` or `0.0:0.1:1.0`)\n- `default` - Initial value\n- `show_value` - Display current value (true/false)\n\n#### 2. TextField\n\nText input field.\n\n```julia\n# Single-line text field\n@bind name TextField()\n\n# Text field with default value\n@bind description TextField(default="Enter description")\n\n# Multi-line textarea\n@bind notes TextField((50, 10))  # (cols, rows)\n```\n\n**Parameters:**\n\n- `default` - Initial text value\n- `dims=(cols, rows)` - For multi-line textarea\n\n#### 3. NumberField\n\nNumeric input field.\n\n```julia\n# Number field with range\n@bind count NumberField(1:100, default=10)\n\n# Float number field\n@bind value NumberField(0.0:0.1:10.0, default=5.0)\n```\n\n**Parameters:**\n\n- `range` - Valid number range\n- `default` - Initial value\n\n#### 4. CheckBox\n\nBoolean checkbox.\n\n```julia\n# Simple checkbox\n@bind enabled CheckBox()\n\n# Checkbox with default value\n@bind show_details CheckBox(default=true)\n```\n\n**Parameters:**\n\n- `default` - Initial state (true/false)\n\n#### 5. Select\n\nDropdown selection.\n\n```julia\n# Select from array\n@bind color Select(["red", "green", "blue"])\n\n# Select with default\n@bind option Select(["Option A", "Option B", "Option C"], default="Option B")\n\n# Select from pairs (value => label)\n@bind choice Select([1 => "First", 2 => "Second", 3 => "Third"])\n```\n\n**Parameters:**\n\n- `options` - Array of options or pairs\n- `default` - Initially selected value\n\n#### 6. MultiSelect\n\nMultiple selection dropdown.\n\n```julia\n# Multi-select\n@bind colors MultiSelect(["red", "green", "blue", "yellow"])\n\n# Multi-select with defaults\n@bind selected MultiSelect(\n    ["A", "B", "C", "D"],\n    default=["A", "C"]\n)\n```\n\n#### 7. Button\n\nClickable button.\n\n```julia\n# Simple button\n@bind clicked Button("Click me!")\n\n# Button that increments on each click\n@bind click_count Button("Increment")\n```\n\n**Note**: Button sends the same value each time clicked, triggering reactive cells.\n\n#### 8. Radio\n\nRadio button group (single selection).\n\n```julia\n@bind choice Radio(["Option 1", "Option 2", "Option 3"])\n\n@bind size Radio(["Small", "Medium", "Large"], default="Medium")\n```\n\n#### 9. FilePicker\n\nFile upload widget.\n\n```julia\n@bind uploaded_file FilePicker()\n\n# Access file content\nfile_data = uploaded_file["data"]\nfile_name = uploaded_file["name"]\n```\n\n#### 10. Clock\n\nTimer that ticks at regular intervals.\n\n```julia\n# Tick every second\n@bind tick Clock()\n\n# Tick every 0.5 seconds\n@bind tick Clock(0.5)\n```\n\n#### 11. DateField\n\nDate picker.\n\n```julia\n@bind selected_date DateField()\n\n@bind start_date DateField(default=Dates.today())\n```\n\n---\n\n## Combining Markdown and PlutoUI\n\n### Inline Widgets in Tables\n\nYou can embed PlutoUI widgets directly in markdown tables:\n\n```julia\nmd"""\n| Parameter | Description | Units | Value |\n| --------- | ----------- | ----- | ----- |\n| `T_inf` | Ambient temperature | K | $(@bind T_inf NumberField(0:500, default=300)) |\n| `h` | Heat transfer coefficient | W/(m\xB2\xB7K) | $(@bind h Slider(0.0:0.1:1.0, default=0.7)) |\n| `mass` | Mass | kg | $(@bind m NumberField(0.0:0.1:10.0, default=1.0)) |\n"""\n```\n\n### Using Widget Values in Markdown\n\n```julia\n@bind speed Slider(1:100, default=50, show_value=true)\n\nmd"""\n## Speed Control\n\nCurrent speed: $(speed) km/h\n\nStatus: $(speed > 80 ? "\u{1F534} Fast" : "\u{1F7E2} Normal")\n"""\n```\n\n### Embedded Plots and Computations\n\n```julia\nmd"""\n# Wave Parameters\n\n| Parameter | Value |\n| --------- | ----- |\n| Amplitude | $(@bind amplitude Slider(0.1:0.1:5.0, default=1.0, show_value=true)) |\n| Frequency | $(@bind frequency Slider(0.1:0.1:10.0, default=1.0, show_value=true)) |\n\n## Waveform\n\n$(begin\n    x = 0:0.01:2\u03C0\n    y = amplitude .* sin.(frequency .* x)\n    plot(x, y, label="sin wave", xlabel="x", ylabel="y")\nend)\n"""\n```\n\n### Dynamic Content Generation\n\n```julia\nbegin\n    @bind param1 NumberField(0:100, default=50)\n    @bind param2 Slider(0.0:0.1:1.0, default=0.5)\n\n    result = param1 * param2\n\n    md"""\n    # Interactive Calculator\n\n    | Input | Value |\n    | ----- | ----- |\n    | Parameter 1 | $(param1) |\n    | Parameter 2 | $(param2) |\n    | **Result** | **$(result)** |\n\n    The computation shows: $(param1) \xD7 $(param2) = $(result)\n    """\nend\n```\n\n---\n\n## Best Practices\n\n### 1. Package Management\n\nAlways use a cell at the beginning for package management:\n\n```julia\nbegin\n    import Pkg\n    Pkg.activate(; temp=true)\n    Pkg.add(["Plots", "DataFrames", "PlutoUI"])\n    using Plots\n    using DataFrames\n    using PlutoUI\nend\n```\n\n### 2. Organize with Markdown Headers\n\n```julia\nmd"""\n# Section 1: Data Loading\n\nLoad and prepare the data.\n"""\n\n# ... code cells ...\n\nmd"""\n# Section 2: Analysis\n\nPerform the analysis.\n"""\n\n# ... code cells ...\n```\n\n### 3. Use `begin...end` for Complex Logic\n\n```julia\nbegin\n    # Multiple related computations\n    data = load_data()\n    cleaned = clean_data(data)\n    result = analyze(cleaned)\n    result\nend\n```\n\n### 4. Display the Last Expression\n\nThe last expression in a cell is automatically displayed:\n\n```julia\nbegin\n    x = 10\n    y = 20\n    x + y  # This value is displayed\nend\n```\n\n### 5. Suppress Output with Semicolon\n\n```julia\n# Suppress display\nlarge_data = load_large_dataset();\n\n# Show specific output\nprintln("Data loaded successfully")\n```\n\n### 6. Use @doc for Documentation\n\n```julia\nmd"""\n## Function Documentation\n\n$(@doc my_function)\n"""\n```\n\n### 7. Bind Multiple Related Widgets\n\n```julia\nmd"""\n## Configuration\n\n| Parameter | Value |\n| --------- | ----- |\n| X | $(@bind x Slider(1:10, default=5)) |\n| Y | $(@bind y Slider(1:10, default=5)) |\n\nSum: $(x + y)\nProduct: $(x * y)\n"""\n```\n\n---\n\n## Common Patterns\n\n### Pattern 1: Interactive Parameter Sweep\n\n```julia\n# Define parameters with widgets\n@bind param Slider(1:100, default=50, show_value=true)\n\n# Compute based on parameter\nresult = expensive_computation(param)\n\n# Display results\nplot(result)\n```\n\n### Pattern 2: Conditional Display\n\n```julia\n@bind show_advanced CheckBox(default=false)\n```\n\n```julia\n\nmd"""\nShow advanced options: $(show_advanced ? "\u2705 Enabled" : "\u274C Disabled")\n\n$(if show_advanced\n    md"## Advanced Settings\n\n    Configure advanced parameters here."\nelse\n    md""\nend)\n"""\n```\n\n### Pattern 3: Multi-Step Workflow\n\n```julia\nmd"""\n# Step 1: Select Dataset\n$(@bind dataset Select(["Dataset A", "Dataset B", "Dataset C"]))\n"""\n\n# Load selected dataset\ndata = load_dataset(dataset)\n\nmd"""\n# Step 2: Configure Analysis\n$(@bind threshold Slider(0:0.1:1, default=0.5, show_value=true))\n"""\n\n# Perform analysis\nresults = analyze(data, threshold)\n\nmd"""\n# Step 3: Results\n\n$(plot(results))\n"""\n```\n\n### Pattern 4: Table with Embedded Widgets\n\n```julia\nmd"""\n# Parameter Configuration\n\n| Parameter | Description | Units | Value |\n| --------- | ----------- | ----- | ----- |\n| `temperature` | Operating temperature | \xB0C | $(@bind temp NumberField(0:200, default=25)) |\n| `pressure` | Operating pressure | bar | $(@bind pres NumberField(0:100, default=1)) |\n| `enabled` | Enable feature | - | $(@bind enabled CheckBox(default=true)) |\n"""\n```\n\n```julia\n# Use the bound values\nconfig = (temperature=temp, pressure=pres, enabled=enabled)\n```\n\n### Pattern 5: Real-time Visualization\n\n```julia\n@bind time Clock(0.1)  # Update every 0.1 seconds\n\nbegin\n    # Generate time-varying data\n    t = time\n    x = 0:0.1:2\u03C0\n    y = sin.(x .+ t)\n\n    plot(x, y, label="sin(x + t)", ylims=(-1.5, 1.5))\nend\n```\n\n### Pattern 6: Form-like Interface\n\n```julia\nmd"""\n# User Profile\n\n| Field | Input |\n| ----- | ----- |\n| Name | $(@bind user_name TextField(default="")) |\n| Age | $(@bind user_age NumberField(1:120, default=25)) |\n| Country | $(@bind country Select(["USA", "UK", "Canada", "Other"])) |\n| Subscribe | $(@bind subscribe CheckBox(default=false)) |\n\n$(@bind submit_button Button("Submit"))\n"""\n```\n\n```julia\nbegin\n    profile = (\n        name = user_name,\n        age = user_age,\n        country = country,\n        subscribe = subscribe\n    )\n\n    md"""\n    ## Submitted Profile\n\n    - **Name**: $(profile.name)\n    - **Age**: $(profile.age)\n    - **Country**: $(profile.country)\n    - **Newsletter**: $(profile.subscribe ? "\u2705 Yes" : "\u274C No")\n    """\nend\n```\n\n---\n\n## Summary\n\n### Key Takeaways\n\n1. **Reactivity**: Cells automatically re-run based on dependencies\n2. **One Variable Rule**: Each variable can only be defined once across all cells\n3. **`@bind` Macro**: Connects UI widgets to variables\n4. **Markdown Integration**: Use `$()` to embed Julia expressions in markdown\n5. **Tables + Widgets**: Combine markdown tables with PlutoUI for interactive forms\n6. **No Hidden State**: All variables are explicit and traceable\n\n### Quick Reference\n\n**Slider**: `@bind x Slider(1:100, default=50, show_value=true)`\n\n**TextField**: `@bind text TextField(default="")`\n\n**NumberField**: `@bind n NumberField(0:100, default=10)`\n\n**CheckBox**: `@bind checked CheckBox(default=false)`\n\n**Select**: `@bind choice Select(["A", "B", "C"])`\n\n**Button**: `@bind clicked Button("Click")`\n\n**Markdown + Widget**: `$(@bind x Slider(1:10))`\n\n**Markdown + Variable**: `The value is $(x)`\n\n---\n\n## Additional Resources\n\n- Official Pluto.jl: <https://plutojl.org/>\n- PlutoUI Documentation: <https://github.com/JuliaPluto/PlutoUI.jl>\n- Featured Examples: <https://featured.plutojl.org/>\n\n---\n\n**Note for AI Tools**: When creating or modifying Pluto notebooks:\n\n- Always respect the one-variable-per-cell rule\n- Use `begin...end` blocks for multiple statements\n- Ensure cell UUIDs are unique\n- Maintain the cell order section at the end\n- Use `@bind` for all interactive widgets\n- Test reactivity by changing dependent variables\n';
 
 // ../../src/mcp-server-http.ts
 var PlutoMCPHttpServer = class {
@@ -62800,7 +62925,7 @@ var PlutoMCPHttpServer = class {
     );
     server.tool(
       "open_notebook",
-      "Open a Pluto notebook file and create a worker session",
+      "Open a Pluto notebook file and create a worker session. The .jl file must already exist on disk \u2014 Pluto will not create a new file from a nonexistent path. Create the file first if needed.",
       {
         path: external_exports.string().describe("Path to the .jl notebook file")
       },
@@ -62870,7 +62995,7 @@ Notebook ID: ${worker2.notebook_id}`
     );
     server.tool(
       "create_cell",
-      "Create and execute a new cell in a notebook",
+      "Create and execute a new cell in a notebook. WARNING: This always executes the code. If the code is slow (e.g. package installs), the call may time out but the cell IS still created in Pluto. Use list_cells to check before retrying. For slow operations, prefer edit_cell with run=false then execute_cell separately.",
       {
         path: external_exports.string().describe("Path to the notebook"),
         code: external_exports.string().describe("Julia code for the new cell"),
@@ -62907,7 +63032,7 @@ Notebook ID: ${worker2.notebook_id}`
     );
     server.tool(
       "edit_cell",
-      "Update the code of an existing cell",
+      "Update the code of an existing cell. Note: editing the .pluto.jl file on disk has NO effect on the running notebook \u2014 all mutations must go through the MCP API. Use save_notebook to persist changes to disk.",
       {
         path: external_exports.string().describe("Path to the notebook"),
         cell_id: external_exports.string().describe("UUID of the cell to edit"),
@@ -63218,6 +63343,120 @@ Notebook ID: ${worker2.notebook_id}`
         }
       }
     );
+    server.tool(
+      "save_notebook",
+      "Save the running notebook to disk as a .pluto.jl file. Notebooks are NOT auto-saved \u2014 you must call this explicitly to persist changes made via create_cell, edit_cell, or delete_cell.",
+      {
+        path: external_exports.string().describe("Path of the open notebook"),
+        output_path: external_exports.string().describe(
+          "Optional alternative file path to save to (defaults to the notebook's original path)"
+        ).optional()
+      },
+      async ({ path: path4, output_path }) => {
+        if (!this.plutoManager.isConnected()) {
+          throw new Error("Pluto server is not running");
+        }
+        const worker2 = await this.plutoManager.getWorker(path4);
+        if (!worker2) {
+          throw new Error(`Notebook ${path4} is not open`);
+        }
+        const content = this.plutoManager.getNotebookContent(worker2);
+        const savePath = output_path ?? path4;
+        await (0, import_promises.writeFile)(savePath, content, "utf-8");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Notebook saved to ${savePath} (${content.length} bytes)`
+            }
+          ]
+        };
+      }
+    );
+    server.tool(
+      "delete_cell",
+      "Permanently remove a cell from the notebook by its ID. Use list_cells to find cell IDs.",
+      {
+        path: external_exports.string().describe("Path to the notebook"),
+        cell_id: external_exports.string().describe("UUID of the cell to delete")
+      },
+      async ({ path: path4, cell_id }) => {
+        if (!this.plutoManager.isConnected()) {
+          throw new Error("Pluto server is not running");
+        }
+        const worker2 = await this.plutoManager.getWorker(path4);
+        if (!worker2) {
+          throw new Error(`Notebook ${path4} is not open`);
+        }
+        await this.plutoManager.deleteCell(worker2, cell_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Cell ${cell_id} deleted`
+            }
+          ]
+        };
+      }
+    );
+    server.tool(
+      "list_cells",
+      "List all cells in a notebook with their IDs, code preview, and execution status. Use this to find cell IDs for read_cell, edit_cell, execute_cell, or delete_cell.",
+      {
+        path: external_exports.string().describe("Path to the notebook")
+      },
+      async ({ path: path4 }) => {
+        if (!this.plutoManager.isConnected()) {
+          throw new Error("Pluto server is not running");
+        }
+        const worker2 = await this.plutoManager.getWorker(path4);
+        if (!worker2) {
+          throw new Error(`Notebook ${path4} is not open`);
+        }
+        const snippets = worker2.getSnippets();
+        const cells = snippets.map((snippet, index) => ({
+          cell_id: snippet.cell_id,
+          index,
+          code_preview: snippet.input.code.split("\n")[0].slice(0, 80),
+          errored: snippet.result.errored,
+          running: snippet.result.running,
+          queued: snippet.result.queued
+        }));
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ count: cells.length, cells }, null, 2)
+            }
+          ]
+        };
+      }
+    );
+    server.tool(
+      "get_notebook_url",
+      "Get the browser URL to open the notebook in Pluto's web interface",
+      {
+        path: external_exports.string().describe("Path to the notebook")
+      },
+      async ({ path: path4 }) => {
+        if (!this.plutoManager.isConnected()) {
+          throw new Error("Pluto server is not running");
+        }
+        const worker2 = await this.plutoManager.getWorker(path4);
+        if (!worker2) {
+          throw new Error(`Notebook ${path4} is not open`);
+        }
+        const url2 = `${this.plutoManager.getServerUrl()}/edit?id=${worker2.notebook_id}`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: url2
+            }
+          ]
+        };
+      }
+    );
   }
   setupRoutes() {
     this.app.get("/mcp", async (_req, res) => {
@@ -63623,10 +63862,10 @@ var NodeServerManager = class {
 };
 
 // ../../src/cli/nodeFileReader.ts
-var import_promises = require("fs/promises");
+var import_promises2 = require("fs/promises");
 var NodeFileReader = class {
   async readFile(path4) {
-    return await (0, import_promises.readFile)(path4, "utf-8");
+    return await (0, import_promises2.readFile)(path4, "utf-8");
   }
 };
 
@@ -63649,45 +63888,52 @@ var consoleLogger = {
 // ../../src/cli/run.ts
 async function run(config) {
   console.log("@plutojl/mcp \u2014 Standalone MCP server for Pluto.jl\n");
-  let serverManager;
-  let plutoManager;
-  if (config.plutoUrl) {
-    console.log(
-      `[cli] Connecting to existing Pluto server at ${config.plutoUrl}`
-    );
-    serverManager = new NodeServerManager(
-      config.plutoPort,
-      config.juliaVersion,
-      config.workDir
-    );
-    plutoManager = new PlutoManager(
-      config.plutoPort,
-      consoleLogger,
-      serverManager,
-      new NodeFileReader(),
-      config.plutoUrl
-    );
-  } else {
-    serverManager = new NodeServerManager(
-      config.plutoPort,
-      config.juliaVersion,
-      config.workDir
-    );
-    plutoManager = new PlutoManager(
-      config.plutoPort,
-      consoleLogger,
-      serverManager,
-      new NodeFileReader()
-    );
-  }
+  const serverManager = new NodeServerManager(
+    config.plutoPort,
+    config.juliaVersion,
+    config.workDir
+  );
+  const plutoManager = new PlutoManager(
+    config.plutoPort,
+    consoleLogger,
+    serverManager,
+    new NodeFileReader(),
+    config.plutoUrl
+  );
   const mcpServer = new PlutoMCPHttpServer(plutoManager, config.mcpPort, true);
   await mcpServer.start();
   console.log(
-    `
-[cli] MCP server listening at http://localhost:${config.mcpPort}/mcp`
+    `[cli] MCP server listening at http://localhost:${config.mcpPort}/mcp`
   );
   console.log(`[cli] Health check: http://localhost:${config.mcpPort}/health`);
-  console.log(`[cli] Press Ctrl+C to stop
+  if (!config.noPluto) {
+    if (config.plutoUrl) {
+      console.log(
+        `[cli] Connecting to existing Pluto server at ${config.plutoUrl}...`
+      );
+    } else {
+      console.log(`[cli] Starting Pluto server on port ${config.plutoPort}...`);
+    }
+    try {
+      await plutoManager.start();
+      console.log(`[cli] Pluto server is ready.`);
+    } catch (err) {
+      console.error(
+        `[cli] Failed to start Pluto: ${err instanceof Error ? err.message : String(err)}`
+      );
+      console.error(
+        `[cli] MCP server is still running \u2014 you can start Pluto later via:`
+      );
+      console.error(`[cli]   npx @plutojl/mcp call start_pluto_server`);
+    }
+  } else {
+    console.log(`[cli] Pluto auto-start skipped (--no-pluto).`);
+    console.log(
+      `[cli] Start it later: npx @plutojl/mcp call start_pluto_server`
+    );
+  }
+  console.log(`
+[cli] Press Ctrl+C to stop
 `);
   console.log(`Tip: Run 'npx @plutojl/mcp install' to configure Claude Code
 `);
@@ -63944,6 +64190,44 @@ async function callTool(port, toolName, argsJson, raw2) {
   }
 }
 
+// ../../src/cli/preflight.ts
+async function preflight(port, opts = {}) {
+  const mcpUrl = `http://localhost:${port}`;
+  let health;
+  try {
+    const res = await fetch(`${mcpUrl}/health`, {
+      signal: AbortSignal.timeout(3e3)
+    });
+    health = await res.json();
+  } catch {
+    console.error(`Error: Cannot reach MCP server at ${mcpUrl}`);
+    console.error(``);
+    console.error(`The MCP server is not running. Start it first:`);
+    console.error(``);
+    console.error(`  npx @plutojl/mcp run`);
+    console.error(``);
+    console.error(
+      `Or, if you are using a different port, pass --mcp-port <port>.`
+    );
+    process.exit(1);
+  }
+  if (opts.requirePluto && !health.plutoServerRunning) {
+    console.error(`Error: MCP server is running but Pluto is not connected.`);
+    console.error(``);
+    console.error(`Start Pluto via the MCP server:`);
+    console.error(``);
+    console.error(`  npx @plutojl/mcp call start_pluto_server`);
+    console.error(``);
+    console.error(`Or connect to an existing Pluto server:`);
+    console.error(``);
+    console.error(
+      `  npx @plutojl/mcp call connect_to_pluto_server '{"port": 1234}'`
+    );
+    process.exit(1);
+  }
+  return { mcpRunning: true, plutoRunning: health.plutoServerRunning };
+}
+
 // ../../src/cli/index.ts
 async function main() {
   const args = parseArgs(process.argv.slice(2));
@@ -63960,6 +64244,7 @@ async function main() {
       break;
     }
     case "tools": {
+      await preflight(mcpPort);
       await listTools(mcpPort);
       break;
     }
@@ -63968,6 +64253,7 @@ async function main() {
         console.error("Usage: npx @plutojl/mcp call <tool_name> [json_args]");
         process.exit(1);
       }
+      await preflight(mcpPort);
       await callTool(
         mcpPort,
         args.toolName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plutojl/mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Standalone MCP server for Pluto.jl notebooks — run with npx @plutojl/mcp",
   "license": "MIT",
   "repository": {