波束示波器MCP
用于Elixir应用程序的强大MCP（模型上下文协议）服务器。BeamScope使AI编码代理能够通过弹性TCP架构访问正在运行的BEAM应用程序，该架构可以在应用程序重启后幸存下来。
为什么选择BeamScope？
BeamScope旨在解决基于HTTP的MCP服务器（如TideWave）的一个基本问题： 当你的Elixir应用程序重新启动时，连接会断开，无法重新连接.
在以下情况下，这在开发过程中尤其痛苦：
- 跑步
mix compile更改后 - 重新启动应用程序以获取配置更改
- 发生崩溃，触发主管重新启动
BeamScope使用 独立TCP架构 TypeScript桥维护与AI代理的连接，并在Elixir应用程序恢复时自动重新连接。
Traditional HTTP-based MCP (TideWave):
┌─────────────┐ HTTP ┌──────────────────────┐
│ AI Agent │ ──────────────► │ Phoenix Endpoint │ ← Dies when app restarts
└─────────────┘ │ (Plug-based MCP) │
└──────────────────────┘
BeamScope Architecture:
┌─────────────┐ stdio ┌───────────────────┐ TCP ┌─────────────────┐
│ AI Agent │ ─────────────► │ TypeScript │ ──────────► │ Elixir │
│ │ │ Bridge │ reconnects │ GenServer │
└─────────────┘ │ (stays running) │ on restart │ (BeamScope) │
└───────────────────┘ └─────────────────┘设计理念
通用Elixir/BEAM，非特定于框架
BeamScope适用于 任何Elixir应用程序不仅仅是凤凰城。这些工具在整个Elixir生态系统中都很有用：
project_eval--评估正在运行的应用程序中的代码get_logs--通过筛选检索应用程序日志get_docs--访问模块和功能的本地文档
我们有意排除特定于框架的工具（Ecto、Ash、Phoenix），以保持BeamScope的可移植性，并专注于每个BEAM应用程序的共同点。
无默认端口--大声失败
BeamScope具有 堆栈中任何位置都没有默认端口。如果未配置端口，应用程序将在启动时崩溃，并显示一条明确的错误消息，告诉您要在配置中添加什么。
这可以防止出现Elixir应用程序在一个端口上监听而MCP网桥试图在另一个端口连接的令人抓狂的情况。每个端口都必须在这两个位置明确配置。
安装
BeamScope MCP有两个组件：Elixir库（TCP服务器+工具）和TypeScript桥（MCP协议）。两者都在本地运行-- 先克隆仓库，然后将其作为路径依赖项引用。
1.克隆仓库
cd ~/your/projects # or wherever you keep local deps
git clone https://github.com/JediLuke/BeamScope-MCP.git beam_scope_mcp2.添加到您的Elixir项目
将克隆的仓库作为路径依赖引用：
# mix.exs
def deps do
[
{:beam_scope_mcp, path: "../beam_scope_mcp", only: :dev}
]
end将路径调整到相对于项目克隆的位置。
mix deps.get3.配置端口（必填）
# config/config.exs (or config/dev.exs)
config :beam_scope_mcp,
port: 9995,
app_name: "MyApp"允许环境变量覆盖（可选）：
# config/runtime.exs
if port = System.get_env("BEAM_SCOPE_MCP_PORT") do
config :beam_scope_mcp, port: String.to_integer(port)
end4.构建TypeScript桥
cd /path/to/beam_scope_mcp
npm install
npm run build5.配置您的AI编码代理
将BeamScope添加到项目的 .mcp.json:
{
"mcpServers": {
"beam-scope-mcp": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/beam_scope_mcp/dist/index.js"],
"env": { "BEAM_SCOPE_MCP_PORT": "9995" }
}
}
}重要提示： 这 BEAM_SCOPE_MCP_PORT env-var必须与Elixir配置中的端口匹配。如果它丢失，TypeScript桥将立即退出并返回错误。
可用工具（20）
连接
| 工具 | 说明 |
|---|---|
connect_beam_scope_mcp | 建立TCP连接。通过env var预先配置端口 |
get_beam_scope_mcp_status | 检查当前连接状态。 |
核心
| 工具 | 说明 |
|---|---|
get_logs | 带有tail/grep/级别过滤的应用程序日志 |
project_eval | 在运行中的应用程序中评估Elixir代码并超时。 |
get_docs | 模块/功能的本地文档 Code.fetch_docs/1. |
编译
| 工具 | 说明 |
|---|---|
recompile | 从BEAM中重新编译项目。返回错误/警告。 |
reload_module | 从源文件热重新加载单个模块。最快的反馈循环。 |
recompile_deps | 强制重新编译依赖关系。所需参数（例如。 ["--force"]). |
系统与流程反思
| 工具 | 说明 |
|---|---|
get_system_stats | 内存、调度器、进程计数、正常运行时间、IO统计数据。 |
list_processes | 可过滤/可排序的进程列表（按名称、内存、队列大小）。 |
get_process_info | 详细信息：功能、内存、链接、监视器、堆栈跟踪。 |
get_process_state | GenServers的内部状态通过 :sys.get_state/1. |
get_process_dictionary | 处理字典元数据（记录器元数据、标志等）。 |
应用程序和OTP
| 工具 | 说明 |
|---|---|
get_app_config | 运行时应用程序配置（BEAM加载的内容，而不是磁盘上的文件）。 |
get_supervision_tree | 递归OTP监督树遍历。需要应用程序名称。 |
美国教育考试服务中心
| 工具 | 说明 |
|---|---|
list_ets_tables | 所有ETS表，包括大小、内存、类型、保护、所有者。 |
inspect_ets_table | 读取带有行限制和截断的ETS表内容。 |
代码智能
| 工具 | 说明 |
|---|---|
xref_callers | 通过以下方式查找模块或函数的所有调用者 mix xref重构前的影响分析 |
追踪
| 工具 | 说明 |
|---|---|
trace_calls | 跟踪模块上的函数调用。写入文件 /tmp/beam_scope_traces/ --使用文件读取工具读取结果。自动在呼叫/时间限制时停止。 |
stop_trace | 任何运行痕迹的紧急停止。即使没有运行跟踪，也可以安全调用。 |
运行多个应用程序
每个应用程序使用不同的端口：
# App 1: config/config.exs
config :beam_scope_mcp, port: 9995
# App 2: config/config.exs
config :beam_scope_mcp, port: 9994每个应用程序 .mcp.json 通过以下方式传递匹配端口 BEAM_SCOPE_MCP_PORT.
建筑
beam_scope_mcp/
├── lib/
│ ├── beam_scope_mcp.ex # Public API
│ └── beam_scope_mcp/
│ ├── application.ex # OTP Application (fail-loudly port config)
│ ├── server.ex # TCP GenServer + command dispatch
│ ├── log_capture.ex # Logger handler + circular buffer
│ └── tools/
│ ├── logs.ex # get_logs
│ ├── eval.ex # project_eval
│ ├── docs.ex # get_docs
│ ├── recompile.ex # recompile, reload_module, recompile_deps
│ ├── system_stats.ex # get_system_stats
│ ├── processes.ex # list_processes, get_process_info/state/dictionary
│ ├── app_config.ex # get_app_config
│ ├── supervision_tree.ex # get_supervision_tree
│ ├── ets.ex # list_ets_tables, inspect_ets_table
│ ├── xref.ex # xref_callers
│ └── trace.ex # trace_calls, stop_trace (writes to /tmp/beam_scope_traces/)
├── src/
│ ├── index.ts # MCP server entry point
│ ├── connection.ts # TCP connection (requires BEAM_SCOPE_MCP_PORT env var)
│ └── tools.ts # Tool definitions and handlers
└── dist/ # Compiled TypeScript (gitignored)工具选择评估
工具描述经过优化，以便LLM为每个任务选择正确的工具。看 EVAL.md 18个测试场景和结果（17/18通过Claude Opus 4.6）。
从潮汐波迁移
看 MIGRATION_FROM_TIDEWAVE.md 获取分步指南。
许可证
麻省理工学院