@evref-bl/pharo-launcher-mcp 0.4.1 → 0.5.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.
- package/README.md +29 -20
- package/dist/answers.d.ts +43 -0
- package/dist/answers.d.ts.map +1 -0
- package/dist/answers.js +744 -0
- package/dist/answers.js.map +1 -0
- package/dist/commandCatalog.d.ts +13 -1
- package/dist/commandCatalog.d.ts.map +1 -1
- package/dist/commandCatalog.js +65 -89
- package/dist/commandCatalog.js.map +1 -1
- package/dist/config.d.ts +5 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +3 -1
- package/dist/config.js.map +1 -1
- package/dist/crossProfileCopy.d.ts +37 -0
- package/dist/crossProfileCopy.d.ts.map +1 -1
- package/dist/crossProfileCopy.js +77 -16
- package/dist/crossProfileCopy.js.map +1 -1
- package/dist/discovery.d.ts +8 -0
- package/dist/discovery.d.ts.map +1 -1
- package/dist/discovery.js +10 -0
- package/dist/discovery.js.map +1 -1
- package/dist/imageStore.d.ts +139 -0
- package/dist/imageStore.d.ts.map +1 -0
- package/dist/imageStore.js +385 -0
- package/dist/imageStore.js.map +1 -0
- package/dist/index.js +4 -4
- package/dist/index.js.map +1 -1
- package/dist/launcher.d.ts +64 -17
- package/dist/launcher.d.ts.map +1 -1
- package/dist/launcher.js +206 -167
- package/dist/launcher.js.map +1 -1
- package/dist/launcherCli.d.ts +13 -0
- package/dist/launcherCli.d.ts.map +1 -1
- package/dist/launcherCli.js +85 -91
- package/dist/launcherCli.js.map +1 -1
- package/dist/models.d.ts +117 -6
- package/dist/models.d.ts.map +1 -1
- package/dist/parser.d.ts +20 -7
- package/dist/parser.d.ts.map +1 -1
- package/dist/parser.js +48 -207
- package/dist/parser.js.map +1 -1
- package/dist/platform.d.ts +6 -0
- package/dist/platform.d.ts.map +1 -1
- package/dist/platform.js +14 -0
- package/dist/platform.js.map +1 -1
- package/dist/probe.d.ts +16 -0
- package/dist/probe.d.ts.map +1 -0
- package/dist/probe.js +31 -0
- package/dist/probe.js.map +1 -0
- package/dist/processTools.d.ts +22 -8
- package/dist/processTools.d.ts.map +1 -1
- package/dist/processTools.js +75 -58
- package/dist/processTools.js.map +1 -1
- package/dist/resultNormalizer.d.ts +9 -0
- package/dist/resultNormalizer.d.ts.map +1 -1
- package/dist/resultNormalizer.js +36 -79
- package/dist/resultNormalizer.js.map +1 -1
- package/dist/server.d.ts +10 -9
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +56 -55
- package/dist/server.js.map +1 -1
- package/dist/ston.d.ts +22 -0
- package/dist/ston.d.ts.map +1 -0
- package/dist/ston.js +127 -0
- package/dist/ston.js.map +1 -0
- package/docs/cleanup-hook-boundary.md +11 -9
- package/docs/development.md +51 -38
- package/docs/reference/tools.md +100 -40
- package/docs/troubleshooting.md +32 -23
- package/docs/user/getting-started.md +4 -4
- package/docs/user/profile-mode.md +30 -21
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -45,12 +45,13 @@ import { openPharoLauncher } from "@evref-bl/pharo-launcher-mcp/launcher";
|
|
|
45
45
|
|
|
46
46
|
const launcher = openPharoLauncher();
|
|
47
47
|
const running = await launcher.listProcesses();
|
|
48
|
-
const images = await launcher.listImages({ nameFilter: "Task" });
|
|
48
|
+
const { imagesDir, images, notImages } = await launcher.listImages({ nameFilter: "Task" });
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
Each call answers the
|
|
52
|
-
`
|
|
53
|
-
|
|
51
|
+
Each call answers a typed object, which the MCP tools only render as text.
|
|
52
|
+
`listImages` reads the images directory and answers `{ imagesDir, images,
|
|
53
|
+
notImages }`; a function that runs a Launcher command answers the launcher
|
|
54
|
+
result, with its `ok`, `data`, `diagnostic` and `command` fields.
|
|
54
55
|
|
|
55
56
|
A TypeScript caller gets those shapes with them, so a result does not have to
|
|
56
57
|
be described a second time on the way out:
|
|
@@ -59,6 +60,7 @@ be described a second time on the way out:
|
|
|
59
60
|
import type {
|
|
60
61
|
LauncherCommandResult,
|
|
61
62
|
LauncherImage,
|
|
63
|
+
LauncherImageList,
|
|
62
64
|
LauncherProcess,
|
|
63
65
|
LauncherTemplate,
|
|
64
66
|
} from "@evref-bl/pharo-launcher-mcp/launcher";
|
|
@@ -96,9 +98,12 @@ server on stdio.
|
|
|
96
98
|
state scope directly.
|
|
97
99
|
- A **pharo-launcher-mcp profile** is an explicit isolated state scope selected
|
|
98
100
|
through environment variables.
|
|
99
|
-
-
|
|
100
|
-
|
|
101
|
-
|
|
101
|
+
- An **image** is a directory `D` of the Launcher's images directory holding
|
|
102
|
+
`D.image` and `D.changes`, Pharo Launcher's own rule.
|
|
103
|
+
- A **launcher result** is the object the library's functions answer for a
|
|
104
|
+
Launcher command: parsed data when available, raw stdout/stderr when asked
|
|
105
|
+
for, parser status, command duration, exit code, and timeout state. The MCP
|
|
106
|
+
tools answer plain text rendered from it, for a model to read.
|
|
102
107
|
|
|
103
108
|
## Quick Start
|
|
104
109
|
|
|
@@ -139,12 +144,15 @@ pharo_launcher_image_list
|
|
|
139
144
|
pharo_launcher_template_list
|
|
140
145
|
```
|
|
141
146
|
|
|
142
|
-
`pharo_launcher_config` only inspects resolved configuration
|
|
143
|
-
|
|
147
|
+
`pharo_launcher_config` only inspects resolved configuration, and
|
|
148
|
+
`pharo_launcher_image_list` reads the images directory; the template list
|
|
149
|
+
crosses the live Launcher boundary.
|
|
144
150
|
|
|
145
151
|
Checking the installation before connecting is the executable's job, not a
|
|
146
|
-
tool's. `pharo-launcher-mcp --health`, `--version-check
|
|
147
|
-
`--validate-installation`
|
|
152
|
+
tool's. `pharo-launcher-mcp --health`, `--version-check` and
|
|
153
|
+
`--validate-installation` each print JSON and exit. `--probe-images` asks the
|
|
154
|
+
Launcher to list its images, exits with that command's status, and prints what
|
|
155
|
+
`pharo_launcher_image_list` answers.
|
|
148
156
|
|
|
149
157
|
## Profile Quick Start
|
|
150
158
|
|
|
@@ -181,8 +189,7 @@ Create an image from a template:
|
|
|
181
189
|
"tool": "pharo_launcher_image_create",
|
|
182
190
|
"arguments": {
|
|
183
191
|
"templateName": "Pharo 13.0 - 64bit",
|
|
184
|
-
"newImageName": "sample-130"
|
|
185
|
-
"noLaunch": true
|
|
192
|
+
"newImageName": "sample-130"
|
|
186
193
|
}
|
|
187
194
|
}
|
|
188
195
|
```
|
|
@@ -221,12 +228,14 @@ spelling of the same intent protects nothing.
|
|
|
221
228
|
What does protect something is the target. `pharo_launcher_process_kill`
|
|
222
229
|
requires exactly one of `pid` or `imageName`, and a PID stops that process
|
|
223
230
|
alone. Prefer the PID a detached launch returned when cleaning up a launch you
|
|
224
|
-
own.
|
|
231
|
+
own. The process tools see only the VMs running an image of this Launcher's
|
|
232
|
+
images directory, so a kill cannot reach another Launcher's image.
|
|
233
|
+
`pharo_launcher_image_delete` refuses an image that a VM runs.
|
|
225
234
|
|
|
226
|
-
`pharo_launcher_image_create` and `pharo_launcher_image_copy`
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
235
|
+
`pharo_launcher_image_create` and `pharo_launcher_image_copy` check that the
|
|
236
|
+
Launcher can list the new image and open it, even after a command that outlived
|
|
237
|
+
the call's timeout. If it cannot, the answer is an error saying which check
|
|
238
|
+
failed.
|
|
230
239
|
|
|
231
240
|
## Documentation
|
|
232
241
|
|
|
@@ -235,8 +244,8 @@ diagnostics.
|
|
|
235
244
|
- [Profile mode](docs/user/profile-mode.md) explains no-profile mode, isolated
|
|
236
245
|
profiles, profile paths, generated configuration, and cross-profile image
|
|
237
246
|
copy.
|
|
238
|
-
- [Tool reference](docs/reference/tools.md) lists the MCP tools,
|
|
239
|
-
|
|
247
|
+
- [Tool reference](docs/reference/tools.md) lists the MCP tools, their
|
|
248
|
+
arguments and answers, the library's results, and special behaviors.
|
|
240
249
|
- [Troubleshooting](docs/troubleshooting.md) maps common setup and live Launcher
|
|
241
250
|
failures to concrete checks.
|
|
242
251
|
- [Development](docs/development.md) covers source layout, tests, local probes,
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { ToolInputError } from "./commandCatalog.js";
|
|
2
|
+
import type { PharoLauncherConfig } from "./config.js";
|
|
3
|
+
import { type CallToolOptions, type PharoLauncher } from "./launcher.js";
|
|
4
|
+
export type ToolResult = {
|
|
5
|
+
content: Array<{
|
|
6
|
+
type: "text";
|
|
7
|
+
text: string;
|
|
8
|
+
}>;
|
|
9
|
+
isError?: boolean;
|
|
10
|
+
};
|
|
11
|
+
/** What one call has to hand: the launcher it opened, and the scope it runs in. */
|
|
12
|
+
export interface AnswerContext {
|
|
13
|
+
launcher: PharoLauncher;
|
|
14
|
+
config: PharoLauncherConfig;
|
|
15
|
+
options: CallToolOptions;
|
|
16
|
+
/** Where this server reads images, as it resolves the path. */
|
|
17
|
+
imagesDir: string;
|
|
18
|
+
}
|
|
19
|
+
type Answer = (context: AnswerContext, input: Record<string, unknown>) => Promise<ToolResult>;
|
|
20
|
+
declare function failure(...lines: ReadonlyArray<string | undefined | false>): ToolResult;
|
|
21
|
+
/**
|
|
22
|
+
* A value that carries whitespace, quoted so that where it ends is never a
|
|
23
|
+
* guess, `"` and `\` escaped: `MCPTool>>inlineValueTextFor:`.
|
|
24
|
+
*/
|
|
25
|
+
export declare function inlineValue(value: string): string;
|
|
26
|
+
/** The Pharo version as Pharo says it: "140" is 14.0 and "61" is 6.1; anything else as it is. */
|
|
27
|
+
export declare function pharoVersionText(raw: string | undefined): string | undefined;
|
|
28
|
+
/** The answer of each tool, by name: the table PLexus mirrors with functions. */
|
|
29
|
+
export declare const toolAnswers: Readonly<Record<string, Answer>>;
|
|
30
|
+
/**
|
|
31
|
+
* Only the arguments a tool's schema names. One it never took is refused,
|
|
32
|
+
* as MCP and PLexus refuse it; one an earlier release took is dropped.
|
|
33
|
+
*/
|
|
34
|
+
export declare function toolArguments(schema: {
|
|
35
|
+
properties?: Record<string, unknown>;
|
|
36
|
+
}, argumentsValue: unknown): Record<string, unknown>;
|
|
37
|
+
/** `Invalid arguments for <tool>. <the error.> It takes <its arguments>.` */
|
|
38
|
+
export declare function invalidArgumentsText(toolName: string, schema: {
|
|
39
|
+
properties?: Record<string, unknown>;
|
|
40
|
+
}, error: ToolInputError): string;
|
|
41
|
+
export declare function unknownToolText(toolName: string): string;
|
|
42
|
+
export { failure as failureResult };
|
|
43
|
+
//# sourceMappingURL=answers.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"answers.d.ts","sourceRoot":"","sources":["../src/answers.ts"],"names":[],"mappings":"AAcA,OAAO,EAKL,cAAc,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQvD,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAYvB,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAgB9F,iBAAS,OAAO,CAAC,GAAG,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC,GAAG,UAAU,CAEhF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAoND,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE5E;AA+mBD,iFAAiF;AACjF,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxD,CAAC;AAkBF;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAChD,cAAc,EAAE,OAAO,GACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAChD,KAAK,EAAE,cAAc,GACpB,MAAM,CAMR;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,CAAC"}
|