Scenic MCP - Input Control for Scenic Applications

Scenic MCP

适用于 Scenic GUI 应用的 Model Context Protocol（MCP）服务

版本：1.0.0

让 AI 助手通过键盘输入、鼠标控制和视觉反馈与 Scenic GUI 应用交互。非常适合自动化测试、AI 驱动的开发工作流和无障碍工具。

功能

• 🎹 键盘输入 - 发送文本和特殊按键，支持修饰键（Ctrl、Shift、Alt、Cmd）
• 🖱️ 鼠标控制 - 移动光标并在指定坐标单击
• 🎯 语义交互 - 使用语义标记而非仅凭原始坐标来单击特定组件
• 📸 视觉反馈 - 检查视口结构并捕获屏幕截图
• 🤖 MCP 集成 - 适用于 Claude Desktop、Claude Code 和其他 MCP 客户端

快速开始

1. 添加到 Scenic 应用的 mix.exs

请注意，目前尚未实际发布到 hex，因此需要先克隆项目并将其作为本地依赖添加。

defp deps do
  [
    {:scenic_mcp, "../scenic_mcp"}
  ]
end

2. 配置视口和驱动程序

Scenic MCP 需要命名的视口和驱动程序进程。更新监督树：

# In your application.ex
def start(_type, _args) do
  children = [
    {Scenic, scenic_viewport_config()}
  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end

defp scenic_viewport_config do
  [
    name: :main_viewport,  # Required!
    size: {800, 600},
    default_scene: MyApp.RootScene,
    drivers: [
      [
        name: :scenic_driver,  # Required!
        module: Scenic.Driver.Local,
        window: [title: "My App"],
        on_close: :stop_system
      ]
    ]
  ]
end

请注意，此处的 name 定义了一个原子，它将成为 ViewPort 和 Driver 进程的注册进程名。为了与 ViewPort 交互，我们需要知道该进程的 pid 才能找到它。我们的解决方案是查找特定名称 main_viewport，因此必须按上方所示在配置中设置此名称，ScenicMCP 才能正常工作。

视口名称：:main_viewport 驱动程序名称：:scenic_driver

可选：自定义进程名称

如果需要使用不同的进程名称，请进行配置：

# config/config.exs
config :scenic_mcp,
  viewport_name: :my_custom_viewport,
  driver_name: :my_custom_driver,
  port: 9999

3. 安装 TypeScript 依赖项

cd scenic_mcp
npm install
npm run build

4. 配置 Claude Code 或 Claude Desktop

使用 Claude Code CLI（推荐）

claude mcp add scenic-mcp /path/to/scenic_mcp/dist/index.js
claude mcp list  # Verify installation

手动配置

编辑 ~/.claude.json：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "scenic-mcp": {
          "type": "stdio",
          "command": "/path/to/scenic_mcp/dist/index.js",
          "args": [],
          "env": {}
        }
      }
    }
  }
}

可选：配置 Tidewave MCP

Tidewave 为 Elixir/Phoenix 应用提供运行时内省功能（日志、SQL 查询、代码求值、文档）。如果项目中包含 Tidewave（Flamelex/Quillex 包含），可以将其与 Scenic MCP 一起添加。

使用 Claude Code CLI：

TIDEWAVE_PORT=4000  # Change to your app's port
claude mcp add --transport http tidewave http://localhost:$TIDEWAVE_PORT/tidewave/mcp

手动配置：

将以下内容添加到 ~/.claude.json 中相同的项目配置：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "scenic-mcp": {
          "type": "stdio",
          "command": "/path/to/scenic_mcp/dist/index.js",
          "args": [],
          "env": {}
        },
        "tidewave": {
          "type": "http",
          "url": "http://localhost:$TIDEWAVE_PORT/tidewave/mcp"
        }
      }
    }
  }
}

将 $TIDEWAVE_PORT 替换为应用的 HTTP 端口（例如，Phoenix 默认端口为 4000）。

5. 启动 Scenic 应用

cd your_scenic_app
iex -S mix

你应该会看到：

✅ ScenicMCP successfully started on port 9999

用法

可用工具

连接与状态

• connect_scenic - 连接到正在运行的 Scenic 应用
• get_scenic_status - 检查连接状态和服务信息

用户输入

• send_keys - 发送键盘输入（文本、特殊按键、修饰键）
• send_mouse_move - 将光标移动到指定坐标
• send_mouse_click - 在指定坐标单击（左键／右键／中键）

视觉反馈

• inspect_viewport - 获取视口结构的文本描述
• take_screenshot - 捕获 PNG 屏幕截图（路径或 base64）

示例

文本输入

send_keys({ text: "Hello, World!" })

特殊按键

send_keys({ key: "enter" })
send_keys({ key: "escape" })
send_keys({ key: "tab" })

键盘快捷键

send_keys({ key: "s", modifiers: ["ctrl"] })      // Ctrl+S (Save)
send_keys({ key: "c", modifiers: ["cmd"] })       // Cmd+C (Copy on Mac)
send_keys({ key: "z", modifiers: ["ctrl", "shift"] })  // Ctrl+Shift+Z (Redo)

鼠标控制

send_mouse_move({ x: 100, y: 200 })
send_mouse_click({ x: 150, y: 250, button: "left" })
send_mouse_click({ x: 300, y: 100, button: "right" })  // Right-click

视觉检查

inspect_viewport()  // Get component structure

take_screenshot({ format: "path" })  // Save to /tmp
take_screenshot({
  filename: "app_state.png",
  format: "base64"  // Get base64 data
})

架构

AI Agent (Claude Desktop/Code)
    ↓ stdio
TypeScript MCP Server (this package)
    ↓ TCP (port 9999)
Elixir GenServer (ScenicMcp.Server)
    ↓ function calls
Scenic Driver Process
    ↓ input events
Your Scenic Application

工作原理

1. TypeScript MCP 服务 通过 stdio 处理 MCP 协议
2. TCP 桥接 与 Elixir 保持持久连接
3. Elixir GenServer 通过 TCP 接收 JSON 命令
4. 工具处理程序 与 Scenic 视口和驱动程序交互
5. 驱动程序 将输入事件注入应用

配置

可用选项

# config/config.exs
config :scenic_mcp,
  # TCP port for MCP server (default: 9999)
  port: 9999,

  # Viewport process name (default: :main_viewport)
  viewport_name: :main_viewport,

  # Driver process name (default: :scenic_driver)
  driver_name: :scenic_driver,

  # Application name for logging (default: "Unknown")
  app_name: "MyApp"

多个 Scenic 应用

如果运行多个 Scenic 应用，请配置不同的端口：

# In flamelex/config/config.exs
config :scenic_mcp, port: 9999, app_name: "Flamelex"

# In quillex/config/config.exs
config :scenic_mcp, port: 9997, app_name: "Quillex"

# In your_test/config/test.exs
config :scenic_mcp, port: 9996, app_name: "Test"

连接到指定端口：

connect_scenic({ port: 9997 })  // Connect to Quillex

开发

构建 TypeScript

npm run build       # One-time build
npm run dev         # Watch mode for development

打包以供分发

npm run bundle      # Copies dist/* to priv/mcp_server/

运行测试

# Elixir tests
mix test

# Test specific file
mix test test/scenic_mcp/server_test.exs

项目结构

scenic_mcp/
├── lib/
│   ├── scenic_mcp.ex           # Module documentation
│   └── scenic_mcp/
│       ├── application.ex      # OTP application
│       ├── config.ex           # Configuration management
│       ├── server.ex           # TCP server (GenServer)
│       └── tools.ex            # Tool handlers
├── src/
│   ├── index.ts                # MCP server entry point
│   ├── connection.ts           # TCP connection management
│   └── tools.ts                # Tool definitions
├── test/
│   └── scenic_mcp/
│       └── server_test.exs     # Integration tests
└── dist/                       # Compiled TypeScript

故障排除

MCP 服务无法连接

错误： MCP 服务无法连接，或 Claude Code/Desktop 中的工具不可用

解决方案： 编译后的 dist/index.js 文件必须具有可执行权限。TypeScript 编译不会保留可执行权限，即使源文件具有该权限也是如此。

修复方法：

chmod +x /path/to/scenic_mcp/dist/index.js

自动修复： 现在，构建脚本会自动将文件设为可执行。如果你在添加此修复之前已完成构建，可以：

1. 再次运行 npm run build（推荐）
2. 手动运行 chmod +x dist/index.js

修复后，重启 Claude Code 或开始新的对话，使更改生效。

端口已被占用

错误： Port 9999 is already in use!

解决方案： 在 config.exs 中配置其他端口：

config :scenic_mcp, port: 9998

找不到视口

错误： Unable to find Scenic viewport process ':main_viewport'

解决方案：

1. 确保视口已命名：在 Scenic 配置中设置 name: :main_viewport
2. 或配置预期的名称：config :scenic_mcp, viewport_name: :your_name
3. 确认 Scenic 应用正在运行：Process.whereis(:main_viewport)

找不到驱动程序

错误： Unable to find Scenic driver process ':scenic_driver'

解决方案：

1. 确保驱动程序已命名：在驱动程序配置中设置 name: :scenic_driver
2. 或配置预期的名称：config :scenic_mcp, driver_name: :your_name
3. 检查驱动程序是否已启动：Process.whereis(:scenic_driver)

连接超时

错误： Command timeout after 5000ms

解决方案：

1. 检查 Scenic 应用是否正在运行
2. 确认端口正确：connect_scenic({ port: YOUR_PORT })
3. 检查防火墙设置（应允许访问 localhost:9999）

测试失败

如果测试因连接错误而失败：

1. 确保没有其他应用占用测试端口（9996-9998）
2. 使用以下命令运行测试：mix test --trace，以查看详细输出
3. 检查 scenic_driver_local 依赖项是否已正确编译

安全注意事项

⚠️ 重要安全说明：

• Scenic MCP 仅绑定到 localhost，无法从外部网络访问
• 没有身份验证——任何能够本地访问的人都可以控制你的应用
• 仅适用于开发和测试环境
• 不要将 TCP 端口（9999）暴露给不可信网络
• 未采取额外安全措施时，不要在生产环境中使用

详细的安全指南请参阅 SECURITY.md。

集成指南

请参阅 docs/INTEGRATION.md，了解分步集成说明，包括：

• 将 Scenic MCP 添加到现有应用
• 常见模式和最佳实践
• 测试策略
• 示例实现

API 参考

错误处理

所有工具函数都会返回一致的错误结构：

{
  "error": "Descriptive error message with context and potential solutions"
}

成功响应包含 status 字段：

{
  "status": "ok",
  "message": "Operation completed successfully",
  ...additional data...
}

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保 mix test 通过
5. 提交拉取请求

要求

• Elixir ~> 1.14
• Erlang/OTP 24+
• Node.js >= 18.0
• Scenic ~> 0.11
• Claude Desktop 或 Claude Code（作为 MCP 客户端）

许可证

MIT 许可证——详情请参阅 LICENSE

相关项目

• Scenic - 面向 Elixir 的 2D UI 框架
• MCP - 模型上下文协议规范
• Tidewave - Elixir/Phoenix MCP 工具

更新日志

版本历史请参阅 CHANGELOG.md。

支持

• 报告错误：GitHub Issues
• 文档：此 README 和 docs/
• 示例：请参阅 examples/ 目录

---

为 Elixir 和 Scenic 社区倾心打造 ❤️