smalltalk-mcp

name	smalltalk-mcp
description	Interact with live Smalltalk images (Squeak, Cuis) via MCP. Evaluate code, browse classes, view method source, define and modify classes and methods, query hierarchies and categories in a running Smalltalk environment.

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 or Squeak
• 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

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):

{
  "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):

{
  "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