Document the headless / TUI / MCP interfaces
Add docs/interfaces.md describing the three runtime interfaces and how to select them: headless (default plain text), --tui (full-screen views), and --mcp (stdio MCP server). Covers the available MCP tools, wiring the server into an MCP client, and a raw JSON-RPC handshake example. Kept generic with placeholders per the public-repo policy. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019fkbx6fUq1uDR5N75Ph5zi
Claude committed
Jul 17, 2026 at 12:58 UTC
5e236028c5197f9feee6f323ad65ad895e68cacc
1 file changed
+104
docs/interfaces.md
new
+104
@@ -0,0 +1,104 @@
1
+# Interfaces: headless, TUI, and MCP
2
+
3
+`smb` presents through one of three interfaces, chosen at runtime. The default
4
+is **headless** — plain, line-based text that works the same in a terminal, a
5
+pipe, or a script. Two global flags switch interface:
6
+
7
+| Flag | Interface | What it does |
8
+|---|---|---|
9
+| _(none)_ | **Headless** (default) | Plain-text output. Interactive prompts still appear on a TTY unless `--ci` is set. No full-screen takeover. |
10
+| `--tui` | **TUI** | Full-screen interactive views (`ratatui`) for the read commands. |
11
+| `--mcp` | **MCP** | Runs as a Model Context Protocol server over stdio instead of a one-shot command. Implies non-interactive. |
12
+
13
+`--tui` and `--mcp` are mutually exclusive. The `--ci` flag is orthogonal: it
14
+forces non-interactive behavior (see [ci.md](./ci.md)) and applies to the
15
+headless interface; `--mcp` is always non-interactive regardless of `--ci`.
16
+
17
+## Headless (default)
18
+
19
+The default interface prints plain text and never seizes the terminal, so it is
20
+safe to pipe or redirect:
21
+
22
+```sh
23
+smb me # plain key/value account block
24
+smb project list # plain table
25
+smb project show --id <id> # plain detail block
26
+smb project deployment # plain table (or detail with --id <id>)
27
+```
28
+
29
+On a real terminal, commands that need input still prompt (project setup, a
30
+monorepo target picker, delete confirmations). Add `--ci` — or run under CI — to
31
+turn those prompts off and fail fast instead of blocking.
32
+
33
+## TUI (`--tui`)
34
+
35
+`--tui` renders the read commands as full-screen interactive views. Press
36
+`q` / `Esc` to leave a view and return to the shell.
37
+
38
+```sh
39
+smb --tui me
40
+smb --tui project list
41
+smb --tui project show --id <id>
42
+smb --tui project deployment
43
+```
44
+
45
+Destructive confirmations (e.g. `project delete`) show a full-screen danger
46
+dialog under `--tui`; in the headless interface they ask inline instead.
47
+
48
+## MCP (`--mcp`)
49
+
50
+`smb --mcp` starts an MCP server that speaks JSON-RPC over stdio. Instead of
51
+running a single command and exiting, it stays up and exposes smbCloud
52
+operations as MCP **tools** that an MCP-capable client (assistant, IDE, agent)
53
+can call. The subcommand is ignored in this mode.
54
+
55
+Authentication uses the token stored by `smb login`, so log in once before
56
+starting the server. Tools run non-interactively and return structured JSON.
57
+
58
+### Available tools
59
+
60
+| Tool | Arguments | Returns |
61
+|---|---|---|
62
+| `me` | _(none)_ | The authenticated user. |
63
+| `project_list` | _(none)_ | The user's projects. |
64
+| `project_show` | `id` | A single project by ID. |
65
+| `deployments` | `project_id` | A project's deployments. |
66
+
67
+### Wiring it into an MCP client
68
+
69
+Most MCP clients take a command plus arguments. Point the client at the `smb`
70
+binary with `--mcp`:
71
+
72
+```json
73
+{
74
+ "mcpServers": {
75
+ "smbcloud": {
76
+ "command": "smb",
77
+ "args": ["--mcp"]
78
+ }
79
+ }
80
+}
81
+```
82
+
83
+To target a local API during development, add the environment flag —
84
+`"args": ["-e", "dev", "--mcp"]`.
85
+
86
+### Talking to it directly
87
+
88
+The server reads newline-delimited JSON-RPC on stdin and writes responses on
89
+stdout. Diagnostics go to stderr and logging goes to the on-disk log file, so
90
+stdout stays a clean protocol channel. A minimal handshake:
91
+
92
+```sh
93
+printf '%s\n' \
94
+ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
95
+ '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
96
+ '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
97
+ | smb --mcp
98
+```
99
+
100
+A tool call names the tool and its arguments:
101
+
102
+```json
103
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"project_show","arguments":{"id":"<id>"}}}
104
+```