Pharo Smalltalk Interop MCP Server

1# pharo-smalltalk-interop-mcp-server
2 
3[![CI](https://github.com/mumez/pharo-smalltalk-interop-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/mumez/pharo-smalltalk-interop-mcp-server/actions/workflows/ci.yml)
4 
5A local MCP server to communicate local Pharo Smalltalk image.
6It supports:
7 
8- Code Evaluation: Execute Smalltalk expressions and return results
9- Code Introspection: Retrieve source code, comments, and metadata for classes and methods
10- Search & Discovery: Find classes, traits, methods, references, and implementors
11- Package Management: Export and import packages in Tonel format
12- Project Installation: Install projects using Metacello
13- Test Execution: Run test suites at package or class level
14- UI Debugging: Capture screenshots and inspect UI structure for World morphs, Spec presenters, and Roassal visualizations
15- Server Configuration: Retrieve and modify server settings dynamically
16 
17## Prerequisites
18 
19- Python 3.10 or later
20- [uv](https://docs.astral.sh/uv/) package manager
21- Pharo with [PharoSmalltalkInteropServer](https://github.com/mumez/PharoSmalltalkInteropServer) installed
22 
23## Installation
24 
25### Quick Start (using uvx)
26 
27The easiest way to run the server without cloning the repository:
28 
29```bash
30uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server
31```
32 
33### Development Installation
34 
35To set up for development:
36 
371. Clone the repository:
38 
39```bash
40git clone https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git
41```
42 
432. Install dependencies using uv:
44 
45```bash
46cd pharo-smalltalk-interop-mcp-server
47uv sync --dev
48```
49 
50## Usage
51 
52### Running the MCP Server
53 
54**Using uvx (no installation required):**
55 
56```bash
57uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server
58```
59 
60**Using uv (after cloning the repository):**
61 
62```bash
63uv run pharo-smalltalk-interop-mcp-server
64```
65 
66#### Environment Variables
67 
68You can configure the server using environment variables:
69 
70- **`PHARO_SIS_PORT`**: Port number for PharoSmalltalkInteropServer (default: 8086)
71 
72Examples:
73 
74**Using uvx:**
75 
76```bash
77PHARO_SIS_PORT=8086 uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server
78```
79 
80**Using uv:**
81 
82```bash
83PHARO_SIS_PORT=9999 uv run pharo-smalltalk-interop-mcp-server
84```
85 
86### Cursor MCP settings
87 
88**Using uvx (recommended):**
89 
90```json:mcp.json
91{
92  "mcpServers": {
93    "smalltalk-interop": {
94      "command": "uvx",
95      "args": [
96        "--from",
97        "git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git",
98        "pharo-smalltalk-interop-mcp-server"
99      ],
100      "env": {
101        "PHARO_SIS_PORT": "8086"
102      }
103    }
104  }
105}
106```
107 
108**Using uv (after cloning):**
109 
110```json:mcp.json
111{
112  "mcpServers": {
113    "smalltalk-interop": {
114      "command": "uv",
115      "args": [
116        "--directory",
117        "/your-path/to/pharo-smalltalk-interop-mcp-server",
118        "run",
119        "pharo-smalltalk-interop-mcp-server"
120      ],
121      "env": {
122        "PHARO_SIS_PORT": "8086"
123      }
124    }
125  }
126}
127```
128 
129Note: The `env` section is optional and can be used to set environment variables for the MCP server.
130 
131### Claude Code Configuration
132 
133**Using uvx (recommended):**
134 
135```bash
136claude mcp add -s user smalltalk-interop -- uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server
137```
138 
139**Using uv (after cloning):**
140 
141```bash
142claude mcp add -s user smalltalk-interop -- uv --directory /path/to/pharo-smalltalk-interop-mcp-server run pharo-smalltalk-interop-mcp-server
143```
144 
145### MCP Tools Available
146 
147This server provides 22 MCP tools that map to all [PharoSmalltalkInteropServer](https://github.com/mumez/PharoSmalltalkInteropServer/blob/main/spec/openapi.json) APIs:
148 
149#### Code Evaluation
150 
151- **`eval`**: Execute Smalltalk expressions and return results
152 
153#### Code Introspection
154 
155- **`get_class_source`**: Retrieve source code of a class
156- **`get_method_source`**: Retrieve source code of a specific method
157- **`get_class_comment`**: Retrieve comment/documentation of a class
158 
159#### Search & Discovery
160 
161- **`search_classes_like`**: Find classes matching a pattern
162- **`search_methods_like`**: Find methods matching a pattern
163- **`search_traits_like`**: Find traits matching a pattern
164- **`search_implementors`**: Find all implementors of a method selector
165- **`search_references`**: Find all references to a method selector
166- **`search_references_to_class`**: Find all references to a class
167 
168#### Package Management
169 
170- **`list_packages`**: List all packages in the image
171- **`list_classes`**: List classes in a specific package
172- **`list_extended_classes`**: List extended classes in a package
173- **`list_methods`**: List methods in a package
174- **`export_package`**: Export a package in Tonel format
175- **`import_package`**: Import a package from specified path
176 
177#### Project Installation
178 
179- **`install_project`**: Install a project using Metacello with optional load groups
180 
181#### Test Execution
182 
183- **`run_package_test`**: Run test suites for a package
184- **`run_class_test`**: Run test suites for a specific class
185 
186#### UI Debugging
187 
188- **`read_screen`**: UI screen reader for debugging Pharo interfaces with screenshot and structure extraction
189 
190#### Server Configuration
191 
192- **`get_settings`**: Retrieve current server configuration
193- **`apply_settings`**: Modify server configuration dynamically
194 
195### read_screen Tool
196 
197The `read_screen` tool captures screenshots and extracts UI structure for debugging Pharo UI issues.
198 
199**Parameters:**
200 
201- `target_type` (string, default: 'world'): UI type to inspect ('world' for morphs, 'spec' for windows, 'roassal' for visualizations)
202- `capture_screenshot` (boolean, default: true): Include PNG screenshot in response
203 
204**Returns:** UI structure with screenshot and human-readable summary
205 
206**Usage Examples:**
207 
208```python
209# Inspect all morphs in World
210read_screen(target_type='world')
211 
212# Inspect Spec presenter windows
213read_screen(target_type='spec', capture_screenshot=false)
214 
215# Inspect Roassal visualizations without screenshot (faster)
216read_screen(target_type='roassal', capture_screenshot=false)
217```
218 
219**Extracted Data Includes:**
220 
221*World (morphs):*
222 
223- Class name and type identification
224- Bounds (x, y, width, height coordinates)
225- Visibility state
226- Background color
227- Owner class
228- Submorph count
229- Text content (if available)
230 
231Example output:
232 
233```json
234{
235  "totalMorphs": 12,
236  "displayedMorphCount": 1,
237  "morphs": [
238    {
239      "class": "MenubarMorph",
240      "visible": true,
241      "bounds": {"x": 0, "y": 0, "width": 976, "height": 18},
242      "backgroundColor": "(Color r: 0.883... alpha: 0.8)",
243      "owner": "WorldMorph",
244      "submorphCount": 8
245    }
246  ]
247}
248```
249 
250*Spec (presenters):*
251 
252- Window title and class name
253- Geometry (extent, position)
254- Window state (maximized, minimized, resizable)
255- Decorations (menu, toolbar, statusbar presence)
256- Presenter hierarchy (recursive with max depth of 3 levels)
257- Presenter class name, child count, and content properties (label, text, value, etc.)
258- Enablement and visibility state
259 
260Example output:
261 
262```json
263{
264  "windowCount": 1,
265  "presenters": [
266    {
267      "class": "SpWindowPresenter",
268      "title": "Welcome",
269      "extent": "(700@550)",
270      "hasMenu": false,
271      "presenter": {
272        "class": "StWelcomeBrowser",
273        "childCount": 2,
274        "isVisible": true,
275        "children": []
276      }
277    }
278  ]
279}
280```
281 
282*Roassal (visualizations):*
283 
284- Canvas bounds and visibility state
285- Canvas class identification
286- Background color and zoom level
287- Shape details (color, position, extent, label, text)
288- Edge details (source, target, color, label)
289- Node and edge counts
290 
291Example output:
292 
293```json
294{
295  "canvasCount": 1,
296  "canvases": [
297    {
298      "class": "RSAthensMorph",
299      "canvasClass": "RSCanvas",
300      "bounds": {"x": 203, "y": 145, "width": 490, "height": 467},
301      "backgroundColor": "Color blue",
302      "zoomLevel": "1.0",
303      "shapeCount": 5,
304      "shapes": [
305        {
306          "class": "RSCircle",
307          "color": "(Color r: 1.0 g: 0.0 b: 0.0 alpha: 0.2)",
308          "position": "(0.0@0.0)",
309          "extent": "(5.0@5.0)"
310        }
311      ],
312      "edgeCount": 0,
313      "edges": [],
314      "nodeCount": 0
315    }
316  ]
317}
318```
319 
320### Server Configuration Tools
321 
322The `get_settings` and `apply_settings` tools provide dynamic server configuration management.
323 
324#### get_settings
325 
326Retrieve the current server configuration.
327 
328**Parameters:** None
329 
330**Returns:** Dictionary containing current server settings
331 
332**Usage Example:**
333 
334```python
335# Get current settings
336get_settings()
337# Returns: {"stackSize": 100, "customKey": "customValue"}
338```
339 
340**Response Format:**
341 
342```json
343{
344  "success": true,
345  "result": {
346    "stackSize": 100,
347    "customKey": "customValue"
348  }
349}
350```
351 
352#### apply_settings
353 
354Modify server configuration dynamically. Settings take effect immediately during the current session.
355 
356**Parameters:**
357 
358- `settings` (dict): Dictionary containing settings to modify
359 
360**Returns:** Success confirmation message
361 
362**Usage Example:**
363 
364```python
365# Apply new settings
366apply_settings(settings={"stackSize": 200, "customKey": "customValue"})
367# Returns: "Settings applied successfully"
368```
369 
370**Common Settings:**
371 
372| Setting     | Type    | Default | Description                                   |
373| ----------- | ------- | ------- | --------------------------------------------- |
374| `stackSize` | integer | 100     | Maximum stack trace depth for error reporting |
375 
376**Note:** The server accepts arbitrary key-value pairs beyond documented settings, allowing custom configuration options.
377 
378## Development
379 
380### Running Tests
381 
382The project includes comprehensive unit tests with mock-based testing to avoid requiring a live Pharo instance:
383 
384```bash
385# Run all tests
386uv run pytest
387 
388# Run tests with verbose output
389uv run pytest -v
390 
391# Run specific test file
392uv run pytest tests/test_core.py -v
393```
394 
395### Code Quality
396 
397```bash
398# Run linting
399uv run ruff check
400 
401# Run formatting
402uv run ruff format
403 
404# Run all pre-commit hooks
405uv run pre-commit run --all-files
406```
407 
408### Project Structure
409 
410```
411pharo-smalltalk-interop-mcp-server/
412├── pharo_smalltalk_interop_mcp_server/
413│   ├── __init__.py
414│   ├── core.py          # HTTP client and core functions
415│   └── server.py        # FastMCP server with tool definitions
416├── tests/
417│   ├── __init__.py
418│   ├── test_core.py     # Tests for core HTTP client functionality
419│   └── test_server.py   # Tests for MCP server integration
420├── pyproject.toml       # Project configuration
421├── pytest.ini          # Test configuration
422└── README.md
423```
424 
425### Testing Strategy
426 
427The test suite uses mock-based testing to ensure:
428 
429- **No external dependencies**: Tests run without requiring a live Pharo instance
430- **Comprehensive coverage**: All 22 endpoints and error scenarios are tested
431- **Fast execution**: Tests complete in under 1 second
432- **Reliable results**: Tests are deterministic and don't depend on external state
433 
434Test coverage includes:
435 
436- HTTP client functionality (`PharoClient` class)
437- All 22 Pharo interop operations
438- Error handling (connection errors, HTTP errors, JSON parsing errors)
439- MCP server initialization and tool registration
440- Integration between core functions and MCP tools
441