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, 13000The server only accepts connections from this machine. To listen on every interface, on a network you trust:
config :nerves_mcp, :ip, :anyUART (Serial) Connection
config :nerves_mcp, :connection,
type: :uart,
port: "/dev/ttyUSB2",
speed: 115_200SSH Connection
config :nerves_mcp, :connection,
type: :ssh,
host: "nerves.local",
user: "root",
port: 22Logging 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
@type id() :: term()
@type server() :: %{ id: id(), port: :inet.port_number(), url: String.t(), connection: keyword() }
Functions
@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.
@spec default_port() :: :inet.port_number()
The port the first server listens on unless told otherwise.
@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.
Describes a running server, or returns nil if there is none with this id.
@spec servers() :: [server()]
Describes every running server.
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:connectionapplication 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:ipoption. Defaults to:loopback, which accepts local clients only. Anyone who can reach the port can run code on the device, so only pass:anyon 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.
@spec stop_server(id()) :: :ok | {:error, :not_found}
Stops a server and closes its device connection.