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

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

@@ -0,0 +1,143 @@
+# Getting Started
+
+This is the canonical guide for loading MCP, starting its HTTP endpoint, and
+connecting a client.
+
+## Requirements
+
+- Pharo 12, 13, or 14
+- 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 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
+package_search
+class_search
+class_get
+method_metadata_search
+method_source_search
+method_implementor_search
+method_sender_search
+method_get
+```
+
+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

@@ -0,0 +1,147 @@
+# 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:`, `registerTool:`,
+  `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

@@ -0,0 +1,139 @@
+# 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;
+- 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.

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

@@ -0,0 +1,256 @@
+# 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 `status`, `summary`, `warnings`, and either
+   `data` or `error`. By default this payload is serialized into the MCP
+   `content` field; the server can also emit `structuredContent` for clients
+   that need programmatic results.
+
+```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.
+
+## Rewrite Preview And Confirmation
+
+`method_rewrite` uses Smalltalk AST rewrite rules. Patterns use RB AST pattern
+syntax, not regex.
+
+The default mode is preview:
+
+```json
+{
+  "rules": [
+    {
+      "lhs": "`@receiver ifTrue: [ `@body ]",
+      "rhs": "`@receiver ifTrue: [ `@body ]"
+    }
+  ],
+  "apply": false
+}
+```
+
+Preview mode returns calculated changes and a `changeSetHash`. Applying requires
+the hash from a preview of the same request:
+
+```json
+{
+  "rules": [
+    {
+      "lhs": "`@old",
+      "rhs": "`@new"
+    }
+  ],
+  "packageNames": ["MyPackage"],
+  "apply": true,
+  "expectedChangeSetHash": 123456
+}
+```
+
+Applying to the whole image also requires `force=true`. Prefer an explicit
+package, class, hierarchy, or method scope.
+
+## 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 work with
+tracked Pharo `DebugSession` records, captured worker-process exceptions,
+SUnit test failures, transient DebugPoint breakpoints, and attached human-opened
+debuggers.
+
+Treat debugger state references as opaque and state-scoped. After stepping,
+resuming, restarting, terminating, or editing from a debug state, use the newly
+returned state before expanding variables or evaluating in a frame again.
+
+Use `debug_method_update` only from a paused debug state and only after reading the
+offered repair actions. It uses the same critique gate as method editing before
+proceeding a repaired computation.
+
+## Evaluation Escape Hatch
+
+`image_evaluate` runs arbitrary Smalltalk and saves the image after a successful
+call. 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.
+
+## Observability And UI
+
+The Spec dashboard is available from an inspected `MCP` object. It shows:
+
+- server status and port
+- debug mode
+- registered tools and descriptions
+- observability status
+- per-tool timing metrics
+- traces for errors, outliers, and output overruns
+- recent logs
+
+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 `OpenTelemetry` group, then enable
+the OpenTelemetry backend for an MCP instance:
+
+```smalltalk
+Metacello new
+   baseline: 'MCP';
+   repository: 'github://Evref-BL/MCP:main/src';
+   load: 'OpenTelemetry'.
+
+mcp useOpenTelemetryObservability
+```
+
+## Version Compatibility
+
+The core baseline loads PharoCompatibility, JRPC, and PCRE2.
+OpenTelemetry is loaded only by the optional `OpenTelemetry` group. CI covers
+Pharo 12, 13, and 14. Code that depends on version-sensitive Pharo APIs should
+go through PharoCompatibility rather than assuming the Pharo 13 API is present
+everywhere.