Scenic MCP

风景MCP

用于Scenic GUI应用程序的模型上下文协议（MCP）服务器

版本：1.0.0

使AI助手能够与 风景优美的 通过键盘输入、鼠标控制和视觉反馈的GUI应用程序。非常适合自动化测试、人工智能驱动的开发工作流程和可访问性工具。

特性

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

快速开始

1.添加到您的Scenic应用程序 mix.exs

请注意，这实际上还没有发布到十六进制，因此您现在需要克隆它并将其添加为本地dep。

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进程的注册进程名称的原子。为了找到这个进程的pid以便与ViewPort交互，我们需要知道这一点，我们的解决方案是寻找这个特定的名称 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 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 do），您可以将其添加到Scenic MCP旁边。

使用克劳德代码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端口（例如。， 4000 Phoenix违约）。

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应用程序，请配置唯一端口：

# 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/Desk中不可用

解决方案： 编译 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. 确保您的视口命名为： name: :main_viewport 在Scenic配置中
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 依赖关系已正确编译

安全考虑

⚠️ 重要安全注意事项：

• 风景MCP绑定 localhost 仅限-无法从外部网络访问
• 无身份验证 -任何具有本地访问权限的人都可以控制您的应用程序
• 旨在 仅限开发和测试环境
• 不要将TCP端口（9999）暴露给不受信任的网络
• 未采取额外安全措施，不得在生产中使用

看 安全.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. 复刻仓库
2. 创建要素分支
3. 添加新功能的测试
4. 确保 mix test 通过
5. 提交拉取请求

需求

• 灵丹妙药~>1.14
• Erlang/OTP 24+
• Node.js>=18.0
• 风景~>0.11
• 克劳德桌面或克劳德代码（适用于MCP客户端）

许可证

MIT许可证-请参阅 许可证 详情

相关项目

• 风景优美的 -Elixir的2D UI框架
• 主控程序 -模型上下文协议规范
• 潮汐波 -Elixir/Phoenix MCP工具

更新日志

看 更改日志.md 版本历史。

支持

• 报告错误：
• 文档：此README和 docs/
• 示例：参见 示例/ 目录

______________________________________________________________________

由...制作❤️ 为Elixir和Scenic社区