v0.5.3: hub hardening — hard ssh timeout, parallel probes, sticky DOWN cache

Three fixes addressing the recurring "hub wedges on offline backends" class
of failures (2 incidents in 24h, root-caused to single-threaded Lua + an
uninterruptible os.execute ssh call):

1. Hard wall-clock cap on ssh fallback via GNU `timeout --kill-after=2 30`.
   ConnectTimeout alone only bounds TCP connect; a half-dead sshd (auth
   stall, remote bash-s hang) used to freeze the whole event loop
   indefinitely. Configurable via LMCP_HUB_SSH_HARD_TIMEOUT. Also adds
   ServerAliveInterval=5/Count=2 so an established-but-dead tunnel dies.

2. Parallel lmcp probes for remote_list_hosts. Shells out a single bash
   fan-out of curl -m 3 calls, bounded by PROBE_BUDGET. Wall clock for a
   full 12-backend probe went from ~28 s (sum of per-host ssh connect
   timeouts) to ~3 s.

3. Probe is lmcp-only — ssh is no longer used as health check. The hub
   exists to absorb lots of offline hosts, so an expensive ssh per probe
   was the exact wrong tradeoff. Actual remote_* tool calls still fall
   through to ssh fallback when lmcp is down.

4. Sticky DOWN cache with exponential backoff: 60 → 120 → 240 → 480 →
   900 s. Prevents a sleeping fleet from burning probe budget on every
   health check. UP hosts still use 30 s TTL. Tunable via
   LMCP_HUB_PROBE_TTL_{UP,DOWN_MIN,DOWN_MAX}.

5. Per-request logging to stderr (tool, host, via, elapsed) — invisible
   before, now captured in journal for the next hang's RCA.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -1,109 +1,33 @@
-# lmcp — Lightweight MCP Server in Lua
+# lmcp — Lua MCP server
 
-A minimal [Model Context Protocol](https://modelcontextprotocol.io/) server in pure Lua. ~350 lines, 2.4MB RSS, zero compiled dependencies beyond Lua + LuaSocket.
+Lightweight Model Context Protocol (MCP) server in pure Lua.
 
-## Features
+## Runtime dependencies
 
-- MCP 2025-03-26 protocol (JSON-RPC over HTTP)
-- Tool registration with JSON Schema validation
-- Optional Bearer token authentication (config file or explicit)
-- SSE and plain JSON response modes
-- Non-blocking shell execution with timeout
-- Runs on any Linux with Lua 5.4 + LuaSocket
-
-## Quick Start
-
-```sh
-# Install dependencies (Debian/Ubuntu)
-apt install lua5.4 lua-socket
-
-# Or use a self-contained archive (see releases)
-tar xzf lmcp-linux-amd64.tar.gz
-export PATH=$PWD/lmcp-linux-amd64/bin:$PATH
-
-# Run
-lua5.4 example_server.lua
-# lmcp: my-tools v0.1.0 listening on 0.0.0.0:8080/mcp
-```
+- Lua 5.1+
+- [luasocket](https://github.com/lunarmodules/luasocket) — needed for the TCP
+  listener. Packaged as `lua-socket` on Arch/ALARM, `lua-socket` on Debian.
 
 ## Files
 
-| File | Description |
-|------|-------------|
-| `lmcp.lua` | Core library — HTTP server, JSON-RPC, MCP protocol, auth |
-| `json.lua` | Minimal JSON encoder/decoder (bundled, no external dep) |
-| `example_server.lua` | Example server with shell, read/write file, list/search tools |
+| File | Role |
+|------|------|
+| `lmcp.lua`         | library: protocol handling, tool registration |
+| `server.lua`       | HTTP server loop |
+| `json.lua`         | vendored JSON encoder/decoder |
+| `example_server.lua` | sample server with a couple of tools |
 
-## Authentication
+## Install
 
-To require a Bearer token, create an `lmcp.conf` next to your server:
+Packaged as `lmcp` in the marfrit overlay repo:
 
 ```
-.godparticle = your-secret-token-here
+# Arch / ALARM
+sudo pacman -S lmcp
+
+# Debian
+sudo apt install lmcp
 ```
 
-Then reference it when creating the server:
-
-```lua
-local server = lmcp.new("my-tools", {
-    port = 8080,
-    conf = dir .. "lmcp.conf",
-})
-```
-
-Clients must send `Authorization: Bearer <token>` on every request. OPTIONS (CORS preflight) is exempt.
-
-You can also set the token directly:
-
-```lua
-local server = lmcp.new("my-tools", {
-    auth_token = "my-secret-token",
-})
-```
-
-## Claude Code Integration
-
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "my-host": {
-      "type": "url",
-      "url": "http://my-host:8080/mcp",
-      "headers": {
-        "Authorization": "Bearer your-token-here"
-      }
-    }
-  }
-}
-```
-
-## Adding Tools
-
-```lua
-server:tool("greet", "Say hello to someone.", {
-    type = "object",
-    properties = {
-        name = { type = "string", description = "Who to greet" },
-    },
-    required = { "name" },
-}, function(args)
-    return "Hello, " .. args.name .. "!"
-end)
-```
-
-Tool handlers return a string (wrapped as text content) or a table (encoded as JSON). Errors thrown via `error()` are caught and returned as MCP error responses.
-
-## Self-Contained Archives
-
-Pre-built archives with Lua 5.4 + LuaSocket for Linux:
-
-- `lmcp-linux-amd64.tar.gz` — x86_64
-- `lmcp-linux-aarch64.tar.gz` — ARM64 (Pi 5, RK3588, etc.)
-
-These include the Lua interpreter and LuaSocket shared library so no system packages are needed.
-
-## License
-
-MIT
+Files land under `/usr/share/lua/5.4/` (Lua LUA_PATH).
+The example server installs as `/usr/bin/lmcp-example`.

example_server.lua

@@ -1,100 +1,73 @@
 #!/usr/bin/env lua
--- Example lmcp server — customize tools for your host
-local dir = arg[0]:match("(.*/)")  or "./"
-package.path = package.path .. ";" .. dir .. "?.lua"
-local lmcp = require("lmcp")
+-- Example lmcp server — shell tools
+-- Usage: lua example_server.lua [port]
 
-local server = lmcp.new("my-tools", {
-    port = tonumber(os.getenv("LMCP_PORT")) or 8080,
-    -- Optional: Bearer token auth from config file
-    -- conf = dir .. "lmcp.conf",
-    -- Or set directly:
-    -- auth_token = "my-secret-token",
+local dir = arg[0]:match('(.*/)')  or './'
+package.path = package.path .. ';' .. dir .. '?.lua'
+
+local lmcp = require('lmcp')
+
+local server = lmcp.new("example-tools", {
+    port = tonumber(arg[1]) or 8080,
 })
 
--- Non-blocking shell execution with timeout
-local function run(cmd, timeout_sec)
-    timeout_sec = timeout_sec or 120
-    local base = os.tmpname()
-    local out_file = base .. ".out"
-    local done_file = base .. ".done"
-    local sh_cmd = string.format("(%s) > '%s' 2>&1; echo $? > '%s'", cmd, out_file, done_file)
-    os.execute("sh -c ' " .. sh_cmd .. " ' &")
-    local elapsed = 0
-    local interval = 50
-    while elapsed < timeout_sec * 1000 do
-        local f = io.open(done_file, "r")
-        if f then f:close(); break end
-        if interval < 1000 then
-            os.execute("sleep 0." .. string.format("%03d", interval))
-        else
-            os.execute("sleep " .. math.ceil(interval / 1000))
-        end
-        elapsed = elapsed + interval
-        if interval < 2000 then interval = math.floor(interval * 1.5) end
-    end
-    local f = io.open(out_file, "r")
-    local output = f and f:read("*a") or ""
-    if f then f:close() end
-    os.remove(out_file); os.remove(done_file); os.remove(base)
-    if elapsed >= timeout_sec * 1000 then return "Error: timed out after " .. timeout_sec .. "s" end
-    return output ~= "" and output or "(no output)"
-end
-
--- Register tools
-server:tool("shell", "Execute a shell command.", {
+server:tool("shell", "Execute a shell command", {
     type = "object",
     properties = {
-        command = { type = "string" },
-        cwd = { type = "string" },
-        timeout = { type = "integer", default = 120 },
+        command = { type = "string", description = "Shell command to execute" },
+        timeout = { type = "integer", description = "Timeout in seconds", default = 30 },
     },
     required = { "command" },
-}, function(a)
-    local c = a.command
-    if a.cwd then c = "cd \"" .. a.cwd .. "\" && " .. c end
-    return run(c, a.timeout or 120)
+}, function(args)
+    local handle = io.popen(args.command .. ' 2>&1', 'r')
+    if not handle then return "Error: could not execute command" end
+    local result = handle:read('*a')
+    handle:close()
+    return result ~= '' and result or '(no output)'
 end)
 
-server:tool("read_file", "Read a file.", {
-    type = "object",
-    properties = { path = { type = "string" } },
-    required = { "path" },
-}, function(a)
-    local f = io.open(a.path, "r")
-    if not f then return "Error: could not read " .. a.path end
-    local c = f:read("*a"); f:close(); return c
-end)
-
-server:tool("write_file", "Write content to a file.", {
-    type = "object",
-    properties = { path = { type = "string" }, content = { type = "string" } },
-    required = { "path", "content" },
-}, function(a)
-    local f = io.open(a.path, "w")
-    if not f then return "Error: could not write " .. a.path end
-    f:write(a.content); f:close()
-    return string.format("Written %d bytes to %s", #a.content, a.path)
-end)
-
-server:tool("list_dir", "List directory contents.", {
-    type = "object",
-    properties = { path = { type = "string", default = "." } },
-}, function(a)
-    return run("ls -la '" .. (a.path or ".") .. "'", 10)
-end)
-
-server:tool("search_files", "Search for files by name.", {
+server:tool("read_file", "Read a file", {
     type = "object",
     properties = {
-        pattern = { type = "string" },
-        path = { type = "string", default = "/" },
-        max_depth = { type = "integer", default = 4 },
+        path = { type = "string", description = "File path to read" },
     },
-    required = { "pattern" },
-}, function(a)
-    return run(string.format("find '%s' -maxdepth %d -name '%s' 2>/dev/null",
-        a.path or "/", a.max_depth or 4, a.pattern), 30)
+    required = { "path" },
+}, function(args)
+    local f = io.open(args.path, 'r')
+    if not f then return "Error: could not open " .. args.path end
+    local content = f:read('*a')
+    f:close()
+    return content
 end)
 
+server:tool("write_file", "Write content to a file", {
+    type = "object",
+    properties = {
+        path = { type = "string", description = "File path to write" },
+        content = { type = "string", description = "Content to write" },
+    },
+    required = { "path", "content" },
+}, function(args)
+    local f = io.open(args.path, 'w')
+    if not f then return "Error: could not open " .. args.path .. " for writing" end
+    f:write(args.content)
+    f:close()
+    return string.format("Written %d bytes to %s", #args.content, args.path)
+end)
+
+server:tool("list_dir", "List directory contents", {
+    type = "object",
+    properties = {
+        path = { type = "string", description = "Directory path", default = "." },
+    },
+}, function(args)
+    local path = args.path or '.'
+    local handle = io.popen('ls -1 ' .. path:gsub("'", "'\\''") .. ' 2>&1')
+    if not handle then return "Error: could not list " .. path end
+    local result = handle:read('*a')
+    handle:close()
+    return result
+end)
+
+io.stderr:write("Starting lmcp example server...\n")
 server:run()

examples/hub-backends.conf.example

@@ -0,0 +1,22 @@
+# lmcp hub backend registry.
+#
+# Format: whitespace-separated "name ssh_host lmcp_url token"
+# Use "-" for not-applicable fields.
+#   - Missing ssh_host (col 2 = -): no ssh fallback available for this backend
+#   - Missing lmcp_url (col 3 = -): this backend is ssh-only
+#   - Missing token   (col 4 = -): backend accepts unauth lmcp (LAN-only hosts)
+#
+# Lines starting with # are comments. Blank lines ignored.
+#
+# LXD-container caveat: if your hub lives on the LXD host and the backend is
+# a sibling LXD container, Fritz DNS often caches a stale DHCP lease for the
+# container's hostname. Hardcode the container IP here and update when it
+# rotates, or wire the .lxd stub zone into systemd-resolved.
+
+# name         ssh_host               lmcp_url                                   token
+# ---          ---                    ---                                        ---
+# boltzmann    boltzmann.fritz.box    http://boltzmann.fritz.box:8080/mcp        <64hex>
+# tesla        192.168.88.67          http://192.168.88.67:8080/mcp              -
+# nc           nc.reauktion.de        http://nc.reauktion.de:8080/mcp            <opaque>
+# pve1         pve1.fritz.box         http://pve1.fritz.box:8080/mcp             <opaque>
+# hertz        -                      http://hertz.fritz.box:8080/mcp            <opaque>

examples/lmcp-hub.service

@@ -0,0 +1,25 @@
+[Unit]
+Description=lmcp hub — fleet MCP broker
+After=network.target
+Wants=network.target
+
+[Service]
+Type=simple
+User=mfritsche
+Group=mfritsche
+# When deploying, copy hub.lua to /opt/lmcp/ or adjust the path below.
+ExecStart=/usr/bin/lua5.4 /usr/share/lua/5.4/hub.lua
+Environment=LMCP_NAME=hub-tools
+Environment=LMCP_PORT=8090
+# Backend registry: space-separated "name ssh_host lmcp_url token" per line.
+# See hub-backends.conf.example in this examples/ dir.
+Environment=LMCP_HUB_BACKENDS=/opt/herding/etc/hub-backends.conf
+# Bearer token file (key `.godparticle=<hex>`).
+Environment=LMCP_HUB_CONF=/opt/herding/etc/lmcp-hub.conf
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target

hub.lua

@@ -0,0 +1,580 @@
+#!/usr/bin/env lua
+-- lmcp hub — fleet-wide MCP broker.
+--
+-- One MCP endpoint that fans out to every lmcp-backed host, with an SSH
+-- fallback for hosts whose lmcp is temporarily down (or not installed).
+-- Exposes a small set of "remote_*" tools that all take a `host` arg
+-- naming the target in the backend registry.
+--
+-- Registry file (default /opt/herding/etc/hub-backends.conf):
+--   # name  ssh_host            lmcp_url                               token
+--   boltzmann boltzmann.fritz.box http://boltzmann.fritz.box:8080/mcp   <bearer>
+--   tesla     tesla               http://tesla.fritz.box:8080/mcp       -
+--   broglie   -                   http://broglie.fritz.box:8080/mcp     -
+-- Use `-` for "not applicable". Lines starting with # are comments.
+-- Missing `ssh_host`: no ssh fallback available. Missing `lmcp_url`: ssh-only.
+--
+-- SPDX-License-Identifier: MIT
+
+local dir = arg[0]:match('(.*/)') or './'
+package.path = package.path .. ';' .. dir .. '?.lua'
+local lmcp = require('lmcp')
+local json = require('json')
+local socket = require('socket')
+
+-- ---- Backend registry ---------------------------------------------------
+
+local CONF_PATH = os.getenv("LMCP_HUB_BACKENDS") or "/opt/herding/etc/hub-backends.conf"
+local PROBE_TTL_UP = tonumber(os.getenv("LMCP_HUB_PROBE_TTL_UP") or "30")
+local PROBE_TTL_DOWN_MIN = tonumber(os.getenv("LMCP_HUB_PROBE_TTL_DOWN_MIN") or "60")
+local PROBE_TTL_DOWN_MAX = tonumber(os.getenv("LMCP_HUB_PROBE_TTL_DOWN_MAX") or "900")
+local PROBE_BUDGET = tonumber(os.getenv("LMCP_HUB_PROBE_BUDGET") or "3")
+local LMCP_TIMEOUT = tonumber(os.getenv("LMCP_HUB_LMCP_TIMEOUT") or "6")
+local SSH_TIMEOUT = tonumber(os.getenv("LMCP_HUB_SSH_TIMEOUT") or "10")
+local SSH_HARD_TIMEOUT = tonumber(os.getenv("LMCP_HUB_SSH_HARD_TIMEOUT") or "30")
+local LOG_REQUESTS = (os.getenv("LMCP_HUB_LOG") or "1") ~= "0"
+
+local function logreq(fmt, ...)
+    if not LOG_REQUESTS then return end
+    io.stderr:write(string.format("[hub %s] " .. fmt .. "\n",
+        os.date("%H:%M:%S"), ...))
+    io.stderr:flush()
+end
+
+local function monotonic()
+    local ok, s = pcall(socket.gettime)
+    return ok and s or os.time()
+end
+
+local backends = {}  -- name -> { name, ssh_host, lmcp_url, token }
+local status = {}    -- name -> { up=bool, via="lmcp"|"ssh"|nil, checked=t, err=... }
+
+local function load_registry()
+    local f = io.open(CONF_PATH, "r")
+    if not f then
+        io.stderr:write("hub: no backend registry at " .. CONF_PATH .. "\n")
+        return
+    end
+    backends = {}
+    for line in f:lines() do
+        line = line:gsub("^%s+", ""):gsub("%s+$", "")
+        if line ~= "" and not line:match("^#") then
+            local parts = {}
+            for p in line:gmatch("%S+") do parts[#parts+1] = p end
+            if #parts >= 2 then
+                local name = parts[1]
+                local ssh_host = (parts[2] ~= "-" and parts[2]) or nil
+                local lmcp_url = (parts[3] ~= "-" and parts[3]) or nil
+                local token = (parts[4] ~= "-" and parts[4]) or nil
+                backends[name] = {
+                    name = name,
+                    ssh_host = ssh_host,
+                    lmcp_url = lmcp_url,
+                    token = token,
+                }
+            end
+        end
+    end
+    f:close()
+end
+
+-- ---- Outbound HTTP client (plain, no TLS) ------------------------------
+
+local function parse_url(url)
+    local scheme, host, port, path = url:match("^(%w+)://([^:/]+):?(%d*)(/?.*)$")
+    if not scheme then return nil, "bad url" end
+    port = tonumber(port) or (scheme == "https" and 443 or 80)
+    if path == "" then path = "/" end
+    return { scheme = scheme, host = host, port = port, path = path }
+end
+
+local function http_post_json(url, body, token, timeout)
+    local u, err = parse_url(url)
+    if not u then return nil, err end
+    if u.scheme ~= "http" then return nil, "hub only speaks http to backends" end
+
+    local sock = socket.tcp()
+    sock:settimeout(timeout or 6)
+    local ok, e = sock:connect(u.host, u.port)
+    if not ok then sock:close(); return nil, "connect: " .. e end
+
+    local headers = {
+        "POST " .. u.path .. " HTTP/1.1",
+        "Host: " .. u.host .. ":" .. u.port,
+        "Content-Type: application/json",
+        "Content-Length: " .. tostring(#body),
+        "Connection: close",
+    }
+    if token then
+        headers[#headers+1] = "Authorization: Bearer " .. token
+    end
+    local req = table.concat(headers, "\r\n") .. "\r\n\r\n" .. body
+    local _, se = sock:send(req)
+    if se then sock:close(); return nil, "send: " .. se end
+
+    local chunks = {}
+    while true do
+        local data, rerr, partial = sock:receive(4096)
+        if data then chunks[#chunks+1] = data
+        elseif partial and #partial > 0 then chunks[#chunks+1] = partial
+        end
+        if not data then
+            if rerr == "timeout" then sock:close(); return nil, "timeout" end
+            break
+        end
+    end
+    sock:close()
+
+    local resp = table.concat(chunks)
+    local hend = resp:find("\r\n\r\n", 1, true)
+    if not hend then return nil, "no body separator" end
+    local status_line = resp:sub(1, resp:find("\r\n", 1, true) - 1)
+    local status_code = tonumber(status_line:match("HTTP/[%d%.]+%s+(%d+)"))
+    local body_str = resp:sub(hend + 4)
+    if status_code ~= 200 then
+        return nil, "http " .. tostring(status_code) .. ": " .. body_str:sub(1, 200)
+    end
+    local ok2, parsed = pcall(json.decode, body_str)
+    if not ok2 then return nil, "bad json: " .. body_str:sub(1, 200) end
+    return parsed
+end
+
+local function jsonrpc_call(url, token, method, params)
+    local body = json.encode({
+        jsonrpc = "2.0",
+        id = os.time() * 1000 + math.random(1000, 9999),
+        method = method,
+        params = params or {},
+    })
+    local resp, err = http_post_json(url, body, token, LMCP_TIMEOUT)
+    if not resp then return nil, err end
+    if resp.error then
+        return nil, "rpc: " .. (resp.error.message or "unknown")
+    end
+    return resp.result
+end
+
+-- ---- SSH exec (shell-escape-free via bash -s on stdin) -----------------
+
+local function shell_quote(s)
+    -- Single-quote wrap, replace embedded single quotes with '\''
+    return "'" .. tostring(s):gsub("'", "'\\''") .. "'"
+end
+
+local function tmpwrite(content)
+    local path = os.tmpname()
+    local f = io.open(path, "w")
+    if not f then return nil, "tmpfile create failed" end
+    f:write(content)
+    f:close()
+    return path
+end
+
+local function ssh_run_script(ssh_host, script)
+    -- Write the script body locally, then ssh with stdin redirected from it.
+    -- bash -s reads the script from stdin. Nothing inside `script` is subject
+    -- to another shell round of expansion — this is the escape-free path.
+    local spath, perr = tmpwrite(script)
+    if not spath then return nil, perr, -1 end
+    local outpath = spath .. ".out"
+    -- Hard-cap wall time with GNU `timeout` — ssh's ConnectTimeout only
+    -- bounds TCP connect, not the session. Without this, a half-dead sshd
+    -- (auth stall, remote bash-s hang) locks the hub event loop indefinitely.
+    local cmd = string.format(
+        "timeout --kill-after=2 %d ssh -o ConnectTimeout=%d -o ServerAliveInterval=5 -o ServerAliveCountMax=2 -o BatchMode=yes -o StrictHostKeyChecking=accept-new %s 'bash -s' < %s > %s 2>&1; echo $? > %s.rc",
+        SSH_HARD_TIMEOUT, SSH_TIMEOUT, shell_quote(ssh_host), shell_quote(spath),
+        shell_quote(outpath), shell_quote(spath)
+    )
+    local t0 = monotonic()
+    os.execute(cmd)
+    local dt = monotonic() - t0
+    local rc_f = io.open(spath .. ".rc", "r")
+    local rc = -1
+    if rc_f then
+        local s = rc_f:read("*a") or ""
+        s = s:match("^(%S+)") or ""
+        rc = tonumber(s) or -1
+        rc_f:close()
+    end
+    local out_f = io.open(outpath, "r")
+    local output = out_f and out_f:read("*a") or ""
+    if out_f then out_f:close() end
+    os.remove(spath); os.remove(outpath); os.remove(spath .. ".rc")
+    -- timeout(1) exits 124 on wall-clock expiry, 137 on SIGKILL. Surface it.
+    if rc == 124 or rc == 137 then
+        logreq("ssh HARD-TIMEOUT host=%s after=%.2fs rc=%d", ssh_host, dt, rc)
+        return nil, string.format("ssh hard-timeout after %ds", SSH_HARD_TIMEOUT), rc
+    end
+    logreq("ssh host=%s elapsed=%.2fs rc=%d bytes=%d", ssh_host, dt, rc, #output)
+    return output, nil, rc
+end
+
+-- ---- Health probe ------------------------------------------------------
+--
+-- Design notes:
+--   - Probe is lmcp-only. SSH is NOT checked here: it's expensive (3-6s per
+--     offline host) and the hub exists specifically to absorb lots of
+--     offline hosts. Hosts with lmcp down but ssh up show as DOWN in the
+--     health list, but actual remote_* calls still fall through to ssh
+--     fallback correctly.
+--   - Sticky DOWN cache with exponential backoff: a DOWN host is re-probed
+--     at intervals that grow from PROBE_TTL_DOWN_MIN (default 60s) up to
+--     PROBE_TTL_DOWN_MAX (default 900s). Prevents a sleeping fleet from
+--     burning probe budget every health check.
+--   - `remote_list_hosts` uses a parallel curl fan-out for all hosts at
+--     once so wall-clock is bounded by PROBE_BUDGET (default 3s), not the
+--     sum of per-host timeouts.
+
+local function cache_fresh(s, now)
+    if not s then return false end
+    local ttl
+    if s.up then
+        ttl = PROBE_TTL_UP
+    else
+        ttl = math.min(PROBE_TTL_DOWN_MAX, PROBE_TTL_DOWN_MIN * (2 ^ (s.down_streak or 0)))
+    end
+    return (now - s.checked) < ttl
+end
+
+local function apply_probe_result(name, up, err, via, tool_count)
+    local prev = status[name]
+    local new_s = {
+        checked = os.time(),
+        up = up,
+        via = up and (via or "lmcp") or nil,
+        err = err,
+        tool_count = tool_count,
+        down_streak = up and 0 or ((prev and prev.down_streak or 0) + 1),
+    }
+    status[name] = new_s
+    return new_s
+end
+
+-- Fallback single-host probe used only when a caller explicitly needs a
+-- status refresh outside the parallel path (currently only
+-- remote_list_hosts when a single host is looked up). lmcp-only.
+local function probe(name, force)
+    local b = backends[name]
+    if not b then return { up = false, err = "unknown host" } end
+    local s = status[name]
+    if not force and cache_fresh(s, os.time()) then return s end
+    if not b.lmcp_url then
+        return apply_probe_result(name, false, "no lmcp url", nil, nil)
+    end
+    local result, err = jsonrpc_call(b.lmcp_url, b.token, "tools/list", {})
+    if result and result.tools then
+        return apply_probe_result(name, true, nil, "lmcp", #result.tools)
+    end
+    return apply_probe_result(name, false, "lmcp: " .. tostring(err), nil, nil)
+end
+
+-- Parallel lmcp probe for every backend with an lmcp_url, via a single
+-- bash fan-out of curl calls. Total wall clock ≈ PROBE_BUDGET.
+local function probe_all_parallel(force)
+    local now = os.time()
+    local need = {}
+    for name, b in pairs(backends) do
+        if b.lmcp_url and (force or not cache_fresh(status[name], now)) then
+            need[#need+1] = b
+        end
+    end
+    if #need == 0 then return end
+
+    local script_parts = {}
+    for _, b in ipairs(need) do
+        local auth = b.token and (" -H 'Authorization: Bearer " .. b.token .. "'") or ""
+        local url = b.lmcp_url:gsub("'", "'\\''")
+        script_parts[#script_parts+1] = string.format(
+            "(curl --max-time %d -s -o /dev/null -w '%s %%{http_code} %%{time_total}\\n' -X POST%s -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' '%s' || echo '%s ERR 0') &",
+            PROBE_BUDGET, b.name, auth, url, b.name
+        )
+    end
+    script_parts[#script_parts+1] = "wait"
+
+    local t0 = monotonic()
+    local p = io.popen(table.concat(script_parts, "\n"))
+    local out = p and p:read("*a") or ""
+    if p then p:close() end
+    local dt = monotonic() - t0
+
+    local seen = {}
+    for line in out:gmatch("[^\n]+") do
+        local name, code, t = line:match("^(%S+)%s+(%S+)%s+([%d%.]+)")
+        if name then
+            seen[name] = true
+            local is_up = (code == "200")
+            if is_up then
+                apply_probe_result(name, true, nil, "lmcp", nil)
+            else
+                apply_probe_result(name, false, "lmcp code=" .. code, nil, nil)
+            end
+        end
+    end
+    -- Hosts with no output (fan-out error): mark DOWN
+    for _, b in ipairs(need) do
+        if not seen[b.name] then
+            apply_probe_result(b.name, false, "probe fan-out missing", nil, nil)
+        end
+    end
+    logreq("probe_all_parallel n=%d elapsed=%.2fs", #need, dt)
+end
+
+-- ---- Call-tool dispatcher ----------------------------------------------
+
+-- `allow_ssh`: whether the tool has an SSH fallback path
+-- `ssh_impl`: function(backend, args) -> output string, or nil + error
+local function call_remote(tool, args, allow_ssh, ssh_impl)
+    local t_start = monotonic()
+    local host = args.host
+    if type(host) ~= "string" or host == "" then
+        logreq("tool=%s ERR missing-host", tool)
+        return "Error: missing `host` parameter"
+    end
+    local b = backends[host]
+    if not b then
+        logreq("tool=%s host=%s ERR unknown-host", tool, host)
+        return string.format("Error: unknown host %q (registry: %s)", host, CONF_PATH)
+    end
+
+    local errs = {}
+    local via = nil
+
+    -- Try lmcp first
+    if b.lmcp_url then
+        local args_pass = {}
+        for k, v in pairs(args) do if k ~= "host" then args_pass[k] = v end end
+        local result, err = jsonrpc_call(b.lmcp_url, b.token, "tools/call",
+            { name = tool, arguments = args_pass })
+        if result then
+            via = "lmcp"
+            logreq("tool=%s host=%s via=lmcp elapsed=%.2fs", tool, host, monotonic() - t_start)
+            -- Propagate backend's content, extract first text block
+            if type(result.content) == "table" and result.content[1] and result.content[1].text then
+                local prefix = result.isError and "[lmcp isError] " or ""
+                return prefix .. result.content[1].text
+            end
+            return json.encode(result)
+        end
+        errs[#errs+1] = "lmcp: " .. tostring(err)
+    else
+        errs[#errs+1] = "lmcp: no url configured"
+    end
+
+    -- Fallback to ssh
+    if allow_ssh and ssh_impl and b.ssh_host then
+        local out, serr = ssh_impl(b, args)
+        if out ~= nil then
+            logreq("tool=%s host=%s via=ssh elapsed=%.2fs", tool, host, monotonic() - t_start)
+            return "[via ssh fallback]\n" .. out
+        end
+        errs[#errs+1] = "ssh: " .. tostring(serr)
+    elseif allow_ssh and not b.ssh_host then
+        errs[#errs+1] = "ssh: no host configured"
+    end
+
+    logreq("tool=%s host=%s FAIL elapsed=%.2fs err=%s", tool, host, monotonic() - t_start, table.concat(errs, " | "):sub(1, 200))
+    return "Error: " .. table.concat(errs, " | ")
+end
+
+-- ---- SSH implementations for each fallback-capable tool ----------------
+
+local function ssh_shell(b, a)
+    if type(a.command) ~= "string" then return nil, "command required" end
+    local cwd_prefix = ""
+    if a.cwd and a.cwd ~= "" then
+        cwd_prefix = "cd " .. shell_quote(a.cwd) .. " && "
+    end
+    local script = cwd_prefix .. a.command .. "\n"
+    local out, err, rc = ssh_run_script(b.ssh_host, script)
+    if err then return nil, err end
+    -- ssh exits 255 when it couldn't connect/authenticate. Treat that as
+    -- fallback-failed so the caller sees the combined lmcp+ssh errors.
+    if rc == 255 then
+        local line1 = (out:match("^([^\n]+)") or ""):gsub("%s+$", "")
+        return nil, "ssh connect failed: " .. line1
+    end
+    return string.format("[rc=%d]\n%s", rc, out)
+end
+
+local function ssh_read_file(b, a)
+    if type(a.path) ~= "string" then return nil, "path required" end
+    local script = "cat -- " .. shell_quote(a.path) .. "\n"
+    local out, err, rc = ssh_run_script(b.ssh_host, script)
+    if err then return nil, err end
+    if rc ~= 0 then return nil, "cat exit " .. rc .. ": " .. out:sub(1, 200) end
+    return out
+end
+
+local function ssh_write_file(b, a)
+    if type(a.path) ~= "string" or type(a.content) ~= "string" then
+        return nil, "path and content required"
+    end
+    -- Emit a script that decodes content from base64, so no shell
+    -- interpretation of the payload is possible. Lua stdlib has no base64;
+    -- implement a minimal encoder inline.
+    local b64_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+    local function b64enc(data)
+        local out = {}
+        local pad = (3 - (#data % 3)) % 3
+        local padded = data .. ("\0"):rep(pad)
+        for i = 1, #padded, 3 do
+            local a1, a2, a3 = padded:byte(i), padded:byte(i+1), padded:byte(i+2)
+            local n = a1 * 65536 + a2 * 256 + a3
+            out[#out+1] = b64_alphabet:sub(((n >> 18) & 63) + 1, ((n >> 18) & 63) + 1)
+            out[#out+1] = b64_alphabet:sub(((n >> 12) & 63) + 1, ((n >> 12) & 63) + 1)
+            out[#out+1] = b64_alphabet:sub(((n >>  6) & 63) + 1, ((n >>  6) & 63) + 1)
+            out[#out+1] = b64_alphabet:sub(((n      ) & 63) + 1, ((n      ) & 63) + 1)
+        end
+        local s = table.concat(out)
+        if pad > 0 then s = s:sub(1, -pad - 1) .. ("="):rep(pad) end
+        return s
+    end
+    local payload = b64enc(a.content)
+    local script = string.format(
+        "base64 -d > %s <<'EOF_B64_PAYLOAD'\n%s\nEOF_B64_PAYLOAD\n",
+        shell_quote(a.path), payload
+    )
+    local out, err, rc = ssh_run_script(b.ssh_host, script)
+    if err then return nil, err end
+    if rc ~= 0 then return nil, "write exit " .. rc .. ": " .. out:sub(1, 200) end
+    return string.format("Written %d bytes to %s (via ssh)", #a.content, a.path)
+end
+
+local function ssh_list_dir(b, a)
+    local path = (a and type(a.path) == "string" and a.path) or "."
+    local script = "ls -1 -- " .. shell_quote(path) .. "\n"
+    local out, err, rc = ssh_run_script(b.ssh_host, script)
+    if err then return nil, err end
+    if rc ~= 0 then return nil, "ls exit " .. rc .. ": " .. out:sub(1, 200) end
+    return out
+end
+
+local function ssh_search_files(b, a)
+    if type(a.pattern) ~= "string" then return nil, "pattern required" end
+    local path = (a.path and a.path ~= "") and a.path or "/"
+    local script = string.format(
+        "find %s -name %s 2>/dev/null | head -200\n",
+        shell_quote(path), shell_quote(a.pattern)
+    )
+    local out, err, rc = ssh_run_script(b.ssh_host, script)
+    if err then return nil, err end
+    return out
+end
+
+-- ---- Server setup ------------------------------------------------------
+
+load_registry()
+math.randomseed(os.time())
+
+local server = lmcp.new(os.getenv("LMCP_NAME") or "hub-tools", {
+    port = tonumber(os.getenv("LMCP_PORT") or arg[1]) or 8090,
+    version = "0.5.3",
+    conf = os.getenv("LMCP_HUB_CONF") or "/opt/herding/etc/lmcp-hub.conf",
+})
+
+local HOST_ARG = {
+    type = "string",
+    description = "Name of the backend host (see remote_list_hosts)",
+}
+
+server:tool("remote_list_hosts",
+    "List all registered fleet hosts and their live status (lmcp vs ssh vs down).",
+    { type = "object", properties = {
+        force = { type = "boolean", description = "Force re-probe (bypass cache)", default = false },
+    } },
+    function(a)
+        local force = a and a.force or false
+        probe_all_parallel(force)
+        local lines = {}
+        local names = {}
+        for n in pairs(backends) do names[#names+1] = n end
+        table.sort(names)
+        for _, n in ipairs(names) do
+            local b = backends[n]
+            local s = status[n] or { up = false, err = "no probe result" }
+            local paths = {}
+            if b.lmcp_url then paths[#paths+1] = "lmcp" end
+            if b.ssh_host then paths[#paths+1] = "ssh" end
+            lines[#lines+1] = string.format(
+                "%-14s  %-6s  via=%-4s  paths=%s  %s",
+                n,
+                s.up and "UP" or "DOWN",
+                tostring(s.via or "-"),
+                table.concat(paths, ","),
+                s.err and ("[" .. s.err .. "]") or ""
+            )
+        end
+        return table.concat(lines, "\n")
+    end
+)
+
+server:tool("remote_shell", "Run a shell command on a fleet host. lmcp-primary with ssh fallback.",
+    { type = "object", properties = {
+        host = HOST_ARG,
+        command = { type = "string", description = "Shell command" },
+        cwd = { type = "string", description = "Working directory" },
+        timeout = { type = "integer", description = "Timeout (seconds)", default = 120 },
+    }, required = { "host", "command" } },
+    function(a) return call_remote("shell", a, true, ssh_shell) end
+)
+
+server:tool("remote_read_file", "Read a file from a fleet host.",
+    { type = "object", properties = {
+        host = HOST_ARG,
+        path = { type = "string", description = "File path" },
+    }, required = { "host", "path" } },
+    function(a) return call_remote("read_file", a, true, ssh_read_file) end
+)
+
+server:tool("remote_write_file", "Write content to a file on a fleet host.",
+    { type = "object", properties = {
+        host = HOST_ARG,
+        path = { type = "string" },
+        content = { type = "string" },
+    }, required = { "host", "path", "content" } },
+    function(a) return call_remote("write_file", a, true, ssh_write_file) end
+)
+
+server:tool("remote_edit_file",
+    "Literal-match edit on a fleet host. **Requires backend lmcp up** — no ssh fallback.",
+    { type = "object", properties = {
+        host = HOST_ARG,
+        path = { type = "string" },
+        old_string = { type = "string" },
+        new_string = { type = "string" },
+        replace_all = { type = "boolean", default = false },
+    }, required = { "host", "path", "old_string", "new_string" } },
+    function(a) return call_remote("edit_file", a, false, nil) end
+)
+
+server:tool("remote_shell_bg",
+    "Launch a detached background command on a fleet host (Linux). Returns PID + log path immediately. Requires backend lmcp v0.5.2+.",
+    { type = "object", properties = {
+        host = HOST_ARG,
+        command = { type = "string", description = "Shell command" },
+        cwd = { type = "string" },
+        log = { type = "string", description = "Log file path" },
+    }, required = { "host", "command" } },
+    function(a) return call_remote("shell_bg", a, false, nil) end
+)
+
+server:tool("remote_list_dir", "List directory entries on a fleet host.",
+    { type = "object", properties = {
+        host = HOST_ARG,
+        path = { type = "string", default = "." },
+    }, required = { "host" } },
+    function(a) return call_remote("list_dir", a, true, ssh_list_dir) end
+)
+
+server:tool("remote_search_files", "find-by-pattern on a fleet host.",
+    { type = "object", properties = {
+        host = HOST_ARG,
+        pattern = { type = "string" },
+        path = { type = "string", default = "/" },
+    }, required = { "host", "pattern" } },
+    function(a) return call_remote("search_files", a, true, ssh_search_files) end
+)
+
+io.stderr:write(string.format("lmcp-hub starting on port %d with %d backends from %s\n",
+    server.port, (function() local n = 0; for _ in pairs(backends) do n = n + 1 end; return n end)(), CONF_PATH))
+server:run()

lmcp.lua

@@ -33,12 +33,17 @@ function lmcp.new(name, opts)
     self.port = opts.port or 8080
     self.tools = {}
     self._session_id = nil
-    -- Auth: explicit opt > conf file > nil (no auth)
+    -- Auth: explicit opt > conf file > LMCP_TOKEN env > nil (no auth)
     if opts.auth_token then
         self._auth_token = opts.auth_token
     elseif opts.conf then
         local conf = read_conf(opts.conf)
         self._auth_token = conf['.godparticle']
+    else
+        local env_token = os.getenv("LMCP_TOKEN")
+        if env_token and env_token ~= "" then
+            self._auth_token = env_token
+        end
     end
     return self
 end
@@ -290,12 +295,19 @@ function lmcp:serve_request(client)
         return
     end
 
-    -- OPTIONS (CORS preflight)
+    -- OPTIONS (CORS preflight). Echo back whatever the client asked for
+    -- (MCP adds e.g. Mcp-Session-Id, Mcp-Protocol-Version); fall back to *.
     if req.method == 'OPTIONS' then
+        local acrh = req.headers and (req.headers['access-control-request-headers']
+                                      or req.headers['Access-Control-Request-Headers'])
         send_response(client, '204 No Content', {
             ['Access-Control-Allow-Origin'] = '*',
             ['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS',
-            ['Access-Control-Allow-Headers'] = 'Content-Type, Accept, Authorization',
+            -- CORS spec: '*' does NOT cover Authorization; must list it explicitly.
+            -- Echo back whatever the client requested plus Authorization.
+            ['Access-Control-Allow-Headers'] = acrh and (acrh .. ', Authorization')
+                or 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version',
+            ['Access-Control-Max-Age'] = '86400',
         }, '')
         client:close()
         return
@@ -341,4 +353,3 @@ function lmcp:run()
 end
 
 return lmcp
-

scripts/lmcp-install-macos.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+# Install lmcp on macOS via Homebrew.
+#
+# Pins to lua@5.4 (keg-only brew formula) to keep library paths aligned
+# with the rest of the fleet (Arch/ALARM, Debian). Installs luasocket via
+# luarocks into the user-local rocks tree (~/.luarocks/) and bakes the
+# required LUA_PATH / LUA_CPATH into the LaunchAgent plist so the service
+# can `require 'socket'`.
+#
+# Usage (from lmcp repo root):
+#   ./scripts/lmcp-install-macos.sh
+#
+# Uninstall:
+#   launchctl unload ~/Library/LaunchAgents/de.reauktion.marfrit.lmcp.plist
+#   rm ~/Library/LaunchAgents/de.reauktion.marfrit.lmcp.plist
+#   rm $(brew --prefix)/etc/lmcp/token
+
+set -euo pipefail
+
+# brew is only on PATH in login shells by default; source its env explicitly
+# so this works under a plain non-login bash too.
+if ! command -v brew >/dev/null 2>&1; then
+    for candidate in /opt/homebrew/bin/brew /usr/local/bin/brew; do
+        if [ -x "$candidate" ]; then
+            eval "$("$candidate" shellenv)"
+            break
+        fi
+    done
+fi
+command -v brew >/dev/null 2>&1 || { echo "error: Homebrew not found"; exit 1; }
+
+REPO=${REPO:-$(cd "$(dirname "$0")/.." && pwd)}
+for f in lmcp.lua json.lua server.lua example_server.lua; do
+    [ -f "$REPO/$f" ] || { echo "error: $REPO/$f not found — run from lmcp repo root or set REPO="; exit 1; }
+done
+
+echo "==> brew install lua@5.4 luarocks"
+brew install --quiet lua@5.4 luarocks
+
+LUA54_PREFIX=$(brew --prefix lua@5.4)
+LUA54=$LUA54_PREFIX/bin/lua5.4
+BREW_PREFIX=$(brew --prefix)
+[ -x "$LUA54" ] || { echo "error: $LUA54 missing after brew install"; exit 1; }
+
+echo "==> luarocks install luasocket (user-local, pinned to lua@5.4)"
+luarocks --lua-version 5.4 --lua-dir "$LUA54_PREFIX" install --local luasocket
+
+LR_PATH=$(luarocks --lua-version 5.4 --lua-dir "$LUA54_PREFIX" path --lr-path)
+LR_CPATH=$(luarocks --lua-version 5.4 --lua-dir "$LUA54_PREFIX" path --lr-cpath)
+DEFAULT_LUA_P="$BREW_PREFIX/share/lua/5.4/?.lua;$BREW_PREFIX/share/lua/5.4/?/init.lua;$BREW_PREFIX/lib/lua/5.4/?.lua;$BREW_PREFIX/lib/lua/5.4/?/init.lua;./?.lua;./?/init.lua"
+DEFAULT_LUA_CP="$BREW_PREFIX/lib/lua/5.4/?.so;./?.so"
+FULL_LUA_P="$DEFAULT_LUA_P;$LR_PATH"
+FULL_LUA_CP="$DEFAULT_LUA_CP;$LR_CPATH"
+
+echo "==> install library files into $BREW_PREFIX/share/lua/5.4/"
+install -d "$BREW_PREFIX/share/lua/5.4"
+install -m 644 "$REPO/lmcp.lua"   "$BREW_PREFIX/share/lua/5.4/lmcp.lua"
+install -m 644 "$REPO/json.lua"   "$BREW_PREFIX/share/lua/5.4/json.lua"
+install -m 644 "$REPO/server.lua" "$BREW_PREFIX/share/lua/5.4/server.lua"
+install -m 755 "$REPO/example_server.lua" "$BREW_PREFIX/bin/lmcp-example"
+
+# Token: retain existing, mint new otherwise
+TOKEN_FILE="$BREW_PREFIX/etc/lmcp/token"
+install -d -m 755 "$BREW_PREFIX/etc/lmcp"
+if [ -r "$TOKEN_FILE" ]; then
+    TOKEN=$(cat "$TOKEN_FILE")
+    echo "==> reusing token from $TOKEN_FILE"
+else
+    TOKEN=$(openssl rand -hex 32)
+    umask 077
+    printf '%s\n' "$TOKEN" > "$TOKEN_FILE"
+    chmod 600 "$TOKEN_FILE"
+    echo "==> minted new token, stored at $TOKEN_FILE (0600)"
+fi
+
+LABEL="de.reauktion.marfrit.lmcp"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+PORT="${LMCP_PORT:-8080}"
+NAME="${LMCP_NAME:-$(hostname -s)-tools}"
+
+echo "==> write LaunchAgent $PLIST"
+mkdir -p "$HOME/Library/LaunchAgents"
+cat > "$PLIST" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>$LABEL</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$LUA54</string>
+        <string>$BREW_PREFIX/share/lua/5.4/server.lua</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>LMCP_PORT</key>
+        <string>$PORT</string>
+        <key>LMCP_NAME</key>
+        <string>$NAME</string>
+        <key>LMCP_TOKEN</key>
+        <string>$TOKEN</string>
+        <key>LUA_PATH</key>
+        <string>$FULL_LUA_P</string>
+        <key>LUA_CPATH</key>
+        <string>$FULL_LUA_CP</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/lmcp.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/lmcp.err</string>
+</dict>
+</plist>
+PLIST
+chmod 600 "$PLIST"  # plist contains token
+
+echo "==> (re)load LaunchAgent"
+launchctl unload "$PLIST" 2>/dev/null || true
+launchctl load "$PLIST"
+
+sleep 2
+echo "==> smoke test (unauth expected 401, Bearer expected 200)"
+unauth=$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 -X POST "http://127.0.0.1:$PORT/mcp" \
+     -H 'Content-Type: application/json' \
+     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' || echo "000")
+auth=$(curl -s --max-time 3 -X POST "http://127.0.0.1:$PORT/mcp" \
+     -H "Authorization: Bearer $TOKEN" \
+     -H 'Content-Type: application/json' \
+     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' || true)
+
+if [ "$unauth" = "401" ] && echo "$auth" | grep -q '"tools"'; then
+    echo "OK — lmcp listening on :$PORT as $NAME, Bearer-gated"
+else
+    echo "smoke test failed (unauth=$unauth, auth body below)"
+    echo "$auth" | head -c 500; echo
+    tail -20 /tmp/lmcp.err 2>/dev/null || true
+    exit 1
+fi
+
+cat <<INFO
+
+Token: $TOKEN
+
+Add to Claude Code ~/.claude.json on the client machine:
+
+    "$NAME": {
+        "type": "http",
+        "url": "http://$(hostname -s).fritz.box:$PORT/mcp",
+        "headers": { "Authorization": "Bearer $TOKEN" }
+    }
+
+(Use .fritz.box, .local, or the LAN IP depending on where the client lives.)
+INFO

server.lua

@@ -0,0 +1,333 @@
+#!/usr/bin/env lua
+-- lmcp server — cross-platform shell tools
+-- Works on Linux, macOS, and Windows without modification.
+-- SPDX-License-Identifier: MIT
+
+-- Resolve package paths relative to this script
+local dir = arg[0]:match('(.*[/\\])') or './'
+local sep = package.config:sub(1, 1)  -- '/' on Unix, '\\' on Windows
+package.path = package.path .. ';' .. dir .. '?.lua'
+
+-- Windows: add lua\ subdirectory for LuaSocket DLLs
+if sep == '\\' then
+    package.cpath = package.cpath .. ';' .. dir .. 'lua\\?.dll'
+        .. ';' .. dir .. 'lua\\socket\\?.dll'
+        .. ';' .. dir .. 'lua\\mime\\?.dll'
+end
+
+local lmcp = require('lmcp')
+
+-- ---- Platform detection ----
+local WINDOWS = sep == '\\'
+local function is_windows() return WINDOWS end
+
+-- ---- Non-blocking command execution with timeout ----
+-- io.popen blocks until the child exits. On any OS, a long-running
+-- process (like a daemon) will hang lmcp forever. We work around this
+-- by spawning into temp files and polling a sentinel.
+
+local function tmpname()
+    if WINDOWS then
+        local tmp = os.getenv("TEMP") or "C:\\Windows\\Temp"
+        return tmp .. "\\lmcp_" .. os.time() .. "_" .. math.random(10000, 99999)
+    else
+        return os.tmpname()
+    end
+end
+
+local function sleep_ms(ms)
+    if WINDOWS then
+        -- ping loopback: ~1s per -n count. For sub-second, use busy-wait.
+        if ms < 500 then
+            local target = os.clock() + ms / 1000
+            while os.clock() < target do end
+        else
+            local secs = math.ceil(ms / 1000)
+            os.execute("ping -n " .. (secs + 1) .. " 127.0.0.1 >nul 2>&1")
+        end
+    else
+        -- POSIX: use sleep command (supports fractional seconds on GNU)
+        if ms < 1000 then
+            os.execute("sleep 0." .. string.format("%03d", ms))
+        else
+            os.execute("sleep " .. math.ceil(ms / 1000))
+        end
+    end
+end
+
+local function file_exists(path)
+    local f = io.open(path, 'r')
+    if f then f:close(); return true end
+    return false
+end
+
+local function read_file(path)
+    local f = io.open(path, 'r')
+    if not f then return nil end
+    local c = f:read('*a'); f:close(); return c
+end
+
+local function remove_silent(path)
+    os.remove(path)
+end
+
+local function run(cmd, timeout_sec)
+    timeout_sec = timeout_sec or 120
+
+    local base = tmpname()
+    local out_file = base .. ".out"
+    local done_file = base .. ".done"
+
+    if WINDOWS then
+        -- Write a batch wrapper that runs the command and signals completion
+        local bat_file = base .. ".bat"
+        local bf = io.open(bat_file, 'w')
+        if not bf then return "Error: could not create temp file" end
+        bf:write("@echo off\r\n")
+        bf:write(cmd .. ' > "' .. out_file .. '" 2>&1\r\n')
+        bf:write('echo %ERRORLEVEL% > "' .. done_file .. '"\r\n')
+        bf:close()
+        os.execute('start /B cmd /C "' .. bat_file .. '"')
+
+        -- Poll for sentinel
+        local elapsed = 0
+        local interval = 100  -- ms
+        while elapsed < timeout_sec * 1000 do
+            if file_exists(done_file) then break end
+            sleep_ms(interval)
+            elapsed = elapsed + interval
+            if interval < 2000 then interval = math.floor(interval * 1.5) end
+        end
+
+        local output = read_file(out_file)
+        remove_silent(bat_file)
+        remove_silent(out_file)
+        remove_silent(done_file)
+
+        if elapsed >= timeout_sec * 1000 then
+            return output or ("Error: command timed out after " .. timeout_sec .. "s")
+        end
+        return output and output ~= "" and output or "(no output)"
+    else
+        -- POSIX: use shell backgrounding + wait with timeout
+        -- sh -c '(cmd > out 2>&1; echo $? > done) &' then poll
+        local sh_cmd = string.format(
+            "(%s) > '%s' 2>&1; echo $? > '%s'",
+            cmd, out_file, done_file
+        )
+        os.execute("sh -c '" .. sh_cmd:gsub("'", "'\\''") .. "' &")
+
+        local elapsed = 0
+        local interval = 50  -- ms
+        while elapsed < timeout_sec * 1000 do
+            if file_exists(done_file) then break end
+            sleep_ms(interval)
+            elapsed = elapsed + interval
+            if interval < 2000 then interval = math.floor(interval * 1.5) end
+        end
+
+        local output = read_file(out_file)
+        remove_silent(out_file)
+        remove_silent(done_file)
+
+        if elapsed >= timeout_sec * 1000 then
+            return output or ("Error: command timed out after " .. timeout_sec .. "s")
+        end
+        return output and output ~= "" and output or "(no output)"
+    end
+end
+
+-- ---- Server setup ----
+
+local server_name = os.getenv("LMCP_NAME") or (WINDOWS and "windows-tools" or "linux-tools")
+local server = lmcp.new(server_name, {
+    port = tonumber(os.getenv("LMCP_PORT") or arg[1]) or 8080,
+})
+
+-- ---- Tools ----
+
+server:tool("shell", "Execute a shell command.", {
+    type = "object",
+    properties = {
+        command = { type = "string", description = "Command to execute" },
+        cwd = { type = "string", description = "Working directory" },
+        timeout = { type = "integer", description = "Timeout in seconds", default = 120 },
+        powershell = { type = "boolean", description = "Use PowerShell (Windows only)", default = false },
+    },
+    required = { "command" },
+}, function(a)
+    local cmd = a.command
+    if a.cwd then
+        if WINDOWS then
+            cmd = 'cd /d "' .. a.cwd .. '" && ' .. cmd
+        else
+            cmd = 'cd "' .. a.cwd .. '" && ' .. cmd
+        end
+    end
+    if a.powershell and WINDOWS then
+        cmd = 'powershell -NoProfile -Command "' .. cmd:gsub('"', '\\"') .. '"'
+    end
+    return run(cmd, a.timeout or 120)
+end)
+
+server:tool("shell_bg",
+    "Fire-and-forget shell command (Linux-only). Fully detaches via setsid+nohup+stdio-redirect and returns immediately with PID and log path. Use for daemons that must outlive the lmcp request.",
+    {
+        type = "object",
+        properties = {
+            command = { type = "string", description = "Shell command to launch" },
+            cwd     = { type = "string", description = "Working directory" },
+            log     = { type = "string", description = "Log file (stdout+stderr). Default: /tmp/lmcp-bg-<ts>-<rand>.log" },
+        },
+        required = { "command" },
+    },
+    function(a)
+        if WINDOWS then
+            return "Error: shell_bg is Linux-only (Windows Start-Process equivalent TBD)"
+        end
+        if type(a.command) ~= "string" or a.command == "" then
+            return "Error: command required"
+        end
+        local log = a.log
+        if not log or log == "" then
+            log = string.format("/tmp/lmcp-bg-%d-%d.log", os.time(), math.random(1000, 9999))
+        end
+        local pid_file = log .. ".pid"
+        local inner = a.command
+        if a.cwd and a.cwd ~= "" then
+            inner = "cd '" .. a.cwd:gsub("'", "'\\''") .. "' && " .. inner
+        end
+        local sq = function(s) return "'" .. s:gsub("'", "'\\''") .. "'" end
+        local full = string.format(
+            "setsid nohup sh -c %s </dev/null >%s 2>&1 & echo $! > %s",
+            sq(inner), sq(log), sq(pid_file)
+        )
+        os.execute(full)
+        local f = io.open(pid_file, 'r')
+        local pid = "?"
+        if f then
+            pid = (f:read('*a') or ""):match("(%d+)") or "?"
+            f:close()
+            os.remove(pid_file)
+        end
+        return string.format("launched pid=%s log=%s", pid, log)
+    end)
+
+server:tool("read_file", "Read a file.", {
+    type = "object",
+    properties = { path = { type = "string" } },
+    required = { "path" },
+}, function(a)
+    local c = read_file(a.path)
+    if not c then return "Error: could not read " .. a.path end
+    return c
+end)
+
+server:tool("write_file", "Write content to a file.", {
+    type = "object",
+    properties = {
+        path = { type = "string" },
+        content = { type = "string" },
+    },
+    required = { "path", "content" },
+}, function(a)
+    local f = io.open(a.path, 'w')
+    if not f then return "Error: could not write " .. a.path end
+    f:write(a.content); f:close()
+    return string.format("Written %d bytes to %s", #a.content, a.path)
+end)
+
+server:tool("edit_file", "Replace exact text in a file (literal match). Fails unless old_string is unique, unless replace_all=true.", {
+    type = "object",
+    properties = {
+        path = { type = "string", description = "Path to file" },
+        old_string = { type = "string", description = "Exact text to replace (literal, no regex)" },
+        new_string = { type = "string", description = "Replacement text" },
+        replace_all = { type = "boolean", description = "Replace every occurrence (default: false)", default = false },
+    },
+    required = { "path", "old_string", "new_string" },
+}, function(a)
+    if type(a.path) ~= "string" or a.path == "" then return "Error: path required" end
+    if type(a.old_string) ~= "string" then return "Error: old_string required" end
+    if type(a.new_string) ~= "string" then return "Error: new_string required" end
+    if a.old_string == "" then return "Error: old_string cannot be empty" end
+    if a.old_string == a.new_string then return "Error: new_string must differ from old_string" end
+
+    local f = io.open(a.path, 'rb')
+    if not f then return "Error: could not read " .. a.path end
+    local content = f:read('*a'); f:close()
+
+    local count, pos = 0, 1
+    while pos <= #content do
+        local i = content:find(a.old_string, pos, true)
+        if not i then break end
+        count = count + 1
+        pos = i + #a.old_string
+    end
+
+    if count == 0 then
+        return "Error: old_string not found in " .. a.path
+    end
+    if count > 1 and not a.replace_all then
+        return string.format("Error: old_string matches %d times in %s (use replace_all=true or provide more surrounding context to disambiguate)", count, a.path)
+    end
+
+    local parts, p, replaced = {}, 1, 0
+    while true do
+        local i = content:find(a.old_string, p, true)
+        if not i then break end
+        parts[#parts+1] = content:sub(p, i-1)
+        parts[#parts+1] = a.new_string
+        p = i + #a.old_string
+        replaced = replaced + 1
+        if not a.replace_all then break end
+    end
+    parts[#parts+1] = content:sub(p)
+
+    local w = io.open(a.path, 'wb')
+    if not w then return "Error: could not write " .. a.path end
+    w:write(table.concat(parts)); w:close()
+
+    return string.format("Edited %s: %d replacement(s)", a.path, replaced)
+end)
+
+server:tool("list_dir", "List directory contents.", {
+    type = "object",
+    properties = { path = { type = "string", default = "." } },
+}, function(a)
+    local path = a.path or "."
+    if WINDOWS then
+        return run('dir /b "' .. path .. '"', 10)
+    else
+        return run("ls -1 '" .. path:gsub("'", "'\\''") .. "'", 10)
+    end
+end)
+
+server:tool("search_files", "Search for files by pattern.", {
+    type = "object",
+    properties = {
+        pattern = { type = "string", description = "File name pattern" },
+        path = { type = "string", default = WINDOWS and "C:\\" or "/" },
+    },
+    required = { "pattern" },
+}, function(a)
+    local path = a.path or (WINDOWS and "C:\\" or "/")
+    if WINDOWS then
+        return run('dir /b /s "' .. path .. '\\' .. a.pattern .. '"', 30)
+    else
+        -- -L: follow symlinks on the start path. macOS BSD find otherwise
+        -- silently emits nothing when the start path is itself a symlink
+        -- (common on Homebrew, e.g. /usr/local/share/lua -> Cellar/…/share/lua).
+        return run("find -L '" .. path:gsub("'", "'\\''") .. "' -name '" .. a.pattern:gsub("'", "'\\''") .. "' 2>/dev/null", 30)
+    end
+end)
+
+if WINDOWS then
+    server:tool("systeminfo", "Get Windows system information.", {
+        type = "object", properties = {},
+    }, function() return run("systeminfo", 30) end)
+end
+
+io.stderr:write(string.format("lmcp %s starting on port %d (%s)\n",
+    server_name, server.port, WINDOWS and "Windows" or "POSIX"))
+server:run()