@evref-bl/pharo-launcher-mcp 0.1.1

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 (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +194 -0
  3. package/bin/pharo-launcher.cmd +46 -0
  4. package/bin/pharo-launcher.sh +41 -0
  5. package/dist/commandCatalog.d.ts +15 -0
  6. package/dist/commandCatalog.d.ts.map +1 -0
  7. package/dist/commandCatalog.js +537 -0
  8. package/dist/commandCatalog.js.map +1 -0
  9. package/dist/config.d.ts +21 -0
  10. package/dist/config.d.ts.map +1 -0
  11. package/dist/config.js +60 -0
  12. package/dist/config.js.map +1 -0
  13. package/dist/discovery.d.ts +55 -0
  14. package/dist/discovery.d.ts.map +1 -0
  15. package/dist/discovery.js +109 -0
  16. package/dist/discovery.js.map +1 -0
  17. package/dist/index.d.ts +3 -0
  18. package/dist/index.d.ts.map +1 -0
  19. package/dist/index.js +39 -0
  20. package/dist/index.js.map +1 -0
  21. package/dist/launcherCli.d.ts +29 -0
  22. package/dist/launcherCli.d.ts.map +1 -0
  23. package/dist/launcherCli.js +116 -0
  24. package/dist/launcherCli.js.map +1 -0
  25. package/dist/launcherScript.d.ts +23 -0
  26. package/dist/launcherScript.d.ts.map +1 -0
  27. package/dist/launcherScript.js +47 -0
  28. package/dist/launcherScript.js.map +1 -0
  29. package/dist/models.d.ts +55 -0
  30. package/dist/models.d.ts.map +1 -0
  31. package/dist/models.js +2 -0
  32. package/dist/models.js.map +1 -0
  33. package/dist/parser.d.ts +18 -0
  34. package/dist/parser.d.ts.map +1 -0
  35. package/dist/parser.js +237 -0
  36. package/dist/parser.js.map +1 -0
  37. package/dist/platform.d.ts +16 -0
  38. package/dist/platform.d.ts.map +1 -0
  39. package/dist/platform.js +67 -0
  40. package/dist/platform.js.map +1 -0
  41. package/dist/processTools.d.ts +28 -0
  42. package/dist/processTools.d.ts.map +1 -0
  43. package/dist/processTools.js +254 -0
  44. package/dist/processTools.js.map +1 -0
  45. package/dist/resultNormalizer.d.ts +4 -0
  46. package/dist/resultNormalizer.d.ts.map +1 -0
  47. package/dist/resultNormalizer.js +44 -0
  48. package/dist/resultNormalizer.js.map +1 -0
  49. package/dist/server.d.ts +20 -0
  50. package/dist/server.d.ts.map +1 -0
  51. package/dist/server.js +126 -0
  52. package/dist/server.js.map +1 -0
  53. package/docs/development.md +166 -0
  54. package/package.json +52 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resultNormalizer.d.ts","sourceRoot":"","sources":["../src/resultNormalizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,aAAa,CAAC;AAYrB,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,iBAAiB,GACxB,qBAAqB,CAoCvB"}
@@ -0,0 +1,44 @@
1
+ import { parseLauncherOutput } from "./parser.js";
2
+ function outputFormat(args) {
3
+ return args.includes("--ston") ? "ston" : "text";
4
+ }
5
+ function trimmedMessage(source) {
6
+ const message = source.trim();
7
+ return message ? message : undefined;
8
+ }
9
+ export function normalizeLauncherResult(toolName, args, result) {
10
+ const ok = result.exitCode === 0 && !result.timedOut;
11
+ const format = outputFormat(args);
12
+ const parseResult = ok
13
+ ? parseLauncherOutput(toolName, format, result.stdout)
14
+ : { status: "skipped", format, message: "Command failed" };
15
+ const data = parseResult.status === "parsed"
16
+ ? parseResult.data
17
+ : ok && parseResult.status === "unsupported"
18
+ ? { message: trimmedMessage(result.stdout) }
19
+ : undefined;
20
+ return {
21
+ ok,
22
+ ...(ok && data !== undefined ? { data } : {}),
23
+ parser: {
24
+ status: parseResult.status,
25
+ format: parseResult.format,
26
+ ...(parseResult.message ? { message: parseResult.message } : {}),
27
+ },
28
+ raw: {
29
+ stdout: result.stdout,
30
+ stderr: result.stderr,
31
+ format,
32
+ },
33
+ command: {
34
+ args: [...args],
35
+ durationMs: result.durationMs,
36
+ exitCode: result.exitCode,
37
+ timedOut: result.timedOut,
38
+ ...(result.timeoutReason
39
+ ? { timeoutReason: result.timeoutReason }
40
+ : {}),
41
+ },
42
+ };
43
+ }
44
+ //# sourceMappingURL=resultNormalizer.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resultNormalizer.js","sourceRoot":"","sources":["../src/resultNormalizer.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,SAAS,YAAY,CAAC,IAAuB;IAC3C,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AACnD,CAAC;AAED,SAAS,cAAc,CAAC,MAAc;IACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,QAAgB,EAChB,IAAuB,EACvB,MAAyB;IAEzB,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IACrD,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,WAAW,GAAG,EAAE;QACpB,CAAC,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;QACtD,CAAC,CAAC,EAAE,MAAM,EAAE,SAAkB,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IACtE,MAAM,IAAI,GACR,WAAW,CAAC,MAAM,KAAK,QAAQ;QAC7B,CAAC,CAAC,WAAW,CAAC,IAAI;QAClB,CAAC,CAAC,EAAE,IAAI,WAAW,CAAC,MAAM,KAAK,aAAa;YAC1C,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE;YAC5C,CAAC,CAAC,SAAS,CAAC;IAElB,OAAO;QACL,EAAE;QACF,GAAG,CAAC,EAAE,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,MAAM,EAAE;YACN,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE;QACD,GAAG,EAAE;YACH,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM;SACP;QACD,OAAO,EAAE;YACP,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YACf,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,GAAG,CAAC,MAAM,CAAC,aAAa;gBACtB,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE;gBACzC,CAAC,CAAC,EAAE,CAAC;SACR;KACF,CAAC;AACJ,CAAC"}
@@ -0,0 +1,20 @@
1
+ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
2
+ import type { PharoLauncherConfig } from "./config.js";
3
+ import { type LauncherCliRunner } from "./discovery.js";
4
+ type ToolResult = {
5
+ content: Array<{
6
+ type: "text";
7
+ text: string;
8
+ }>;
9
+ isError?: boolean;
10
+ };
11
+ export interface CallToolOptions {
12
+ config?: PharoLauncherConfig;
13
+ runner?: LauncherCliRunner;
14
+ timeoutMs?: number;
15
+ }
16
+ export declare function callTool(name: string, argumentsValue: unknown, options?: CallToolOptions): Promise<ToolResult>;
17
+ export declare function createServer(): Server;
18
+ export declare function startStdioServer(): Promise<void>;
19
+ export {};
20
+ //# sourceMappingURL=server.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAYnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,gBAAgB,CAAC;AA4CxB,KAAK,UAAU,GAAG;IAChB,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,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA+BD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,OAAO,EACvB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,UAAU,CAAC,CA+DrB;AAED,wBAAgB,YAAY,IAAI,MAAM,CAsBrC;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}
package/dist/server.js ADDED
@@ -0,0 +1,126 @@
1
+ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
2
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
+ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
4
+ import { buildLauncherCommandArgs, launcherCommandTools, rawCommandTool, ToolInputError, } from "./commandCatalog.js";
5
+ import { getPharoLauncherConfigReport, getPharoLauncherHealth, getPharoLauncherVersion, validatePharoLauncherInstallation, } from "./discovery.js";
6
+ import { runLauncherCli } from "./launcherCli.js";
7
+ import { runNativeProcessTool, shouldUseNativeProcessTool, } from "./processTools.js";
8
+ import { normalizeLauncherResult } from "./resultNormalizer.js";
9
+ const serverVersion = "0.1.1";
10
+ const emptyInputSchema = {
11
+ type: "object",
12
+ properties: {},
13
+ additionalProperties: false,
14
+ };
15
+ const tools = [
16
+ {
17
+ name: "pharo_launcher_health",
18
+ description: "Return pharo-launcher-mcp health, resolved paths, script source, and file existence without invoking PharoLauncher.",
19
+ inputSchema: emptyInputSchema,
20
+ },
21
+ {
22
+ name: "pharo_launcher_config",
23
+ description: "Return resolved PharoLauncher configuration paths, script source, and file existence.",
24
+ inputSchema: emptyInputSchema,
25
+ },
26
+ {
27
+ name: "pharo_launcher_version",
28
+ description: "Run a harmless PharoLauncher --version call.",
29
+ inputSchema: emptyInputSchema,
30
+ },
31
+ {
32
+ name: "pharo_launcher_validate_installation",
33
+ description: "Validate resolved paths and run a harmless PharoLauncher --version call.",
34
+ inputSchema: emptyInputSchema,
35
+ },
36
+ ...launcherCommandTools,
37
+ rawCommandTool,
38
+ ];
39
+ function textResult(text, isError = false) {
40
+ return {
41
+ content: [{ type: "text", text }],
42
+ ...(isError ? { isError } : {}),
43
+ };
44
+ }
45
+ function jsonResult(value, isError = false) {
46
+ return textResult(JSON.stringify(value, null, 2), isError);
47
+ }
48
+ async function cliResult(toolName, args, options) {
49
+ const runner = options.runner ?? runLauncherCli;
50
+ const result = toolName.startsWith("pharo_launcher_process_") && shouldUseNativeProcessTool()
51
+ ? await runNativeProcessTool(args, options.timeoutMs)
52
+ : await runner(args, {
53
+ ...(options.config ? { config: options.config } : {}),
54
+ ...(options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}),
55
+ });
56
+ const isError = result.exitCode !== 0 || result.timedOut;
57
+ return jsonResult(normalizeLauncherResult(toolName, args, result), isError);
58
+ }
59
+ export async function callTool(name, argumentsValue, options = {}) {
60
+ const runner = options.runner ?? runLauncherCli;
61
+ switch (name) {
62
+ case "pharo_launcher_health":
63
+ return jsonResult({
64
+ version: serverVersion,
65
+ ...getPharoLauncherHealth(options.config),
66
+ });
67
+ case "pharo_launcher_config":
68
+ return jsonResult(getPharoLauncherConfigReport(options.config));
69
+ case "pharo_launcher_version": {
70
+ const result = await getPharoLauncherVersion(runner, options.config);
71
+ return jsonResult(result, !result.ok);
72
+ }
73
+ case "pharo_launcher_validate_installation": {
74
+ const result = await validatePharoLauncherInstallation(runner, options.config);
75
+ return jsonResult(result, !result.ok);
76
+ }
77
+ default:
78
+ try {
79
+ const commandArgs = buildLauncherCommandArgs(name, argumentsValue);
80
+ if (commandArgs) {
81
+ return cliResult(name, commandArgs, options);
82
+ }
83
+ }
84
+ catch (error) {
85
+ if (error instanceof ToolInputError) {
86
+ return jsonResult({ error: error.message }, true);
87
+ }
88
+ throw error;
89
+ }
90
+ if (name === rawCommandTool.name) {
91
+ try {
92
+ return cliResult(name, rawCommandTool.buildArgs(argumentsValue), options);
93
+ }
94
+ catch (error) {
95
+ if (error instanceof ToolInputError) {
96
+ return jsonResult({ error: error.message }, true);
97
+ }
98
+ throw error;
99
+ }
100
+ }
101
+ return jsonResult({
102
+ error: `Unknown tool: ${name}`,
103
+ }, true);
104
+ }
105
+ }
106
+ export function createServer() {
107
+ const server = new Server({
108
+ name: "pharo-launcher-mcp",
109
+ version: serverVersion,
110
+ }, {
111
+ capabilities: {
112
+ tools: {},
113
+ },
114
+ });
115
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
116
+ tools: [...tools],
117
+ }));
118
+ server.setRequestHandler(CallToolRequestSchema, async (request) => callTool(request.params.name, request.params.arguments ?? {}));
119
+ return server;
120
+ }
121
+ export async function startStdioServer() {
122
+ const server = createServer();
123
+ const transport = new StdioServerTransport();
124
+ await server.connect(transport);
125
+ }
126
+ //# sourceMappingURL=server.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,166 @@
1
+ # pharo-launcher-mcp Development
2
+
3
+ This document contains development notes for pharo-launcher-mcp. The main README is kept
4
+ focused on installation, configuration, and tool usage.
5
+
6
+ ## Source Layout
7
+
8
+ - `src/server.ts`: MCP server surface and tool dispatch.
9
+ - `src/commandCatalog.ts`: Pharo Launcher command definitions and input checks.
10
+ - `src/config.ts`: Pharo Launcher and profile path resolution.
11
+ - `src/platform.ts`: host-specific defaults and wrapper selection.
12
+ - `src/launcherScript.ts`: bundled wrapper discovery.
13
+ - `src/launcherCli.ts`: command execution boundary.
14
+ - `src/processTools.ts`: native process list and kill backends.
15
+ - `src/parser.ts`: Pharo Launcher output parsing.
16
+ - `src/resultNormalizer.ts`: normalized MCP result envelopes.
17
+ - `bin/pharo-launcher.cmd`: Windows wrapper.
18
+ - `bin/pharo-launcher.sh`: POSIX wrapper.
19
+ - `scripts/*.ps1`: Windows helper scripts for local live checks.
20
+
21
+ ## Local Setup
22
+
23
+ ```sh
24
+ npm install
25
+ npm run build
26
+ npm test
27
+ ```
28
+
29
+ Useful scripts:
30
+
31
+ ```sh
32
+ npm run build
33
+ npm run typecheck
34
+ npm test
35
+ npm run test:integration
36
+ ```
37
+
38
+ `npm test` runs unit coverage only. It does not invoke a local Pharo Launcher.
39
+
40
+ ## Platform Contract
41
+
42
+ The production code handles Windows, macOS, and Linux explicitly:
43
+
44
+ - Windows defaults to `%LOCALAPPDATA%\Pharo Launcher`,
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`.
48
+ - Linux defaults to `$HOME/.local/share/Pharo Launcher`, `pharo-vm/pharo`,
49
+ and `pharo-launcher.sh`.
50
+
51
+ `src/crossPlatform.test.ts` covers configuration defaults, bundled wrapper
52
+ selection, and native process backend selection for all three platforms.
53
+
54
+ ## Process Backend
55
+
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:
59
+
60
+ - Windows uses a PowerShell/CIM query.
61
+ - macOS and Linux use `ps -axo pid=,args=`.
62
+ - Unsupported host platforms return an explicit unsupported-backend error.
63
+
64
+ ## Parsing Boundary
65
+
66
+ `src/parser.ts` is the only layer that translates Pharo Launcher output into
67
+ pharo-launcher-mcp models.
68
+
69
+ - STON output is parsed where Pharo Launcher exposes stable STON for list/info
70
+ commands.
71
+ - Plain text is parsed only for stable tables and process listings.
72
+ - Unsupported commands still return command metadata and raw output.
73
+ - Failed commands skip parsing so command failure is not confused with parser
74
+ failure.
75
+
76
+ Typed launcher results include `parser.status` so result handlers can distinguish
77
+ normalized model data from raw-only output.
78
+
79
+ Stable model names include:
80
+
81
+ ```text
82
+ LauncherImage
83
+ LauncherTemplate
84
+ LauncherVm
85
+ LauncherProcess
86
+ LauncherCommandResult
87
+ ```
88
+
89
+ ## Integration Tests
90
+
91
+ Run the live integration suite explicitly:
92
+
93
+ ```sh
94
+ npm run test:integration
95
+ ```
96
+
97
+ The integration suite prepares an isolated temporary launcher profile by copying
98
+ the Pharo Launcher control image. It includes live checks for:
99
+
100
+ - health
101
+ - version
102
+ - installation validation
103
+ - config
104
+ - template categories, list, info, and update
105
+ - VM list and info
106
+ - image list
107
+ - image create
108
+ - image copy
109
+ - image info
110
+ - image package
111
+ - image launch
112
+ - image recreate
113
+ - image delete
114
+ - process list
115
+ - process kill
116
+ - raw command with explicit confirmation
117
+
118
+ External-source image creation variants such as build, pull request,
119
+ repository, SHA, and VM mutation commands should use explicit fixtures because
120
+ they require network inputs or can alter VM installations.
121
+
122
+ ## Windows Live Helpers
123
+
124
+ The helper scripts under `scripts/*.ps1` are Windows PowerShell conveniences for
125
+ the current development environment:
126
+
127
+ ```powershell
128
+ .\scripts\verify-environment.ps1
129
+ npm run live:profile
130
+ npm run live:smoke
131
+ ```
132
+
133
+ The live smoke test uses a dedicated profile root and copies the Pharo Launcher
134
+ control image there before making live calls. It runs harmless checks by
135
+ default: health, `--version`, and installation validation.
136
+
137
+ Default profile root:
138
+
139
+ ```text
140
+ C:\dev\code\git\.pharo-launcher-mcp\profiles\live-test
141
+ ```
142
+
143
+ Refresh the copied launcher control image:
144
+
145
+ ```powershell
146
+ .\scripts\live-smoke.ps1 -ForceProfileRefresh
147
+ ```
148
+
149
+ These helpers are not a substitute for cross-platform verification on macOS and
150
+ Linux.
151
+
152
+ ## Local Probes
153
+
154
+ Probe the local Pharo Launcher image list without starting MCP stdio:
155
+
156
+ ```powershell
157
+ npm run build
158
+ node .\dist\index.js --health
159
+ node .\dist\index.js --probe-images
160
+ ```
161
+
162
+ Start the MCP server over stdio from a local build:
163
+
164
+ ```powershell
165
+ node .\dist\index.js
166
+ ```
package/package.json ADDED
@@ -0,0 +1,52 @@
1
+ {
2
+ "name": "@evref-bl/pharo-launcher-mcp",
3
+ "version": "0.1.1",
4
+ "description": "MCP server for controlling Pharo Launcher images, templates, VMs, and processes.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "keywords": [
8
+ "mcp",
9
+ "pharo",
10
+ "pharo-launcher",
11
+ "pharolauncher",
12
+ "smalltalk"
13
+ ],
14
+ "bin": {
15
+ "pharo-launcher-mcp": "dist/index.js"
16
+ },
17
+ "main": "./dist/index.js",
18
+ "types": "./dist/index.d.ts",
19
+ "files": [
20
+ "bin",
21
+ "docs/development.md",
22
+ "dist",
23
+ "LICENSE",
24
+ "README.md"
25
+ ],
26
+ "engines": {
27
+ "node": ">=24"
28
+ },
29
+ "publishConfig": {
30
+ "access": "public"
31
+ },
32
+ "scripts": {
33
+ "build": "tsc -p tsconfig.json",
34
+ "prepack": "npm run build",
35
+ "typecheck": "tsc -p tsconfig.json --noEmit",
36
+ "test": "npm run test:unit",
37
+ "test:unit": "vitest run --exclude src/**/*.integration.test.ts",
38
+ "test:integration": "vitest run src/integration/live.integration.test.ts src/integration/lifecycle.integration.test.ts --testTimeout=900000",
39
+ "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
40
+ "verify:env": "powershell -ExecutionPolicy Bypass -File ./scripts/verify-environment.ps1",
41
+ "live:profile": "powershell -ExecutionPolicy Bypass -File ./scripts/prepare-live-profile.ps1",
42
+ "live:smoke": "powershell -ExecutionPolicy Bypass -File ./scripts/live-smoke.ps1"
43
+ },
44
+ "dependencies": {
45
+ "@modelcontextprotocol/sdk": "^1.29.0"
46
+ },
47
+ "devDependencies": {
48
+ "@types/node": "^24.0.0",
49
+ "typescript": "^5.9.0",
50
+ "vitest": "^4.0.0"
51
+ }
52
+ }