# `NervesMCP`
[🔗](https://github.com/nerves-project/nerves_mcp/blob/v0.1.0/lib/nerves_mcp.ex#L5)

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
    )

# `id`

```elixir
@type id() :: term()
```

# `server`

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

# `console`

```elixir
@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`

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

The port the first server listens on unless told otherwise.

# `history`

```elixir
@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`

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

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

# `servers`

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

Describes every running server.

# `start_server`

```elixir
@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`

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

Stops a server and closes its device connection.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
