smalltalk-interop-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Python-based MCP (Model Context Protocol) server designed to communicate with local Smalltalk images (Pharo or Squeak). The server provides an interface for:

• 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
• Connection Management: Recreate the SIS HTTP connection at runtime with an optional host/port override

Development Setup

This project uses uv as the Python package manager. Prerequisites:

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

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 (non-numeric or outside 1–65535), a warning is logged and the default port is used. The reset_connection tool can override host and port at runtime without restarting the MCP server.

Common Commands

# Install dependencies
uv sync --dev

# Run the MCP server
uv run smalltalk-interop-mcp-server

# Run the MCP server with custom port
SIS_PORT=8081 uv run smalltalk-interop-mcp-server

# Run tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run linting and formatting
uv run ruff check
uv run ruff format

# Format markdown files
uv run mdformat .

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