@evref-bl/pharo-mcp 2.3.0 → 3.1.0

package/templates/pharo-skills/pharo-project-load/SKILL.md

@@ -37,7 +37,8 @@ For local Tonel, use an absolute `tonel:///.../src` URL.
 
 - Baseline/package not found: verify branch and source directory.
 - Missing global/class/selector: compare the project API surface with the
-  target Pharo version; use `pharo-version-compat` when appropriate.
+  target Pharo version. Version-specific code belongs in a package the
+  baseline loads only where it applies.
 - Metacello conflict: reproduce the project's documented or CI conflict policy.
 - Native or CI-only failure: reproduce once, then use `pharo-ci-repro`.
 

package/templates/pharo.AGENTS.md

@@ -1,36 +1,40 @@
 # Pharo MCP Agent Guide
 
 Use the configured `pharo` MCP server whenever a task depends on the running
-image. Preserve unrelated changes and report unavailable live checks instead of
-guessing from source.
+image. Preserve unrelated changes, and say which live check you could not run
+rather than letting source stand in for it.
 
 ## Read First
 
 - Inspect the tools and schemas exposed by the current client; do not rely on
-  remembered names.
+  remembered names. `tool_search` finds what is not advertised, and `tool_get`
+  answers one tool's schema.
 - Prefer the least-mutating dedicated tool. Use `image_evaluate` only when no
   dedicated tool fits.
-- Treat image, Tonel, Iceberg, and Git state as separate.
+- Treat image, Tonel, Iceberg, and Git state as separate. None of them proves
+  anything about the others.
+- The image is one workspace. It has no branches and no worktrees, so two
+  agents working in it at once share every edit, and one export writes both
+  their changes into one diff. One writer at a time.
 - Tools change the running image but never save it; use a safe image boundary.
 
 ## Context Loading
 
 - Before Pharo source changes: read the project's Pharo coding and testing
   guidance. If none exists, use the local
-  [coding rules](pharo-references/pharo-coding-rules.md) and
-  [coding style](pharo-references/pharo-coding-style.md).
+  [Pharo coding](pharo-references/pharo-coding.md) reference.
+- Before reading an answer closely, rewriting methods, or acting on a warning a
+  call came back with: read
+  [tool reference](pharo-references/tool-reference.md).
 - Before loading a project: use `skills/pharo-project-load/SKILL.md`.
-- Before cross-version work: use `skills/pharo-version-compat/SKILL.md`.
-- Before exporting image changes or changing Git state: use
-  `skills/pharo-image-git-handoff/SKILL.md`.
+- Before moving code between the image and its files: use
+  `skills/pharo-image-sync/SKILL.md`.
 - Before reproducing smalltalkCI or GitHub failures: use
   `skills/pharo-ci-repro/SKILL.md`.
 - Before profiling or optimizing Pharo code: use
   `skills/pharo-code-profiling/SKILL.md`.
 - Before recovering a stopped standalone image: use
   `skills/pharo-mcp-recovery/SKILL.md`.
-- Before debugger sessions or repairs: read the local
-  [debugging guide](pharo-references/debugging.md).
 
 ## Workflow
 
@@ -38,7 +42,7 @@ guessing from source.
 2. Preview or verify identity before risky mutation.
 3. Make the narrowest image-side change.
 4. Run focused SUnit tests and inspect the result.
-5. Use the handoff skill before exporting or committing Tonel changes.
+5. Use the image-sync skill before exporting or committing Tonel changes.
 
 For repository work, verify repository identity before mutation and inspect the
 image-side diff before export or commit.

package/templates/pharo-references/debugging.md

@@ -1,70 +0,0 @@
-# Debugging Tools
-
-Applies when using MCP-Pharo to watch values while code runs, or to see what
-debuggers a person has open.
-
-## Goal
-
-See what running code is doing without guessing from source and without driving
-the Morphic debugger by hand.
-
-Debugger tools are discoverable, not part of the default static surface.
-
-## Discovery Flow
-
-1. Use `tool_search` with a query such as `watch` or `debugger`.
-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 tool by name. Otherwise use the callable form exposed by the
-   current client.
-
-## Tool Map
-
-| Tool | Use |
-| --- | --- |
-| `debug_watch` | Record what variables hold while an expression runs, without stopping it. |
-| `debug_search` | Answer the debuggers open in the image, read-only. |
-
-Neither tool keeps anything. No session is started, attached or registered, so
-there is no reference to carry between calls and nothing to clean up.
-
-## Watching Values
-
-`debug_watch` is print debugging without editing the method. Name the methods to
-probe, the variables to record, and the expression to run. Every assignment to a
-named variable is recorded as it happens, the expression runs to completion, and
-the probes are removed before the call answers.
-
-Name no variable and each method's arguments are recorded as it is entered.
-Both `method` and `variable` take one value or a list, and a probe goes on every
-pair that exists, so a variable a method never assigns simply has no series there.
-
-Reach for it whenever the question is what a value became, rather than where to
-intervene.
-
-## Seeing A Person's Debuggers
-
-`debug_search` answers the debuggers open in the image: each one's name, the
-exception it stopped on, and the frames nearest the stop with what those frames
-hold. Pass a `query` to keep only the debuggers whose name or exception matches.
-
-It is a query and nothing else. It attaches to nothing, changes nothing, and
-remembers nothing, so the picture it gives is whatever is open at that moment.
-Ask again for a fresh one.
-
-Act on what it shows with the ordinary tools: read the method with `method_get`,
-change it with `method_compile`, run something with `image_evaluate`. Stepping,
-resuming and repairing from inside a frame belong to the person at the debugger,
-not to the agent.
-
-## To Debug Your Own Code
-
-Do not open a debugger for it. Call the tool that runs the code and read the
-failure it reports: it names the frames nearest the error and the values they
-held. When that is not enough, `debug_watch` shows how a value got there.
-
-## Do Not
-
-- Do not drive debugger windows or mutate contexts through general
-  `image_evaluate` code.
-- Do not resume, step or terminate a person's debugger. It is theirs.

package/templates/pharo-references/getting-started.md

@@ -1,151 +0,0 @@
-# Getting Started
-
-This is the canonical guide for loading MCP, starting its HTTP endpoint, and
-connecting a client.
-
-## Requirements
-
-- Pharo 12, 13, 14, or 15
-- An MCP client that supports Streamable HTTP directly or through a local bridge
-- Network access from the client to the image host
-
-For local use, keep the image and client on the same machine and use
-`127.0.0.1`.
-
-## Load MCP
-
-Evaluate in a supported image:
-
-```smalltalk
-Metacello new
-   baseline: 'MCP';
-   repository: 'github://Evref-BL/MCP:main/src';
-   load.
-```
-
-As a project dependency:
-
-```smalltalk
-spec
-   baseline: 'MCP'
-   with: [ spec repository: 'github://Evref-BL/MCP:main/src' ].
-```
-
-## Load Groups
-
-The default load includes the server, optional UI, and their tests.
-
-| Group | Contents |
-| --- | --- |
-| `default` | `Core`, `UI`, `Tests`, and `UI Tests` |
-| `Core` | The `MCP` server package |
-| `UI` | `MCP-UI` and its required core package |
-| `Tests` | Core server tests and test resources |
-| `UI Tests` | UI tests and their required test dependencies |
-| `OpenTelemetry` | Optional OpenTelemetry backend |
-| `all` | Every package, including the optional OpenTelemetry backend |
-
-For a headless image, load only the core server:
-
-```smalltalk
-Metacello new
-   baseline: 'MCP';
-   repository: 'github://Evref-BL/MCP:main/src';
-   load: 'Core'.
-```
-
-Dependencies can select the same group with `loads: #( 'Core' )`.
-
-## Start And Stop
-
-```smalltalk
-mcp := MCP startOnPort: 4000.
-```
-
-That answers the server already on 4000 when the image has one, rather than
-failing on the port it holds. Build one by hand when it needs configuring
-before it starts:
-
-```smalltalk
-mcp := MCP new.
-mcp port: 4000.
-mcp start.
-```
-
-Tool calls return canonical LLM-facing `content` by default. If a client or
-integration needs programmatic payloads, configure the response fields before
-starting:
-
-```smalltalk
-mcp useStructuredContentOnlyToolResponses.
-mcp useContentAndStructuredContentToolResponses.
-```
-
-Inspect or control the server with:
-
-```smalltalk
-mcp localUrlString.
-mcp isRunning.
-mcp isListening.
-mcp restart.
-mcp stop.
-```
-
-The server lives in the image and stops when the image exits.
-
-## Connect A Client
-
-The endpoint above is:
-
-```text
-http://127.0.0.1:4000
-```
-
-Client configuration formats differ. Configure a Streamable HTTP MCP server
-using the client documentation rather than copying another client's JSON.
-Loopback addresses work only when the client connects from the local machine;
-cloud-brokered connectors cannot reach `127.0.0.1`.
-
-Install the supplied guide, local references, workflow skills, and direct MCP
-configuration into the current agent 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.
-
-## First Calls
-
-Start with catalog discovery:
-
-```text
-tools/list
-tool_search
-tool_get
-```
-
-Then inspect the image with focused read-only tools such as:
-
-```text
-class_search
-class_get
-method_search
-method_source_search
-method_reference_search
-method_get
-```
-
-`package_search` and the specialized tools are found with `tool_search`.
-
-Before mutation, inspect the target and use a copied or disposable image.
-Prefer dedicated tools such as `class_create`, `method_compile`, refactoring
-tools, and `test_run` over `image_evaluate`.
-
-Continue with:
-
-- [Using MCP from an agent](using-pharo-mcp.md)
-- [Tool reference](tool-reference.md)
-- [Safety and ecosystem integration](safety-and-ecosystem.md)
-- [Troubleshooting](troubleshooting.md)

package/templates/pharo-references/pharo-coding-rules.md

@@ -1,147 +0,0 @@
-# Pharo Coding Rules For MCP Users
-
-Applies when using MCP to inspect, write, review, or refactor Pharo source in
-any project.
-
-This file covers object-design and correctness-oriented rules. For
-expression-level readability heuristics, also read
-[Pharo coding style](pharo-coding-style.md).
-
-## First Principle
-
-Pharo code should communicate through messages and protocols. Prefer normal
-dispatch over representation checks, class checks, reflective lookup, or
-dynamic selector tricks.
-
-## Dispatch Over Inspection
-
-Do:
-
-- send a domain message to the receiver;
-- add or refine a protocol on the object that owns the behavior;
-- use polymorphic collaborators, strategy objects, double dispatch, or visitors
-  when behavior varies by object role.
-
-Avoid in application behavior:
-
-- `class = ...`;
-- `isKindOf:` and `isMemberOf:`;
-- `respondsTo:` as control flow;
-- `perform:` as a disguised switch;
-- method dictionary or instance-variable reflection.
-
-Reflection is acceptable for tools, proxies, compatibility shims, and explicit
-framework boundaries. Keep reflective behavior isolated and named as tooling
-or boundary behavior; do not spread it through ordinary domain logic.
-
-## Tell, Do Not Ask
-
-Do not pull state out of an object, compute externally, then push state back
-when the object can own the behavior.
-
-Prefer:
-
-- `aCommand executeOn: aModel`;
-- `aDocument writeOn: aStream`;
-- `aPolicy accepts: anObject`.
-
-over clients branching on concrete classes or internal fields.
-
-## Object APIs, Not Data Bags
-
-- Keep domain objects behavior-rich instead of using them only as data bags.
-- Avoid dictionaries or arrays as internal domain models unless the data is
-  genuinely unstructured external input.
-- If several clients repeat the same extraction and calculation, move the
-  behavior to the object with the knowledge.
-- Avoid long message chains through internals; add a meaningful domain method.
-
-## Small Methods And Hooks
-
-- Extract meaningful steps into small named methods.
-- Use self-send hooks when subclass or compatibility variation is plausible.
-- Keep block bodies short; move domain logic from blocks into methods.
-- Do not add wrappers that only rename obvious library calls unless the wrapper
-  captures a domain concept or extension hook.
-- Trust collaborators first. Prefer direct sends to the documented protocol of
-  the object you were given; add adapters or project-specific extensions only
-  when the code truly accepts multiple concrete framework shapes or compatibility
-  differences.
-- Be especially conservative with extensions on broad system classes such as
-  `Object`, `Behavior`, `String`, or `Exception`. They should model a real
-  boundary protocol, not hypothetical defense against wrong callers.
-
-## Nil And Error Handling
-
-- Return empty collections for "no elements".
-- Use a null object when "do nothing" is valid behavior.
-- Signal or return structured domain errors for exceptional cases.
-- Do not use `nil` as a normal status code.
-- Do not swallow broad `Error` silently.
-- Catch the most specific exception class that matches the recovery policy.
-- Use `ensure:` for cleanup.
-
-## Initialization
-
-- Instance-side `initialize` starts with `super initialize`.
-- Initialize sensible defaults.
-- Methods without an explicit return answer `self`. Do not add a trailing
-  `^ self` to initializers or mutators only to return the receiver; keep
-  explicit returns for early exits or non-self results.
-- Do not redefine class-side `new` just to call `initialize`.
-- Use class-side creation messages such as `on:`, `with:`, or domain-specific
-  constructors when required data exists.
-- Use `basicNew` only when deliberately bypassing initialization.
-
-## Names And Selectors
-
-- Use domain vocabulary.
-- Getter selector is the variable name; setter selector is `name:`.
-- Do not use `getName` or `setName:`.
-- Predicates should read as predicates: `isReady`, `hasErrors`,
-  `canHandle:`.
-- Action selectors should use verbs: `parseRequest:`, `addTool:`,
-  `writeResponseOn:`.
-- Conversion selectors should start with `as`.
-
-## Collections And Streams
-
-- Prefer collection protocol such as `collect:`, `select:`, `reject:`,
-  `detect:ifNone:`, `inject:into:`, `anySatisfy:`, and `allSatisfy:`.
-- Do not mutate a collection while iterating it unless iterating a copy is
-  intentional.
-- Do not rely on `add:` answering the collection; use a variable or cascade
-  with `yourself`.
-- Override `hash` when overriding `=`.
-- Use `String streamContents:` or writer streams for string construction.
-- Do not concatenate strings with `,` in loops or recursive code.
-
-## Tests
-
-- Add or update SUnit tests for behavior changes.
-- Use `assert:equals:` for comparisons when possible.
-- Use `deny:` for negative assertions.
-- Use `should:raise:` and `shouldnt:raise:` with blocks for exception
-  behavior.
-- Prefer focused tests around the public protocol.
-- Use memory filesystems, fakes, or injected collaborators for unit tests when
-  possible.
-- Keep live-image and external-state tests separate from source-only checks.
-
-## Review Checklist
-
-Before finishing a Pharo source change, scan for:
-
-- class checks or reflection used as ordinary dispatch;
-- `perform:` selector registries;
-- normal control flow through `nil`;
-- repeated client-side extraction from an object;
-- long methods or blocks hiding named domain steps;
-- project-specific extensions on broad system classes that only defend
-  hypothetical collaborators;
-- missing `super initialize`;
-- stream/file cleanup without `ensure:`;
-- string concatenation in loops;
-- overridden `=` without `hash`;
-- broad exception handlers that hide failures;
-- missing tests for changed public behavior.

package/templates/pharo-references/pharo-coding-style.md

@@ -1,141 +0,0 @@
-# Pharo Coding Style
-
-Applies when writing or reviewing the shape of Pharo source code after loading
-[Pharo coding rules](pharo-coding-rules.md).
-
-## Goal
-
-Keep Pharo code readable, scannable, and idiomatic. These are readability
-heuristics, not mechanical laws. Prefer the shape that makes dependencies,
-main operations, and exceptional paths easiest to understand.
-
-## Main Send
-
-- Make the main send easy to see. When both branches of a conditional perform
-  the same operation, lift the branch-invariant send out of the branches and
-  use the conditional only for the receiver or argument that varies.
-- This applies to return expressions, assigned values, message arguments, and
-  nested expressions.
-- Do not over-compress multi-step domain logic into one expression.
-
-Prefer:
-
-```smalltalk
-result := self transform: (condition ifTrue: [ selectedValue ])
-```
-
-over duplicating the same `transform:` send inside both conditional branches.
-
-## Guards
-
-- Guard before dependent work. If `nil`, invalid bounds, failed lookup, or
-  missing capability exits early or returns a fallback, check it before sends,
-  computations, or mutations that assume the value is present.
-- Keep the normal path visible. Use early returns for local exceptional or
-  fallback cases when they keep the main path low-indentation.
-- Do not mechanically move every condition to the top. Choose the order that
-  makes dependencies and intent clearest.
-- Prefer "win fast" when the successful case is tiny, obvious, and safe to
-  attempt before fallback work.
-
-## Temporaries
-
-- Prefer short supporting expressions for simple receiver or argument
-  computation.
-- Use a temporary when the value has domain meaning, is reused, names an
-  important step, or helps debugging and review.
-- Keep temporaries near their use.
-
-## Collections
-
-Common collection families, as a protocol reminder rather than a reason to
-branch on concrete collection classes:
-
-```text
-Collection
-  HashedCollection
-    Dictionary
-    Set
-  OrderedDictionary
-  SequenceableCollection
-    OrderedCollection
-      SortedCollection
-    ArrayedCollection
-      Array
-      String
-```
-
-- Build the collection you mean to return. When the result type matters, use
-  messages such as `collect:as:`, `select:as:`, or `flatCollect:as:` instead
-  of collecting into one species and immediately converting to another.
-- Avoid intermediate collections. Prefer fused messages such as
-  `select:thenCollect:` and `reject:thenCollect:` when filtering and
-  transforming. When a filtered or transformed collection exists only to feed
-  iteration, use `select:thenDo:`, `reject:thenDo:`, or `collect:thenDo:`.
-  Use `groupedBy:` for simple grouping.
-- Prefer direct queries over filtered collections. Use `detect:ifNone:` for a
-  first match with fallback, and `anySatisfy:`, `allSatisfy:`, or
-  `noneSatisfy:` when asking a boolean question.
-- Use streaming constructors such as `Array streamContents:` and
-  `String streamContents:` when code conditionally appends values or would
-  otherwise need a temporary `OrderedCollection`.
-- Avoid conversion chains that exist only to sort or change species, such as
-  `asSortedCollection asArray`. Sort a `SequenceableCollection` in-place with
-  `sort`/`sort:`, or make a copy with `sorted`/`sorted:`.
-
-## Conditions
-
-- Avoid assignment inside boolean conditions. Conditions should decide control
-  flow, not also mutate state.
-- Keep questions pure: predicates should answer questions, not mutate state.
-- When the fallback value is `nil`, prefer a one-arm conditional. In Pharo,
-  `ifTrue:` answers `nil` when the condition is false, and `ifFalse:` answers
-  `nil` when the condition is true.
-- Use `ifNotNil:` for local nil traversal when a boundary API can genuinely
-  return `nil` and the next step is asking the non-nil object for a value.
-- Prefer presence-aware lookup messages over lookup-to-nil followed by a nil
-  check. Use `ifPresent:` or `ifPresent:ifAbsent:` variants when they keep the
-  present case local; add `ifAbsent: [ ]` when absence should be an explicit
-  no-op.
-- Keep simple boolean predicates simple. Expressions such as
-  `value notNil and: [ value isReady ]` are idiomatic when the result is a
-  boolean. Do not rewrite them into `ifNil:/ifNotNil:` only to return a
-  boolean literal from one branch.
-- Remove nil-only branches from nil traversal. Both `receiver ifNil: [ nil ]
-  ifNotNil: [ ... ]` and `receiver ifNotNil: [ ... ] ifNil: [ nil ]` should
-  normally become `receiver ifNotNil: [ ... ]`.
-- Avoid defensive type or protocol checks in private helpers unless the helper
-  is an explicit boundary. Let incorrect callers fail or validate at the
-  boundary with a named policy.
-- Prefer a direct send to a known collaborator over a defensive wrapper. Add a
-  wrapper or extension after concrete variation appears, not before.
-
-## Review Smells
-
-Scan for:
-
-- duplicated sends in both conditional branches when only one receiver or
-  argument changes;
-- dependent work performed before a guard proves the value is present or valid;
-- assignment embedded inside boolean conditions;
-- repeated `isNotNil` checks where `ifNotNil:` would express local nil
-  traversal;
-- lookup with `ifAbsent: [ nil ]` followed by a nil check where an
-  `ifPresent:` variant can express the positive path directly;
-- `ifNil:/ifNotNil:` expressions that return only `true` or `false` from one
-  branch and would read more directly as a boolean condition;
-- `ifNil: [ nil ] ifNotNil: [...]` or `ifNotNil: [...] ifNil: [ nil ]`
-  branches where plain `ifNotNil:` communicates the same behavior;
-- collection pipelines that allocate intermediate collections only to
-  immediately convert, sort, query emptiness, take a first match, or group
-  values manually;
-- `select:`, `reject:`, or `collect:` immediately followed by `do:` when a
-  `thenDo:` variant would avoid the intermediate collection;
-- sorting through conversion chains instead of sorting a result array directly;
-- defensive type checks in private helpers that hide caller bugs;
-- cascaded stream writes, where `stream << a; << b` says what `stream << a << b`
-  says with more punctuation, since `<<` answers the stream;
-- wrapper methods or extensions that exist only because a collaborator might be
-  wrong someday;
-- dense nested expressions that would be clearer with a temporary or extracted
-  method.