Skip to main content
Glama
smalltalk-interop-mcp-server

smalltalk-interop-mcp-server

by mumez

smalltalk-interop-mcp-server

CI

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

  • Connection Management: Recreate the SIS HTTP connection at runtime with an optional host/port override

Prerequisites

Related MCP server: MCP Server Demo

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
  1. 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). An empty value is treated as unset. If the value cannot be interpreted as a port number, a warning is logged and the default port is used. Use the reset_connection tool to override host and port at runtime without restarting the MCP server.

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 23 MCP tools. 22 map to the Smalltalk Interop Server API, shared by both PharoSmalltalkInteropServer and SqueakSmalltalkInteropServer. reset_connection is a local MCP tool that switches the HTTP client to another SIS host or port:

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

Connection Management

  • reset_connection: Recreate the SIS HTTP connection, optionally overriding host and port

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.

reset_connection Tool

The reset_connection tool recreates the MCP server's HTTP client so you can point at a different SIS instance without restarting the process.

Parameters:

  • host (string, optional, default: localhost): SIS host. Empty or whitespace values use localhost.

  • port (integer, optional, default: SIS_PORT, or 8086 if unset/invalid): SIS port. An explicit invalid port is rejected and the current connection is left unchanged.

Returns: The resolved host, port, and base URL

Usage Examples:

# Switch to another SIS instance
reset_connection(host="127.0.0.1", port=8081)
# Returns: {"success": True, "result": {"host": "127.0.0.1", "port": 8081, "base_url": "http://127.0.0.1:8081"}}

# Override only the port (host stays localhost)
reset_connection(port=9090)

# Restore localhost and SIS_PORT (or 8086)
reset_connection()

Response Format:

{
  "success": true,
  "result": {
    "host": "127.0.0.1",
    "port": 8081,
    "base_url": "http://127.0.0.1:8081"
  }
}

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 SIS endpoints, reset_connection, 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 plus reset_connection

  • Error handling (connection errors, HTTP errors, JSON parsing errors)

  • MCP server initialization and tool registration

  • Integration between core functions and MCP tools

Available Tools

23 tools
apply_settingsApply SettingsB
Idempotent

Modify server configuration dynamically.

Inputs: settings (required). Returns: object

evalEvaluate SmalltalkB
Destructive

Evaluate a Smalltalk expression via the Smalltalk Interop Server.

Inputs: code (required). Returns: object

export_packageExport PackageA
Idempotent

Export a package in Tonel format.

Inputs: package_name (required), path. Returns: object

get_class_commentGet Class CommentA
Read-only

Get the comment of a Smalltalk class.

Inputs: class_name (required). Returns: object

get_class_sourceGet Class SourceB
Read-only

Get the source code of a Smalltalk class.

Inputs: class_name (required). Returns: object

get_method_sourceGet Method SourceB
Read-only

Get the source code of a specific method in a class.

Inputs: class_name (required), method_name (required), is_class_method. Returns: object

get_settingsGet SettingsA
Read-only

Retrieve current server configuration.

Returns: dict: API response with success/error and result - Success: {"success": True, "result": dict} - result contains current server settings - Error: {"success": False, "error": str} - error contains error message

Inputs: no named parameters. Returns: object

import_packageImport PackageB
Destructive

Import a package from specified path.

Inputs: package_name (required), path. Returns: object

install_projectInstall ProjectB
Destructive

Install a project using Metacello.

Inputs: project_name (required), repository_url (required), force, load_groups. Returns: object

list_classesList ClassesA
Read-only

Get list of classes in a package.

Inputs: package_name (required). Returns: object

list_extended_classesList Extended ClassesA
Read-only

Get list of extended classes in a package.

Inputs: package_name (required). Returns: object

list_methodsList MethodsB
Read-only

Get list of methods in a package.

Inputs: package_name (required). Returns: object

list_packagesList PackagesA
Read-only

Get list of all packages.

Returns: dict: API response with success/error and result - Success: {"success": True, "result": list[str]} - result contains list of all package names - Error: {"success": False, "error": str} - error contains error message

Inputs: no named parameters. Returns: object

read_screenRead ScreenA
Read-only

Comprehensive UI screen reader for debugging Smalltalk interfaces.

Captures screenshot and extracts complete UI structure for World morphs (Pharo and Squeak), and Spec presenters and Roassal visualizations (Pharo only).

Inputs: target_type, capture_screenshot. Returns: object

reset_connectionReset ConnectionA
Idempotent

Recreate the HTTP connection to the Smalltalk Interop Server.

Use this to switch the MCP server to another SIS host or port at runtime without restarting the process. Omitted arguments fall back to localhost and SIS_PORT (or 8086).

Inputs: host, port. Returns: object

run_class_testRun Class TestA
Read-only

Run tests for a class.

Inputs: class_name (required). Returns: object

run_package_testRun Package TestB
Read-only

Run tests for a package.

Inputs: package_name (required). Returns: object

search_classes_likeSearch Classes LikeB
Read-only

Find classes matching a pattern.

Inputs: class_name_query (required). Returns: object

search_implementorsSearch ImplementorsA
Read-only

Get all implementors of a method selector.

Inputs: method_name (required). Returns: object

search_methods_likeSearch Methods LikeC
Read-only

Find methods matching a pattern.

Inputs: method_name_query (required). Returns: object

search_referencesSearch ReferencesB
Read-only

Get all references to a method selector or a symbol.

Inputs: method_name_or_symbol (required). Returns: object

search_references_to_classSearch References to ClassC
Read-only

Find references to a class.

Inputs: class_name (required). Returns: object

search_traits_likeSearch Traits LikeB
Read-only

Find traits matching a pattern.

Inputs: trait_name_query (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools target a distinct resource (packages, classes, methods, settings, connection, UI) with clear list/get/search/run verb distinctions. The main soft spots are search_references vs search_references_to_class (selector vs class references) and the cluster of search_*_like tools, which an agent could easily pick wrongly.

    Naming Consistency4/5

    Names are uniformly snake_case and almost all follow a verb_noun pattern (list_packages, get_method_source, run_class_test, reset_connection). The only real deviation is the bare 'eval' with no noun, and 'read_screen' slightly stretches the verb set, but the overall pattern is predictable.

    Tool Count3/5

    At 23 tools this is on the heavy side for the domain, and several are near-duplicates of each other (search_references vs search_references_to_class, list_classes vs search_classes_like, list_extended_classes as a niche listing). Each tool is individually defensible, but the surface could be consolidated.

    Completeness4/5

    Read coverage is thorough — package/class/method listing, sources, comments, implementors, references, tests, plus settings and UI inspection — and 'eval' backstops arbitrary mutations. Explicit write operations (define/compile/delete class or method, delete/unload package) are absent, so lifecycle changes depend on eval rather than a declared API.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers