@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.
- package/README.md +229 -199
- package/bin/pharo-launcher.cmd +46 -46
- package/bin/pharo-launcher.sh +0 -0
- package/dist/commandCatalog.d.ts.map +1 -1
- package/dist/commandCatalog.js +17 -0
- package/dist/commandCatalog.js.map +1 -1
- package/dist/config.d.ts +21 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +75 -6
- package/dist/config.js.map +1 -1
- package/dist/crossProfileCopy.d.ts +87 -0
- package/dist/crossProfileCopy.d.ts.map +1 -0
- package/dist/crossProfileCopy.js +437 -0
- package/dist/crossProfileCopy.js.map +1 -0
- package/dist/discovery.d.ts +165 -1
- package/dist/discovery.d.ts.map +1 -1
- package/dist/discovery.js +744 -1
- package/dist/discovery.js.map +1 -1
- package/dist/imageMetadata.d.ts +1 -0
- package/dist/imageMetadata.d.ts.map +1 -1
- package/dist/imageMetadata.js +35 -2
- package/dist/imageMetadata.js.map +1 -1
- package/dist/launcherCli.d.ts +2 -0
- package/dist/launcherCli.d.ts.map +1 -1
- package/dist/launcherCli.js +561 -62
- package/dist/launcherCli.js.map +1 -1
- package/dist/models.d.ts +2 -0
- package/dist/models.d.ts.map +1 -1
- package/dist/platform.d.ts +2 -0
- package/dist/platform.d.ts.map +1 -1
- package/dist/platform.js +21 -0
- package/dist/platform.js.map +1 -1
- package/dist/resultNormalizer.d.ts.map +1 -1
- package/dist/resultNormalizer.js +47 -0
- package/dist/resultNormalizer.js.map +1 -1
- package/dist/server.d.ts +2 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +387 -10
- package/dist/server.js.map +1 -1
- package/docs/README.md +26 -0
- package/docs/cleanup-hook-boundary.md +94 -0
- package/docs/development.md +59 -23
- package/docs/reference/tools.md +179 -0
- package/docs/troubleshooting.md +135 -0
- package/docs/user/getting-started.md +172 -0
- package/docs/user/profile-mode.md +176 -0
- package/package.json +57 -52
package/docs/development.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Development
|
|
2
2
|
|
|
3
|
-
This document
|
|
4
|
-
focused on installation
|
|
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
|
|
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
|
|
21
|
+
## Local setup
|
|
22
22
|
|
|
23
23
|
```sh
|
|
24
24
|
npm install
|
|
25
|
-
npm run
|
|
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
|
|
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
|
|
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
|
|
47
|
-
|
|
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
|
|
65
|
+
## Process backend
|
|
55
66
|
|
|
56
|
-
Pharo Launcher process commands can vary by host. pharo-launcher-mcp uses a
|
|
57
|
-
backend for `pharo_launcher_process_list` and
|
|
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
|
|
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
|
-
|
|
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
|
|
140
|
+
## Windows live helpers
|
|
123
141
|
|
|
124
142
|
The helper scripts under `scripts/*.ps1` are Windows PowerShell conveniences for
|
|
125
|
-
|
|
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
|
-
|
|
155
|
+
When `-StateRoot` is not supplied, the helper uses:
|
|
138
156
|
|
|
139
157
|
```text
|
|
140
|
-
|
|
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
|
|
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
|
|
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.
|