doc updates
This commit is contained in:
1 parent
7e1bd4a9a4
commit
a511ff532e
26 files changed
+573
-770
No files matched your search
+59
@@ -0,0 +1,59 @@
|
||||
# REST and MCP reference
|
||||
|
||||
Full endpoint and MCP client reference. The short version is in the [README](../README.md); the design is in [ARCHITECTURE.md](../ARCHITECTURE.md#rest-api).
|
||||
|
||||
## REST
|
||||
|
||||
Base: `http://127.0.0.1:1984`. Errors are `{"error":{"code","message"}}`.
|
||||
|
||||
| Route | Notes |
|
||||
|---|---|
|
||||
| `GET /healthz` | public, `{"status":"ok","version":...}` |
|
||||
| `GET /api/v1/systemd/units?state=failed` | `state` is an active state (`failed`, `active`, ...) |
|
||||
| `GET /api/v1/systemd/units/{name}` | one unit with details; read-only, so only units systemd has loaded (unloaded or unknown is 404) |
|
||||
| `GET /api/v1/systemd/timers` | |
|
||||
| `GET /api/v1/journal?unit=&priority=err&lines=100` | priority by name or number |
|
||||
| `GET /api/v1/journal/follow?unit=&priority=` | SSE, event `journal` |
|
||||
| `GET /api/v1/docker/ps` | `503` when Docker is unavailable |
|
||||
| `GET /api/v1/docker/containers/{name}` | |
|
||||
| `GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0\|1` | JSON, or SSE with events `stdout`/`stderr` |
|
||||
|
||||
```sh
|
||||
TOKEN=slinuxm_...
|
||||
curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/systemd/units?state=failed'
|
||||
curl -N -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/journal/follow?priority=err'
|
||||
```
|
||||
|
||||
## MCP
|
||||
|
||||
Endpoint: `http://127.0.0.1:1984/mcp` (Streamable HTTP). Eight tools (`list_systemd_units`, `get_systemd_unit`, `list_systemd_timers`, `get_journal_logs`, `tail_journal`, `list_containers`, `get_container`, `get_container_logs`), two prompts (`diagnose_unit`, `container_health_report`) two resources (`systemd://units/failed`, `docker://containers`) and two resource templates (`systemd://unit/{name}`, `docker://container/{name}`, same JSON as `get_systemd_unit` and `get_container`; percent-encode unusual characters in the name). Log content is untrusted data and is labelled as such in tool results.
|
||||
|
||||
Generic client config (header-capable clients):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"linux-tracker": {
|
||||
"url": "http://127.0.0.1:1984/mcp",
|
||||
"headers": { "Authorization": "Bearer slinuxm_..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Claude Code: `claude mcp add --transport http linux-tracker http://127.0.0.1:1984/mcp --header "Authorization: Bearer $TOKEN"`.
|
||||
|
||||
Inspector: `npx @modelcontextprotocol/inspector`, transport Streamable HTTP, add the bearer header.
|
||||
|
||||
Raw handshake with curl:
|
||||
|
||||
```sh
|
||||
curl -si -X POST http://127.0.0.1:1984/mcp \
|
||||
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json, text/event-stream' \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
|
||||
```
|
||||
|
||||
### Origin and Host checks
|
||||
|
||||
`/mcp` validates `Origin` and `Host` to defend against DNS rebinding from browsers. Loopback names, `server.bind` and the configured port are accepted by default. Requests without an `Origin` header (non-browser clients) pass this check, so the bearer token remains the real gate. If you bind to `0.0.0.0` or serve behind a name, add the names clients use to `server.allowed_hosts` (for example `["monitor.lan:1984"]`) and any browser origins to `server.allowed_origins`. With `auth.enabled = false` (loopback only), REST requests are checked against a Host allowlist (loopback names, `server.bind` and `server.allowed_hosts`) and get `403` otherwise, to blunt DNS rebinding. There is no Origin check on REST and no token in that mode, so keep auth enabled on any multi-user host. If the host is reachable beyond a trusted network, enable native TLS (see [tls.md](tls.md)) or terminate TLS in a reverse proxy.
|
||||
Reference in new issue
Block a user