Erlang节点调试服务器

Erlang分布式MCP服务器

一种模型上下文协议（MCP）服务器，通过Erlang分发协议连接到Erlang/BEAM节点，为AI助手提供在远程Erlang系统上进行自检、调试、跟踪和代码评估的工具。

特性

• 🔌 动态节点连接：在运行时动态连接到多个Erlang节点
• 🔍 过程反思：列出、搜索和检查流程及其状态
• 📊 系统监控：内存使用率、调度程序利用率、ETS表等
• 🐛 高级调试：堆栈跟踪、消息队列、GenServer状态检查
• 🔬 函数跟踪：使用recon或dbg进行安全生产跟踪
• 🎨 多语言输出：以Erlang、Elixir、Gleam或LFE语法格式化输出
• 🚀 代码评估：执行任意Erlang表达式（带安全防护）
• 🌳 监督树：可视化OTP监督层次结构
• 📦 应用程序管理：列出并检查OTP应用程序

安装

来源（推荐）

git clone https://github.com/jimsynz/erl_dist_mcp.git
cd erl_dist_mcp
cargo build --release

二进制文件将位于 target/release/erl_dist_mcp.

使用货物安装

cargo install erl_dist_mcp

预构建二进制文件

从以下网址下载适用于您平台的最新版本 发布页面.

可用目标：

• Linux: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu
• macOS: x86_64-apple-darwin （英特尔）， aarch64-apple-darwin （苹果硅）
• 视窗: x86_64-pc-windows-msvc

解压缩存档并将二进制文件移动到PATH中的一个目录中：

# Linux/macOS
tar xzf erl_dist_mcp-*.tar.gz
sudo mv erl_dist_mcp /usr/local/bin/

# Windows (PowerShell)
Expand-Archive erl_dist_mcp-*.zip
Move-Item erl_dist_mcp.exe C:\Windows\System32\

平台特定注意事项

macOS：首次运行时，您可能会看到安全警告。右键单击二进制文件并选择“打开”以绕过Gatekeeper，或运行：

xattr -d com.apple.quarantine /usr/local/bin/erl_dist_mcp

视窗：您可能需要将二进制位置添加到PATH环境变量中。

Linux（ARM）：The aarch64 构建需要glibc 2.27或更高版本（Ubuntu 18.04+，Debian 10+）。

验证

安装后，验证二进制文件是否正常工作：

erl_dist_mcp --version

您应该看到如下输出：

erl_dist_mcp 0.1.0

测试帮助输出：

erl_dist_mcp --help

快速开始

1.启动Erlang节点

首先，启动一个启用了分发的Erlang节点：

# Erlang
erl -sname test -setcookie mycookie

# Elixir
iex --sname test --cookie mycookie

# Gleam (with Erlang runtime)
gleam run -- --name test --cookie mycookie

2.配置克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "erlang": {
      "command": "/path/to/erl_dist_mcp",
      "args": ["--mode", "elixir", "--allow-eval"],
      "env": {}
    }
  }
}

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

3.使用Claude

启动Claude Desktop并尝试：

Connect to my local Elixir node at test@localhost with cookie mycookie

List all processes on the node sorted by memory usage

Show me the supervision tree for the main application

CLI参考

erl_dist_mcp [OPTIONS]

Options:
  --mode <MODE>           Output format mode [default: elixir]
                          Values: erlang, elixir, gleam, lfe

  --allow-eval            Enable code evaluation tools (rpc_call, eval_code)
                          WARNING: Only use with trusted nodes

  --log-level <LEVEL>     Set logging level [default: info]
                          Values: trace, debug, info, warn, error

  -h, --help              Print help information
  -V, --version           Print version information

输出模式

这 --mode flag控制Erlang术语的格式：

• Erlang：标准Erlang语法（例如。， {ok, Value}, #{key => value})
• 灵药：Elixir惯用语法（例如。， {:ok, value}, %{key: value})
• 微光：类似Gleam的语法（例如。， Ok(value), #(tuple, elements))
• 低频扩展：Lisp风味二郎（例如。， #(ok value), #m(key value))

您可以在运行时使用以下命令更改模式 set_mode 工具。

不同编辑器的配置

克劳德桌面

请参阅上面的快速入门部分。

光标

添加到光标MCP设置(.cursor/mcp.json 或光标设置）：

{
  "mcpServers": {
    "erlang": {
      "command": "/path/to/erl_dist_mcp",
      "args": ["--mode", "elixir"],
      "env": {}
    }
  }
}

Continue.dev

增添 ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "erlang",
      "command": "/path/to/erl_dist_mcp",
      "args": ["--mode", "elixir"]
    }
  ]
}

Cline（VS代码）

添加到“临床：MCP服务器”下的VS代码设置：

{
  "erl_dist_mcp": {
    "command": "/path/to/erl_dist_mcp",
    "args": ["--mode", "elixir"]
  }
}

可用工具

连接管理

过程检查

OTP和GenServer

系统信息

ETS表格

跟踪与调试

模块信息

代码评估（受限）

安全注意事项

这 --allow-eval 旗帜

⚠️ 重要： 这 --allow-eval flag启用了强大但危险的工具，可以在连接的节点上执行任意代码：

• rpc_call：可以使用任何参数调用远程节点上的任何函数
• eval代码：可以计算任意Erlang表达式

仅启用 --allow-eval 什么时候：

• 您完全信任AI助手及其指示
• 您正在连接到开发/测试节点，而不是生产节点
• 您了解安全影响
• 您已经查看了将执行的代码

缓解策略：

1. 不使用 --allow-eval 在生产环境中
2. 使用网络防火墙 限制可以访问哪些节点
3. 使用Erlang Cookie 作为共享密钥身份验证机制
4. 审查生成的代码 在允许执行之前
5. 在专用调试节点上运行 与生产系统分开

Erlang分发安全

Erlang分发协议使用共享密钥（cookie）进行身份验证：

• 安全地存储Cookie：不要将它们提交给版本控制
• 使用强Cookie：长的随机字符串（不是“mycookie”）
• 定期轮换Cookie 在生产环境中
• 限制网络访问：使用防火墙限制谁可以连接
• 监控连接：注意意外的连接尝试

代码评估安全(eval_code 工具）

这 eval_code 该工具包括安全机制：

• 流程级沙盒：评估在资源有限的单独过程中进行
• 堆大小限制：防止内存耗尽
• 超时：防止无限循环
• 低优先级：减少对系统性能的影响
• 功能白名单：只允许安全操作（算术、比较、列表/映射操作）
• 阻止危险操作：无文件I/O、网络、进程生成或代码加载

注： 这些安全机制不是一个完整的沙盒。熟练的攻击者可能会找到绕过限制的方法。仅在您控制的节点上使用。

故障排除

“节点无法访问”或“EPMD查找失败”

问题： 无法连接到Erlang节点。

解决：

1. 验证节点是否正在运行: epmd -names 应该列出您的节点
2. 检查节点名称格式：应该是 name@host （例如。， test@localhost)
3. 检查EPMD端口：确保端口4369未堵塞
4. 检查分配端口：节点的分发端口必须可访问
5. 验证主机名解析: ping localhost 应该可以

“节点身份验证失败”

问题： 客户端和服务器之间的Cookie不匹配。

解决：

1. 检查服务器上的cookie：在Erlang运行中 erlang:get_cookie()，在Elixir运行 Node.get_cookie()
2. 在连接命令中检查cookie：必须完全匹配
3. 检查 .erlang.cookie 文件：位于Unix系统的主目录中
4. 明确设置cookie：使用 -setcookie 启动节点时标记

操作中“连接丢失”

问题： 网络中断或节点崩溃。

解决：

1. 检查节点是否仍处于活动状态：使用 epmd -names 或者试试 ping
2. 重新连接：使用 connect_node 工具再次
3. 检查节点是否重新启动：应用程序崩溃可能会重新启动节点
4. 查看错误日志：检查客户端和服务器日志

“工具需要--允许eval标志”

问题： 尝试使用 rpc_call 或 eval_code 未经许可。

解决：

1. 使用标志重新启动服务器：添加 --allow-eval 命令参数
2. 更新配置：将标志添加到Claude Desktop配置或光标设置中
3. 考虑安全性：启用前审查安全影响

“未加载模块：mcp_eval_helper”

问题： 这 eval_code 该工具要求目标节点上有一个辅助模块。

解决：

1. 部署助手模块:

   复制

   cd /path/to/erl_dist_mcp
   # Copy to target node
   scp erlang/mcp_eval_helper.erl user@targethost:/tmp/
   
   # On target node (Erlang shell):
   c("/tmp/mcp_eval_helper").
   

2. 验证模块是否已加载:

   复制

   % Erlang
   code:which(mcp_eval_helper).
   
   # Elixir
   :code.which(:mcp_eval_helper)
   

内存使用率高或响应慢

问题： 服务器消耗太多资源。

解决：

1. 降低跟踪限制：使用时降低max_traces start_trace
2. 避免大型消息队列：不要使用 get_message_queue 关于消息数超过1000的进程
3. 限制ETS采样：使用小限制 sample_ets_table
4. 检查工艺限制：确保节点有足够的资源
5. 启用流媒体：一些工具支持流式传输大型结果集

“意外响应格式”错误

问题： 工具从Erlang节点接收到格式异常的数据。

解决：

1. 检查Erlang/OTP版本：某些功能需要特定版本
2. 验证节点类型：确保您已连接到Erlang/BEAM节点
3. 报告问题：这可能是一个错误-请提交一个包含详细信息的问题

例子

连接和基本检查

Connect to test@localhost with cookie mycookie

List all processes sorted by memory

Show the top 5 processes by reductions

调试特定进程

Find processes with registered name "my_server"

Get the full process info for <0.123.0>

Show me the stack trace for that process

Get the GenServer state for <0.123.0>

监控系统健康状况

Show me the memory breakdown for the node

Get the scheduler usage (CPU utilisation)

List all ETS tables sorted by memory usage

Show system info - how close are we to process limits?

调查申请

List all running applications

Get detailed info for the "myapp" application

Show the supervision tree starting from myapp_sup

跟踪函数调用

Start tracing calls to my_module:my_function/2 with max 100 traces

Get the trace results

Stop the trace

使用不同的输出模式

Set mode to erlang

Show me the process info for <0.123.0>

Set mode to gleam

Show me that again

发展

建筑

cargo build

运行测试

cargo test

掉毛

cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check

本地运行

cargo run -- --mode elixir --allow-eval --log-level debug

建筑

服务器由几个关键组件组成：

• 连接管理器：管理多个Erlang节点连接
• RPC层：通过rex进程处理远程过程调用
• 格式化工具：将Erlang术语转换为特定语言的语法
• 跟踪管理器：管理功能跟踪会话
• MCP服务器：通过模型上下文协议公开工具

关键设计决策：

• 与运行时无关的erl_dist：使用futures_io特性，通过适配器与tokio运行时配合使用
• 后台连接任务：每个节点连接都在自己的tokio任务中运行
• 基于特征的格式化：适用于不同BEAM语言的可插拔格式化程序
• 全面的错误处理：所有错误都包括上下文信息

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 通过测试进行更改
4. 确保所有测试通过(cargo test)
5. 确保clippy满意(cargo clippy --all-targets --all-features -- -D warnings)
6. 设置代码格式(cargo fmt)
7. 提交您的更改(git commit -m 'feat: add amazing feature')
8. 推到分支(git push origin feature/amazing-feature)
9. 打开拉取请求

许可证

此项目根据Apache许可证2.0版获得许可——请参阅 许可证 文件以获取详细信息。

致谢

• erl_dist -Erlang分发协议客户端
• rmcp -模型上下文协议服务器框架
• 侦察 -Erlang/OTP生产调试工具
• 模型上下文协议 -协议规范