smalltalk-interop-mcp-server

A local MCP server to communicate with a local Smalltalk image (Pharo or Squeak). It supports:

• Code Evaluation: Execute Smalltalk expressions and return results
• Code Introspection: Retrieve source code, comments, and metadata for classes and methods
• Search & Discovery: Find classes, traits, methods, references, and implementors
• Package Management: Export and import packages in Tonel format
• Project Installation: Install projects using Metacello
• Test Execution: Run test suites at package or class level
• UI Debugging: Capture screenshots and inspect UI structure for World morphs, and (Pharo only) Spec presenters and Roassal visualizations
• Server Configuration: Retrieve and modify server settings dynamically

Prerequisites

• Python 3.10 or later
• uv package manager
• A Smalltalk Interop Server installed in the target image:
  • PharoSmalltalkInteropServer for Pharo
  • SqueakSmalltalkInteropServer for Squeak

Installation

Quick Start (using uvx)

The easiest way to run the server without cloning the repository:

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

Development Installation

To set up for development:

1. Clone the repository:

git clone https://github.com/mumez/smalltalk-interop-mcp-server.git

2. Install dependencies using uv:

cd smalltalk-interop-mcp-server
uv sync --dev

Usage

Running the MCP Server

Using uvx (no installation required):

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

Using uv (after cloning the repository):

uv run smalltalk-interop-mcp-server

Environment Variables

You can configure the server using environment variables:

• SIS_PORT: Port number for the Smalltalk Interop Server (default: 8086)

Examples:

Using uvx:

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

Using uv:

SIS_PORT=9999 uv run smalltalk-interop-mcp-server

Cursor MCP settings

Using uvx (recommended):

{
  "mcpServers": {
    "smalltalk-interop": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mumez/smalltalk-interop-mcp-server.git",
        "smalltalk-interop-mcp-server"
      ],
      "env": {
        "SIS_PORT": "8086"
      }
    }
  }
}

Using uv (after cloning):

{
  "mcpServers": {
    "smalltalk-interop": {
      "command": "uv",
      "args": [
        "--directory",
        "/your-path/to/smalltalk-interop-mcp-server",
        "run",
        "smalltalk-interop-mcp-server"
      ],
      "env": {
        "SIS_PORT": "8086"
      }
    }
  }
}

Note: The env section is optional and can be used to set environment variables for the MCP server.

Claude Code Configuration

Using uvx (recommended):

claude mcp add -s user smalltalk-interop -- uvx --from git+https://github.com/mumez/smalltalk-interop-mcp-server.git smalltalk-interop-mcp-server

Using uv (after cloning):

claude mcp add -s user smalltalk-interop -- uv --directory /path/to/smalltalk-interop-mcp-server run smalltalk-interop-mcp-server

MCP Tools Available

This server provides 22 MCP tools that map to the Smalltalk Interop Server API, shared by both PharoSmalltalkInteropServer and SqueakSmalltalkInteropServer:

Code Evaluation

• eval: Execute Smalltalk expressions and return results

Code Introspection

• get_class_source: Retrieve source code of a class
• get_method_source: Retrieve source code of a specific method
• get_class_comment: Retrieve comment/documentation of a class

Search & Discovery

• search_classes_like: Find classes matching a pattern
• search_methods_like: Find methods matching a pattern
• search_traits_like: Find traits matching a pattern
• search_implementors: Find all implementors of a method selector
• search_references: Find all references to a method selector
• search_references_to_class: Find all references to a class

Package Management

• list_packages: List all packages in the image
• list_classes: List classes in a specific package
• list_extended_classes: List extended classes in a package
• list_methods: List methods in a package
• export_package: Export a package in Tonel format
• import_package: Import a package from specified path

Project Installation

• install_project: Install a project using Metacello with optional load groups

Test Execution

• run_package_test: Run test suites for a package
• run_class_test: Run test suites for a specific class

UI Debugging

• read_screen: UI screen reader for debugging Smalltalk interfaces with screenshot and structure extraction

Server Configuration

• get_settings: Retrieve current server configuration
• apply_settings: Modify server configuration dynamically

read_screen Tool

The read_screen tool captures screenshots and extracts UI structure for debugging Smalltalk UI issues.

Parameters:

• target_type (string, default: 'world'): UI type to inspect ('world' for morphs — Pharo and Squeak, 'spec' for windows — Pharo only, 'roassal' for visualizations — Pharo only)
• capture_screenshot (boolean, default: true): Include PNG screenshot in response

Returns: UI structure with screenshot and human-readable summary

Usage Examples:

# Inspect all morphs in World
read_screen(target_type='world')

# Inspect Spec presenter windows (Pharo only)
read_screen(target_type='spec', capture_screenshot=false)

# Inspect Roassal visualizations without screenshot (Pharo only, faster)
read_screen(target_type='roassal', capture_screenshot=false)

Extracted Data Includes:

World (morphs):

• Class name and type identification
• Bounds (x, y, width, height coordinates)
• Visibility state
• Background color
• Owner class
• Submorph count
• Text content (if available)

Example output:

{
  "totalMorphs": 12,
  "displayedMorphCount": 1,
  "morphs": [
    {
      "class": "MenubarMorph",
      "visible": true,
      "bounds": {"x": 0, "y": 0, "width": 976, "height": 18},
      "backgroundColor": "(Color r: 0.883... alpha: 0.8)",
      "owner": "WorldMorph",
      "submorphCount": 8
    }
  ]
}

Spec (presenters, Pharo only):

• Window title and class name
• Geometry (extent, position)
• Window state (maximized, minimized, resizable)
• Decorations (menu, toolbar, statusbar presence)
• Presenter hierarchy (recursive with max depth of 3 levels)
• Presenter class name, child count, and content properties (label, text, value, etc.)
• Enablement and visibility state

Example output:

{
  "windowCount": 1,
  "presenters": [
    {
      "class": "SpWindowPresenter",
      "title": "Welcome",
      "extent": "(700@550)",
      "hasMenu": false,
      "presenter": {
        "class": "StWelcomeBrowser",
        "childCount": 2,
        "isVisible": true,
        "children": []
      }
    }
  ]
}

Roassal (visualizations, Pharo only):

• Canvas bounds and visibility state
• Canvas class identification
• Background color and zoom level
• Shape details (color, position, extent, label, text)
• Edge details (source, target, color, label)
• Node and edge counts

Example output:

{
  "canvasCount": 1,
  "canvases": [
    {
      "class": "RSAthensMorph",
      "canvasClass": "RSCanvas",
      "bounds": {"x": 203, "y": 145, "width": 490, "height": 467},
      "backgroundColor": "Color blue",
      "zoomLevel": "1.0",
      "shapeCount": 5,
      "shapes": [
        {
          "class": "RSCircle",
          "color": "(Color r: 1.0 g: 0.0 b: 0.0 alpha: 0.2)",
          "position": "(0.0@0.0)",
          "extent": "(5.0@5.0)"
        }
      ],
      "edgeCount": 0,
      "edges": [],
      "nodeCount": 0
    }
  ]
}

Server Configuration Tools

The get_settings and apply_settings tools provide dynamic server configuration management.

get_settings

Retrieve the current server configuration.

Parameters: None

Returns: Dictionary containing current server settings

Usage Example:

# Get current settings
get_settings()
# Returns: {"stackSize": 100, "customKey": "customValue"}

Response Format:

{
  "success": true,
  "result": {
    "stackSize": 100,
    "customKey": "customValue"
  }
}

apply_settings

Modify server configuration dynamically. Settings take effect immediately during the current session.

Parameters:

• settings (dict): Dictionary containing settings to modify

Returns: Success confirmation message

Usage Example:

# Apply new settings
apply_settings(settings={"stackSize": 200, "customKey": "customValue"})
# Returns: "Settings applied successfully"

Common Settings:

Setting	Type	Default	Description
stackSize	integer	100	Maximum stack trace depth for error reporting

Note: The server accepts arbitrary key-value pairs beyond documented settings, allowing custom configuration options.

Development

Running Tests

The project includes comprehensive unit tests with mock-based testing to avoid requiring a live Pharo or Squeak instance:

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_core.py -v

Code Quality

# Run linting
uv run ruff check

# Run formatting
uv run ruff format

# Run all pre-commit hooks
uv run pre-commit run --all-files

Project Structure

smalltalk-interop-mcp-server/
├── smalltalk_interop_mcp_server/
│   ├── __init__.py
│   ├── core.py          # HTTP client and core functions
│   └── server.py        # FastMCP server with tool definitions
├── tests/
│   ├── __init__.py
│   ├── test_core.py     # Tests for core HTTP client functionality
│   └── test_server.py   # Tests for MCP server integration
├── pyproject.toml       # Project configuration
├── pytest.ini          # Test configuration
└── README.md

Testing Strategy

The test suite uses mock-based testing to ensure:

• No external dependencies: Tests run without requiring a live Pharo or Squeak instance
• Comprehensive coverage: All 22 endpoints and error scenarios are tested
• Fast execution: Tests complete in under 1 second
• Reliable results: Tests are deterministic and don't depend on external state

Test coverage includes:

• HTTP client functionality (SmalltalkInteropClient class)
• All 22 Smalltalk interop operations
• Error handling (connection errors, HTTP errors, JSON parsing errors)
• MCP server initialization and tool registration
• Integration between core functions and MCP tools