erl dist MCP

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            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      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").

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

   % 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 

Show me the stack trace for that process

Get the GenServer state for 

监控系统健康状况

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 

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生产调试工具
• 模型上下文协议 -协议规范