BeamScope MCP

BeamScope MCP

A robust MCP (Model Context Protocol) server for Elixir applications. BeamScope gives AI coding agents access to your running BEAM application through a resilient TCP architecture that survives app restarts.

Why BeamScope?

BeamScope was built to solve a fundamental problem with HTTP-based MCP servers like TideWave: when your Elixir app restarts, the connection dies and doesn't reconnect.

This is particularly painful during development when you're:

• Running mix compile after making changes
• Restarting your app to pick up config changes
• Experiencing crashes that trigger supervisor restarts

BeamScope uses a standalone TCP architecture where a TypeScript bridge maintains the connection to your AI agent and automatically reconnects when the Elixir app comes back up.

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)    │
                               └───────────────────┘              └─────────────────┘

Design Philosophy

Generic Elixir/BEAM, Not Framework-Specific

BeamScope works with any Elixir application, not just Phoenix. The tools are useful across the entire Elixir ecosystem:

• project_eval — Evaluate code in your running application
• get_logs — Retrieve application logs with filtering
• get_docs — Access local documentation for modules and functions

We intentionally excluded framework-specific tools (Ecto, Ash, Phoenix) to keep BeamScope portable and focused on what every BEAM app has in common.

No Default Ports — Fail Loudly

BeamScope has no default port anywhere in the stack. If the port isn't configured, the app crashes at startup with a clear error message telling you exactly what to add to your config.

This prevents the maddening situation where your Elixir app is listening on one port and the MCP bridge is trying to connect on another. Every port must be explicitly configured in both places.

Installation

BeamScope MCP has two components: an Elixir library (TCP server + tools) and a TypeScript bridge (MCP protocol). Both run locally — clone the repo first, then reference it as a path dependency.

1. Clone the repo

cd ~/your/projects  # or wherever you keep local deps
git clone https://github.com/JediLuke/BeamScope-MCP.git beam_scope_mcp

2. Add to your Elixir project

Reference the cloned repo as a path dependency:

# mix.exs
def deps do
  [
    {:beam_scope_mcp, path: "../beam_scope_mcp", only: :dev}
  ]
end

Adjust the path to wherever you cloned it relative to your project.

mix deps.get

3. Configure the port (required)

# config/config.exs (or config/dev.exs)
config :beam_scope_mcp,
  port: 9995,
  app_name: "MyApp"

Optionally allow env var override:

# config/runtime.exs
if port = System.get_env("BEAM_SCOPE_MCP_PORT") do
  config :beam_scope_mcp, port: String.to_integer(port)
end

4. Build the TypeScript bridge

cd /path/to/beam_scope_mcp
npm install
npm run build

5. Configure your AI coding agent

Add BeamScope to your project's .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" }
    }
  }
}

Important: The BEAM_SCOPE_MCP_PORT env var must match the port in your Elixir config. If it's missing, the TypeScript bridge will exit immediately with an error.

Available Tools (20)

Connection

| Tool | Description | |------|-------------| | connect_beam_scope_mcp | Establish TCP connection. Port pre-configured via env var. | | get_beam_scope_mcp_status | Check current connection status. |

Core

| Tool | Description | |------|-------------| | get_logs | Application logs with tail/grep/level filtering. | | project_eval | Evaluate Elixir code in the running app with timeout. | | get_docs | Local documentation for modules/functions via Code.fetch_docs/1. |

Compilation

| Tool | Description | |------|-------------| | recompile | Recompile the project from within the BEAM. Returns errors/warnings. | | reload_module | Hot-reload a single module from its source file. Fastest feedback loop. | | recompile_deps | Force recompile dependencies. Args required (e.g. ["--force"]). |

System & Process Introspection

| Tool | Description | |------|-------------| | get_system_stats | Memory, schedulers, process counts, uptime, IO stats. | | list_processes | Filterable/sortable process listing (by name, memory, queue size). | | get_process_info | Detailed info: function, memory, links, monitors, stacktrace. | | get_process_state | Internal state of GenServers via :sys.get_state/1. | | get_process_dictionary | Process dictionary metadata (Logger metadata, flags, etc.). |

Application & OTP

| Tool | Description | |------|-------------| | get_app_config | Runtime application config (what the BEAM has loaded, not files on disk). | | get_supervision_tree | Recursive OTP supervision tree walk. App name required. |

ETS

| Tool | Description | |------|-------------| | list_ets_tables | All ETS tables with size, memory, type, protection, owner. | | inspect_ets_table | Read ETS table contents with row limits and truncation. |

Code Intelligence

| Tool | Description | |------|-------------| | xref_callers | Find all callers of a module or function via mix xref. Impact analysis before refactoring. |

Tracing

| Tool | Description | |------|-------------| | trace_calls | Trace function calls on a module. Writes to file in /tmp/beam_scope_traces/ — read results with your file reading tools. Auto-stops at call/time limit. | | stop_trace | Emergency stop for any running trace. Safe to call even if no trace is running. |

Running Multiple Applications

Each application uses a different port:

# App 1: config/config.exs
config :beam_scope_mcp, port: 9995

# App 2: config/config.exs
config :beam_scope_mcp, port: 9994

Each app's .mcp.json passes the matching port via BEAM_SCOPE_MCP_PORT.

Architecture

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)

Tool Selection Eval

Tool descriptions are optimized so LLMs select the correct tool for each task. See EVAL.md for 18 test scenarios and results (17/18 pass on Claude Opus 4.6).

Migrating from TideWave

See MIGRATION_FROM_TIDEWAVE.md for a step-by-step guide.

License

MIT