{"id":50516586,"url":"https://github.com/evref-bl/pharo-launcher-mcp","last_synced_at":"2026-06-03T01:00:17.572Z","repository":{"id":358265905,"uuid":"1222016011","full_name":"Evref-BL/pharo-launcher-mcp","owner":"Evref-BL","description":"MCP server for Pharo Launcher","archived":false,"fork":false,"pushed_at":"2026-06-02T15:59:48.000Z","size":150,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T16:10:35.905Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Evref-BL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T00:50:38.000Z","updated_at":"2026-06-02T16:00:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Evref-BL/pharo-launcher-mcp","commit_stats":null,"previous_names":["evref-bl/pharo-launcher-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Evref-BL/pharo-launcher-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evref-BL%2Fpharo-launcher-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evref-BL%2Fpharo-launcher-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evref-BL%2Fpharo-launcher-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evref-BL%2Fpharo-launcher-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Evref-BL","download_url":"https://codeload.github.com/Evref-BL/pharo-launcher-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evref-BL%2Fpharo-launcher-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33843611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-03T01:00:16.717Z","updated_at":"2026-06-03T01:00:17.565Z","avatar_url":"https://github.com/Evref-BL.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pharo-launcher-mcp\n\npharo-launcher-mcp is an MCP server for controlling Pharo Launcher from a host\nprocess.\n\nIt exposes Pharo Launcher image, template, VM, and process operations as MCP\ntools. An MCP client can ask it what Launcher installation it resolved, list\ntemplates, create or copy images, launch images, package images, inspect running\nPharo processes, and delete caller-owned images or VMs when explicitly\nconfirmed.\n\nThe server works outside the target images. It does not install code into those\nimages, keep project state, or decide which images are safe to mutate. It is the\nlauncher boundary that higher-level tools can call when they need a concrete\nimage or process action.\n\n## Install\n\nRequirements:\n\n- Node.js 22.12.0 or newer\n- `npm` and `npx`\n- Pharo Launcher installed on the host\n\nInstall from npm:\n\n```sh\nnpm install @evref-bl/pharo-launcher-mcp\n```\n\nRun the MCP server over stdio:\n\n```sh\nnpx @evref-bl/pharo-launcher-mcp\n```\n\nThe package also provides the `pharo-launcher-mcp` executable when installed in\na project or globally.\n\n## Terms\n\n- A **Pharo Launcher installation** is the app or data directory, VM executable,\n  control image, and launcher wrapper used to run Launcher commands.\n- A **launcher state scope** is the set of image, VM, template-source,\n  init-script, and log directories affected by Launcher commands.\n- **No-profile mode** uses the user's normal Pharo Launcher installation and\n  state scope directly.\n- A **pharo-launcher-mcp profile** is an explicit isolated state scope selected\n  through environment variables.\n- A **launcher tool result** is the normalized JSON envelope returned by most\n  tools. It includes parsed data when available, raw stdout/stderr, parser\n  status, command duration, exit code, and timeout state.\n\n## Quick Start\n\nCheck what installation the server will use without invoking Pharo Launcher:\n\n```sh\nnpx @evref-bl/pharo-launcher-mcp --health\n```\n\nIf the discovered paths are not right, set the installation paths explicitly:\n\n```sh\nPHARO_LAUNCHER_DIR=\"/path/to/Pharo Launcher\"\nPHARO_LAUNCHER_VM=\"/path/to/pharo\"\nPHARO_LAUNCHER_IMAGE=\"/path/to/PharoLauncher.image\"\nnpx @evref-bl/pharo-launcher-mcp --health\n```\n\nConfigure an MCP client to start the stdio server. A generic MCP configuration\nlooks like this:\n\n```json\n{\n  \"mcpServers\": {\n    \"pharo-launcher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@evref-bl/pharo-launcher-mcp\"]\n    }\n  }\n}\n```\n\nOnce connected, start with these tools:\n\n```text\npharo_launcher_health\npharo_launcher_config\npharo_launcher_validate_installation\npharo_launcher_inventory\n```\n\n`pharo_launcher_health` and `pharo_launcher_config` only inspect resolved\nconfiguration. `pharo_launcher_validate_installation` invokes `--version`, so it\ncrosses the live Launcher boundary.\n\n## Profile Quick Start\n\nUse a profile when automation or tests need an isolated Launcher state scope:\n\n```sh\nPHARO_LAUNCHER_MCP_PROFILE=isolated\nPHARO_LAUNCHER_MCP_STATE_ROOT=/path/to/launcher-profile\nnpx @evref-bl/pharo-launcher-mcp --health\n```\n\nIn profile mode, pharo-launcher-mcp copies the Launcher control image into the\nprofile root when needed, creates profile directories, and writes a Launcher CLI\nconfiguration that points images, VMs, templates, init scripts, and logs at that\nprofile. No-profile mode stays inactive unless one of the profile environment\nvariables is set.\n\nRead [Profile mode](docs/user/profile-mode.md) before using profiles for live\nimage creation, launch, or cleanup.\n\n## Common Workflows\n\nList available templates:\n\n```text\npharo_launcher_template_update\npharo_launcher_template_list\n```\n\nCreate an image from a template:\n\n```json\n{\n  \"tool\": \"pharo_launcher_image_create\",\n  \"arguments\": {\n    \"templateName\": \"Pharo 13.0 - 64bit\",\n    \"newImageName\": \"sample-130\",\n    \"noLaunch\": true\n  }\n}\n```\n\nCopy an image:\n\n```json\n{\n  \"tool\": \"pharo_launcher_image_copy\",\n  \"arguments\": {\n    \"imageName\": \"sample-130\",\n    \"newImageName\": \"sample-130-copy\"\n  }\n}\n```\n\nLaunch an image:\n\n```json\n{\n  \"tool\": \"pharo_launcher_image_launch\",\n  \"arguments\": {\n    \"imageName\": \"sample-130-copy\",\n    \"displayMode\": \"headless\",\n    \"detached\": true\n  }\n}\n```\n\nPackage an image:\n\n```json\n{\n  \"tool\": \"pharo_launcher_image_package\",\n  \"arguments\": {\n    \"imageName\": \"sample-130-copy\",\n    \"location\": \"/path/to/packages\",\n    \"zip\": true\n  }\n}\n```\n\n## Safety Model\n\nMutating tools are explicit. The destructive ones require `confirm: true`:\n\n```text\npharo_launcher_image_delete\npharo_launcher_image_recreate\npharo_launcher_vm_delete\npharo_launcher_process_kill\npharo_launcher_raw_command\n```\n\n`pharo_launcher_process_kill` requires exactly one target: `pid` or\n`imageName`. Prefer a recorded PID when cleaning up a known launch.\n\n`pharo_launcher_image_create` and `pharo_launcher_image_copy` verify the target\nimage after Launcher reports success. If the target image cannot be listed and\ninspected, the MCP result is an error with the command output and verification\ndiagnostics.\n\nProfile-scoped `pharo_launcher_image_create_from_build` is refused before\nLauncher is invoked, because that Launcher path can launch and download VMs\noutside the configured profile VM directory.\n\n## Documentation\n\n- [Getting started](docs/user/getting-started.md) covers installation,\n  environment discovery, MCP client setup, and the first health checks.\n- [Profile mode](docs/user/profile-mode.md) explains no-profile mode, isolated\n  profiles, profile paths, generated configuration, and cross-profile image\n  copy.\n- [Tool reference](docs/reference/tools.md) lists the MCP tools, arguments,\n  result envelope, and special behaviors.\n- [Troubleshooting](docs/troubleshooting.md) maps common setup and live Launcher\n  failures to concrete checks.\n- [Development](docs/development.md) covers source layout, tests, local probes,\n  and live test boundaries.\n- [Cleanup hook boundary](docs/cleanup-hook-boundary.md) describes the status,\n  timeout, stop, and cleanup contract for caller-managed live checks.\n\n## Source Development\n\n```sh\nnpm install\nnpm run check\n```\n\n`npm run check` runs type checking, build, and unit tests. Live integration tests\nare separate because they invoke a local Pharo Launcher installation:\n\n```sh\nnpm run test:integration\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevref-bl%2Fpharo-launcher-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevref-bl%2Fpharo-launcher-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevref-bl%2Fpharo-launcher-mcp/lists"}