SqueakSmalltalkInteropServer

README excerpt

# SqueakSmalltalkInteropServer

A powerful web API server that bridges Squeak Smalltalk environments with external tools, enabling seamless integration with AI agents, editors, and other development tools. The server provides comprehensive introspection and manipulation capabilities for Smalltalk code.

Port of [PharoSmalltalkInteropServer](https://github.com/mumez/PharoSmalltalkInteropServer)

## Features

- **Code Evaluation**: Execute Smalltalk expressions and return results
- **Settings Management**: Dynamically configure server settings via API endpoints
- **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
- **Test Execution**: Run test suites at package or class level
- **Project Installation**: Install Smalltalk projects using Metacello
- **UI Debugging**: Capture screenshots and extract UI structure for World morphs
- **MCP Protocol**: Designed as a Model Context Protocol server core for AI integration

## Use Cases

- **AI Code Assistants**: Enable AI agents to understand and manipulate Smalltalk code
- **IDE Integration**: Connect external editors with Smalltalk environments
- **Code Analysis Tools**: Build tools that analyze Smalltalk codebases
- **Remote Development**: Access Smalltalk environments from remote tools
- **Educational Platforms**: Create interactive Smalltalk learning environments

## Installation
- Squeak Smalltalk image (tested with Squeak 6.1 & 6.0)

### Prerequisites

First, you need to add Tonel support to Squeak -  [squeak-tonel](https://github.com/squeak-smalltalk/squeak-tonel)

```Smalltalk
Installer ensureRecentMetacello.
(Smalltalk classNamed: #Metacello) new
   baseline: 'Tonel';
   repository: 'github://squeak-smalltalk/squeak-tonel:squeak';
   load.
```

### Install SqueakSmalltalkInteropServer

Then, you can load SqueakSmalltalkInteropServer.

```Smalltalk
Metacello new
  baseline: 'SqueakSmalltalkInteropServer';
  repository: 'github://mumez/SqueakSmalltalkInteropServer:main/src';
  load.
```

## Quick Start

The server **automatically starts** after installation (on default port 8086) and **auto-restarts** whenever the Squeak image starts up. You can immediately start using the API:

```bash
# Evaluate a Smalltalk expression
curl -X POST http://localhost:8086/eval/ \
  -H "Content-Type: application/json" \
  -d '{"code": "42 factorial"}'

# Search for classes
curl "http://localhost:8086/search-classes-like?class_name_query=String"

# Get class source code
curl "http://localhost:8086/get-class-source?class_name=OrderedCollection"

# Get method source code
curl "http://localhost:8086/get-method-source?class_name=OrderedCollection&method_name=add:"
```

## API

The server exposes a RESTful API for Smalltalk introspection and manipulation. All endpoints return standardized JSON responses.

| Category | Endpoints |
|---|---|
| **Code Evaluation** | `POST /eval/` |
| **Class Operations** | `GET /list-classes`, `/list-extended-classes`, `/get-class-source`, `/get-class-comment` |
| **Method Operations** | `GET /list-methods`, `/get-method-source` |
| **Search** | `GET /search-classes-like`, `/search-traits-like`, `/search-methods-like`, `/search-references`, `/search-implementors`, `/search-references-to-class` |
| **Package Operations** | `GET /list-packages`, `/export-package`, `/import-package` |
| **Test Execution** | `GET /run-package-test`, `/run-class-test` |
| **Project** | `GET /install-project` |
| **Settings** | `POST /apply-settings`, `GET /get-settings` |
| **UI Debugging** | `GET /read-screen` |

> **Note:** `/search-traits-like` always returns empty results (Squeak has no Traits), and `/read-screen` with `target_type=roassal` or `spec` returns an empty structure (Squeak has no Roassal or Spec UI).

## Server Management

### Start / Stop / Restart

```Smalltalk
SisServer current start.   "Start the server"
SisServer current stop.    "Stop the server"
SisServer restart.         "Restart (stop, reset, start)"
```

### Configuration

```Smalltalk
"Change server port (default: 8086) and restart to apply it"
SisSettings default port: 9090.
SisServer restart.

"View current settings"
SisServer current settings.

"Configure server settings (applies immediately, no restart needed)"
SisServer current settings at: #stackSize put: 200.
```

### Environment Variables

Default values can be overridden via environment variables before starting the Squeak image:

| Variable | Description | Default |
|---|---|---|
| `SQUEAK_SISPORT` | Server port | `8086` |
| `SQUEAK_SISSCREENSHOT_DIR` | Screenshot save directory | system temp dir |

> **Note:** This feature is not supported on Windows version of Squeak 6.0 due to a limitation of OSProcess.

### Settings Management via API

Settings can also be managed dynamically through HTTP endpoints. The API accepts both camelCase and snake_case keys (e.g., `stackSize` or `stack_size`), which are automatically normalized to camelCase:

```bash
# Get current settings
curl http://localhost:8086/get-settings

# Apply new settings
curl -X POST http://localhost:8086/apply-settings \
  -H "Content-Type: application/json" \
  -d '{"settings": {"stackSize": 150, "customKey": "value"}}'
```

> **Note:** Squeak has no Announcement framework, so `SisRequestAnnouncement`/`subscribeOnRequest:`-style request hooks (available in PharoSmalltalkInteropServer) are not available here.

## License

See [LICENSE](LICENSE) file for details.
Description

Details

README excerpt
