NervesMCP (NervesMCP v0.1.0)

Copy Markdown View Source

MCP Server for interacting with Nerves devices.

Running the Server

Start with mix nerves_mcp, or with iex -S mix when a connection is configured.

The MCP server will be available at: http://localhost:13000/mcp

Configuration

Configure in your config/config.exs:

HTTP Server Port

config :nerves_mcp, :port, 13000

The server only accepts connections from this machine. To listen on every interface, on a network you trust:

config :nerves_mcp, :ip, :any

UART (Serial) Connection

config :nerves_mcp, :connection,
  type: :uart,
  port: "/dev/ttyUSB2",
  speed: 115_200

SSH Connection

config :nerves_mcp, :connection,
  type: :ssh,
  host: "nerves.local",
  user: "root",
  port: 22

Logging device output

Nothing the device prints is written to disk unless you ask for it. To append everything the default server receives to a file:

config :nerves_mcp, :log_file, "nerves_mcp.log"

The file holds whatever passed over the console, which can include secrets.

Interactive Console

Call NervesMCP.console() to enter an interactive console session. Type #quit to exit and return to IEx, or #history to view buffered output.

Output History

Device output that arrives when no console is attached is stored in a circular buffer. Call NervesMCP.history() to view it, or use #history in the console.

Use as a library

A host application can run one server per device, each on its own port:

{:ok, server} =
  NervesMCP.start_server("nerves-1234.local",
    connection: [type: :ssh, host: "nerves-1234.local"]
  )

server.url
#=> "http://localhost:13000/mcp"

Ports are handed out from default_port/0 upwards, so the first server lands on 13000, the next on 13001, and so on. Pass :port to choose where to look, see start_server/2.

To collect what goes on with a device, pass a function as :on_output. It is given everything the device prints, including what the MCP tools cause:

NervesMCP.start_server(id,
  connection: connection,
  on_output: fn data -> MyApp.DeviceLog.append(id, data) end
)

Summary

Functions

Opens an interactive console to the connected device.

The port the first server listens on unless told otherwise.

Prints the buffered device output history.

Describes a running server, or returns nil if there is none with this id.

Describes every running server.

Starts an MCP server for one device.

Stops a server and closes its device connection.

Types

id()

@type id() :: term()

server()

@type server() :: %{
  id: id(),
  port: :inet.port_number(),
  url: String.t(),
  connection: keyword()
}

Functions

console(id \\ :default)

@spec console(id()) :: :ok

Opens an interactive console to the connected device.

Displays all incoming data from the device and allows you to send commands directly. Type #quit to exit the console and return to IEx.

default_port()

@spec default_port() :: :inet.port_number()

The port the first server listens on unless told otherwise.

history(id \\ :default)

@spec history(id()) :: :ok

Prints the buffered device output history.

All device output that arrives when no console is attached is stored in a circular buffer. Use this to view what you might have missed.

server(id)

@spec server(id()) :: server() | nil

Describes a running server, or returns nil if there is none with this id.

servers()

@spec servers() :: [server()]

Describes every running server.

start_server(id, opts)

@spec start_server(id(), keyword()) :: {:ok, server()} | {:error, term()}

Starts an MCP server for one device.

id names the server and is what every other function takes to refer to it. Any term works; a hostname or serial port path is a natural choice.

Options

  • :connection (required) - how to reach the device, in the same shape as the :connection application config: [type: :ssh, host: "nerves.local", user: "root", port: 22] or [type: :uart, port: "/dev/ttyUSB0", speed: 115_200].
  • :port - the HTTP port to listen on. Either one port, or an enumerable of ports to try in order, of which the first free one is used. Defaults to 13000..13099. To keep a device on the port it had last time, put that port first.
  • :ip - the address to listen on, as Bandit's :ip option. Defaults to :loopback, which accepts local clients only. Anyone who can reach the port can run code on the device, so only pass :any on a trusted network.
  • :on_output - a function that is called with each piece of output the device sends, as a binary. Pieces arrive as they come off the wire, so they do not line up with lines. The function runs in the connection process and holds up the device while it does, so keep it quick. Not set by default.
  • :log_file - a file to append all device output to. Not set by default.

Returns {:error, :already_started} if a server with this id is running, {:error, :no_free_port} if none of the ports could be used, {:error, {:invalid_connection, message}} if the connection cannot work and {:error, {:invalid_option, message}} if another option cannot be used.

stop_server(id)

@spec stop_server(id()) :: :ok | {:error, :not_found}

Stops a server and closes its device connection.