@plutojl/cli 0.5.5 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +107 -39
  2. package/dist/cli.cjs +995 -83487
  3. package/package.json +9 -9
package/README.md CHANGED
@@ -1,17 +1,31 @@
1
1
  # @plutojl/cli
2
2
 
3
- Standalone MCP (Model Context Protocol) server for [Pluto.jl](https://plutojl.org/) notebooks. Enables AI assistants like Claude and GitHub Copilot to interact with Julia Pluto notebooks.
3
+ Command-line tool for [Pluto.jl](https://plutojl.org/) notebooks. Start a Pluto server and drive notebooks straight from your terminal — open notebooks, create and execute cells, read outputs. The tool server it starts also speaks MCP (Model Context Protocol), so AI assistants like Claude and GitHub Copilot can use the same tools.
4
4
 
5
5
  ## Quick Start
6
6
 
7
7
  ```bash
8
- # Start the MCP server (also starts a Pluto server)
8
+ # See what is running and how to use the CLI
9
+ npx @plutojl/cli
10
+
11
+ # Start Pluto and the tool server
9
12
  npx @plutojl/cli run
10
13
 
11
- # Install MCP config for Claude Code
14
+ # In another terminal: drive notebooks from the command line
15
+ npx @plutojl/cli tools
16
+ npx @plutojl/cli call open_notebook '{"path": "notebook.pluto.jl"}'
17
+ npx @plutojl/cli call execute_code '{"code": "1 + 1"}'
18
+
19
+ # Optional: install MCP config so AI assistants can connect too
12
20
  npx @plutojl/cli install
13
21
  ```
14
22
 
23
+ Running with no arguments prints the help followed by a status block that says whether a Pluto server (port 1234) and a tool server are running, and who owns the tool server.
24
+
25
+ ## Inside VS Code
26
+
27
+ The [Advanced Pluto Notebook](https://marketplace.visualstudio.com/items?itemName=juliapluto-pankgeorg.advanced-vscode-extension) extension runs the same tool server automatically. When the CLI runs inside a VS Code terminal (or from an agent launched there), `tools` and `call` find and use that server, including when the extension had to move to a nearby port because the default was busy. `run` notices it too and tells you nothing needs starting; pass `--mcp-port` to run a separate server anyway.
28
+
15
29
  ## Prerequisites
16
30
 
17
31
  - **Node.js** >= 18
@@ -22,34 +36,73 @@ npx @plutojl/cli install
22
36
 
23
37
  ### `run`
24
38
 
25
- Start the MCP server (and a Pluto server if needed).
39
+ Start Pluto and the tool server. Pluto is installed into a shared Julia environment on the first run; later runs skip the install unless `--update` is passed.
26
40
 
27
41
  ```bash
28
42
  npx @plutojl/cli run [options]
29
43
  ```
30
44
 
31
- | Option | Default | Description |
32
- | ----------------------- | -------- | ---------------------------------------------------- |
33
- | `--mcp-port <port>` | `3100` | MCP server port |
34
- | `--pluto-port <port>` | `1234` | Pluto server port |
35
- | `--pluto-url <url>` | — | Connect to existing Pluto server (skip starting one) |
36
- | `--julia-version <ver>` | `1.11.7` | Julia version via juliaup |
45
+ | Option | Default | Description |
46
+ | ----------------------- | -------- | --------------------------------------------------------------------- |
47
+ | `--mcp-port <port>` | `3100` | Tool server (MCP) port |
48
+ | `--pluto-port <port>` | `1234` | Pluto server port |
49
+ | `--pluto-url <url>` | — | Connect to existing Pluto server (skip starting one) |
50
+ | `--julia-version <ver>` | `1.12.7` | juliaup channel to use, or `default` for whatever `julia` resolves to |
51
+ | `--update` | — | Re-install and precompile Pluto before starting |
52
+ | `--no-pluto` | — | Start the tool server only, without starting Pluto |
53
+
54
+ ### `status`
55
+
56
+ Show whether Pluto and a tool server are running. Exits 0 when a tool server was found, 1 otherwise. `--json` prints the same information as JSON. `--wait` blocks until a tool server with Pluto connected answers (up to `--timeout`, default 600 seconds), which is the easy way to wait out a first `run`.
57
+
58
+ ```bash
59
+ npx @plutojl/cli status [--wait] [--timeout <seconds>] [--json] [--mcp-port <port>] [--pluto-port <port>]
60
+ ```
61
+
62
+ ### `tools`
63
+
64
+ List the notebook tools available on a running server, or show one tool's parameters.
65
+
66
+ ```bash
67
+ npx @plutojl/cli tools [name] [--mcp-port <port>]
68
+ ```
69
+
70
+ ### `call`
71
+
72
+ Call a notebook tool from the command line. The tool name and JSON arguments may appear before or after the options.
73
+
74
+ ```bash
75
+ npx @plutojl/cli call <tool_name> [json_args] [options]
76
+
77
+ # Examples
78
+ npx @plutojl/cli call get_notebook_status
79
+ npx @plutojl/cli call open_notebook '{"path": "/tmp/nb.pluto.jl"}'
80
+ npx @plutojl/cli call execute_code '{"code": "sqrt(2)"}'
81
+ ```
82
+
83
+ | Option | Default | Description |
84
+ | --------------------- | ------- | ------------------------------------ |
85
+ | `--mcp-port <port>` | `3100` | Tool server (MCP) port |
86
+ | `--timeout <seconds>` | `120` | How long to wait for the tool result |
87
+ | `--raw` | — | Output raw JSON response |
37
88
 
38
89
  ### `install`
39
90
 
40
- Add MCP configuration files for AI assistants.
91
+ Add MCP configuration files so AI assistants can connect to the tool server.
41
92
 
42
93
  ```bash
43
94
  npx @plutojl/cli install [options]
44
95
  ```
45
96
 
46
- | Option | Default | Description |
47
- | ------------------- | ------------- | ------------------------------------------------- |
48
- | `--target <target>` | `claude-code` | Config target: `claude-code`, `copilot`, or `all` |
49
- | `--mcp-port <port>` | `3100` | MCP server port to configure |
50
- | `--global` | — | Write to `~/.claude/` instead of `./.claude/` |
51
- | `--dry-run` | — | Print config without writing |
52
- | `--force` | — | Overwrite existing config |
97
+ | Option | Default | Description |
98
+ | ------------------- | ------------- | ------------------------------------------------------------ |
99
+ | `--target <target>` | `claude-code` | Config target: `claude-code`, `copilot`, or `all` |
100
+ | `--mcp-port <port>` | `3100` | Tool server (MCP) port to configure |
101
+ | `--global` | — | Claude Code: write `~/.claude.json` instead of `./.mcp.json` |
102
+ | `--dry-run` | — | Print config without writing |
103
+ | `--force` | — | Overwrite existing config |
104
+
105
+ Claude Code config goes to `.mcp.json` at the project root; Copilot (VS Code) config goes to `.vscode/mcp.json`.
53
106
 
54
107
  ## Configuration
55
108
 
@@ -66,30 +119,45 @@ Example `.plutomcp.json`:
66
119
  {
67
120
  "mcpPort": 3100,
68
121
  "plutoPort": 1234,
69
- "juliaVersion": "1.11.7"
122
+ "juliaVersion": "1.12.7",
123
+ "serverUrl": "http://localhost:1234"
70
124
  }
71
125
  ```
72
126
 
73
- ## MCP Tools
74
-
75
- The server exposes these tools to AI assistants:
76
-
77
- | Tool | Description |
78
- | ------------------------- | ---------------------------------- |
79
- | `learn_pluto_basics` | Get a comprehensive Pluto.jl guide |
80
- | `start_pluto_server` | Start the Pluto server |
81
- | `stop_pluto_server` | Stop the Pluto server |
82
- | `connect_to_pluto_server` | Connect to an existing server |
83
- | `get_notebook_status` | Check server status |
84
- | `open_notebook` | Open a notebook file |
85
- | `list_notebooks` | List all open notebooks |
86
- | `create_cell` | Create and execute a new cell |
87
- | `read_cell` | Read cell code and output |
88
- | `edit_cell` | Update cell code |
89
- | `execute_cell` | Run an existing cell |
90
- | `execute_code` | Execute code ephemerally |
91
- | `get_docs` | Get Julia symbol documentation |
92
- | `introspect_notebook` | List all symbols in a notebook |
127
+ Cell outputs returned by tools are trimmed for the terminal: byte bodies are decoded (text, SVG) or base64-encoded (images), and bodies longer than 32,000 characters are truncated with a `body_note`; `export_notebook_html` writes the complete output.
128
+
129
+ Unknown options, options that do not apply to the command, and invalid values are errors (exit code 2). Set `PLUTO_CLI_DEBUG=1` to see stack traces for unexpected failures. Colors follow `NO_COLOR` / `FORCE_COLOR`.
130
+
131
+ ## Notebook tools
132
+
133
+ These tools are callable from the command line via `call`, and exposed to AI assistants over MCP:
134
+
135
+ | Tool | Description |
136
+ | ------------------------- | ------------------------------------------ |
137
+ | `learn_pluto_basics` | Get a comprehensive Pluto.jl guide |
138
+ | `start_pluto_server` | Start the Pluto server |
139
+ | `stop_pluto_server` | Stop the Pluto server |
140
+ | `connect_to_pluto_server` | Connect to an existing server |
141
+ | `get_notebook_status` | Check server status |
142
+ | `create_notebook` | Create an empty notebook file and open it |
143
+ | `open_notebook` | Open a notebook file |
144
+ | `move_notebook` | Move a notebook to a new path |
145
+ | `save_notebook` | Save the running notebook to disk |
146
+ | `export_notebook_html` | Export a static HTML snapshot to disk |
147
+ | `wait_for_notebook_idle` | Block until no cell is running or queued |
148
+ | `list_notebooks` | List all open notebooks |
149
+ | `get_notebook_url` | Get the Pluto web UI URL for a notebook |
150
+ | `list_cells` | List cells with IDs and execution status |
151
+ | `create_cell` | Create and execute a new cell |
152
+ | `read_cell` | Read cell code and output |
153
+ | `edit_cell` | Update cell code |
154
+ | `execute_cell` | Run an existing cell |
155
+ | `delete_cell` | Remove a cell |
156
+ | `move_cells` | Reorder cells |
157
+ | `fold_cell` | Show or hide a cell's code in the Pluto UI |
158
+ | `execute_code` | Execute code ephemerally (no cell created) |
159
+ | `get_docs` | Get Julia symbol documentation |
160
+ | `introspect_notebook` | List all symbols defined in a notebook |
93
161
 
94
162
  ## Related
95
163