@evref-bl/pharo-launcher-mcp 0.1.2 → 0.1.3

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 (47) hide show
  1. package/README.md +229 -199
  2. package/bin/pharo-launcher.cmd +46 -46
  3. package/bin/pharo-launcher.sh +0 -0
  4. package/dist/commandCatalog.d.ts.map +1 -1
  5. package/dist/commandCatalog.js +17 -0
  6. package/dist/commandCatalog.js.map +1 -1
  7. package/dist/config.d.ts +21 -1
  8. package/dist/config.d.ts.map +1 -1
  9. package/dist/config.js +75 -6
  10. package/dist/config.js.map +1 -1
  11. package/dist/crossProfileCopy.d.ts +87 -0
  12. package/dist/crossProfileCopy.d.ts.map +1 -0
  13. package/dist/crossProfileCopy.js +437 -0
  14. package/dist/crossProfileCopy.js.map +1 -0
  15. package/dist/discovery.d.ts +165 -1
  16. package/dist/discovery.d.ts.map +1 -1
  17. package/dist/discovery.js +744 -1
  18. package/dist/discovery.js.map +1 -1
  19. package/dist/imageMetadata.d.ts +1 -0
  20. package/dist/imageMetadata.d.ts.map +1 -1
  21. package/dist/imageMetadata.js +35 -2
  22. package/dist/imageMetadata.js.map +1 -1
  23. package/dist/launcherCli.d.ts +2 -0
  24. package/dist/launcherCli.d.ts.map +1 -1
  25. package/dist/launcherCli.js +561 -62
  26. package/dist/launcherCli.js.map +1 -1
  27. package/dist/models.d.ts +2 -0
  28. package/dist/models.d.ts.map +1 -1
  29. package/dist/platform.d.ts +2 -0
  30. package/dist/platform.d.ts.map +1 -1
  31. package/dist/platform.js +21 -0
  32. package/dist/platform.js.map +1 -1
  33. package/dist/resultNormalizer.d.ts.map +1 -1
  34. package/dist/resultNormalizer.js +47 -0
  35. package/dist/resultNormalizer.js.map +1 -1
  36. package/dist/server.d.ts +2 -0
  37. package/dist/server.d.ts.map +1 -1
  38. package/dist/server.js +387 -10
  39. package/dist/server.js.map +1 -1
  40. package/docs/README.md +26 -0
  41. package/docs/cleanup-hook-boundary.md +94 -0
  42. package/docs/development.md +59 -23
  43. package/docs/reference/tools.md +179 -0
  44. package/docs/troubleshooting.md +135 -0
  45. package/docs/user/getting-started.md +172 -0
  46. package/docs/user/profile-mode.md +176 -0
  47. package/package.json +57 -52
@@ -1,9 +1,9 @@
1
- # pharo-launcher-mcp Development
1
+ # Development
2
2
 
3
- This document contains development notes for pharo-launcher-mcp. The main README is kept
4
- focused on installation, configuration, and tool usage.
3
+ This document is for maintainers changing pharo-launcher-mcp. The README stays
4
+ focused on installation and first use; user-facing detail lives under `docs/`.
5
5
 
6
- ## Source Layout
6
+ ## Source layout
7
7
 
8
8
  - `src/server.ts`: MCP server surface and tool dispatch.
9
9
  - `src/commandCatalog.ts`: Pharo Launcher command definitions and input checks.
@@ -18,12 +18,11 @@ focused on installation, configuration, and tool usage.
18
18
  - `bin/pharo-launcher.sh`: POSIX wrapper.
19
19
  - `scripts/*.ps1`: Windows helper scripts for local live checks.
20
20
 
21
- ## Local Setup
21
+ ## Local setup
22
22
 
23
23
  ```sh
24
24
  npm install
25
- npm run build
26
- npm test
25
+ npm run check
27
26
  ```
28
27
 
29
28
  Useful scripts:
@@ -35,33 +34,45 @@ npm test
35
34
  npm run test:integration
36
35
  ```
37
36
 
38
- `npm test` runs unit coverage only. It does not invoke a local Pharo Launcher.
37
+ `npm run check` runs type checking, build, and unit tests. `npm test` runs unit
38
+ coverage only. It does not invoke a local Pharo Launcher.
39
39
 
40
- ## Platform Contract
40
+ ## Platform contract
41
41
 
42
42
  The production code handles Windows, macOS, and Linux explicitly:
43
43
 
44
44
  - Windows defaults to `%LOCALAPPDATA%\Pharo Launcher`,
45
45
  `PharoConsole.exe`, and `pharo-launcher.cmd`.
46
- - macOS defaults to `$HOME/Library/Application Support/Pharo Launcher`,
47
- the app-bundle VM path, and `pharo-launcher.sh`.
46
+ - macOS discovery checks `$HOME/Applications/PharoLauncher.app` and
47
+ `/Applications/PharoLauncher.app` before falling back to
48
+ `$HOME/Library/Application Support/Pharo Launcher`. App-bundle installs use
49
+ `Contents/MacOS/Pharo` and `Contents/Resources/PharoLauncher.image`.
48
50
  - Linux defaults to `$HOME/.local/share/Pharo Launcher`, `pharo-vm/pharo`,
49
51
  and `pharo-launcher.sh`.
50
52
 
51
53
  `src/crossPlatform.test.ts` covers configuration defaults, bundled wrapper
52
54
  selection, and native process backend selection for all three platforms.
55
+ `src/config.test.ts` covers macOS app-bundle discovery, fallback, and explicit
56
+ environment override precedence.
57
+
58
+ No-profile mode means no pharo-launcher-mcp profile is active and no
59
+ pharo-launcher-mcp home/cache is created. The resolved Pharo Launcher
60
+ installation and its normal state scope are used directly. Profile mode is
61
+ entered only when `PHARO_LAUNCHER_MCP_PROFILE`,
62
+ `PHARO_LAUNCHER_MCP_STATE_ROOT`, or one of the explicit profile directory
63
+ variables is present.
53
64
 
54
- ## Process Backend
65
+ ## Process backend
55
66
 
56
- Pharo Launcher process commands can vary by host. pharo-launcher-mcp uses a native process
57
- backend for `pharo_launcher_process_list` and `pharo_launcher_process_kill`
58
- when needed:
67
+ Pharo Launcher process commands can vary by host. pharo-launcher-mcp uses a
68
+ native process backend for `pharo_launcher_process_list` and
69
+ `pharo_launcher_process_kill` when needed:
59
70
 
60
71
  - Windows uses a PowerShell/CIM query.
61
72
  - macOS and Linux use `ps -axo pid=,args=`.
62
73
  - Unsupported host platforms return an explicit unsupported-backend error.
63
74
 
64
- ## Parsing Boundary
75
+ ## Parsing boundary
65
76
 
66
77
  `src/parser.ts` is the only layer that translates Pharo Launcher output into
67
78
  pharo-launcher-mcp models.
@@ -86,7 +97,14 @@ LauncherProcess
86
97
  LauncherCommandResult
87
98
  ```
88
99
 
89
- ## Integration Tests
100
+ Inventory output adds normalized identity metadata on top of parsed launcher
101
+ models. Template identities normalize Pharo and Moose template names to the
102
+ underlying Pharo version when possible, infer architecture from template names
103
+ or URLs, and attach source-file digest/mtime for installed `.ston` template
104
+ files. Image identities mirror the launcher metadata returned by image
105
+ list/info commands.
106
+
107
+ ## Integration tests
90
108
 
91
109
  Run the live integration suite explicitly:
92
110
 
@@ -119,10 +137,10 @@ External-source image creation variants such as build, pull request,
119
137
  repository, SHA, and VM mutation commands should use explicit fixtures because
120
138
  they require network inputs or can alter VM installations.
121
139
 
122
- ## Windows Live Helpers
140
+ ## Windows live helpers
123
141
 
124
142
  The helper scripts under `scripts/*.ps1` are Windows PowerShell conveniences for
125
- the current development environment:
143
+ a local Windows development environment:
126
144
 
127
145
  ```powershell
128
146
  .\scripts\verify-environment.ps1
@@ -134,10 +152,10 @@ The live smoke test uses a dedicated profile root and copies the Pharo Launcher
134
152
  control image there before making live calls. It runs harmless checks by
135
153
  default: health, `--version`, and installation validation.
136
154
 
137
- Default profile root:
155
+ When `-StateRoot` is not supplied, the helper uses:
138
156
 
139
157
  ```text
140
- C:\dev\code\git\.pharo-launcher-mcp\profiles\live-test
158
+ <repo-parent>\.pharo-launcher-mcp\profiles\live-test
141
159
  ```
142
160
 
143
161
  Refresh the copied launcher control image:
@@ -149,13 +167,13 @@ Refresh the copied launcher control image:
149
167
  These helpers are not a substitute for cross-platform verification on macOS and
150
168
  Linux.
151
169
 
152
- ## Cleanup Hook Boundary
170
+ ## Cleanup hook boundary
153
171
 
154
172
  Use `docs/cleanup-hook-boundary.md` when mapping launcher status, stop,
155
173
  timeout, and cleanup hooks for isolated live checks. That boundary
156
174
  distinguishes read-only planning checks from host inspection and mutation.
157
175
 
158
- ## Local Probes
176
+ ## Local probes
159
177
 
160
178
  Probe the local Pharo Launcher image list without starting MCP stdio:
161
179
 
@@ -170,3 +188,21 @@ Start the MCP server over stdio from a local build:
170
188
  ```powershell
171
189
  node .\dist\index.js
172
190
  ```
191
+
192
+ ## Documentation updates
193
+
194
+ Keep docs close to the behavior they describe:
195
+
196
+ - Put the fastest install and health path in `README.md`.
197
+ - Put profile details in `docs/user/profile-mode.md`.
198
+ - Put tool arguments and result shape in `docs/reference/tools.md`.
199
+ - Put live host failure modes in `docs/troubleshooting.md`.
200
+ - Keep examples generic. Do not use local machine paths, project names, issue
201
+ numbers, or incident history as examples.
202
+
203
+ Before committing docs changes, run:
204
+
205
+ ```sh
206
+ npm run check
207
+ npm pack --dry-run
208
+ ```
@@ -0,0 +1,179 @@
1
+ # Tool Reference
2
+
3
+ pharo-launcher-mcp exposes MCP tools over stdio. Most tools call Pharo Launcher
4
+ and return a normalized launcher result envelope. Health and configuration tools
5
+ only inspect local paths.
6
+
7
+ ## Health And Configuration
8
+
9
+ | Tool | Live Launcher invocation | Purpose |
10
+ | --- | --- | --- |
11
+ | `pharo_launcher_health` | No | Reports service version, resolved paths, wrapper source, and existence checks. |
12
+ | `pharo_launcher_config` | No | Reports resolved installation, profile, wrapper, and configuration paths. |
13
+ | `pharo_launcher_version` | Yes | Runs `--version`. |
14
+ | `pharo_launcher_validate_installation` | Yes | Checks resolved paths and runs `--version`. |
15
+ | `pharo_launcher_inventory` | Yes | Reports profile roots, templates, image identities, declared image handles, probes, and diagnostics. |
16
+
17
+ `pharo_launcher_inventory` accepts optional `declaredImages` supplied by a
18
+ scoped caller:
19
+
20
+ ```json
21
+ {
22
+ "declaredImages": [
23
+ {
24
+ "imageId": "image:sample-130",
25
+ "imageName": "sample-130",
26
+ "status": "active"
27
+ }
28
+ ]
29
+ }
30
+ ```
31
+
32
+ ## Image Tools
33
+
34
+ | Tool | Arguments |
35
+ | --- | --- |
36
+ | `pharo_launcher_image_list` | `nameFilter`, table options |
37
+ | `pharo_launcher_image_info` | `imageName`, table options |
38
+ | `pharo_launcher_image_create` | `templateName`, `newImageName`, `templateCategory`, `dev`, `noLaunch` |
39
+ | `pharo_launcher_image_copy` | `imageName`, `newImageName` |
40
+ | `pharo_launcher_image_copy_between_profiles` | `sourceProfile`, `destinationProfile`, `sourceImageName`, `destinationImageName` |
41
+ | `pharo_launcher_image_launch` | `imageName`, `script`, `detached`, `displayMode` |
42
+ | `pharo_launcher_image_package` | `imageName`, `location`, `zip`, `vm` |
43
+ | `pharo_launcher_image_bisect` | `pharoVersion` |
44
+ | `pharo_launcher_image_create_from_build` | `buildNumber`, `pharoVersion`, `newImageName` |
45
+ | `pharo_launcher_image_create_from_pull_request` | `pullRequest`, `newImageName`, `templateName`, `templateCategory` |
46
+ | `pharo_launcher_image_create_from_repo` | `repository`, `newImageName`, `templateName`, `templateCategory`, `subfolder`, `baseline`, `group` |
47
+ | `pharo_launcher_image_create_from_sha` | `sha`, `pharoVersion`, `newImageName` |
48
+ | `pharo_launcher_image_delete` | `imageName`, `force`, `confirm: true` |
49
+ | `pharo_launcher_image_recreate` | `imageName`, `confirm: true` |
50
+
51
+ `pharo_launcher_image_create` and `pharo_launcher_image_copy` verify the target
52
+ image after Launcher returns. A successful Launcher exit is not enough: the MCP
53
+ result is successful only when the target image can be listed and inspected.
54
+
55
+ `pharo_launcher_image_launch` supports:
56
+
57
+ - `displayMode: "headless"` or `"interactive"`
58
+ - `detached: true` for detached launches with log paths in the result
59
+ - `script` for a launch script passed to Launcher, or evaluated by the profile
60
+ VM launch path
61
+
62
+ In profile mode, image launch resolves the image and VM inside the active
63
+ profile roots instead of using Launcher defaults.
64
+
65
+ ## Template Tools
66
+
67
+ | Tool | Arguments |
68
+ | --- | --- |
69
+ | `pharo_launcher_template_category_list` | table options |
70
+ | `pharo_launcher_template_list` | `templateCategory`, table options |
71
+ | `pharo_launcher_template_info` | `templateName`, `templateCategory` |
72
+ | `pharo_launcher_template_update` | none |
73
+
74
+ Table options are:
75
+
76
+ ```json
77
+ {
78
+ "format": "ston",
79
+ "brief": true,
80
+ "rowMode": true,
81
+ "delimiter": "|"
82
+ }
83
+ ```
84
+
85
+ `format` can be `ston` or `text`. The default is `ston` when a tool supports
86
+ table output.
87
+
88
+ In profile mode, `pharo_launcher_template_update` also verifies that the active
89
+ profile source list is usable and probes `template list`.
90
+
91
+ ## VM Tools
92
+
93
+ | Tool | Arguments |
94
+ | --- | --- |
95
+ | `pharo_launcher_vm_list` | `vmId`, table options |
96
+ | `pharo_launcher_vm_info` | `vmId` |
97
+ | `pharo_launcher_vm_update` | `vmId` |
98
+ | `pharo_launcher_vm_delete` | `vmId`, `confirm: true` |
99
+
100
+ VM update can download or install VM files. Use profile mode when automation
101
+ needs VM state isolated from a user's normal Launcher installation.
102
+
103
+ ## Process Tools
104
+
105
+ | Tool | Arguments |
106
+ | --- | --- |
107
+ | `pharo_launcher_process_list` | none |
108
+ | `pharo_launcher_process_kill` | exactly one of `pid` or `imageName`, plus `confirm: true` |
109
+
110
+ On Windows, process tools use PowerShell/CIM. On macOS and Linux, they use
111
+ `ps -axo pid=,args=`. Unsupported platforms return an explicit unsupported
112
+ backend error.
113
+
114
+ Prefer PID-based cleanup when a prior detached launch returned a PID. Image-name
115
+ cleanup can match more than one process if multiple command lines contain the
116
+ same image name.
117
+
118
+ ## Raw Command
119
+
120
+ `pharo_launcher_raw_command` is the escape hatch for Launcher CLI arguments not
121
+ covered by a dedicated MCP tool:
122
+
123
+ ```json
124
+ {
125
+ "args": ["image", "list", "--ston"],
126
+ "confirm": true
127
+ }
128
+ ```
129
+
130
+ It always requires `confirm: true`.
131
+
132
+ ## Result Envelope
133
+
134
+ Launcher tools return JSON shaped like this:
135
+
136
+ ```ts
137
+ {
138
+ ok: boolean;
139
+ data?: unknown;
140
+ diagnostic?: string;
141
+ action?: string;
142
+ parser: {
143
+ status: "parsed" | "unsupported" | "failed" | "skipped";
144
+ format: "ston" | "text";
145
+ message?: string;
146
+ };
147
+ raw: {
148
+ stdout: string;
149
+ stderr: string;
150
+ format: "ston" | "text";
151
+ };
152
+ command: {
153
+ args: string[];
154
+ durationMs: number;
155
+ exitCode: number | null;
156
+ timedOut: boolean;
157
+ timeoutReason?: string;
158
+ };
159
+ }
160
+ ```
161
+
162
+ Use `ok` and normalized `data` for program flow. Treat `raw.stdout` and
163
+ `raw.stderr` as diagnostics.
164
+
165
+ ## Confirmation Gates
166
+
167
+ These tools require `confirm: true`:
168
+
169
+ ```text
170
+ pharo_launcher_image_delete
171
+ pharo_launcher_image_recreate
172
+ pharo_launcher_vm_delete
173
+ pharo_launcher_process_kill
174
+ pharo_launcher_raw_command
175
+ ```
176
+
177
+ The confirmation flag only confirms that the caller meant to cross that tool's
178
+ mutation boundary. It does not prove the image, VM, profile, or process is
179
+ caller-owned.
@@ -0,0 +1,135 @@
1
+ # Troubleshooting
2
+
3
+ Start with `pharo_launcher_health` or the local CLI health check:
4
+
5
+ ```sh
6
+ npx @evref-bl/pharo-launcher-mcp --health
7
+ ```
8
+
9
+ Health checks do not invoke Pharo Launcher. They show the resolved installation,
10
+ control image, VM path, wrapper path, profile paths, and whether those paths
11
+ exist.
12
+
13
+ ## Launcher Paths Are Wrong
14
+
15
+ Set the installation paths explicitly:
16
+
17
+ ```sh
18
+ PHARO_LAUNCHER_DIR="/path/to/Pharo Launcher"
19
+ PHARO_LAUNCHER_VM="/path/to/pharo"
20
+ PHARO_LAUNCHER_IMAGE="/path/to/PharoLauncher.image"
21
+ PHARO_LAUNCHER_SCRIPT="/path/to/pharo-launcher.sh"
22
+ ```
23
+
24
+ Then run:
25
+
26
+ ```sh
27
+ npx @evref-bl/pharo-launcher-mcp --health
28
+ ```
29
+
30
+ On macOS, the server checks user and system `PharoLauncher.app` locations before
31
+ falling back to the Application Support layout. The health report includes the
32
+ selected discovery source and all attempted candidates.
33
+
34
+ ## Wrapper Is Missing
35
+
36
+ `PHARO_LAUNCHER_SCRIPT` is optional. If it is unset, the server tries the
37
+ bundled wrapper for the host platform. If that wrapper cannot be resolved, the
38
+ server invokes the VM directly with the Launcher control image.
39
+
40
+ If a selected wrapper path exists but is not executable, the command result
41
+ contains a startup diagnostic with the command, args, working directory, PATH,
42
+ and active profile variables.
43
+
44
+ ## `validate_installation` Fails
45
+
46
+ `pharo_launcher_validate_installation` runs `--version`. If it fails:
47
+
48
+ 1. Run `pharo_launcher_config` and confirm the VM and control image paths.
49
+ 2. Run `pharo_launcher_health` and check `launcherScript.exists`.
50
+ 3. If using a profile, confirm the installation control image exists. The
51
+ profile control image is copied from that source before live commands.
52
+ 4. Try `node ./dist/index.js --version-check` from a local build to separate MCP
53
+ client setup from Launcher startup.
54
+
55
+ ## Profile Configuration Is Refused
56
+
57
+ When `PHARO_LAUNCHER_MCP_STATE_ROOT` is set, the profile launcher image and
58
+ generated Launcher configuration must be inside that state root.
59
+
60
+ Use a state-root layout:
61
+
62
+ ```text
63
+ <state-root>/launcher/PharoLauncher.image
64
+ <state-root>/launcher/pharo-launcher-cli-config.ston
65
+ <state-root>/images
66
+ <state-root>/vms
67
+ <state-root>/templates
68
+ <state-root>/init-scripts
69
+ <state-root>/logs
70
+ ```
71
+
72
+ Or provide a complete explicit profile without relying on `stateRoot`. See
73
+ [Profile mode](user/profile-mode.md).
74
+
75
+ ## Template List Fails In Profile Mode
76
+
77
+ Run:
78
+
79
+ ```text
80
+ pharo_launcher_template_update
81
+ pharo_launcher_inventory
82
+ ```
83
+
84
+ `template_update` seeds the active profile source list when Launcher leaves it
85
+ missing or empty, then probes `template list`. Inventory diagnostics report
86
+ missing profile directories, missing configuration files, and failed probes.
87
+
88
+ ## Image Create Or Copy Reports An Error After Launcher Succeeds
89
+
90
+ Create and copy tools verify the target image after the command exits. The MCP
91
+ result is an error when the target image cannot be listed and inspected.
92
+
93
+ Check:
94
+
95
+ - the `createVerification` or `copyVerification` section
96
+ - `raw.stdout` and `raw.stderr`
97
+ - whether the image name already existed
98
+ - whether the active profile points at the expected images directory
99
+ - whether the Launcher template source list is valid
100
+
101
+ For copied images, the result also reports metadata repair and inspected image
102
+ metadata when available.
103
+
104
+ ## Process List Or Kill Does Not See A Process
105
+
106
+ Process tools use native host process queries:
107
+
108
+ - Windows: PowerShell/CIM
109
+ - macOS and Linux: `ps -axo pid=,args=`
110
+
111
+ The process must have a Pharo or Squeak command line that includes a `.image`
112
+ path. For cleanup, prefer a PID captured from the detached launch result. If
113
+ using `imageName`, confirm that no unrelated process command line contains the
114
+ same text.
115
+
116
+ ## Commands Time Out
117
+
118
+ Every Launcher command is bounded by a timeout. Timeout results include:
119
+
120
+ - `command.timedOut: true`
121
+ - `command.timeoutReason`
122
+ - command args
123
+ - raw stdout/stderr captured before the timeout
124
+
125
+ A timeout does not authorize broader host cleanup. Cleanup should use only
126
+ recorded image names, profile roots, and PIDs that the caller owns.
127
+
128
+ ## Profile `create_from_build` Is Refused
129
+
130
+ Profile-scoped `pharo_launcher_image_create_from_build` is refused before
131
+ Launcher starts. That Launcher path can automatically launch the image and may
132
+ download or use VMs outside `PHARO_LAUNCHER_MCP_VMS_DIR`.
133
+
134
+ Use a non-`fromBuild` creation path with explicit launch control, or run the
135
+ operation outside profile mode when using the normal Launcher state is intended.
@@ -0,0 +1,172 @@
1
+ # Getting Started
2
+
3
+ This guide gets pharo-launcher-mcp running as a stdio MCP server and shows the
4
+ first checks to run before mutating any Launcher state.
5
+
6
+ ## Requirements
7
+
8
+ - Node.js 22.12.0 or newer
9
+ - `npm` and `npx`
10
+ - A local Pharo Launcher installation
11
+ - An MCP client that can start a stdio server
12
+
13
+ ## Install
14
+
15
+ Install the package in a project:
16
+
17
+ ```sh
18
+ npm install @evref-bl/pharo-launcher-mcp
19
+ ```
20
+
21
+ Or run it directly with `npx`:
22
+
23
+ ```sh
24
+ npx @evref-bl/pharo-launcher-mcp
25
+ ```
26
+
27
+ The server prints MCP JSON-RPC messages on stdio. For a human-readable local
28
+ check, run the health command instead:
29
+
30
+ ```sh
31
+ npx @evref-bl/pharo-launcher-mcp --health
32
+ ```
33
+
34
+ `--health` reports resolved paths and wrapper availability. It does not invoke
35
+ Pharo Launcher.
36
+
37
+ ## Discovery
38
+
39
+ pharo-launcher-mcp resolves the Launcher installation from environment
40
+ variables first. If they are not set, it uses host defaults.
41
+
42
+ | Host OS | Launcher directory | VM path | Wrapper |
43
+ | --- | --- | --- | --- |
44
+ | Windows | `%LOCALAPPDATA%\Pharo Launcher` | `<launcher-dir>\PharoConsole.exe` | `pharo-launcher.cmd` |
45
+ | macOS app bundle | `$HOME/Applications/PharoLauncher.app` or `/Applications/PharoLauncher.app` | `<app>/Contents/MacOS/Pharo` | `pharo-launcher.sh` |
46
+ | macOS data directory | `$HOME/Library/Application Support/Pharo Launcher` | `<launcher-dir>/pharo-vm/Pharo.app/Contents/MacOS/Pharo` | `pharo-launcher.sh` |
47
+ | Linux | `$HOME/.local/share/Pharo Launcher` | `<launcher-dir>/pharo-vm/pharo` | `pharo-launcher.sh` |
48
+
49
+ For macOS app bundles, the control image is
50
+ `<app>/Contents/Resources/PharoLauncher.image`.
51
+
52
+ Override the installation when needed:
53
+
54
+ ```sh
55
+ PHARO_LAUNCHER_DIR="/path/to/Pharo Launcher"
56
+ PHARO_LAUNCHER_VM="/path/to/pharo"
57
+ PHARO_LAUNCHER_IMAGE="/path/to/PharoLauncher.image"
58
+ PHARO_LAUNCHER_SCRIPT="/path/to/pharo-launcher.sh"
59
+ npx @evref-bl/pharo-launcher-mcp --health
60
+ ```
61
+
62
+ PowerShell:
63
+
64
+ ```powershell
65
+ $env:PHARO_LAUNCHER_DIR="C:\Path\To\Pharo Launcher"
66
+ $env:PHARO_LAUNCHER_VM="$env:PHARO_LAUNCHER_DIR\PharoConsole.exe"
67
+ $env:PHARO_LAUNCHER_IMAGE="$env:PHARO_LAUNCHER_DIR\PharoLauncher.image"
68
+ $env:PHARO_LAUNCHER_SCRIPT="C:\Path\To\pharo-launcher.cmd"
69
+ npx @evref-bl/pharo-launcher-mcp --health
70
+ ```
71
+
72
+ `PHARO_LAUNCHER_SCRIPT` is optional. If it is not set, the server tries its
73
+ bundled wrapper for the host platform. If no wrapper is available, it invokes
74
+ the VM directly with:
75
+
76
+ ```text
77
+ --headless <PharoLauncher.image> --no-default-preferences clap launcher ...
78
+ ```
79
+
80
+ ## MCP Client Setup
81
+
82
+ A generic MCP client entry looks like this:
83
+
84
+ ```json
85
+ {
86
+ "mcpServers": {
87
+ "pharo-launcher": {
88
+ "command": "npx",
89
+ "args": ["-y", "@evref-bl/pharo-launcher-mcp"]
90
+ }
91
+ }
92
+ }
93
+ ```
94
+
95
+ If the package is installed in a project, point the client at the package
96
+ executable from that project environment:
97
+
98
+ ```json
99
+ {
100
+ "mcpServers": {
101
+ "pharo-launcher": {
102
+ "command": "pharo-launcher-mcp"
103
+ }
104
+ }
105
+ }
106
+ ```
107
+
108
+ For a profile-backed server, add the profile environment variables to the MCP
109
+ client entry. See [Profile mode](profile-mode.md).
110
+
111
+ ## First Tools
112
+
113
+ Run read-only checks first:
114
+
115
+ ```text
116
+ pharo_launcher_health
117
+ pharo_launcher_config
118
+ pharo_launcher_validate_installation
119
+ pharo_launcher_inventory
120
+ ```
121
+
122
+ Use the output this way:
123
+
124
+ - `pharo_launcher_health` confirms whether the resolved directory, VM, control
125
+ image, and wrapper exist. It does not invoke Pharo Launcher.
126
+ - `pharo_launcher_config` shows the same resolved configuration in a direct
127
+ report.
128
+ - `pharo_launcher_validate_installation` runs `--version` and verifies that the
129
+ launcher command can start.
130
+ - `pharo_launcher_inventory` gathers templates, images, profile roots, and
131
+ declared image handles for lifecycle planning.
132
+
133
+ After validation, list templates:
134
+
135
+ ```text
136
+ pharo_launcher_template_update
137
+ pharo_launcher_template_list
138
+ ```
139
+
140
+ Then create an image with an explicit name:
141
+
142
+ ```json
143
+ {
144
+ "tool": "pharo_launcher_image_create",
145
+ "arguments": {
146
+ "templateName": "Pharo 13.0 - 64bit",
147
+ "newImageName": "sample-130",
148
+ "noLaunch": true
149
+ }
150
+ }
151
+ ```
152
+
153
+ The create result is only successful when the new image can be listed and
154
+ inspected after Launcher returns.
155
+
156
+ ## No-Profile Defaults
157
+
158
+ With no profile variables set, commands operate on the user's normal Pharo
159
+ Launcher state scope. pharo-launcher-mcp does not create a hidden default
160
+ profile or redirect images and VMs into its own cache.
161
+
162
+ Detached image launches may write log files under `.pharo-launcher-mcp/logs` in
163
+ the server working directory when no profile log directory is active.
164
+
165
+ ## When To Use A Profile
166
+
167
+ Use a profile when the caller needs an isolated Launcher state scope for tests,
168
+ automation, disposable images, or a project-bound runtime. In profile mode,
169
+ image and VM state are separated from the user's normal Launcher installation.
170
+
171
+ Continue with [Profile mode](profile-mode.md) before running live image create,
172
+ launch, delete, or process cleanup calls from automation.