@evref-bl/pharo-mcp 2.3.0 → 3.1.0

package/templates/pharo-references/safety-and-ecosystem.md

@@ -1,322 +0,0 @@
-# Safety And Ecosystem Integration
-
-MCP is safest when callers use the dedicated tools before falling back to raw
-evaluation. The tools are built around Pharo's normal development systems, so an
-agent works through image-aware operations instead of editing exported source
-text blindly.
-
-## Tool Boundary
-
-Each tool owns its MCP metadata:
-
-- name and title
-- description
-- icon
-- input JSON schema
-- output JSON schema
-
-The execution path is:
-
-1. The HTTP endpoint receives a JSON-RPC `tools/call`.
-2. `MCPToolRequest` validates raw arguments against the tool input schema.
-3. The concrete tool parses the request into a typed request or spec object.
-4. The tool dispatches a command or query object.
-5. The command uses Pharo APIs to query or mutate the image.
-6. The tool returns a payload with `summary`, `warnings`, and either `data` or
-   `error`, with a failure flagged by the protocol's own `isError`. By default
-   this payload reaches the MCP `content` field; the server can also emit
-   `structuredContent` for clients that need programmatic results.
-
-### Notifications
-
-A notification is not a failed call. Pharo signals them for remarks rather than
-faults, and every `Warning` is one. The tool boundary resumes them with the
-value the image itself would have produced and the call proceeds, so a
-deprecated send, or an undeclared variable during a package load, does not fail
-it. A deprecated method called from a test does not abort the suite.
-
-Refactoring warnings are the exception. `RBRefactoringWarning` reports a change
-that breaks something, so it reaches the boundary unresumed and stops the call,
-aborting a removal or a rename that `force=true` did not authorize.
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant HTTP as HTTP Endpoint
-    participant Req as MCPToolRequest
-    participant Tool as Concrete Tool
-    participant Cmd as Command/Query
-    participant Pharo as Pharo Image
-
-    Client->>HTTP: JSON-RPC tools/call
-    HTTP->>Req: validate raw arguments
-    Req->>Req: check against tool input schema
-    alt invalid arguments
-        Req-->>HTTP: validation error
-        HTTP-->>Client: error response
-    else valid arguments
-        Req->>Tool: validated arguments
-        Tool->>Tool: parse into typed request/spec
-        Tool->>Cmd: dispatch command or query
-        Cmd->>Pharo: query or mutate image via Pharo APIs
-        Pharo-->>Cmd: result / side effect
-        Cmd-->>Tool: outcome
-        Tool-->>HTTP: structured content (status, summary, warnings, data/error)
-        HTTP-->>Client: JSON-RPC response
-    end
-```
-
-This keeps transport parsing, schema validation, image operations, and result
-formatting in separate places.
-
-## Refactorings
-
-Class and method edits use Refactoring Browser and Refactoring Engine operations
-where Pharo owns the behavior.
-
-Examples include:
-
-- class rename with `ReRenameClassRefactoring`
-- class removal with `ReRemoveClassRefactoring`
-- method rename with `ReRenameMethodRefactoring`
-- argument add/remove with `RBAddParameterRefactoring` and
-  `RBRemoveParameterRefactoring`
-- slot add, remove, rename, pull-up, and push-down with the corresponding
-  instance-variable refactorings
-- method batch removal with `ReRemoveMethodsRefactoring`
-
-When a refactoring raises `RBRefactoringWarning`, the default behavior is to
-stop. The tool result includes:
-
-```text
-impactMessages
-howToProceed
-forceSupported: true
-```
-
-Review the impact and rerun the same request with `force=true` only when the
-warning is acceptable. When forced, the warning messages are returned in the
-normal `warnings` array.
-
-## Critiques
-
-`method_compile` compiles method source in the image and returns selected Renraku
-critiques in the structured result. It includes error-severity critiques and a
-small set of non-error rules that are useful after automated edits, such as
-excessive arguments, missing super sends, return in ensure, temporary variable
-overrides, and unary accessing methods without returns.
-
-Critiques include:
-
-- Renraku rule class
-- title
-- description
-- source interval when available
-
-The method may compile successfully and still return critiques. Treat critiques
-as follow-up review evidence, not as transport failures.
-
-## Rewriting Methods
-
-`method_rewrite` uses Smalltalk AST rewrite patterns, not regex. A rule has a
-`match` and a `replacement`, and a scope is required, so rewriting everything is
-something a caller asks for by naming the packages rather than by leaving an
-argument out.
-
-A metavariable starts with a backquote and stands for whatever is in its place.
-`` `@receiver `` matches one expression, however big: the same rule rewrites
-`anObject notNil` and `(anObject foo) notNil`. **The names must be the same on
-both sides** — a name that appears only in `replacement` is bound to nothing.
-
-The default mode is preview, which carries the old and new source of every
-change:
-
-```json
-{
-  "rules": [
-    {
-      "match": "`@receiver notNil",
-      "replacement": "`@receiver isNotNil"
-    }
-  ],
-  "scope": { "packages": ["MyPackage"] }
-}
-```
-
-A metavariable stands for a block just as readily, which is how a rule drops
-one branch of a conditional:
-
-```json
-{
-  "rules": [
-    {
-      "match": "`@receiver ifTrue: [ `@body ] ifFalse: [ nil ]",
-      "replacement": "`@receiver ifTrue: [ `@body ]"
-    }
-  ],
-  "scope": { "packages": ["MyPackage"] }
-}
-```
-
-Add `apply` to make the changes. One call is enough; preview first only when
-you want to read them before they land. `history_entry_revert` undoes a rewrite
-that turned out wrong.
-
-Any rewrite rule stands for its own patterns, so its name can be given instead
-of writing them out. That includes Pharo's own, not only MCP's:
-
-```json
-{
-  "ruleClasses": ["MCPCollectionThenDoRule"],
-  "scope": { "packages": ["MyPackage"] },
-  "apply": true
-}
-```
-
-Rules that report a critique are not applied by the tools that compile. A
-compile reports what it would change; changing it is this tool's job, and the
-caller asks.
-
-## Tests And Coverage
-
-`test_run` runs SUnit classes or individual methods and returns structured test
-results. Use `test_coverage_run` when the same test run should collect
-CoverageCollector method and node coverage for an explicit method scope.
-`test_run` deduplicates concrete test cases across a batch. Use
-`selectedTestCount` for selected unique tests, `runCount` for non-skipped
-executed tests, and `skippedCount` for skipped tests.
-
-Coverage output includes method counts, node counts, uncovered methods,
-partially covered methods, and optional covered method details. Use it after
-edits to ask whether the relevant methods were exercised.
-
-## Repository Work
-
-MCP uses Iceberg for repository state. The repository tools can:
-
-- list registered repositories and their branch, head, package, modified, and
-  remote metadata
-- load Metacello baselines
-- create image-side repository registrations or update their metadata,
-  including registrations for linked Git worktree checkouts
-- inspect `workingCopyDiff`
-- verify expected repository identity before edits or exports
-- export image changes to Tonel files
-- commit, fetch, pull, push, create branches, and switch branches
-
-Use `repository_identity_verify` before edits or exports, and
-`repository_change_list` before exporting or committing. Use
-`repository_create`, `repository_attach`, and `repository_update` for repository
-registration workflows. Export writes image changes to disk and updates the
-Iceberg index; it does not stage or commit Git changes.
-
-## Change History
-
-MCP uses Epicea change history. `history_file_list` lists `.ombu`
-files, and `history_entry_list` lists entries from the current history
-or a selected file. `history_entry_apply` and `history_entry_revert` preview
-selected entries, and perform the selected apply or revert only when
-`confirm=true`.
-
-Use this when recovering image-side changes or preparing a clean handoff from a
-live image back to Tonel/Git.
-
-## Debugging
-
-Debugger tools are discoverable through the `debugging` group. They keep no
-state: `debug_watch` installs non-halting probes and removes them before it
-answers, and `debug_search` only reads the debuggers a person has open.
-
-A debugger somebody opened belongs to them. Read it, then act with the ordinary
-class and method tools; do not step, resume or terminate it.
-
-## Evaluation Escape Hatch
-
-`image_evaluate` runs arbitrary Smalltalk in the running image without saving
-it. It is useful for short inspection or glue code when no dedicated tool
-exists.
-
-Prefer a dedicated tool when one exists, because the dedicated tools validate
-input, return structured result data, and often use safer Pharo APIs.
-
-Compiling source is one of those cases. Method source in the image separates
-lines with CR, and `method_compile` normalizes what it is given; a bare
-`compile:` from `image_evaluate` stores whatever it receives, so source written
-with LF compares unequal to every other method in the image. Use
-`method_compile` for a method, and `withInternalLineEndings` if you must compile
-source by hand.
-
-## Observability And UI
-
-The servers an image holds are listed under `Library → MCP Servers` in the
-world menu, and on the `Servers` tab of an inspected `MCP` class. From there a
-server can be started, stopped, or opened in its dashboard, and a new one
-created on a port, where 0 asks for a free one. The tool catalog sits beside it
-under `Library → MCP Tool Catalog`, since it describes the image rather than
-any one server. The same list in a script:
-
-```smalltalk
-MCP allServers
-```
-
-It is taken from the heap rather than from a registry, so a server is never
-kept alive for being listable, and one that is still holding a port after its
-owner forgot it is shown rather than hidden.
-
-To reach the server on a port, whether or not this script is the one that
-started it, ask for the port rather than for a new server:
-
-```smalltalk
-MCP startOnPort: 4000
-```
-
-That answers the server already on 4000, starting it if it was stopped, and
-makes one only when the image has none there. Starting a second server on a
-taken port fails after a couple of seconds, and the error now says when the
-port is held by another MCP in the same image.
-
-An inspected `MCP` object has two Spec tabs. The dashboard runs the server:
-
-- server status, endpoint and port
-- debug mode
-- every tool the server could run, with `Enabled` for whether it has the tool
-  at all and `Listed` for whether `tools/list` shows it; an unlisted tool is
-  still found by `tool_search` and still runs
-
-The observability tab shows what the server recorded about itself:
-
-- per-tool timing metrics
-- traces for errors, outliers, and output overruns
-- recent logs
-- auto-refresh while the tab is displayed
-
-MCP starts with the built-in JSON observability backend enabled. Disable it for
-a specific server when its local metrics, traces, and logs are not wanted:
-
-```smalltalk
-mcp observabilityEnabled: false
-```
-
-By default, JSON observability exports under the image-local
-`pharo-local/mcp/observability` directory. Configure
-`mcp observabilityExportDirectory: aDirectory` to override that export root for
-instance metadata, `logs.jsonl`, `metrics.json`, and `traces.jsonl`.
-
-OpenTelemetry support is optional. Load the `Telemetry` group, then enable
-the OpenTelemetry backend for an MCP instance:
-
-```smalltalk
-Metacello new
-   baseline: 'MCP';
-   repository: 'github://Evref-BL/MCP:main/src';
-   load: 'Telemetry'.
-
-mcp useOpenTelemetryObservability
-```
-
-## Version Compatibility
-
-The core baseline loads PharoBackwardCompatibility, JRPC, and PCRE2.
-OpenTelemetry is loaded only by the optional `Telemetry` group. CI covers
-Pharo 12, 13, 14, and 15. Code should target the Pharo 14 API;
-PharoBackwardCompatibility backports supported APIs to older images.

package/templates/pharo-references/source-vs-live-image.md

@@ -1,75 +0,0 @@
-# Source Files Vs Live Pharo Image State
-
-Applies when an agent uses the Pharo MCP server to inspect, modify, or verify a
-Pharo project.
-
-## Goal
-
-Keep source inspection, loaded image state, Iceberg state, and Git state
-separate. Each one can answer different questions, and none should be treated
-as a substitute for the others.
-
-## Source-Only Checks
-
-Source-only checks can confirm:
-
-- files exist where expected;
-- packages, classes, and methods are exported in Tonel;
-- baseline files and package declarations look coherent;
-- static documentation and scripts are present;
-- Git diffs contain the expected source changes;
-- formatting and whitespace checks pass.
-
-Source-only checks cannot prove:
-
-- the project loads in the image;
-- classes and methods are currently loaded;
-- tools see the expected image state;
-- tests pass inside the image;
-- image-side edits were exported to source;
-- the running server or application behaves correctly.
-
-## Live Image Checks
-
-Use live image checks when the answer depends on image state:
-
-- loading a baseline or package;
-- listing loaded repositories, packages, classes, or methods;
-- inspecting compiled methods or class definitions;
-- running SUnit tests;
-- starting or exercising a server/application in the image;
-- applying image-side edits;
-- exporting image-side changes to Tonel or Git.
-
-Prefer dedicated `pharo` MCP tools for these checks. Use `image_evaluate` only
-when no dedicated tool fits.
-
-## Iceberg And Git
-
-Remember:
-
-- Tonel files are exported source.
-- The loaded image can differ from Tonel files.
-- Iceberg working-copy state can differ from both image state and Git state.
-- Git commits record disk files, not unsaved image changes.
-
-When these states disagree, report the mismatch and resolve it deliberately.
-Do not claim a change is complete just because one layer looks correct.
-
-## Blocked Live Verification
-
-If the current context does not have a safe or approved live image:
-
-- run only source-safe checks;
-- say which live checks are still needed;
-- do not use image-side evaluation or mutation as a workaround;
-- do not claim live behavior is verified.
-
-## Reporting
-
-When finishing work, report:
-
-- source checks run;
-- live image checks run;
-- live checks not run and why;
-- any image/source/Iceberg/Git state mismatch observed.

package/templates/pharo-references/troubleshooting.md

@@ -1,145 +0,0 @@
-# Troubleshooting
-
-Most failures fall into one of three groups: the image is not reachable, the
-requested tool input is invalid, or the live image state differs from what the
-caller expected.
-
-For standalone image crashes or stopped servers, the installed
-`pharo-mcp-recovery` skill gives agents a recovery workflow for preserving
-evidence, restarting or replacing the image, reloading projects, and recovering
-change history.
-
-## The Client Cannot Connect
-
-Ask the image what servers it holds, which answers after a restart even when
-nothing in the workspace refers to one:
-
-```smalltalk
-MCP allServers.
-```
-
-`Library → MCP Servers` in the world menu shows the same list, with the state,
-port and endpoint of each, and starts or stops the one selected.
-
-Check a server directly:
-
-```smalltalk
-mcp isRunning.
-mcp isListening.
-mcp localUrlString.
-```
-
-Confirm that the client URL uses the same host and port:
-
-```text
-http://127.0.0.1:4000
-```
-
-If you changed the port in Pharo, update the MCP client configuration.
-
-MCP currently handles MCP calls over HTTP POST. Unsupported HTTP methods
-return method-not-allowed instead of hanging.
-
-## `tools/list` Is Empty Or Stale
-
-Run:
-
-```smalltalk
-mcp refreshToolsList.
-```
-
-Then call `tools/list` again. If you loaded new MCP code into the image, restart
-the server:
-
-```smalltalk
-mcp restart.
-```
-
-## A Tool Rejects Input
-
-Each tool validates arguments against its input schema. Call `tools/list` and
-inspect the tool's `inputSchema`.
-
-Common causes:
-
-- missing required fields for the selected tool
-- extra fields rejected by `additionalProperties: false`
-- passing arguments from a different tool
-- `history_entry_apply` or `history_entry_revert` without `confirm=true`
-
-## A Refactoring Stops With A Warning
-
-This is expected for Pharo refactoring warnings. With `force=false`, the edit
-tool stops and returns impact details.
-
-Read:
-
-```text
-impactMessages
-howToProceed
-forceSupported
-```
-
-Rerun with `force=true` only when the impact is acceptable.
-
-## A Method Compiles But Returns Critiques
-
-`method_compile` can return Renraku critiques after compilation. The method exists,
-but Pharo found review issues. Inspect the critique rule class, title,
-description, and source interval if present.
-
-Use a follow-up `method_compile`, `method_update`, `test_run`, or
-`method_get` call depending on the critique.
-
-## Repository State Looks Wrong
-
-MCP reads repository state from Iceberg in the running image. The exported
-Tonel files, the image's loaded packages, and Iceberg's working-copy state can
-differ.
-
-Start with:
-
-```text
-repository_search
-repository_identity_verify
-repository_change_list
-```
-
-Use `repository_export` only when you mean to write image changes to files.
-Export updates the Iceberg index but does not stage or commit Git changes.
-
-## Tests Do Not Prove The Edited Scope
-
-`test_run` tells you whether selected tests passed. Use `test_coverage_run` with
-an explicit coverage scope when you need to know whether the edited methods
-executed.
-
-Coverage scopes should be narrow: package, class, hierarchy, or method names.
-
-## The Image Changed Unexpectedly
-
-Image-changing tools change the running image without saving it. If you are
-using an automation or agent, run it against a copied or disposable image.
-
-Use `history_file_list` and `history_entry_list` to inspect
-Epicea history. Apply or revert operations stay in `history_entry_apply` and
-`history_entry_revert`, where they can be previewed first and performed with
-`confirm=true`.
-
-## A Debugger Picture Goes Out Of Date
-
-`debug_search` answers what is open at the moment it is called. A person can
-step, resume or close their debugger at any time, so ask again rather than
-acting on an older answer.
-
-Do not drive debugger windows with raw `image_evaluate` code, and do not step,
-resume or terminate a debugger a person opened.
-
-## Source Checks Are Not Enough
-
-Exported source files can confirm package layout, class definitions, and docs.
-They cannot prove that the running image has loaded the latest code or that an
-MCP tool works over HTTP.
-
-Use [Source vs live image](source-vs-live-image.md) to decide which checks are
-valid for the current work boundary.