@evref-bl/pharo-mcp 2.0.0 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-mcp",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Pharo MCP agent-host templates",
   "license": "MIT",
   "type": "module",

package/templates/pharo-references/tool-reference.md

@@ -74,9 +74,57 @@ target under `results`, in request order. An entry that failed carries its
 A call naming one target answers exactly what it answers when the argument
 holds a single value.
 
+## Changing A Class Or A Method
+
+`class_update` and `method_update` take the whole change rather than one
+property each. Every property is optional and at least one is required;
+omitted ones are left alone.
+
+Scalar properties are replaced by value, and so are the collections that hold
+no state:
+
+```text
+class_update   name, and any of newName, superclass, package, tag, comment,
+               layout, traits, classTraits, sharedVariables, sharedPools
+```
+
+Slots are patched instead, through `slots` and `classSlots`, because they hold
+the instance's values. A replacement list cannot tell a rename from a
+remove-plus-add, and the two differ in whether the value survives; it also has
+to be complete, so a stale one silently drops a slot the caller did not know
+about.
+
+```text
+slots: { add:      [names]
+         remove:   [names]
+         rename:   { current: new }
+         pullUp:   [names]      moves them to the superclass
+         pushDown: [names]      moves them to every direct subclass
+         replace:  [names] }    the whole list; prefer add and remove
+```
+
+`method_update` takes `class` and `selector`, then `protocol`, `newSelector`
+or both. A selector change is classified by arity, so the one argument renames,
+adds or removes arguments and updates senders. Name the new argument list in
+`arguments` and the index map is worked out: names that match the current ones
+are kept, new names are added arguments needing `argumentValueExpressions`, and
+current names left out are removed. `permutation` is only for reordering, which
+names cannot express.
+
+The changes are applied in dependency order, not the order they were written:
+a superclass change first, because it decides what the rest validates against,
+slots added before anything refers to them and removed last, and a rename last,
+because every other change resolves the target by the name the caller wrote.
+
+A change that fails stops the ones after it. This is the opposite of a batch
+over several targets, and deliberately so: these all land on one class or one
+method, so carrying on would leave half a definition nobody asked for. The
+error names the change that failed, the ones already applied, and the ones not
+attempted.
+
 ## The Advertised Surface
 
-Fifteen tools are advertised directly: `tool_search`, `tool_get`, `tool_call`, `class_search`, `class_get`, `class_create`, `class_remove`, `method_search`, `method_source_search`, `method_reference_search`, `method_get`, `method_compile`, `method_remove`, `test_run` and `image_evaluate`. Every other tool is found with `tool_search` and called through `tool_call`.
+Fifteen tools are advertised directly: `tool_search`, `tool_get`, `tool_call`, `class_search`, `class_get`, `class_create`, `class_remove`, `method_search`, `method_source_search`, `method_reference_search`, `method_get`, `method_compile`, `method_remove`, `test_run` and `image_evaluate`. Every other tool is found with `tool_search` and called by name like any other; `tool_call` does the same for a client that will only send a name its own list holds.
 
 A server chooses its own surface before `start`:
 
@@ -90,7 +138,8 @@ The server answers for its own catalogue. `tool_search` ranks it by keyword,
 best match first, and answers the closest tools even when none matches every
 word; add words to narrow the ranking. With no query it answers the catalogue's
 size and its groups. `tool_get` returns one tool's metadata and input schema,
-and `tool_call` invokes a tool the current client does not advertise directly.
+and `tool_call` invokes a tool by nesting its arguments, for a client that cannot
+send a name outside its own list.
 
 Search before calling anything less common or high-risk, and read the schema
 before invoking it.

package/templates/pharo-references/troubleshooting.md

@@ -88,7 +88,7 @@ Rerun with `force=true` only when the impact is acceptable.
 but Pharo found review issues. Inspect the critique rule class, title,
 description, and source interval if present.
 
-Use a follow-up `method_compile`, `method_selector_update`, `test_run`, or
+Use a follow-up `method_compile`, `method_update`, `test_run`, or
 `method_get` call depending on the critique.
 
 ## Repository State Looks Wrong

package/templates/pharo-references/using-pharo-mcp.md

@@ -17,8 +17,9 @@ guessing from source or memory.
 
 - Inspect the tools exposed by the current client; do not rely on remembered
   names or schemas.
-- Use `tool_search`, then `tool_get`, for less common tools. Invoke a catalog
-  tool through `tool_call` when the client does not expose it directly.
+- Use `tool_search`, then `tool_get`, for less common tools. Call one by name
+  like any other, or through `tool_call` when the client will only send a name
+  its own list holds.
 - Prefer the least-mutating dedicated tool. Use `image_evaluate` only when no
   dedicated tool fits.
 - Start list/search calls with the default page or a small `limit`. Continue
@@ -123,18 +124,18 @@ MyProjectMCPTool class >> shouldAutoRegister
 ```
 
 Auto-registered external tools are discoverable by default. Agents can find
-them with `tool_search`, inspect them with `tool_get`, and call them through
-`tool_call`.
+them with `tool_search`, inspect them with `tool_get`, and call them by name.
 
 `MCPToolRegistry` is the server's source of truth for registered tools. In
 normal use, configure it through the `MCP` instance messages below. The
 `tools/list` response contains only the static tool surface cached by the MCP
-instance; discoverable tools remain available through `tool_search`, `tool_get`,
-and `tool_call`.
+instance; discoverable tools remain callable, and are found with `tool_search`
+and `tool_get`.
 
-Two words govern the surface. A **registered** tool is in the catalog and
-reachable through `tool_search`, `tool_get` and `tool_call`. An **advertised**
-tool is also in `tools/list`.
+Two words govern the surface. A **registered** tool is in the catalog, found
+with `tool_search` and `tool_get`, and callable. An **advertised** tool is also
+in `tools/list`. Advertising decides what a client is shown, not what it may
+call.
 
 For a server with only your own tools: