pharo-smalltalk-interop

This MCP server provides a bridge to a local Pharo Smalltalk image, exposing a set of tools that map to the PharoSmalltalkInteropServer API. It supports code evaluation, code introspection (retrieving sources and comments), search and discovery across classes and methods, package management (export/import in Tonel format), project installation via Metacello, test execution at package or class level, and UI debugging capabilities such as screen capture and UI structure extraction. The server is designed to run locally and be configurable at runtime via environment variables or the read/write server settings endpoints, enabling you to adapt ports and behavior to your environment.

To use the MCP server, start it with uvx (as shown in the quick start) or uv after cloning. The uvx approach pulls the server directly from Git and runs it without a local installation, while uv requires you to have the repository checked out locally. Once running, you can access 22 MCP tools, including eval for evaluating Smalltalk expressions, get_class_source and get_method_source for introspection, search_classes_like and search_methods_like for discovery, export_package and import_package for Tonel packaging, install_project for Metacello-based installations, and read_screen for UI debugging. You can also retrieve and modify server settings with get_settings and apply_settings.

Example capabilities include: evaluating Smalltalk expressions and returning results, fetching class or method sources, locating classes or methods by pattern, exporting a package in Tonel format, installing a project via Metacello, running tests at the package or class level, and capturing a screenshot along with a UI tree for World morphs or Roassal visualizations. The server emphasizes a workflow that mirrors PharoSmalltalkInteropServer APIs, so you can integrate these capabilities into automation scripts, Claude, or your development pipelines.

Prerequisites:

• Python 3.10 or later
• uv package manager (https://docs.astral.sh/uv/)
• Pharo with PharoSmalltalkInteropServer installed (as referenced in the README)

Installation steps:

1. Quick start (no clone required):

uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server

2. Development installation (clone and install dependencies):

# Clone the repository
git clone https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git

# Navigate into the project and sync/dev dependencies
cd pharo-smalltalk-interop-mcp-server
uv sync --dev

3. Run the server locally (after installation):

# Using uv (directory must point to the cloned repo)
PHARO_SIS_PORT=8086 uv run pharo-smalltalk-interop-mcp-server

4. Environment configuration (optional):

• You can set PHARO_SIS_PORT or other environment variables to customize the server behavior.
• Example:

PHARO_SIS_PORT=8086 uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server

Notes:

• The MCP server relies on the PharoSmalltalkInteropServer integration; ensure that dependency is available in your Pharo image.
• If you modify code, re-run uv sync --dev or restart the uv/uvx process to pick up changes.

Tips and common issues:

• If PHARO_SIS_PORT is in use, choose an available port and update the environment variable accordingly.
• When using uvx, the server is pulled from Git; ensure your network allows accessing GitHub. If you encounter SSL or certificate errors, ensure your environment has up-to-date CA certificates.
• The MCP tools list can be lengthy; start with eval for quick experiments and progressively explore introspection and packaging features.
• For Claude integration, use the commands shown in the README to register the MCP in Claude, replacing the git URL if you fork or clone your own version.
• If you plan to run Metacello-based installations via install_project, ensure the Pharo image has the necessary network access to fetch dependencies.
• The read_screen tool has optional capture_screenshot behavior; you can disable screenshots for faster responses by setting capture_screenshot to false in its parameters.