Files
skyg-linux-tracker/docs/api.md
T
2026-10-19 22:35:51 -04:00

4.6 KiB

REST and MCP reference

Full endpoint and MCP client reference. The short version is in the README; the design is in ARCHITECTURE.md.

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
GET /api/v1/peers consolidator only; sorted status list; absent when peers are disabled
GET /api/v1/peers/{peer} one peer's status object; unknown name is 404
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'

Peers

Present only when [peers] enabled = true. The same inbound token as the rest of /api/v1 is required. GET /api/v1/peers returns {"peers":[...]} sorted by name, including disabled peers. GET /api/v1/peers/{peer} returns one object, not wrapped:

{
  "name": "beta",
  "enabled": true,
  "url": "http://beta:1984",
  "server": { "up": true, "since": "2026-10-19T10:00:00Z", "last_checked": "2026-10-19T10:00:09Z", "last_error": null, "latency_ms": 1 },
  "api": { "up": true, "since": "2026-10-19T10:00:00Z", "last_checked": "2026-10-19T10:00:05Z", "last_error": null, "latency_ms": 7, "auth": "ok", "peer_version": "0.1.0" }
}

server is the TCP check and api is the authenticated ping. auth is ok, rejected or unknown. Before the first check, up is false, auth is unknown and the timestamps are null. An unknown name is 404 {"error":{"code":"not_found","message":"peer <name>: unknown peer"}}.

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):

{
  "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:

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) or terminate TLS in a reverse proxy.