pharo-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 Pharo Smalltalk images. 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, Spec presenters, and Roassal visualizations

Development Setup

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

• Python 3.10 or later
• uv package manager
• Pharo with PharoSmalltalkInteropServer installed

Environment Variables

You can configure the server using environment variables:

• PHARO_SIS_PORT: Port number for PharoSmalltalkInteropServer (default: 8086)

Common Commands

# Install dependencies
uv sync --dev

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

# Run the MCP server with custom port
PHARO_SIS_PORT=8081 uv run pharo-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

Architecture Overview

The codebase follows a layered architecture with clean separation of concerns:

Core Components

1. core.py - HTTP client layer

   • PharoClient class handles all HTTP communication with PharoSmalltalkInteropServer
   • Connects to localhost:8086 by default
   • Comprehensive error handling for connection, HTTP, and JSON parsing errors
   • Enhanced error handling supporting detailed error information from PharoSmalltalkInteropServer
   • 22 core operations mapped to Pharo API endpoints