# `SuperPi.MCP.Server`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/mcp/server.ex#L1)

Model Context Protocol (MCP) server (`REQ-MCP-01`..`REQ-MCP-04`), over `stdio` here and over
Streamable HTTP in `SuperPi.MCP.HTTPPlug`.

Allows any MCP-compliant host (OpenCode, Claude Desktop, Cursor, Zed, Continue.dev)
to connect to Super-Pi-BEAM as a standard tool and context provider.

`handle_mcp_line/2` is pure: it takes one JSON-RPC message and the connection state and returns
the reply and the next state. The transports only move lines (stdio) or request bodies (HTTP).

## Protocol versions

`initialize` answers the client's `protocolVersion` when the server speaks it (`2025-06-18`,
`2025-03-26`, `2024-11-05`), else the newest. The requested version is logged at debug level,
which is how to find out what a host asks for. `2026-07-28` is not supported: it replaces
elicitation, sampling and roots with a different round trip.

## Supported Methods
- `initialize` - Handshake declaring tool, resource, and prompt capabilities.
- `notifications/initialized` - Post-handshake acknowledgment.
- `ping` - Heartbeat check.
- `tools/list` - The eight tools with JSON Schema and annotations (`readOnlyHint`,
  `destructiveHint`, `idempotentHint`, `openWorldHint`), which hosts use to decide what to
  approve without asking.
- `tools/call` - Runs a tool through the permission policy of the connection's harness. The
  result carries `content` (text) and, when the tool returns structured data, `structuredContent`.
- `prompts/list` & `prompts/get` - One prompt per harness (`SuperPi.Harness.list/0`), plus the
  `plan_architecture` alias.
- `resources/list`, `resources/read` - The workspace context, the tool loadout and the
  conversations that this connection started.
- `resources/templates/list` - `superpi://conversation/{id}/transcript`, which `resources/read`
  answers with the conversation transcript as JSON lines (the compact form that
  `SuperPi.Plugins.TranscriptLogger` writes). A conversation of another principal is not found.

## Choosing a harness

`harness_task` takes a `harness` argument (an id from `Harness.list/0`) and runs the task in
that harness. Direct tool calls (`read`, `bash` ...) run under the connection's harness: the
state key `:harness`, else `config :super_pi, :mcp_harness`, else `Harness.default/0`. The
workspace is the first of `SuperPi.Discovery.default_workspace_paths/0`.

Tools run in the mode that `SuperPi.Plugins.Permissions.apply_remote_mode/2` allows a remote
caller. State keys: `:harness`, `:principal` (an `SuperPi.Auth` principal, default anonymous).

# `handle_mcp_line`

Handles a single raw MCP JSON-RPC 2.0 payload string.
Pure handler suitable for unit tests and property testing.

# `negotiate_version`

```elixir
@spec negotiate_version(term()) :: String.t()
```

The version to answer `initialize` with: the client's when supported, else the newest supported.
The client then decides whether it can speak that version (MCP lifecycle, version negotiation).

# `run_stdio`

Runs the MCP server over standard input and output in a blocking loop.

# `supported_versions`

Protocol versions this server speaks, newest first.

# `tool_definitions`

The eight tools with their input schema and annotations. `harness_task` lists the harness ids.

---

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