@evref-bl/pharo-mcp 0.0.0-stage → 1.4.0

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+[![Pharo version](https://img.shields.io/badge/Pharo-12%20%7C%2013%20%7C%2014-%23aac9ff.svg)](https://github.com/pharo-project/Pharo)
+[![CI](https://github.com/Evref-BL/MCP/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/Evref-BL/MCP/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush)
+[![Coverage Status](https://coveralls.io/repos/github/Evref-BL/MCP/badge.svg?branch=main)](https://coveralls.io/github/Evref-BL/MCP?branch=main)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# MCP for Pharo
+
+MCP is an in-image [Model Context Protocol](https://modelcontextprotocol.io/)
+server for Pharo. It lets MCP clients inspect and change the running image
+through Pharo-aware tools for packages, classes, methods, tests, repositories,
+change history, debugging, and UI inspection.
+
+MCP works through the Pharo ecosystem—compilation, refactorings, Renraku,
+SUnit, Iceberg, Metacello, Epicea, and Spec—rather than patching exported Tonel
+files as plain text.
+
+## Supported Versions
+
+Pharo 12, 13, and 14 are supported. Development targets Pharo 13 while CI
+checks the full matrix.
+
+## Install And Start
+
+Load MCP in a supported image:
+
+```smalltalk
+Metacello new
+   baseline: 'MCP';
+   repository: 'github://Evref-BL/MCP:main/src';
+   load.
+```
+
+Start the Streamable HTTP server:
+
+```smalltalk
+mcp := MCP new.
+mcp port: 4000.
+mcp start.
+```
+
+Connect a local MCP client to `http://127.0.0.1:4000`. Client configuration
+formats differ; see [Getting started](templates/pharo-references/getting-started.md) for setup
+and first calls.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Getting started](templates/pharo-references/getting-started.md)
+- [Using MCP from an agent](templates/pharo-references/using-pharo-mcp.md)
+- [Tool reference](templates/pharo-references/tool-reference.md)
+- [Safety and ecosystem integration](templates/pharo-references/safety-and-ecosystem.md)
+- [Troubleshooting](templates/pharo-references/troubleshooting.md)
+- [Developing MCP](docs/developing-mcp.md)
+
+## Agent Templates
+
+Install the guide, local references, workflow skills, and direct MCP
+configuration for an agent host into the current project:
+
+```sh
+npx @evref-bl/pharo-mcp install --host codex
+```
+
+Use `--host claude` or `--host opencode` for those hosts. The direct MCP
+configuration expects port `4000`; update it when the image uses another port.
+
+Node integrations that provide their own MCP transport can install only the
+guide, skills, references, and soft-loading instruction block:
+
+```js
+import { installGuidance } from "@evref-bl/pharo-mcp";
+
+installGuidance({ host: "codex", cwd: process.cwd() });
+```
+
+## Contributing
+
+Use Pharo 13 for normal development and preserve Pharo 12/14 compatibility.
+Live behavior must be verified in an image; source inspection alone is not
+enough. Start with [AGENTS.md](AGENTS.md) and
+[MCP verification](docs/mcp-verification.md).

package/bin/pharo-mcp.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { install } from "../node/index.js";
+
+function usage() {
+  return "Usage: pharo-mcp install --host <claude|codex|opencode>";
+}
+
+const [command, option, host, ...extra] = process.argv.slice(2);
+
+if (command !== "install" || option !== "--host" || !host || extra.length > 0) {
+  console.error(usage());
+  process.exitCode = 1;
+} else {
+  try {
+    const result = install({ host });
+    console.log(`Installed Pharo MCP templates for ${result.host} in ${result.cwd}.`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/node/index.js

@@ -0,0 +1 @@
+export { install, installGuidance, templateDirectory } from "./installer.js";

package/node/installer.js

@@ -0,0 +1,151 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const hosts = {
+  claude: {
+    directory: ".claude",
+    guide: "CLAUDE.md",
+    configuration: [".claude/mcp.json", ".mcp.json"],
+  },
+  codex: {
+    directory: ".codex",
+    guide: "AGENTS.md",
+    configuration: [".codex/config.toml", ".codex/config.toml"],
+  },
+  opencode: {
+    directory: ".opencode",
+    guide: "AGENTS.md",
+    configuration: [".opencode/opencode.json", "opencode.json"],
+  },
+};
+
+const managedBlock = {
+  begin: "<!-- pharo-mcp:begin -->",
+  end: "<!-- pharo-mcp:end -->",
+};
+
+export function templateDirectory() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../templates");
+}
+
+function hostConfiguration(host) {
+  const configuration = hosts[host];
+  if (!configuration) {
+    throw new Error(`Unknown agent host: ${host}. Use claude, codex, or opencode.`);
+  }
+  return configuration;
+}
+
+function filesIn(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const source = path.join(directory, entry.name);
+    return entry.isDirectory() ? filesIn(source) : [source];
+  });
+}
+
+function directoryPlan(sourceRelativePath, targetRelativePath) {
+  const sourceDirectory = path.join(templateDirectory(), sourceRelativePath);
+  return filesIn(sourceDirectory).map((source) => ({
+    source,
+    target: path.join(targetRelativePath, path.relative(sourceDirectory, source)),
+  }));
+}
+
+function filePlan(sourceRelativePath, targetRelativePath) {
+  return [{
+    source: path.join(templateDirectory(), sourceRelativePath),
+    target: targetRelativePath,
+  }];
+}
+
+function guidancePlan(configuration) {
+  return [
+    ...filePlan("pharo.AGENTS.md", path.join(configuration.directory, "pharo.AGENTS.md")),
+    ...directoryPlan("pharo-skills", path.join(configuration.directory, "skills")),
+    ...directoryPlan("pharo-references", path.join(configuration.directory, "pharo-references")),
+  ];
+}
+
+function fullPlan(configuration) {
+  const [source, target] = configuration.configuration;
+  return [...guidancePlan(configuration), ...filePlan(source, target)];
+}
+
+function absolutePlan(cwd, plan) {
+  return plan.map(({ source, target }) => ({ source, target: path.resolve(cwd, target) }));
+}
+
+function assertCompatible(plan) {
+  for (const { source, target } of plan) {
+    if (!fs.existsSync(target)) {
+      continue;
+    }
+    if (!fs.statSync(target).isFile() || !fs.readFileSync(source).equals(fs.readFileSync(target))) {
+      throw new Error(`Refusing to replace existing file: ${target}`);
+    }
+  }
+}
+
+function copyMissing(plan) {
+  for (const { source, target } of plan) {
+    if (fs.existsSync(target)) {
+      continue;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(source, target);
+    fs.chmodSync(target, fs.statSync(source).mode & 0o777);
+  }
+}
+
+function bridgeContent(directory) {
+  return `${managedBlock.begin}\nWhen the task uses Pharo, read \`${directory}/pharo.AGENTS.md\` before acting.\n${managedBlock.end}\n`;
+}
+
+function updatedGuide(current, block) {
+  const starts = current.includes(managedBlock.begin);
+  const ends = current.includes(managedBlock.end);
+  if (starts !== ends) {
+    throw new Error("The existing Pharo MCP instruction block is incomplete.");
+  }
+  if (starts) {
+    const expression = new RegExp(`${managedBlock.begin}[\\s\\S]*?${managedBlock.end}\\n?`);
+    return current.replace(expression, block);
+  }
+  return current ? `${current.trimEnd()}\n\n${block}` : block;
+}
+
+function guidePlan(cwd, configuration) {
+  const target = path.join(cwd, configuration.guide);
+  const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  return { target, content: updatedGuide(current, bridgeContent(configuration.directory)) };
+}
+
+function writeGuide({ target, content }) {
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content);
+}
+
+function prepare(options, direct) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const configuration = hostConfiguration(options.host);
+  const plan = absolutePlan(cwd, direct ? fullPlan(configuration) : guidancePlan(configuration));
+  const guide = guidePlan(cwd, configuration);
+  assertCompatible(plan);
+  return { configuration, cwd, guide, plan };
+}
+
+function apply(options, direct) {
+  const { configuration, cwd, guide, plan } = prepare(options, direct);
+  copyMissing(plan);
+  writeGuide(guide);
+  return { cwd, host: options.host, directory: configuration.directory };
+}
+
+export function installGuidance(options) {
+  return apply(options, false);
+}
+
+export function install(options) {
+  return apply(options, true);
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@evref-bl/pharo-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "Pharo MCP agent-host templates",
+  "license": "MIT",
+  "type": "module",
+  "exports": "./node/index.js",
+  "bin": {
+    "pharo-mcp": "./bin/pharo-mcp.js"
+  },
+  "files": [
+    "bin",
+    "node",
+    "templates",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Evref-BL/MCP.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Evref-BL/MCP/issues"
+  },
+  "homepage": "https://github.com/Evref-BL/MCP#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/.claude/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "pharo": {
+      "type": "http",
+      "url": "http://127.0.0.1:4000"
+    }
+  }
+}

package/templates/.codex/config.toml

@@ -0,0 +1,4 @@
+[mcp_servers.pharo]
+enabled = true
+required = true
+url = "http://127.0.0.1:4000"

package/templates/.opencode/opencode.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "pharo": {
+      "type": "remote",
+      "url": "http://127.0.0.1:4000",
+      "enabled": true
+    }
+  }
+}

package/templates/pharo-references/debugger-driven-development.md

@@ -0,0 +1,101 @@
+# Debugger-Driven Development
+
+Applies when using MCP-Pharo to repair code from a live debugger state.
+
+Debugger-driven development keeps execution paused at the failure, edits the
+relevant method, and continues from the debugger instead of restarting the
+whole scenario.
+
+## Goal
+
+Repair code from the paused execution context while preserving the debugger as
+the source of truth for receiver, selector, class side, selected frame, and
+repair action.
+
+## Main Flow
+
+1. Get a state with `debug_state_get`, `debug_capture`, or
+   `debug_candidate_attach`.
+2. Check `repairActions` before inventing an edit target.
+3. Call `debug_method_update` with the action's `sessionId`, `stateId`, and `frameRef`.
+4. Review returned `critiques`.
+5. If the edit is blocked by critiques and the critiques are acceptable, retry
+   with `ignoreCritiques=true`.
+6. Continue with the returned state when execution pauses again.
+
+## Must Do
+
+- Use the repair action's frame reference instead of selecting a target class or
+  method by hand.
+- Review critiques before allowing the repaired computation to proceed.
+- Treat returned states and references as fresh; discard older state-scoped
+  references after each edit or control action.
+- Stop after the bounded action the user requested and report the resulting
+  state.
+
+## Do Not
+
+- Do not guess the receiver class, target behavior, selector, or class side for
+  missing-method repair.
+- Do not use general `image_evaluate` code to mutate contexts or drive
+  debugger UI.
+- Do not continue issuing frame commands when the repair outcome is running,
+  timed out, completed, or blocked by critiques.
+
+## Missing Methods
+
+For `MessageNotUnderstood`, `debug_method_update` creates the method implied by the
+paused message send. The target behavior, selector, class side, and frame are
+derived from the debug state; do not guess them in the request.
+
+You may omit `methodSource` when the default generated source is acceptable.
+Provide `methodSource` when the method should do real work. The compiled method
+is formatted before it is returned or used to continue execution.
+
+## Stub Methods
+
+For `subclassResponsibility`, `shouldBeImplemented`, and `notYetImplemented`,
+`debug_method_update` recompiles the method associated with the selected repair frame.
+Use the repair action's frame reference instead of selecting a target class by
+hand.
+
+## Critiques
+
+`debug_method_update` uses the same critique gate expected from method-editing tools. It
+stops before proceeding when critiques are reported unless
+`ignoreCritiques=true`.
+
+Use `ignoreCritiques=true` only after reading the critiques and deciding that
+continuing the suspended computation is still the right next step.
+
+## Proceeding
+
+After a successful accepted edit, `debug_method_update` attempts to proceed the repaired
+computation. Outcomes include completed, paused, running, timed out, or blocked
+by critiques.
+
+When the outcome is paused, use the returned state and repair actions. When it
+is completed, inspect the result class and print string. When it is running or
+timed out, avoid issuing stale frame commands.
+
+## Human-Owned Debuggers
+
+For debugger windows opened by a human, discover candidates with
+`debug_candidate_search`, attach with `debug_candidate_attach`, and let the
+debugger controller perform control actions. The visible debugger remains the
+UI owner. Do not use general `image_evaluate` code to drive Morphic debugger
+widgets or mutate contexts directly.
+
+When the user asks you to perform a bounded action and give control back, run
+only the requested debugger calls, then stop and report the resulting state.
+
+## Reporting
+
+When finishing a debugger-driven repair, report:
+
+- repair action used;
+- method created or recompiled, when any;
+- critiques returned and whether they were accepted;
+- proceed outcome;
+- final state or why no fresh state is available;
+- cleanup still needed.

package/templates/pharo-references/debugging.md

@@ -0,0 +1,147 @@
+# Debugging Tools
+
+Applies when using MCP-Pharo to capture exceptions, inspect debug sessions,
+control paused execution, manage breakpoints, or repair code from a debugger
+state.
+
+## Goal
+
+Use debugger tools without guessing from source, driving Morphic debugger UI by
+hand, or issuing stale frame and variable references.
+
+Debugger tools are discoverable, not part of the default static surface.
+
+## Discovery Flow
+
+1. Use `tool_search` with `group=debugging` to find available debugger
+   tools.
+2. Use `tool_get` for the exact schema of the tool you plan to call.
+3. If the current client exposes a catalog bridge, use `tool_call` to invoke
+   the selected debugger tool by name. Otherwise use the callable form exposed
+   by the current client.
+
+## Must Do
+
+- Treat `stateId`, `frameRef`, and `variableRef` values as opaque and
+  state-scoped.
+- Use the newest returned state after every control or edit action.
+- Keep stack and variable limits small first, then expand only what is needed.
+- Clear temporary breakpoints and forget agent-owned sessions when the task is
+  done.
+- Report the exact debugger tool names used and the final session state.
+
+## Do Not
+
+- Do not drive debugger windows or mutate contexts through general `image_evaluate`
+  code.
+- Do not reuse frame or variable references after stepping, restarting,
+  resuming, terminating, or editing.
+- Do not leave breakpoints or captured sessions behind without reporting them.
+- Do not use debugger editing as a substitute for normal source tools when
+  there is no paused debugger state.
+
+## Tool Map
+
+| Tool | Use |
+| --- | --- |
+| `debug_capture` | Evaluate a Smalltalk expression in a bounded worker process and capture runtime exceptions as tracked debug sessions. |
+| `debug_test_run` | Run one SUnit test method in a bounded worker process and capture failures or errors as tracked debug sessions. |
+| `debug_session_list` | List tracked debug sessions. |
+| `debug_session_get` | Inspect one tracked debug session summary. |
+| `debug_session_remove` | Remove a tracked debug session from the registry. |
+| `debug_candidate_search` | Search unattached open debugger candidates. |
+| `debug_candidate_attach` | Attach an open debugger candidate and return its debug state. |
+| `debug_state_get` | Return the current session snapshot: stack, selected frame, source, scopes, repair actions, and state-scoped refs. |
+| `debug_variable_get` | Expand scope and variable refs returned by `debug_state_get`. |
+| `debug_expression_evaluate` | Evaluate a Smalltalk expression in a selected debug frame. |
+| `debug_session_step_into` | Step into the selected frame of a tracked session. |
+| `debug_session_step_over` | Step over the selected frame of a tracked session. |
+| `debug_session_step_through` | Step through the selected frame of a tracked session. |
+| `debug_session_restart` | Restart the selected frame of a tracked session. |
+| `debug_session_resume` | Resume a tracked session. |
+| `debug_session_terminate` | Terminate a tracked session. |
+| `debug_breakpoint_list` | List tracked transient DebugPoint breakpoints. |
+| `debug_breakpoint_set` | Install a transient method-entry or source-interval DebugPoint breakpoint. |
+| `debug_breakpoint_remove` | Remove one tracked transient DebugPoint breakpoint. |
+| `debug_breakpoint_enable` | Enable one tracked transient DebugPoint breakpoint. |
+| `debug_breakpoint_disable` | Disable one tracked transient DebugPoint breakpoint. |
+| `debug_breakpoint_clear` | Remove all tracked transient DebugPoint breakpoints. |
+| `debug_method_update` | Update the method associated with a paused debug state, then proceed when possible. |
+
+## Session Workflow
+
+Use `debug_capture` when the agent should run code and capture its own
+failure. If execution completes normally, there is no debugger session. If a
+runtime exception is captured, use the returned `sessionId` and `state`.
+
+Use `debug_test_run` when the failure is already expressed as one SUnit test method.
+If the test passes, there is no debugger session. If it fails or errors, use the
+returned `sessionId` and `state`.
+
+Use `debug_candidate_search` when a human already opened a debugger. It returns
+unattached candidates with identifying details. Attach by passing the
+candidate's `candidateRef` to `debug_candidate_attach`.
+
+Use `debug_session_remove` when you are done. Removing an agent-owned captured
+session can terminate its worker process. Removing an attached human debugger
+only removes it from the MCP registry.
+
+## State And References
+
+Treat `stateId`, `frameRef`, and `variableRef` values as state-scoped opaque
+references. After a debug-session control tool or `debug_method_update`, old
+frame and variable refs can be stale. Use the new returned state before
+evaluating, expanding variables, or controlling execution again.
+
+Use `debug_state_get` as the main context-loading tool. Keep stack and variable
+limits small first, then expand details with `debug_variable_get` only when needed.
+
+Use `debug_expression_evaluate` only for expressions that need the selected frame's
+receiver or temporaries. Prefer normal code tools for project edits.
+
+## Control
+
+Use `debug_session_step_into`, `debug_session_step_over`,
+`debug_session_step_through`, `debug_session_restart`,
+`debug_session_resume`, and `debug_session_terminate` for control actions.
+Control tools can return a `debug_state_get` snapshot when execution pauses.
+Set `returnState=true` when the next step needs that snapshot inline;
+otherwise call `debug_state_get` after the control action.
+When the user asks for a bounded action, such as "step into twice", perform
+those control calls and stop.
+
+For externally attached debuggers, control should operate through the attached
+debugger controller so the visible debugger remains the owner of its UI. Do not
+manipulate debugger windows or contexts with general `image_evaluate` code.
+
+## Breakpoints
+
+Use the `debug_breakpoint_*` tools for temporary method-entry or
+source-interval DebugPoint breakpoints. Clear breakpoints when the debugging
+task ends.
+
+File/line breakpoints are intentionally not emulated. Resolve source intervals
+from the relevant method when source-interval precision is needed.
+
+## Debugger-Driven Development
+
+When a debug state offers repair actions, prefer `debug_method_update` over separate
+manual edits. It can create missing methods or recompile stub/selected methods,
+formats the compiled method, reports critiques, and proceeds when the edit is
+accepted.
+
+Read [Debugger-Driven Development](debugger-driven-development.md) before using
+`debug_method_update` for missing methods, `subclassResponsibility`,
+`shouldBeImplemented`, `notYetImplemented`, or iterative repair workflows.
+
+## Reporting
+
+When finishing debugger work, report:
+
+- how the session was obtained: capture, test, discovered debugger, or attached
+  debugger;
+- debugger tools called;
+- final session outcome: completed, paused, running, terminated, forgotten, or
+  still open;
+- breakpoints created, cleared, or left in place;
+- cleanup performed or still needed.