smalltalk-mcp

# Smalltalk MCP Skill This skill connects Claude to a live Smalltalk image (Cuis or Squeak) via MCP. ## Setup (if tools are not yet connected) If the Smalltalk MCP tools are not available, help the user configure them: ### Prerequisites - Python 3.10+ - A Smalltalk VM: [Cuis](https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev) or [Squeak](https://squeak.org/downloads/) - The ClaudeSmalltalk repository: `git clone https://github.com/CorporateSmalltalkConsultingLtd/ClaudeSmalltalk.git` - Build a `ClaudeCuis.image` following CUIS-SETUP.md. For Squeak, see SQUEAK-SETUP.md. ### Step 1: Install Python dependency ```bash pip install httpx ``` If using Anthropic as the agent LLM provider, also: `pip install anthropic` ### Step 2: Create `smalltalk-mcp.json` Create this file in the ClaudeSmalltalk repo directory. All paths must be absolute. Example using Anthropic (copy from `examples/smalltalk-mcp-anthropic.json`): ```json { "version": "1.0", "model": { "provider": "anthropic", "name": "claude-sonnet-4-6", "maxTokens": 256000, "apiKeyEnv": "ANTHROPIC_API_KEY" }, "vm": { "squeak": "/absolute/path/to/Squeak6.0.app/Contents/MacOS/Squeak", "cuis": "/absolute/path/to/CuisVM.app/Contents/MacOS/Squeak" }, "image": { "selected": "cuis", "squeak": "/absolute/path/to/ClaudeSqueak.image", "cuis": "/absolute/path/to/ClaudeSmalltalk/ClaudeCuis.image" }, "transport": { "type": "stdio", "args": ["--mcp"], "timeout": 180 } } ``` The user must set their API key: `export ANTHROPIC_API_KEY=sk-ant-...` Other provider examples are in the `examples/` folder (Ollama, OpenAI, xAI, MQTT). ### Step 3: Configure Claude Desktop The user must edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS): ```json { "mcpServers": { "smalltalkAgent": { "command": "python3", "args": ["/absolute/path/to/ClaudeSmalltalk/smalltalk_agent_mcp.py"], "env": { "SMALLTALK_MCP_CONFIG": "/absolute/path/to/ClaudeSmalltalk/.smalltalk-mcp.json" } } } } ``` An example is at `examples/claude_desktop_config.json`. All paths must be absolute. After saving, Claude Desktop will reload and the 13 Smalltalk tools will become available. --- ## How to use the tools Once connected, you have 13 MCP tools for the live Smalltalk image. ### When to use `smalltalk_task` vs individual tools **Use `smalltalk_task`** for complex, multi-step work: - "Review the Random class" — the agent browses, reads methods, and produces an assessment - "Audit the Set class for correctness" - "Define a Counter class with increment/decrement methods and tests" - "Compare OrderedCollection and Array implementations" `smalltalk_task` delegates to a separate LLM configured in `.smalltalk-mcp.json`. You provide a natural language task and get back a complete result. This is the preferred tool for anything requiring multiple browse/evaluate steps. **Use individual tools** for quick, single operations: - `smalltalk_evaluate` — run code: `3 factorial`, `Date today` - `smalltalk_browse` — get class metadata (superclass, ivars, method lists) - `smalltalk_method_source` — read one method's source code - `smalltalk_list_classes` — find classes by prefix - `smalltalk_hierarchy` / `smalltalk_subclasses` — explore inheritance ### Best practices **Always browse before modifying.** Before defining or changing a method, use `smalltalk_browse` to understand the class structure and `smalltalk_method_source` to read existing implementations. **Class-side methods.** Use the `side` parameter with value `"class"` when viewing or defining class-side methods. The `smalltalk_browse` tool returns both instance and class methods. **Class definitions.** Use standard Smalltalk class definition syntax: ``` Object subclass: #MyClass instanceVariableNames: 'foo bar' classVariableNames: '' poolDictionaries: '' category: 'MyCategory' ``` **Method source format.** Provide complete method source including the selector line: ``` increment count := (count ifNil: [0]) + 1. ^ count ``` **Testing.** After defining methods, verify with `smalltalk_evaluate`: ``` MyClass new increment ``` Run SUnit tests: `MyClassTest buildSuite run` **Exploring the system.** Start broad, then narrow: 1. `smalltalk_list_categories` — see what's in the image 2. `smalltalk_classes_in_category` — explore a category 3. `smalltalk_browse` — understand a class 4. `smalltalk_method_source` — read specific methods ## Tool reference | Tool | Description | |------|-------------| | `smalltalk_task` | Run a complex task via the agent loop (preferred for multi-step work) | | `smalltalk_evaluate` | Execute Smalltalk code and return the result | | `smalltalk_browse` | Get class metadata: superclass, ivars, instance and class methods | | `smalltalk_method_source` | View source code of a method (use `side: "class"` for class side) | | `smalltalk_define_class` | Create or modify a class definition | | `smalltalk_define_method` | Add or update a method on a class | | `smalltalk_delete_method` | Remove a method from a class | | `smalltalk_delete_class` | Remove a class from the system | | `smalltalk_list_classes` | List classes matching a prefix | | `smalltalk_hierarchy` | Get superclass chain for a class | | `smalltalk_subclasses` | Get immediate subclasses of a class | | `smalltalk_list_categories` | List all system categories | | `smalltalk_classes_in_category` | List classes in a category |