Pharo Smalltalk Interop Mcp Server

pharo-smalltalk-interop-mcp-server

⚠️ 本项目已迁移。 从 v4.0.0 开始，开发工作已迁移至 smalltalk-interop-mcp-server，该项目除了支持 Pharo，还新增了对 Squeak SIS 服务的支持。请使用新仓库获取最新功能和更新；本仓库仅作历史参考。

用于与本地 Pharo Smalltalk 镜像通信的本地 MCP 服务。 它支持：

• 代码求值：执行 Smalltalk 表达式并返回结果
• 代码内省：获取类和方法的源代码、注释和元数据
• 搜索与发现：查找类、trait、方法、引用和实现者
• 包管理：以 Tonel 格式导出和导入包
• 项目安装：使用 Metacello 安装项目
• 测试执行：在包或类级别运行测试套件
• UI 调试：捕获屏幕截图并检查 World morph、Spec presenter 和 Roassal 可视化的 UI 结构
• 服务配置：动态获取和修改服务设置

前提条件

• Python 3.10 或更高版本
• uv 包管理器
• 已安装 PharoSmalltalkInteropServer 的 Pharo

安装

快速开始（使用 uvx）

无需克隆仓库即可运行服务的最简单方法：

uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server

开发安装

设置开发环境：

1. 克隆仓库：

git clone https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git

2. 使用 uv 安装依赖：

cd pharo-smalltalk-interop-mcp-server
uv sync --dev

使用方法

运行 MCP 服务

使用 uvx（无需安装）：

uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server

使用 uv（克隆仓库后）：

uv run pharo-smalltalk-interop-mcp-server

环境变量

你可以使用环境变量配置服务：

• PHARO_SIS_PORT：PharoSmalltalkInteropServer 的端口号（默认：8086）

示例：

使用 uvx：

PHARO_SIS_PORT=8086 uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server

使用 uv：

PHARO_SIS_PORT=9999 uv run pharo-smalltalk-interop-mcp-server

Cursor MCP 设置

使用 uvx（推荐）：

{
  "mcpServers": {
    "smalltalk-interop": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git",
        "pharo-smalltalk-interop-mcp-server"
      ],
      "env": {
        "PHARO_SIS_PORT": "8086"
      }
    }
  }
}

使用 uv（克隆后）：

{
  "mcpServers": {
    "smalltalk-interop": {
      "command": "uv",
      "args": [
        "--directory",
        "/your-path/to/pharo-smalltalk-interop-mcp-server",
        "run",
        "pharo-smalltalk-interop-mcp-server"
      ],
      "env": {
        "PHARO_SIS_PORT": "8086"
      }
    }
  }
}

注意：env 部分为可选项，可用于为 MCP 服务设置环境变量。

Claude Code 配置

使用 uvx（推荐）：

claude mcp add -s user smalltalk-interop -- uvx --from git+https://github.com/mumez/pharo-smalltalk-interop-mcp-server.git pharo-smalltalk-interop-mcp-server

使用 uv（克隆后）：

claude mcp add -s user smalltalk-interop -- uv --directory /path/to/pharo-smalltalk-interop-mcp-server run pharo-smalltalk-interop-mcp-server

可用的 MCP 工具

此服务提供 22 个 MCP 工具，对应 PharoSmalltalkInteropServer 的所有 API：

代码求值

• eval：执行 Smalltalk 表达式并返回结果

代码内省

• get_class_source：获取类的源代码
• get_method_source：获取特定方法的源代码
• get_class_comment：获取类的注释／文档

搜索与发现

• search_classes_like：查找符合模式的类
• search_methods_like：查找符合模式的方法
• search_traits_like：查找符合模式的 trait
• search_implementors：查找方法选择器的所有实现者
• search_references：查找方法选择器的所有引用
• search_references_to_class：查找类的所有引用

包管理

• list_packages：列出镜像中的所有包
• list_classes：列出特定包中的类
• list_extended_classes：列出包中的扩展类
• list_methods：列出包中的方法
• export_package：以 Tonel 格式导出包
• import_package：从指定路径导入包

项目安装

• install_project：使用 Metacello 安装项目，可选择加载组

测试执行

• run_package_test：运行包的测试套件
• run_class_test：运行特定类的测试套件

UI 调试

• read_screen：用于调试 Pharo 界面的 UI 屏幕读取工具，可提取屏幕截图和结构信息

服务配置

• get_settings：获取当前服务配置
• apply_settings：动态修改服务配置

read_screen 工具

read_screen 工具会捕获屏幕截图并提取 UI 结构，以便调试 Pharo UI 问题。

参数：

• target_type（字符串，默认值：'world'）：要检查的 UI 类型（'world' 表示形态，'spec' 表示窗口，'roassal' 表示可视化内容）
• capture_screenshot（布尔值，默认值：true）：在响应中包含 PNG 屏幕截图

**返回值：**包含屏幕截图和易读摘要的 UI 结构

使用示例：

# Inspect all morphs in World
read_screen(target_type='world')

# Inspect Spec presenter windows
read_screen(target_type='spec', capture_screenshot=false)

# Inspect Roassal visualizations without screenshot (faster)
read_screen(target_type='roassal', capture_screenshot=false)

提取的数据包括：

World（形态）：

• 类名和类型识别信息
• 边界（x、y、宽度、高度坐标）
• 可见状态
• 背景色
• 所有者类
• 子形态数量
• 文本内容（如有）

输出示例：

{
  "totalMorphs": 12,
  "displayedMorphCount": 1,
  "morphs": [
    {
      "class": "MenubarMorph",
      "visible": true,
      "bounds": {"x": 0, "y": 0, "width": 976, "height": 18},
      "backgroundColor": "(Color r: 0.883... alpha: 0.8)",
      "owner": "WorldMorph",
      "submorphCount": 8
    }
  ]
}

Spec（呈现器）：

• 窗口标题和类名
• 几何信息（范围、位置）
• 窗口状态（最大化、最小化、可调整大小）
• 装饰元素（菜单、工具栏、状态栏是否存在）
• 呈现器层级（递归，最大深度为 3 层）
• 呈现器类名、子项数量和内容属性（标签、文本、值等）
• 启用状态和可见状态

输出示例：

{
  "windowCount": 1,
  "presenters": [
    {
      "class": "SpWindowPresenter",
      "title": "Welcome",
      "extent": "(700@550)",
      "hasMenu": false,
      "presenter": {
        "class": "StWelcomeBrowser",
        "childCount": 2,
        "isVisible": true,
        "children": []
      }
    }
  ]
}

Roassal（可视化内容）：

• 画布边界和可见状态
• 画布类识别信息
• 背景色和缩放级别
• 形状详情（颜色、位置、范围、标签、文本）
• 边详情（源、目标、颜色、标签）
• 节点和边的数量

输出示例：

{
  "canvasCount": 1,
  "canvases": [
    {
      "class": "RSAthensMorph",
      "canvasClass": "RSCanvas",
      "bounds": {"x": 203, "y": 145, "width": 490, "height": 467},
      "backgroundColor": "Color blue",
      "zoomLevel": "1.0",
      "shapeCount": 5,
      "shapes": [
        {
          "class": "RSCircle",
          "color": "(Color r: 1.0 g: 0.0 b: 0.0 alpha: 0.2)",
          "position": "([email protected])",
          "extent": "([email protected])"
        }
      ],
      "edgeCount": 0,
      "edges": [],
      "nodeCount": 0
    }
  ]
}

服务配置工具

get_settings 和 apply_settings 工具可用于动态管理服务配置。

get_settings

获取当前服务配置。

**参数：**无

**返回值：**包含当前服务设置的字典

使用示例：

# Get current settings
get_settings()
# Returns: {"stackSize": 100, "customKey": "customValue"}

响应格式：

{
  "success": true,
  "result": {
    "stackSize": 100,
    "customKey": "customValue"
  }
}

apply_settings

动态修改服务配置。设置会在当前会话中立即生效。

参数：

• settings（字典）：包含要修改的设置的字典

**返回值：**成功确认消息

使用示例：

# Apply new settings
apply_settings(settings={"stackSize": 200, "customKey": "customValue"})
# Returns: "Settings applied successfully"

常见设置：

设置	类型	默认值	描述
stackSize	整数	100	错误报告的最大堆栈跟踪深度

**注意：**除已记录的设置外，服务还接受任意键值对，因此可以配置自定义选项。

开发

运行测试

该项目包含全面的单元测试，并采用基于模拟的测试方式，无需运行中的 Pharo 实例：

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_core.py -v

代码质量

# Run linting
uv run ruff check

# Run formatting
uv run ruff format

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

项目结构

pharo-smalltalk-interop-mcp-server/
├── pharo_smalltalk_interop_mcp_server/
│   ├── __init__.py
│   ├── core.py          # HTTP client and core functions
│   └── server.py        # FastMCP server with tool definitions
├── tests/
│   ├── __init__.py
│   ├── test_core.py     # Tests for core HTTP client functionality
│   └── test_server.py   # Tests for MCP server integration
├── pyproject.toml       # Project configuration
├── pytest.ini          # Test configuration
└── README.md

测试策略

测试套件采用基于模拟的测试方式，以确保：

• 无外部依赖：测试无需运行中的 Pharo 实例即可执行
• 全面覆盖：测试涵盖全部 22 个端点和错误场景
• 执行迅速：测试在 1 秒内完成
• 结果可靠：测试结果具有确定性，且不依赖外部状态

测试覆盖范围包括：

• HTTP 客户端功能（PharoClient 类）
• 全部 22 项 Pharo 互操作操作
• 错误处理（连接错误、HTTP 错误、JSON 解析错误）
• MCP 服务初始化和工具注册
• 核心函数与 MCP 工具之间的集成