@evref-bl/pharo-mcp 1.5.0 → 2.0.0

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

@@ -5,19 +5,31 @@ advertised directly; less common tools can be found through the catalog tools.
 Tool names use `snake_case` names that generally put the domain before the
 action.
 
-By default, every tool returns MCP call `content` as the canonical response for
-LLMs. The text block contains the complete tool payload encoded as JSON using
-this common shape:
+Every tool returns MCP call `content` as the canonical response for LLMs, in
+plain text: the summary first, then any warnings, then the payload as lines.
+The fields that identify one record share a line as `key=value` pairs, and a
+value carrying spaces is quoted, as in `protocol="private - results"`. A record
+that names a method opens with the method, written the way Pharo writes it:
+`MCPTool>>batchSummaryNoun`, or `MCPTool class>>toolName` on the class side. A
+list of plain values is bracketed, as in `required: [name, slotName]`, and a
+list of records is named before its entries. Text with its own lines, such as
+method source, follows under its own label. `tool_get` answers a tool's
+contract as YAML.
+
+A result does not repeat itself: what the summary states in prose, and what a
+record already says another way, is left out of the lines.
+
+The same payload is also carried as `structuredContent`:
 
 ```text
-status: ok | error
 summary: human-readable summary
 warnings: array of warning strings
 data: structured success payload
 error: structured error payload
 ```
 
-`data` is present on success. `error` is present on failure.
+`data` is present on success. `error` is present on failure, where the call is
+also flagged with the protocol's own `isError`.
 
 For clients or integrations that need programmatic payloads, configure the
 server response fields before `start`:
@@ -30,231 +42,90 @@ mcp useContentAndStructuredContentToolResponses.
 
 ## Compact Paging
 
-List and search tools are optimized for low token usage. Broad tools return a
-small page by default and put only the entry array in `data`. When another page
-exists, `data` includes `nextOffset`; call the same tool again with that
-`offset` to continue.
+List and search tools are optimized for low token usage. A page is the tool's
+own size, chosen for what one of its entries costs to read: fifty classes,
+twenty-five methods or packages, twenty critique hits, ten repositories. When
+another page exists, `data` includes `nextOffset`; call the same tool again
+with that `offset` to continue.
 
-Use the returned array size for the current page and follow `nextOffset` when
-present. Request larger pages only when the next step truly needs more entries.
+A search answers what identifies each hit, not everything known about it.
+`repository_search` says how many packages a repository holds rather than
+naming them, which `package_search` answers; `critique_run` names the rule
+rather than restating its documentation on every hit.
 
-## Tool Catalog
+## Naming Several Targets
 
-| Tool | Use |
-| --- | --- |
-| `tool_search` | Search the tool catalog by group, keyword, title, or description. |
-| `tool_get` | Return input schema and metadata for one catalog tool. |
-| `tool_call` | Invoke a catalog tool that is not exposed directly by the current client. |
-
-Use `tool_search` before calling less common or high-risk tools. Inspect the
-schema before invoking a discoverable tool.
+Four tools act on several targets in one call. The argument that names the
+target holds either one value or a list of them, and every other argument
+applies to all of them:
 
-## Repositories
+| Tool | Argument | One call covers |
+| --- | --- | --- |
+| `method_get` | `selector` | Methods of one class, on one side. |
+| `method_compile` | `source` | Sources compiled into one class, under one protocol. |
+| `class_get` | `name` | Classes read with the same options. |
+| `class_create` | `name` | Classes sharing a superclass, package and slots. |
 
-| Tool | Use |
-| --- | --- |
-| `repository_search` | List Iceberg repositories registered in the image, including location, branch/head metadata, exact head commit id, modified packages, remotes, and upstream details. |
-| `repository_identity_verify` | Assert expected Iceberg repository identity fields before edits, exports, commits, pulls, or pushes. |
-| `repository_change_list` | Inspect Iceberg `workingCopyDiff` without writing files. |
-| `repository_create` | Create a new Iceberg repository directory and optionally attach initial packages. |
-| `repository_attach` | Register an existing Git checkout, including a linked Git worktree checkout, and optionally attach packages. |
-| `repository_update` | Change image-side repository subdirectory or package membership without exporting packages. |
-| `repository_export` | Export image-side package changes to Tonel files and update the Iceberg index without staging or committing Git changes. |
-| `repository_commit` | Commit Iceberg repository changes with a message. |
-| `repository_fetch` | Fetch repository remotes through Iceberg. |
-| `repository_pull` | Pull through Iceberg. |
-| `repository_push` | Push through Iceberg. |
-| `repository_branch_create` | Create and switch to a new repository branch through Iceberg. |
-| `repository_branch_switch` | Switch the Iceberg repository head to an existing branch without loading package changes into the image. |
-| `repository_branch_checkout` | Check out an existing repository branch and load changes for packages already loaded in the image. |
-| `repository_head_adopt` | Adopt the current repository head as the Iceberg working-copy reference after verifying the image and Git state. |
-| `baseline_load` | Load an already-known Metacello baseline available in the image. |
-| `repository_load` | Load a Metacello baseline from a remote repository. |
-
-Use `repository_identity_verify` before edits or exports, and
-`repository_change_list` before exporting or committing image changes.
-Identity verification requires at least one expected identity field, such as
-`location`, `branchName`, `subdirectory`, `packageNames`,
-`modifiedPackageNames`, or `isModified`.
-
-Use plural fields such as `repositoryNames`, `directoryPaths`, and
-`packageNames` for exact repository scope. Use singular text filters such as
-`repositoryName`, `branchName`, `headCommitId`, `remoteUrl`, and
-`upstreamBranchName` for field-specific matching.
-
-## Packages
-
-| Tool | Use |
-| --- | --- |
-| `package_search` | List packages by project/package scope, with optional `packageName`, `projectName`, and `tag` filters. |
+Every target is attempted. The summary states how many succeeded, each target
+then reads as it would have read on its own, and `data` carries one entry per
+target under `results`, in request order. An entry that failed carries its
+`error`. The call is flagged `isError` only when every target failed.
 
-## Classes
+A call naming one target answers exactly what it answers when the argument
+holds a single value.
 
-| Tool | Use |
-| --- | --- |
-| `class_search` | List classes by package/class/hierarchy scope, with optional `className`, `tag`, `instanceSlot`, and `classSlot` filters. |
-| `class_get` | Get one class by name and return structured class metadata with optional superclass and subclass context. |
-| `class_create` | Create one class definition. |
-| `class_name_update` | Rename one class through the Refactoring Engine. |
-| `class_superclass_update` | Change one class superclass. |
-| `class_package_update` | Move one class to a package and/or recategorize it under a package tag. |
-| `class_comment_update` | Set or clear one class comment. |
-| `class_slots_update` | Replace instance-side and/or class-side slot definitions. |
-| `class_traits_update` | Replace instance-side trait composition. |
-| `class_side_traits_update` | Replace class-side trait composition. |
-| `class_shared_variables_update` | Replace class variables. |
-| `class_shared_pools_update` | Replace shared pools. |
-| `class_layout_update` | Replace the layout class. |
-| `class_slot_add` | Add one instance-side or class-side slot. |
-| `class_slot_remove` | Remove one instance-side or class-side slot. |
-| `class_slot_name_update` | Rename one instance-side or class-side slot. |
-| `class_slot_pull_up` | Pull one instance-side or class-side slot up to a superclass. |
-| `class_slot_push_down` | Push one instance-side or class-side slot down to subclasses. |
-| `class_remove` | Remove classes as one batch. Refactoring warnings stop removal unless `force=true`. |
-
-Class mutation tools and `class_remove` use Pharo refactoring support
-where available. With `force=false`, refactoring warnings return impact details
-instead of continuing.
-
-## Methods
-
-| Tool | Use |
-| --- | --- |
-| `method_metadata_search` | List/search methods by class/package/hierarchy scope, with optional `selector` and `protocol` filters. |
-| `method_source_search` | Search methods by source text. |
-| `method_equivalent_search` | Search methods whose AST is equivalent to a referenced method. |
-| `method_implementor_search` | Search methods that implement a selector. |
-| `method_sender_search` | Search methods that send a selector. |
-| `method_class_reference_search` | Search methods that reference a class binding. |
-| `method_variable_reference_search` | Search methods that reference a variable. |
-| `method_get` | Get one known method and return source plus structured variable-reference context. |
-| `method_compile` | Create or replace one method from source. |
-| `method_selector_update` | Rename selectors, add/remove arguments, or reorder arguments through the Refactoring Engine. |
-| `method_protocol_update` | Move one method to another regular or extension protocol. |
-| `method_rewrite` | Preview or apply AST rewrite rules across a method scope. Applying requires `expectedChangeSetHash` from a preview. |
-| `critique_run` | Run selected or all Renraku critiques over a scope and return hits grouped by rule class. |
-| `method_remove` | Remove methods from one class as a batch without sender safety checks. |
-
-Prefer the specialized lookup tools for navigation tasks. Use
-`method_source_search` for source text and `method_equivalent_search` for
-equivalent-AST matches. Keep `method_metadata_search` for method metadata
-search. Top-level `method_metadata_search` filtering is limited to `selector`
-and `protocol` fields (`substring`, `prefix`, `exact`, or `regex`); use
-specialized tools for source, equivalent methods, implementors, senders, class
-references, and variable references.
-
-`method_compile` returns selected Renraku critiques after method compilation when
-they are relevant to review.
-
-## History
-
-| Tool | Use |
-| --- | --- |
-| `history_file_list` | List Epicea `.ombu` change-history files, including the current history file. |
-| `history_entry_list` | List entries from the current image change history or a selected `.ombu` file. |
-| `history_entry_apply` | Preview applying selected entries, and apply them with `confirm=true`. |
-| `history_entry_revert` | Preview reverting selected entries, and revert them with `confirm=true`. |
+## The Advertised Surface
 
-Prefer the read-only tools when browsing history. Use
-`history_entry_apply` or `history_entry_revert` when you need apply/revert
-preview or confirmation.
+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`.
 
-## Tests
+A server chooses its own surface before `start`:
 
-| Tool | Use |
-| --- | --- |
-| `test_run` | Run SUnit test classes or individual methods. |
-| `test_coverage_run` | Run SUnit test classes or individual methods while collecting method and node coverage for an explicit method scope. |
+```smalltalk
+mcp advertiseTools: #( 'tool_search' 'tool_get' 'tool_call' 'method_get' ).
+```
 
-## UI
+## Finding A Tool
 
-| Tool | Use |
-| --- | --- |
-| `screenshot_capture` | Capture the active Morphic world and return MCP image content with dimensions and MIME type metadata. |
+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.
 
-## Debugging
+Search before calling anything less common or high-risk, and read the schema
+before invoking it.
 
-The debugger tools are discoverable under the `debugging` group. Read
-[Debugging with MCP](debugging.md) before using them.
+Tools are named `domain_action`, and the domains are:
 
-| Tool | Use |
+| Group | Covers |
 | --- | --- |
-| `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 under debugger control 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 a debug-session snapshot with stack, selected frame, source, scopes, repair actions, and state-scoped references. |
-| `debug_variable_get` | Expand scope and variable references 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 debug session. |
-| `debug_session_step_over` | Step over the selected frame of a tracked debug session. |
-| `debug_session_step_through` | Step through the selected frame of a tracked debug session. |
-| `debug_session_restart` | Restart the selected frame of a tracked debug session. |
-| `debug_session_resume` | Resume a tracked debug session. |
-| `debug_session_terminate` | Terminate a tracked debug 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. |
+| `classes` | Defining classes and changing their slots, traits, shared variables, pools, layout, package and comment, including the slot refactorings. |
+| `methods` | Compiling, reading, removing and rewriting methods, renaming selectors and protocols, and searching by source, metadata, senders, implementors, references or equivalence. |
+| `repositories` | What the image knows about its Iceberg repositories: identity, package membership, working-copy changes, export, commit, and reloading the image from the files. Branches, remotes and transfers are git's, and belong in a shell. |
+| `debugging` | Reading the debuggers a person opened, with their exceptions and nearest frames, and watching what variables hold while an expression runs. Neither attaches to a debugger or leaves a session behind. |
+| `history` | Epicea change history: locating files, listing entries, and applying or reverting them. |
+| `tests` | Running tests and running them under coverage. |
+| `packages` | Searching packages. |
+| `runtime` | `image_evaluate`, the escape hatch. |
+| `ui` | Reading what is on screen, as a tree of windows and the presenters or morphs inside them, or as a screenshot. Either one can take a single window instead of the whole world, for a fraction of the cost. |
+| `tool-catalog` | `tool_search`, `tool_get` and `tool_call`. |
 
 ## Scripting
 
-| Tool | Use |
-| --- | --- |
-| `image_evaluate` | Evaluate arbitrary Smalltalk and return a bounded preview of the result. |
-
-Use `image_evaluate` only when no dedicated tool fits. A successful evaluation can
-mutate and save the image.
+Use `image_evaluate` only when no dedicated tool fits. A successful evaluation
+can mutate the running image.
 
 ## Mutation And Saving
 
-Most search and inspection tools are read-only and do not save the image.
-Mutating tools save the image after a successful call.
-
-Tools that can save after success include:
+No tool saves the image. Mutating tools change the running image only, so
+closing it discards every change since its last save, and a mistake costs the
+session rather than the image file. Saving is the caller's responsibility:
+evaluate `Smalltalk saveSession` when a change should survive, or leave it to
+whoever owns the image lifecycle.
 
-```text
-class_create
-class_name_update
-class_package_update
-class_comment_update
-class_slot_add
-class_slot_remove
-class_slot_name_update
-method_compile
-method_selector_update
-method_protocol_update
-repository_create
-repository_attach
-repository_update
-repository_export
-repository_commit
-repository_fetch
-repository_pull
-repository_push
-repository_branch_create
-repository_branch_switch
-repository_branch_checkout
-repository_head_adopt
-baseline_load
-repository_load
-class_remove
-method_remove
-method_rewrite when apply=true and changes were applied
-history_entry_apply when entries were performed
-history_entry_revert when entries were performed
-debug_expression_evaluate
-debug_capture
-debug_test_run
-debug_method_update when a method is accepted
-image_evaluate
-```
+Use `history_entry_list` to see what changed and `history_entry_revert` to undo
+a change in the running image; both preview first and perform with
+`confirm=true`.
 
 `repository_identity_verify` and `repository_change_list` are read-only.
 

package/templates/pharo-references/troubleshooting.md

@@ -11,7 +11,17 @@ change history.
 
 ## The Client Cannot Connect
 
-Check the server in the image:
+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.
@@ -55,7 +65,6 @@ Common causes:
 - missing required fields for the selected tool
 - extra fields rejected by `additionalProperties: false`
 - passing arguments from a different tool
-- `method_rewrite` with `apply=true` but no `expectedChangeSetHash`
 - `history_entry_apply` or `history_entry_revert` without `confirm=true`
 
 ## A Refactoring Stops With A Warning
@@ -109,23 +118,22 @@ Coverage scopes should be narrow: package, class, hierarchy, or method names.
 
 ## The Image Changed Unexpectedly
 
-Image-changing tools save the image after successful mutation. If you are using
-an automation or agent, run it against a copied or disposable image.
+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`.
 
-## Debugger References Are Stale
+## A Debugger Picture Goes Out Of Date
 
-Debugger `stateId`, `frameRef`, and `variableRef` values are scoped to one
-debug_state_get snapshot. After a control action, debugger edit, or resume, discard
-old references and use the newly returned state.
+`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.
 
-If a human opened the debugger, attach through the debugging tools and let the
-debugger controller own UI actions. Do not drive debugger windows with raw
-`image_evaluate` code.
+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
 

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

@@ -28,7 +28,7 @@ See [Tool reference](tool-reference.md) for tool groups and common workflows.
 
 ## Choose Specialized Lookups
 
-Use `method_metadata_search` for metadata, `method_source_search` for source,
+Use `method_search` for metadata, `method_source_search` for source,
 `method_equivalent_search` for equivalent ASTs, and the implementor, sender,
 class-reference, or variable-reference search matching the question.
 
@@ -37,19 +37,39 @@ mutation, and inspect `repository_change_list` before export or commit. Read
 [Safety and ecosystem integration](safety-and-ecosystem.md) for mutation
 boundaries.
 
+`method_get` and `class_get` read several targets in one call when their
+`selector` or `name` holds a list, and `method_compile` and `class_create`
+write several the same way. See [Tool reference](tool-reference.md).
+
 For history recovery, inspect files and entries before applying or reverting.
-For debugger sessions, breakpoints, or repairs, read the installed local
+For watching values, debugger sessions, or repairs, read the installed local
 debugging guide.
 
 ## Image Mutation
 
-Successful mutating tools save the image. Use a copied or disposable image for
-broad or risky edits, preview changes when the tool supports it, and run focused
-tests after source changes.
+Mutating tools change the running image and never save it, so closing the image
+discards everything since its last save. Saving is the caller's responsibility:
+evaluate `Smalltalk saveSession` when a change should survive, or leave it to
+whoever owns the image lifecycle. Use a copied or disposable image for broad or
+risky edits, preview changes when the tool supports it, and run focused tests
+after source changes.
 
 Report incomplete or failing tool results clearly. Never silently fall back to
 exported source for a question about the live image.
 
+## Failures And Notifications
+
+A notification is not a failure. Pharo signals them for remarks rather than
+faults, and every `Warning` is one, so a deprecated send or an undeclared
+variable during a load is resumed and the call proceeds. A refactoring warning
+is the exception: it reports a change that breaks something, so it stops the
+call until you rerun with `force=true`.
+
+A failed call reports the error class, the message and the frames of the failing
+code; the server's own frames are left out. For `image_evaluate` a compilation
+failure also names the line and shows it, and a `MessageNotUnderstood` suggests
+selectors the receiver does understand.
+
 ## Reusable Workflows
 
 Run `npx @evref-bl/pharo-mcp install --host <host>` in the target project to
@@ -86,10 +106,6 @@ MyProjectMCPTool >> buildInputSchema
 		additionalProperties: false;
 		yourself
 
-MyProjectMCPTool >> buildOutputSchema
-
-	^ self standardOutputSchemaForDataProperties: #(  ) required: #(  )
-
 MyProjectMCPTool >> executeWithRequest: request
 
 	^ self
@@ -116,40 +132,39 @@ normal use, configure it through the `MCP` instance messages below. The
 instance; discoverable tools remain available through `tool_search`, `tool_get`,
 and `tool_call`.
 
-For a server with only your own tools, use a profile:
+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`.
+
+For a server with only your own tools:
 
 ```smalltalk
-mcp := MCP profile: (MCPProfile tools: { MyProjectMCPTool }).
+mcp := MCP onlyTools: { MyProjectMCPTool }.
 mcp start.
 ```
 
-`MCPProfile tools:` registers the given tools and advertises them directly in
-`tools/list`. Use `tools:static:` when some registered tools should stay
-discoverable through the catalog tools:
+`onlyTools:` replaces the catalog with exactly those tools and advertises all of
+them. Advertise a subset when some registered tools should stay discoverable
+through the catalog tools instead:
 
 ```smalltalk
-mcp := MCP profile: (MCPProfile
-	tools: { MyProjectMCPTool. MyOtherMCPTool }
-	static: { MyProjectMCPTool }).
+mcp := MCP onlyTools: { MyProjectMCPTool. MyOtherMCPTool }.
+mcp advertiseTools: { MyProjectMCPTool }.
 ```
 
-For incremental per-server configuration, register tools explicitly before
-starting the server:
+To add to the tools a server already has, rather than replacing them:
 
 ```smalltalk
 mcp := MCP new.
-mcp registerToolClass: MyProjectMCPTool.
+mcp addTool: MyProjectMCPTool.
 mcp start.
 ```
 
-You can also register several classes, register an already-created tool, or
-remove a tool from one server instance:
-
-```smalltalk
-mcp registerToolClasses: { MyProjectMCPTool. MyOtherMCPTool }.
-mcp registerTool: MyProjectMCPTool new.
-mcp unregisterToolNamed: 'my_project_tool'.
-```
+`addTool:` takes a class or a ready instance, and `addTools:` takes several.
+`removeTool:` takes one back out by name. `advertiseTools:` accepts classes,
+instances or names, and registers anything not in the catalog yet, so it can be
+called before or after adding. `advertiseAllTools` advertises everything, and
+`advertiseToolDefaults` returns to each tool's own default exposure.
 
 Use `defaultExposure` to decide whether a registered tool is directly
 advertised in `tools/list` (`'static'`) or kept discoverable through the catalog