smalltalk-interop-mcp-server
This MCP server connects to a local Pharo or Squeak Smalltalk image through the Smalltalk Interop Server and exposes tools for code, packages, tests, UI debugging, settings, and connection management.
Evaluate Smalltalk expressions.
Retrieve class source, method source, and class comments.
Search for classes, methods, traits, implementors, method/symbol references, and class references.
List packages, package classes, extended classes, and methods.
Export/import packages in Tonel format.
Install projects using Metacello with optional load groups.
Run package-level and class-level tests.
Capture screenshots and inspect UI structure for World morphs, Spec presenters (Pharo), and Roassal visualizations (Pharo).
Read and modify server settings dynamically.
Reset/recreate the SIS HTTP connection with optional host/port overrides.
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
Connection Management: Recreate the SIS HTTP connection at runtime with an optional host/port override
Prerequisites
Python 3.10 or later
uv package manager
A Smalltalk Interop Server installed in the target image:
PharoSmalltalkInteropServer for Pharo
SqueakSmalltalkInteropServer for Squeak
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-serverDevelopment Installation
To set up for development:
Clone the repository:
git clone https://github.com/mumez/smalltalk-interop-mcp-server.gitInstall dependencies using uv:
cd smalltalk-interop-mcp-server
uv sync --devUsage
Running the MCP Server
Using uvx (no installation required):
uvx --from git+https://github.com/mumez/smalltalk-interop-mcp-server.git smalltalk-interop-mcp-serverUsing uv (after cloning the repository):
uv run smalltalk-interop-mcp-serverEnvironment 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 thereset_connectiontool 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-serverUsing uv:
SIS_PORT=9999 uv run smalltalk-interop-mcp-serverCursor 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-serverUsing uv (after cloning):
claude mcp add -s user smalltalk-interop -- uv --directory /path/to/smalltalk-interop-mcp-server run smalltalk-interop-mcp-serverMCP 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 classget_method_source: Retrieve source code of a specific methodget_class_comment: Retrieve comment/documentation of a class
Search & Discovery
search_classes_like: Find classes matching a patternsearch_methods_like: Find methods matching a patternsearch_traits_like: Find traits matching a patternsearch_implementors: Find all implementors of a method selectorsearch_references: Find all references to a method selectorsearch_references_to_class: Find all references to a class
Package Management
list_packages: List all packages in the imagelist_classes: List classes in a specific packagelist_extended_classes: List extended classes in a packagelist_methods: List methods in a packageexport_package: Export a package in Tonel formatimport_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 packagerun_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 configurationapply_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 |
| 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 -vCode Quality
# Run linting
uv run ruff check
# Run formatting
uv run ruff format
# Run all pre-commit hooks
uv run pre-commit run --all-filesProject 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.mdTesting 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 testedFast 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 (
SmalltalkInteropClientclass)All 22 Smalltalk interop operations plus
reset_connectionError handling (connection errors, HTTP errors, JSON parsing errors)
MCP server initialization and tool registration
Integration between core functions and MCP tools
Available Tools
23 toolsapply_settingsApply SettingsBIdempotent
Modify server configuration dynamically.
Inputs: settings (required). Returns: object
evalEvaluate SmalltalkBDestructive
Evaluate a Smalltalk expression via the Smalltalk Interop Server.
Inputs: code (required). Returns: object
export_packageExport PackageAIdempotent
Export a package in Tonel format.
Inputs: package_name (required), path. Returns: object
get_class_commentGet Class CommentARead-only
Get the comment of a Smalltalk class.
Inputs: class_name (required). Returns: object
get_class_sourceGet Class SourceBRead-only
Get the source code of a Smalltalk class.
Inputs: class_name (required). Returns: object
get_method_sourceGet Method SourceBRead-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 SettingsARead-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 PackageBDestructive
Import a package from specified path.
Inputs: package_name (required), path. Returns: object
install_projectInstall ProjectBDestructive
Install a project using Metacello.
Inputs: project_name (required), repository_url (required), force, load_groups. Returns: object
list_classesList ClassesARead-only
Get list of classes in a package.
Inputs: package_name (required). Returns: object
list_extended_classesList Extended ClassesARead-only
Get list of extended classes in a package.
Inputs: package_name (required). Returns: object
list_methodsList MethodsBRead-only
Get list of methods in a package.
Inputs: package_name (required). Returns: object
list_packagesList PackagesARead-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 ScreenARead-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 ConnectionAIdempotent
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 TestARead-only
Run tests for a class.
Inputs: class_name (required). Returns: object
run_package_testRun Package TestBRead-only
Run tests for a package.
Inputs: package_name (required). Returns: object
search_classes_likeSearch Classes LikeBRead-only
Find classes matching a pattern.
Inputs: class_name_query (required). Returns: object
search_implementorsSearch ImplementorsARead-only
Get all implementors of a method selector.
Inputs: method_name (required). Returns: object
search_methods_likeSearch Methods LikeCRead-only
Find methods matching a pattern.
Inputs: method_name_query (required). Returns: object
search_referencesSearch ReferencesBRead-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 ClassCRead-only
Find references to a class.
Inputs: class_name (required). Returns: object
search_traits_likeSearch Traits LikeBRead-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
Scored across 23 tools
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.
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.
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.
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
Related MCP Connectors
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server to list and launch applications on MacOS7 npm19MIT
- AlicenseNot gradedqualityDmaintenanceA minimal WebSocket-based MCP server implementation that enables modern tool integrations with VSCode, Claude, and other applications.6 npmISC
- AlicenseBqualityDmaintenanceA local MCP server that enables users to evaluate Pharo Smalltalk expressions and retrieve system information via NeoConsole. It provides comprehensive tools for inspecting class definitions, method sources, and system metrics within a Pharo environment.112MIT
- AlicenseAqualityFmaintenanceMCP server to communicate local Pharo Smalltalk image2212MIT