CLI Bridge

VisualWorks Smalltalk CLI桥

一个TCP网桥，通过简单的基于线路的协议公开VisualWorks Smalltalk代码浏览和评估功能。包括一个MCP（模型上下文协议）服务器，用于与Claude Code集成。

特性

• 浏览类、方法和层次结构
• 读取源代码（如果可用）
• 创建类 和 编辑方法 具有单层撤消支持
• 计算任意Smalltalk表达式
• 查找选择器的发送者和实施者
• 分析编译的方法（发送的消息、引用的文本）
• 适用于已部署的图像（反射不需要任何源）

快速开始

自动设置

安装脚本安装依赖项，配置服务器连接，并使用Claude Code注册MCP服务器：

bun setup.ts

它将引导您通过：

1. 安装Node.js依赖项
2. 配置要连接到的VisualWorks映像(~/.config/clibridge/servers.json)
3. 使用Claude Code注册MCP服务器
4. 测试与图像的连接

在VisualWorks中启动CliBridge

"File in the code"
(Filename named: '/path/to/CliBridge.st') fileIn.

"Start without auth (local development)"
CliBridge startOn: 9999.

"Start with authentication (production/remote access)"
CliBridge startWithAuthOn: 9999.
"Prints API key to Transcript - copy this to your MCP config"

或者从命令行参数开始：

./vwlinuxx86_64gui myimage.im -clibridge:9999

然后重新启动Claude Code以启动MCP服务器。

手动设置

如果你更喜欢手动设置（或者没有面包）：

npm install

claude mcp add -s user -t stdio \
  -e CLIBRIDGE_CONFIG=~/.config/clibridge/servers.json \
  visualworks -- node /absolute/path/to/vw_mcp_server.js

看 配置 下面是servers.json格式。

配置

多图像配置（推荐）

创建一个配置文件来管理多个Smalltalk映像：

~/.config/clibridge/servers.json 或 ~/.clibridge/servers.json:

{
  "servers": {
    "local": {
      "host": "localhost",
      "port": 9999
    },
    "production": {
      "host": "prod-server.example.com",
      "port": 9999,
      "apiKey": "vw_abc123..."
    },
    "staging": {
      "host": "staging.example.com",
      "port": 9999,
      "apiKey": "vw_def456..."
    }
  },
  "default": "local"
}

然后添加MCP服务器：

claude mcp add --transport stdio visualworks \
  --env CLIBRIDGE_CONFIG=~/.config/clibridge/servers.json \
  -- node /path/to/cli-bridge/vw_mcp_server.js

所有工具都接受可选 image 针对特定服务器的参数：

mcp__visualworks__classes({ pattern: "Http" })                  # uses default
mcp__visualworks__classes({ pattern: "Http", image: "production" })  # uses production
mcp__visualworks__list_images()                                 # shows all servers

遗留环境变量（单服务器）

对于简单的设置，您可以使用环境变量：

项目级配置（.mcp.json）

对于团队共享，请创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "visualworks": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/cli-bridge/vw_mcp_server.js"],
      "env": {
        "CLIBRIDGE_CONFIG": "/path/to/servers.json"
      }
    }
  }
}

可用工具

所有工具都接受可选 image 参数，用于从配置中定位特定服务器。

协议

CliBridge使用简单的基于线路的TCP协议：

请求： COMMAND [args...]\n 答复： {"status":"ok","data":...}\n 或 {"status":"error","message":"..."}\n

命令

PING                          → "pong"
CLASSES [pattern]             → ["ClassName", ...]
CLASS className               → {name, superclass, instanceVariables, ...}
METHODS className [class|instance] → ["selector", ...]
SOURCE className selector     → "source code..."
FULLSOURCE className          → "all methods..."
HIERARCHY className           → {class, superclasses, subclasses}
EVAL expression               → {result, class}
NAMESPACES                    → ["Namespace", ...]
SEARCH pattern                → [{type, name/class, selector}, ...]
SENDERS selector              → [{class, selector}, ...]
IMPLEMENTORS selector         → [{class, side}, ...]
MESSAGES className selector   → {messages, literals}
EDIT className selector side base64Source → {class, selector, side, wasNew}
UNDO className selector side  → {restored, class, selector, side}
CREATECLASS base64JsonPayload → {created, name, superclass, category}

编辑协议注释

这 EDIT 命令使用Base64编码源来处理多行方法：

• side：“实例”或“类”
• base64Source：完整的方法源，包括签名行，Base64编码
• 以前的版本会自动保存以进行单级撤消
• 使用后撤销被清除（仅限单层）

创建类协议

这 CREATECLASS 命令使用Base64编码的JSON有效载荷：

{
  "name": "MyClass",
  "superclass": "Object",
  "instanceVariables": ["foo", "bar"],
  "classVariables": ["SharedState"],
  "classInstanceVariables": [],
  "category": "MyApp-Model"
}

• 如果类已存在，则失败
• 除以下字段外的所有字段 name 是可选的

CLI包装器（vwcli）

包含一个bash包装器用于命令行使用：

# Set port
export VWCLI_PORT=9999

# Test connection
./vwcli ping

# List classes matching pattern
./vwcli classes Servlet

# Get class info
./vwcli class HttpServlet

# Get method source
./vwcli source GetVersionServlet doGet:response:

# Evaluate expression
./vwcli eval "Date today"

# Find senders
./vwcli senders restorePartQuarry:

# Find implementors
./vwcli implementors doGet:response:

文件

需求

• VisualWorks Smalltalk 8.x或9.x
• Node.js 18+（用于MCP服务器运行时）
• 包子 （用于设置脚本——如果手动设置，则可选）
• 克劳德代码（用于MCP集成）

认证

CliBridge支持用于远程访问的可选API密钥身份验证。

启用身份验证（Smalltalk端）

"Start with authentication required"
CliBridge startWithAuthOn: 9999.

"API key is auto-generated and saved to ~/.clibridge/api-key"
"Also printed to Transcript for copying to your MCP config"

API关键在于：

• 首次生成一次 startWithAuthOn: 呼叫
• 坚持 ~/.clibridge/api-key
• 打印到成绩单上，以便您复制
• 可以被覆盖 CLIBRIDGE_API_KEY 环境变量（对EC2/SSM有用）

认证协议

启用身份验证后，客户端必须在命令前加上 AUTH:key:

AUTH:vw_abc123 PING
AUTH:vw_abc123 CLASSES Array

如果没有auth前缀，您将收到：

{"status":"error","code":"AUTH_REQUIRED","message":"Authentication required"}

安全须知

• startOn: -无需授权，适合本地开发
• startWithAuthOn: -所有连接都需要身份验证
• eval 命令执行任意代码-谨慎使用
• edit 命令修改运行映像中的代码-更改是即时的
• API密钥以明文传输-对于不受信任的网络，使用SSH隧道或VPN

故障排除

连接被拒绝：

• 确保CliBridge正在运行： CliBridge default 应该返回实例
• 检查端口： CliBridge default port

连接超时：

• 验证主机/端口设置
• 检查防火墙是否允许端口

无可用来源：

• 一些部署的映像不包括源代码
• 使用 messages 分析编译方法的工具

端口已在使用中：

• 等待约30秒以清除TIME_Wait
• 或者使用其他端口

许可证

麻省理工学院