v1.2.1/#22: LMCP_HOST + LMCP_CONF env support

Adds two env vars to the packaged server.lua so hosts can switch
fully to the packaged entrypoint (combined with v1.2.0's tools.d/
plugin scan):

  LMCP_HOST — interface to bind on (default 0.0.0.0). Hosts that
              need .18-only binding (hertz) or similar single-NIC
              constraints set this. Threaded into lmcp.new opts.host.
  LMCP_CONF — path to a conf file with bearer-token entries (e.g.
              /opt/herding/etc/hertz-tools.conf). Read by lmcp.lua's
              read_conf; the `.godparticle` entry becomes the bearer
              token. Threaded into lmcp.new opts.conf.

Both unset → unchanged behavior (binds 0.0.0.0, no conf file).

Together with v1.2.0's tools.d/ scan, this lets a host like hertz
ship NO override server.lua — just an /opt/lmcp/tools.d/hertz.lua
plugin file and a systemd unit that points at the packaged
server.lua with LMCP_HOST=192.168.88.18 + LMCP_CONF=/opt/herding/
etc/hertz-tools.conf. apt upgrade then delivers all packaged
improvements automatically.

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

.gitignore

@@ -0,0 +1,13 @@
+# Generated by windows/sync.sh — see windows/README.md
+windows/pkg/lmcp.lua
+windows/pkg/server.lua
+windows/pkg/json.lua
+
+# Bundled Lua + LuaSocket runtime for the Windows MSI; downloaded
+# separately, not in git.
+windows/pkg/lua/
+
+# Editor / OS noise
+*.swp
+*.swo
+.DS_Store

example_server.lua

@@ -11,6 +11,10 @@ local server = lmcp.new("example-tools", {
     port = tonumber(arg[1]) or 8080,
 })
 
+-- The optional 5th `opts` arg to server:tool carries MCP annotations.
+-- Omit it and clients assume the worst (destructive, openWorld) — fine
+-- for prototypes; declare annotations once you know each tool's stance.
+
 server:tool("shell", "Execute a shell command", {
     type = "object",
     properties = {
@@ -24,7 +28,15 @@ server:tool("shell", "Execute a shell command", {
     local result = handle:read('*a')
     handle:close()
     return result ~= '' and result or '(no output)'
-end)
+end, {
+    annotations = {
+        title           = "Run shell",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = false,
+        openWorldHint   = true,
+    },
+})
 
 server:tool("read_file", "Read a file", {
     type = "object",
@@ -38,7 +50,15 @@ server:tool("read_file", "Read a file", {
     local content = f:read('*a')
     f:close()
     return content
-end)
+end, {
+    annotations = {
+        title           = "Read file",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = false,
+    },
+})
 
 server:tool("write_file", "Write content to a file", {
     type = "object",
@@ -53,7 +73,15 @@ server:tool("write_file", "Write content to a file", {
     f:write(args.content)
     f:close()
     return string.format("Written %d bytes to %s", #args.content, args.path)
-end)
+end, {
+    annotations = {
+        title           = "Write file",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = true,
+        openWorldHint   = false,
+    },
+})
 
 server:tool("list_dir", "List directory contents", {
     type = "object",
@@ -67,7 +95,85 @@ server:tool("list_dir", "List directory contents", {
     local result = handle:read('*a')
     handle:close()
     return result
+end, {
+    annotations = {
+        title           = "List directory",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = false,
+    },
+})
+
+-- ---- Resources (MCP primitive — see issue #5) ----
+-- Tools-only servers force the client to spend a tools/call round-trip
+-- for every read. Resources let the client list and read by URI, with a
+-- stable identity it can cache and reference in prompts.
+
+server:resource("text://greeting", {
+    name = "Greeting",
+    mimeType = "text/plain",
+}, function() return "Hello from lmcp!" end)
+
+-- Tiny binary resource: 8-byte PNG signature, demonstrates blob handling.
+server:resource("data://lmcp.png", {
+    name = "PNG signature",
+    mimeType = "image/png",
+}, function()
+    return { blob_bytes = "\x89PNG\r\n\x1a\n", mimeType = "image/png" }
 end)
 
-io.stderr:write("Starting lmcp example server...\n")
-server:run()
+-- Template: any local file. `args.path` is captured greedily (no leading
+-- slash because the template literal already includes ///).
+server:resource_template("file:///{path}", {
+    name = "Local file",
+    mimeType = "text/plain",
+}, function(args)
+    local f = io.open("/" .. args.path, "r")
+    if not f then error("file not found: /" .. args.path) end
+    local content = f:read("*a"); f:close()
+    return content
+end)
+
+-- ---- Prompts (MCP primitive — see issue #6) ----
+-- Parameterised prompt templates the client surfaces as a menu
+-- (slash-commands, snippets). Handler returns either a plain string (one
+-- user-role text message) or a full { description?, messages = {...} }
+-- shape for finer control.
+
+server:prompt("release_note", {
+    description = "Draft a release note for a given version",
+    arguments = {
+        { name = "version", description = "Tag, e.g. v0.7.1", required = true },
+        { name = "since",   description = "Previous tag",      required = false },
+    },
+}, function(args)
+    return "Write concise release notes for version " .. (args.version or "?")
+        .. " since " .. (args.since or "the previous tag")
+        .. ". Group by category (features / fixes / docs)."
+end)
+
+-- Completion for the release_note prompt's `version` argument. Returned
+-- list is filtered against `value` (prefix match) by the server's spec
+-- contract is "candidates"; clients may further filter.
+server:complete("ref/prompt", "release_note", "version", function(value, ctx)
+    local all = { "v0.5.0", "v0.5.1", "v0.5.2", "v0.5.3", "v0.5.4",
+                  "v0.6.0", "v0.7.0", "v0.7.1", "v1.0.0-rc1" }
+    if value == "" then return all end
+    local out = {}
+    for _, v in ipairs(all) do
+        if v:sub(1, #value) == value then out[#out + 1] = v end
+    end
+    return out
+end)
+
+local transport = os.getenv("LMCP_TRANSPORT") or "http"
+if transport == "stdio" then
+    if os.getenv("LMCP_PORT") then
+        io.stderr:write("lmcp: LMCP_PORT ignored in stdio mode\n")
+    end
+    server:run_stdio()
+else
+    io.stderr:write("Starting lmcp example server...\n")
+    server:run()
+end

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

examples/lmcp.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=lmcp MCP Server
+After=network.target
+
+[Service]
+Type=simple
+User=root
+# Arch ships the Lua 5.4 binary as /usr/bin/lua; Debian ships /usr/bin/lua5.4.
+# Override ExecStart if your distro differs.
+ExecStart=/usr/bin/lua /usr/share/lua/5.4/server.lua
+# Distinct name per host: foo-tools appears in /mcp listings and logs.
+Environment=LMCP_NAME=CHANGEME-tools
+Environment=LMCP_PORT=8080
+# Bearer token. Generate with: openssl rand -hex 24
+# For untrusted networks, bind to LAN-only via firewall; the server itself
+# listens on 0.0.0.0 by default.
+Environment=LMCP_TOKEN=CHANGEME
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

hub.lua

@@ -0,0 +1,636 @@
+#!/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.4",
+    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,
+    { annotations = {
+        title           = "List fleet hosts",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = true,
+    } }
+)
+
+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,
+    { annotations = {
+        title           = "Remote shell",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = false,
+        openWorldHint   = true,
+    } }
+)
+
+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,
+    { annotations = {
+        title           = "Remote read file",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = true,
+    } }
+)
+
+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,
+    { annotations = {
+        title           = "Remote write file",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = true,
+        openWorldHint   = true,
+    } }
+)
+
+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,
+    { annotations = {
+        title           = "Remote edit file",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = false,
+        openWorldHint   = true,
+    } }
+)
+
+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,
+    { annotations = {
+        title           = "Remote shell (background)",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = false,
+        openWorldHint   = true,
+    } }
+)
+
+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,
+    { annotations = {
+        title           = "Remote list directory",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = true,
+    } }
+)
+
+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,
+    { annotations = {
+        title           = "Remote find files",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = true,
+    } }
+)
+
+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()

json.lua

@@ -60,6 +60,13 @@ encode_value = function(v)
     local t = type(v)
     if v == nil or v == json.null then
         return 'null'
+    elseif v == json.empty_object then
+        -- Sentinel for forcing {} (object) instead of [] (array) when
+        -- the field semantically requires an object but is empty.
+        -- Without this, every empty Lua table goes through is_array()
+        -- and emits as [], breaking spec-strict JSON-RPC consumers
+        -- (e.g. ping result, MUST be {}).
+        return '{}'
     elseif t == 'boolean' then
         return v and 'true' or 'false'
     elseif t == 'number' then
@@ -110,9 +117,20 @@ local function decode_string(s, pos)
             pos = pos + 1
             c = s:sub(pos, pos)
             if c == 'u' then
-                local hex = s:sub(pos + 1, pos + 4)
-                parts[#parts + 1] = utf8.char(tonumber(hex, 16))
+                local cp = tonumber(s:sub(pos + 1, pos + 4), 16)
                 pos = pos + 5
+                -- Combine UTF-16 surrogate pair so non-BMP chars (emoji,
+                -- supplementary CJK) decode correctly instead of as two
+                -- lone surrogates → invalid UTF-8.
+                if cp and cp >= 0xD800 and cp <= 0xDBFF
+                   and s:sub(pos, pos + 1) == "\\u" then
+                    local lo = tonumber(s:sub(pos + 2, pos + 5), 16)
+                    if lo and lo >= 0xDC00 and lo <= 0xDFFF then
+                        cp = (cp - 0xD800) * 0x400 + (lo - 0xDC00) + 0x10000
+                        pos = pos + 6
+                    end
+                end
+                parts[#parts + 1] = utf8.char(cp)
             else
                 local esc = { n = '\n', r = '\r', t = '\t', b = '\b', f = '\f' }
                 parts[#parts + 1] = esc[c] or c
@@ -210,6 +228,12 @@ end
 -- Sentinel for JSON null
 json.null = setmetatable({}, { __tostring = function() return 'null' end })
 
+-- Sentinel for an empty JSON object ({}). Use when a field semantically
+-- requires an object but is empty — e.g. `ping` result, MCP _meta = {}.
+-- Without this, an empty Lua table goes through is_array() → '[]'.
+-- See memory project_json_empty_table_gotcha.md.
+json.empty_object = setmetatable({}, { __tostring = function() return '{}' end })
+
 -- Helper: encode a table as a JSON array even if empty
 function json.array(t)
     return setmetatable(t or {}, { __is_array = true })

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

@@ -35,7 +35,51 @@ local function tmpname()
     end
 end
 
+-- Lazy-required luasocket — only needed in the coroutine path for
+-- gettime(). Avoids forcing luasocket as a hard dep at server.lua
+-- load time (callers like example_server already require it via lmcp).
+local _socket = nil
+local function gettime()
+    if not _socket then _socket = require("socket") end
+    return _socket.gettime()
+end
+
+-- Lazy access to the lmcp module for cross-module ctx lookup (issue #11).
+-- server.lua doesn't statically require lmcp (it's an example/runtime
+-- server, not the library); but lmcp must already be loaded when we run.
+-- Defensive: if the lookup fails for any reason, current_ctx returns nil
+-- and run() falls back to non-cancellable behaviour.
+local _lmcp_mod = nil
+local function current_ctx()
+    if _lmcp_mod == false then return nil end
+    if _lmcp_mod == nil then
+        local ok, mod = pcall(require, "lmcp")
+        _lmcp_mod = ok and mod or false
+        if _lmcp_mod == false then return nil end
+    end
+    return _lmcp_mod.current_ctx and _lmcp_mod.current_ctx() or nil
+end
+
+-- in_coroutine() — true if we're running inside an lmcp dispatch
+-- coroutine (issue #20). Handles both Lua 5.4 (coroutine.running →
+-- (co, isMain)) and LuaJIT 5.1 (coroutine.running → nil on main).
+local function in_coroutine()
+    local co, is_main = coroutine.running()
+    if co == nil then return false end       -- 5.1 / LuaJIT main
+    if is_main then return false end          -- 5.4 main thread
+    return true
+end
+
 local function sleep_ms(ms)
+    -- Coroutine-aware: yield with a wake deadline instead of busy-blocking.
+    -- The lmcp event loop services I/O for other connections while this
+    -- coroutine sleeps, then resumes it once the deadline elapses.
+    -- (Issue #20: gives concurrent tool dispatch without changing handler
+    -- source code — tools that go through run() get it for free.)
+    if in_coroutine() then
+        coroutine.yield({ wake_at = gettime() + (ms / 1000) })
+        return
+    end
     if WINDOWS then
         -- ping loopback: ~1s per -n count. For sub-second, use busy-wait.
         if ms < 500 then
@@ -78,6 +122,35 @@ local function run(cmd, timeout_sec)
     local out_file = base .. ".out"
     local done_file = base .. ".done"
 
+    -- Wall-clock deadline rather than an accumulated interval-counter:
+    -- when we're inside a dispatch coroutine (issue #20), the scheduler
+    -- may delay our resume by more than `interval`, so an accumulator
+    -- diverges from real elapsed. gettime() comparison stays honest in
+    -- both busy-poll and yield-resume modes.
+    --
+    -- Auto-cancellation (issue #11): if a ctx is available on the
+    -- running coroutine AND it has been cancelled, exit the polling
+    -- loop early. The interval is capped at 500ms when a ctx is
+    -- present so worst-case cancel latency is ~0.5s, not ~2s.
+    local started = gettime()
+    local cancelled = false
+    local function poll_loop()
+        local interval = WINDOWS and 100 or 50  -- ms
+        while gettime() - started < timeout_sec do
+            if file_exists(done_file) then return true end
+            local ctx = current_ctx()
+            if ctx and ctx.cancelled and ctx.cancelled() then
+                cancelled = true
+                return false
+            end
+            sleep_ms(interval)
+            if interval < 2000 then interval = math.floor(interval * 1.5) end
+            -- When cancellable, cap so we can respond to cancel quickly.
+            if ctx and interval > 500 then interval = 500 end
+        end
+        return false
+    end
+
     if WINDOWS then
         -- Write a batch wrapper that runs the command and signals completion
         local bat_file = base .. ".bat"
@@ -89,22 +162,14 @@ local function run(cmd, timeout_sec)
         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 completed = poll_loop()
         local output = read_file(out_file)
         remove_silent(bat_file)
         remove_silent(out_file)
         remove_silent(done_file)
 
-        if elapsed >= timeout_sec * 1000 then
+        if not completed then
+            if cancelled then return "(cancelled)" end
             return output or ("Error: command timed out after " .. timeout_sec .. "s")
         end
         return output and output ~= "" and output or "(no output)"
@@ -117,20 +182,13 @@ local function run(cmd, timeout_sec)
         )
         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 completed = poll_loop()
         local output = read_file(out_file)
         remove_silent(out_file)
         remove_silent(done_file)
 
-        if elapsed >= timeout_sec * 1000 then
+        if not completed then
+            if cancelled then return "(cancelled)" end
             return output or ("Error: command timed out after " .. timeout_sec .. "s")
         end
         return output and output ~= "" and output or "(no output)"
@@ -142,6 +200,13 @@ end
 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,
+    -- LMCP_HOST: bind interface (default 0.0.0.0). Hosts that need
+    -- single-interface binding (hertz: 192.168.88.18 only) set this.
+    host = os.getenv("LMCP_HOST"),
+    -- LMCP_CONF: path to a conf file with bearer-token entries
+    -- (e.g. /opt/herding/etc/hertz-tools.conf). Read by lmcp.lua's
+    -- read_conf; the `.godparticle` entry becomes the bearer token.
+    conf = os.getenv("LMCP_CONF"),
 })
 
 -- ---- Tools ----
@@ -168,7 +233,66 @@ server:tool("shell", "Execute a shell command.", {
         cmd = 'powershell -NoProfile -Command "' .. cmd:gsub('"', '\\"') .. '"'
     end
     return run(cmd, a.timeout or 120)
-end)
+end, {
+    annotations = {
+        title           = "Run shell",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = false,
+        openWorldHint   = true,
+    },
+})
+
+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, {
+        annotations = {
+            title           = "Run shell (background)",
+            readOnlyHint    = false,
+            destructiveHint = true,
+            idempotentHint  = false,
+            openWorldHint   = true,
+        },
+    })
 
 server:tool("read_file", "Read a file.", {
     type = "object",
@@ -178,7 +302,15 @@ server:tool("read_file", "Read a file.", {
     local c = read_file(a.path)
     if not c then return "Error: could not read " .. a.path end
     return c
-end)
+end, {
+    annotations = {
+        title           = "Read file",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = false,
+    },
+})
 
 server:tool("write_file", "Write content to a file.", {
     type = "object",
@@ -192,7 +324,15 @@ server:tool("write_file", "Write content to a file.", {
     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)
+end, {
+    annotations = {
+        title           = "Write file",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = true,
+        openWorldHint   = false,
+    },
+})
 
 server:tool("edit_file", "Replace exact text in a file (literal match). Fails unless old_string is unique, unless replace_all=true.", {
     type = "object",
@@ -246,7 +386,15 @@ server:tool("edit_file", "Replace exact text in a file (literal match). Fails un
     w:write(table.concat(parts)); w:close()
 
     return string.format("Edited %s: %d replacement(s)", a.path, replaced)
-end)
+end, {
+    annotations = {
+        title           = "Edit file",
+        readOnlyHint    = false,
+        destructiveHint = true,
+        idempotentHint  = false,
+        openWorldHint   = false,
+    },
+})
 
 server:tool("list_dir", "List directory contents.", {
     type = "object",
@@ -258,7 +406,254 @@ server:tool("list_dir", "List directory contents.", {
     else
         return run("ls -1 '" .. path:gsub("'", "'\\''") .. "'", 10)
     end
-end)
+end, {
+    annotations = {
+        title           = "List directory",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = false,
+    },
+})
+
+-- ---- fetch: HTTP GET/HEAD with bounded body and optional HTML→plain rendering ----
+--
+-- Contract (per Phase 4 plan, issue #3):
+--   1. Transfer cap is enforced by curl --max-filesize, not by post-hoc
+--      slicing. curl aborts mid-stream with exit 63 and the body file
+--      holds up-to-N bytes (verified Phase 0).
+--   2. Curl exit code is recovered via -w "exit=%{exitcode}\n" because
+--      run() captures stdout-only. Line-anchored parsing because
+--      run()'s 2>&1 merges curl's stderr into the same stream.
+--   3. ok = (exit == 0 or exit == 63). exit 63 is a deliberate
+--      truncation, not a failure — set truncated=true and ok=true.
+--   4. URL whitelist (RFC-3986-ish) rejects whitespace, control chars,
+--      both quote styles in one shot — no per-platform branching.
+--   5. Renderer chain (plain, text/html only): pandoc → lynx → w3m →
+--      pure-Lua strip. Probe results are process-local cached.
+--   6. os.execute return shape differs between Lua 5.1/LuaJIT (number)
+--      and Lua 5.4 (boolean,...). fetch_have normalises both.
+--   7. timeout_s covers fetch *and* render combined.
+
+local function fetch_html_strip(s)
+    if not s or s == "" then return "" end
+    s = s:gsub("<script.->.-</script>", " ")
+    s = s:gsub("<style.->.-</style>", " ")
+    s = s:gsub("<!%-%-.-%-%->", " ")
+    s = s:gsub("<[^>]+>", " ")
+    local ents = { amp = "&", lt = "<", gt = ">", quot = '"', apos = "'", nbsp = " " }
+    s = s:gsub("&(%a+);", function(n) return ents[n] or ("&" .. n .. ";") end)
+    s = s:gsub("&#(%d+);",  function(n) return string.char(tonumber(n)) end)
+    s = s:gsub("&#x(%x+);", function(n) return string.char(tonumber(n, 16)) end)
+    s = s:gsub("%s+", " "):gsub("^%s+", ""):gsub("%s+$", "")
+    return s
+end
+
+local _fetch_have_cache = {}
+local function fetch_have(cmd)
+    local cached = _fetch_have_cache[cmd]
+    if cached ~= nil then return cached end
+    local probe
+    if WINDOWS then
+        probe = "where " .. cmd .. " >NUL 2>&1"
+    else
+        probe = "command -v " .. cmd .. " >/dev/null 2>&1"
+    end
+    local rc = os.execute(probe)
+    if type(rc) == "number" then rc = (rc == 0) end
+    rc = rc and true or false
+    _fetch_have_cache[cmd] = rc
+    return rc
+end
+
+local function fetch_safe_url(url)
+    if type(url) ~= "string" or url == "" then
+        return false, "url required"
+    end
+    if not url:match("^https?://") then
+        return false, "url scheme must be http or https"
+    end
+    if not url:match("^https?://[%w%-._~:/?#%[%]@!%$&()*+,;=%%]+$") then
+        return false, "url contains disallowed characters (whitespace, quote, control)"
+    end
+    return true
+end
+
+local function fetch_parse_kv(blob)
+    local out = {}
+    for line in blob:gmatch("[^\r\n]+") do
+        local k, v = line:match("^(http_code)=(.*)$")
+        if k then out[k] = v end
+        k, v = line:match("^(content_type)=(.*)$")
+        if k then out[k] = v end
+        k, v = line:match("^(size_download)=(.*)$")
+        if k then out[k] = v end
+        k, v = line:match("^(exit)=(.*)$")
+        if k then out[k] = v end
+    end
+    return out
+end
+
+local function fetch_render_plain(body, body_file)
+    -- Try external renderers in order; each receives body_file on stdin.
+    local order = { "pandoc", "lynx", "w3m" }
+    for _, r in ipairs(order) do
+        if fetch_have(r) then
+            local cmd
+            if r == "pandoc" then
+                cmd = "pandoc -f html -t plain"
+            elseif r == "lynx" then
+                cmd = "lynx -stdin -dump -nolist -force_html"
+            else  -- w3m
+                cmd = "w3m -dump -T text/html"
+            end
+            local pipe
+            if WINDOWS then
+                pipe = cmd .. ' < "' .. body_file .. '"'
+            else
+                pipe = cmd .. " < '" .. body_file:gsub("'", "'\\''") .. "'"
+            end
+            local out = run(pipe, 15)
+            if out and out ~= "" and not out:match("^Error:") then
+                return out, r
+            end
+        end
+    end
+    return fetch_html_strip(body), "lua-strip"
+end
+
+server:tool("fetch",
+    "HTTP GET/HEAD with bounded body and optional HTML→plain rendering. " ..
+    "timeout_s covers the entire fetch+render combined.",
+    {
+        type = "object",
+        properties = {
+            url        = { type = "string",  description = "http(s) URL" },
+            method     = { type = "string",  description = "GET or HEAD", default = "GET" },
+            render     = { type = "string",  description = "plain | html | raw", default = "plain" },
+            max_bytes  = { type = "integer", description = "Hard cap on body bytes returned", default = 65536 },
+            timeout_s  = { type = "integer", description = "Wall-clock cap for entire call", default = 20 },
+            user_agent = { type = "string",  description = "Custom User-Agent", default = "lmcp-fetch/1.0" },
+        },
+        required = { "url" },
+    },
+    function(a)
+        local ok_url, url_err = fetch_safe_url(a.url)
+        if not ok_url then
+            return { ok = false, status = 0, content_type = "", bytes_read = 0,
+                     truncated = false, renderer = "raw", body = "", error = url_err }
+        end
+
+        local method = (a.method or "GET"):upper()
+        if method ~= "GET" and method ~= "HEAD" then
+            return { ok = false, status = 0, content_type = "", bytes_read = 0,
+                     truncated = false, renderer = "raw", body = "",
+                     error = "method must be GET or HEAD" }
+        end
+
+        local render    = a.render     or "plain"
+        local max_bytes = tonumber(a.max_bytes) or 65536
+        local timeout_s = tonumber(a.timeout_s) or 20
+        local ua        = a.user_agent or "lmcp-fetch/1.0"
+
+        local base      = tmpname()
+        local hdr_file  = base .. ".hdr"
+        local body_file = base .. ".body"
+
+        local wfmt = "http_code=%{http_code}\\ncontent_type=%{content_type}\\nsize_download=%{size_download}\\nexit=%{exitcode}\\n"
+
+        local curl_cmd
+        if WINDOWS then
+            local head_flag = (method == "HEAD") and " -I" or ""
+            curl_cmd = string.format(
+                'curl -sS --proto =http,https%s -X %s --max-time %d --max-filesize %d -A "%s" -D "%s" -o "%s" -w "%s" "%s"',
+                head_flag, method, timeout_s, max_bytes, ua, hdr_file, body_file, wfmt, a.url
+            )
+        else
+            local head_flag = (method == "HEAD") and " -I" or ""
+            curl_cmd = string.format(
+                "curl -sS --proto =http,https%s -X %s --max-time %d --max-filesize %d -A '%s' -D '%s' -o '%s' -w '%s' '%s'",
+                head_flag, method, timeout_s, max_bytes, ua, hdr_file, body_file, wfmt, a.url
+            )
+        end
+
+        local raw_out = run(curl_cmd, timeout_s + 5) or ""
+        local kv = fetch_parse_kv(raw_out)
+        local exit = tonumber(kv.exit or "") or -1
+        local http_code = tonumber(kv.http_code or "0") or 0
+        local content_type = kv.content_type or ""
+
+        local body = ""
+        if method ~= "HEAD" then
+            local bf = io.open(body_file, 'rb')
+            if bf then body = bf:read('*a') or ""; bf:close() end
+        end
+        remove_silent(hdr_file)
+        remove_silent(body_file)
+
+        -- Defensive cap (curl already capped, but enforce on the wire).
+        if #body > max_bytes then body = body:sub(1, max_bytes) end
+        local bytes_read = #body
+        local truncated  = (exit == 63)
+        local transport_ok = (exit == 0 or exit == 63)
+
+        if not transport_ok then
+            -- Strip the -w block from raw_out for a clean error message.
+            local err_msg = raw_out:gsub("http_code=[^\n]*\n?", "")
+                                   :gsub("content_type=[^\n]*\n?", "")
+                                   :gsub("size_download=[^\n]*\n?", "")
+                                   :gsub("exit=[^\n]*\n?", "")
+                                   :gsub("^%s+", ""):gsub("%s+$", "")
+            if err_msg == "" then err_msg = "curl exit " .. tostring(exit) end
+            return { ok = false, status = 0, content_type = content_type,
+                     bytes_read = 0, truncated = false, renderer = "raw",
+                     body = "", error = err_msg }
+        end
+
+        local renderer, out_body
+        if render == "raw" or render == "html" or method == "HEAD" then
+            renderer, out_body = "raw", body
+        elseif render == "plain" then
+            local is_html = content_type:match("text/html") or content_type:match("xml")
+            if is_html and body ~= "" then
+                -- Re-materialise body to a temp for the renderer pipe.
+                local rf = tmpname() .. ".rbody"
+                local f = io.open(rf, 'wb')
+                if f then f:write(body); f:close() end
+                out_body, renderer = fetch_render_plain(body, rf)
+                remove_silent(rf)
+            else
+                renderer, out_body = "raw", body
+            end
+        else
+            return { ok = false, status = 0, content_type = content_type,
+                     bytes_read = 0, truncated = false, renderer = "raw",
+                     body = "", error = "render must be plain, html, or raw" }
+        end
+
+        if #out_body > max_bytes then out_body = out_body:sub(1, max_bytes) end
+
+        return {
+            ok           = true,
+            status       = http_code,
+            content_type = content_type,
+            bytes_read   = bytes_read,
+            truncated    = truncated,
+            renderer     = renderer,
+            body         = out_body,
+        }
+    end, {
+        annotations = {
+            title           = "HTTP GET/HEAD",
+            readOnlyHint    = true,
+            destructiveHint = false,
+            -- Idempotent in MCP sense: the tool itself has no effect on
+            -- its own environment. World-side variability is conveyed
+            -- by openWorldHint.
+            idempotentHint  = true,
+            openWorldHint   = true,
+        },
+    })
 
 server:tool("search_files", "Search for files by pattern.", {
     type = "object",
@@ -272,16 +667,460 @@ server:tool("search_files", "Search for files by pattern.", {
     if WINDOWS then
         return run('dir /b /s "' .. path .. '\\' .. a.pattern .. '"', 30)
     else
-        return run("find '" .. path:gsub("'", "'\\''") .. "' -name '" .. a.pattern:gsub("'", "'\\''") .. "' 2>/dev/null", 30)
+        -- -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)
+end, {
+    annotations = {
+        title           = "Find files by pattern",
+        readOnlyHint    = true,
+        destructiveHint = false,
+        idempotentHint  = true,
+        openWorldHint   = false,
+    },
+})
+
+-- ---- web_search: pluggable-backend search with normalised result shape ----
+--
+-- Contract (per Phase 4 plan + Phase 5 review actions, issue #4):
+--   1. Backend selection: explicit LMCP_SEARCH_BACKEND (lower+trim) wins;
+--      else first-present of SEARXNG_URL, TAVILY_API_KEY, BRAVE_API_KEY;
+--      else "ddg" zero-config.
+--   2. Result envelope is always:
+--      { ok, backend, query, results=[{title,url,snippet,age?}], error? }
+--      On failure: ok=false, results=[], error=string.
+--   3. DDG is best-effort. The HTML endpoint serves anti-bot 202 pages
+--      from many IP ranges; when the parser matches 0 results from a
+--      200/202, surface a structured "parser found 0" error rather
+--      than a silent empty list.
+--   4. DDG parser iterates per-result-block, not per-class globally —
+--      otherwise a missing snippet shifts later snippets onto wrong titles.
+--   5. DDG result URLs are unwrapped from /l/?uddg=<URLENCODED>. If
+--      unwrap fails (no uddg= or non-http(s) result), the row is dropped.
+--   6. JSON backends (searxng/tavily/brave) use json.decode under pcall.
+--      json.lua patched in this issue to combine UTF-16 surrogate pairs
+--      so emoji/non-BMP CJK in snippets render correctly.
+--   7. Tavily uses Authorization: Bearer <key> header, not body, so the
+--      key never lands in a tempfile.
+--   8. URL query strings are RFC-3986 unreserved-only encoded. After
+--      encoding, the only attacker-controlled portion is shell-safe
+--      inside single quotes.
+
+local function ws_url_encode(s)
+    return (s:gsub("([^%w%-._~])", function(c)
+        return string.format("%%%02X", string.byte(c))
+    end))
+end
+
+local function ws_url_decode(s)
+    s = s:gsub("%%(%x%x)", function(h) return string.char(tonumber(h, 16)) end)
+    return s
+end
+
+local function ws_ddg_unwrap(href)
+    -- href shape: //duckduckgo.com/l/?uddg=<URLENC>&rut=<hex>
+    -- &amp; in raw HTML; pattern strips the entity first.
+    href = href:gsub("&amp;", "&")
+    local enc = href:match("[?&]uddg=([^&]+)")
+    if not enc then return nil end
+    local decoded = ws_url_decode(enc)
+    if not decoded:match("^https?://") then return nil end
+    return decoded
+end
+
+local function ws_safe_envurl(url)
+    if not url or url == "" then return false, "url empty" end
+    if not url:match("^https?://") then return false, "url scheme must be http(s)" end
+    if not url:match("^https?://[%w%-._~:/?#%[%]@!%$&()*+,;=%%]+$") then
+        return false, "url contains disallowed characters"
+    end
+    return true
+end
+
+local function ws_safe_key(s)
+    if not s or s == "" then return false, "empty" end
+    if s:find("['\"\n\r]") then return false, "contains quote or newline" end
+    return true
+end
+
+local function ws_curl_run(curl_cmd, body_file, timeout_s)
+    local raw_out = run(curl_cmd, timeout_s + 5) or ""
+    local http_code = tonumber(raw_out:match("http_code=(%d+)") or "0") or 0
+    local exit      = tonumber(raw_out:match("exit=(%-?%d+)") or "-1") or -1
+    local body = ""
+    local bf = io.open(body_file, 'rb')
+    if bf then body = bf:read('*a') or ""; bf:close() end
+    remove_silent(body_file)
+    return body, http_code, exit, raw_out
+end
+
+local function ws_curl_err(raw_out, http_code, exit, default)
+    local err = raw_out:gsub("http_code=[^\n]*\n?", "")
+                       :gsub("exit=[^\n]*\n?", "")
+                       :gsub("^%s+", ""):gsub("%s+$", "")
+    if err ~= "" then return err end
+    if http_code ~= 0 and http_code ~= 200 then
+        return string.format("HTTP %d", http_code)
+    end
+    return default or ("curl exit " .. tostring(exit))
+end
+
+-- ---- DDG (HTML scrape, zero-config) ----
+local function ws_ddg(query, n, region, time_range, safesearch)
+    local kp = ({off = -2, moderate = -1, strict = 1})[safesearch] or -1
+    local df = ({day = "d", week = "w", month = "m", year = "y"})[time_range or ""] or ""
+    local url = "https://html.duckduckgo.com/html/?q=" .. ws_url_encode(query)
+                .. "&kp=" .. tostring(kp)
+    if df ~= "" then url = url .. "&df=" .. df end
+    if region and region ~= "" then url = url .. "&kl=" .. ws_url_encode(region) end
+
+    local body_file = tmpname() .. ".body"
+    local wfmt = "http_code=%{http_code}\\nexit=%{exitcode}\\n"
+    local cmd
+    if WINDOWS then
+        cmd = string.format(
+            'curl -sS --proto =https --max-time 15 -A "lmcp-search/1.0" -o "%s" -w "%s" "%s"',
+            body_file, wfmt, url)
+    else
+        cmd = string.format(
+            "curl -sS --proto =https --max-time 15 -A 'lmcp-search/1.0' -o '%s' -w '%s' '%s'",
+            body_file, wfmt, url)
+    end
+    local body, http_code, exit, raw = ws_curl_run(cmd, body_file, 15)
+    if exit ~= 0 then
+        return nil, ws_curl_err(raw, http_code, exit, "ddg request failed")
+    end
+
+    -- Per-result-block iteration (avoids title↔snippet mispairing).
+    -- Split on the opening <div class="result results_links"… boundary
+    -- rather than on close-tag depth — DDG nests multiple <div>s inside
+    -- each block, so a fixed close-tag pattern is fragile.
+    local block_pat = '<div class="result results_links[^"]-"[^>]*>'
+    local positions = {}
+    for s in body:gmatch("()" .. block_pat) do positions[#positions + 1] = s end
+    positions[#positions + 1] = #body + 1  -- sentinel end-of-body
+
+    local results = {}
+    for i = 1, #positions - 1 do
+        local block = body:sub(positions[i], positions[i + 1] - 1)
+        local href, title_raw = block:match('<a[^>]-class="result__a"[^>]-href="([^"]+)"[^>]*>(.-)</a>')
+        if href and title_raw then
+            local real_url = ws_ddg_unwrap(href)
+            if real_url then
+                local snip_raw = block:match('<a[^>]-class="result__snippet"[^>]*>(.-)</a>') or ""
+                local title = fetch_html_strip(title_raw):sub(1, 200)
+                local snippet = fetch_html_strip(snip_raw):sub(1, 280)
+                results[#results + 1] = { title = title, url = real_url, snippet = snippet }
+                if #results >= n then break end
+            end
+        end
+    end
+
+    if #results == 0 then
+        return nil, "ddg parser matched no results (anti-bot challenge or markup change)"
+    end
+    return results, nil
+end
+
+-- ---- SearXNG (JSON) ----
+local function ws_searxng(query, n, region, time_range, safesearch)
+    local base = os.getenv("SEARXNG_URL")
+    if not base or base == "" then return nil, "searxng requires SEARXNG_URL" end
+    base = base:gsub("/+$", "")
+    local ok, errmsg = ws_safe_envurl(base)
+    if not ok then return nil, "SEARXNG_URL: " .. errmsg end
+
+    local ss_map = { off = 0, moderate = 1, strict = 2 }
+    local url = base .. "/search?q=" .. ws_url_encode(query)
+                .. "&format=json&safesearch=" .. tostring(ss_map[safesearch] or 1)
+    if time_range and time_range ~= "" then
+        url = url .. "&time_range=" .. ws_url_encode(time_range)
+    end
+    if region and region ~= "" then
+        url = url .. "&language=" .. ws_url_encode(region)
+    end
+
+    local body_file = tmpname() .. ".body"
+    local wfmt = "http_code=%{http_code}\\nexit=%{exitcode}\\n"
+    local cmd
+    if WINDOWS then
+        cmd = string.format(
+            'curl -sS --proto =https --max-time 15 -A "lmcp-search/1.0" -o "%s" -w "%s" "%s"',
+            body_file, wfmt, url)
+    else
+        cmd = string.format(
+            "curl -sS --proto =https --max-time 15 -A 'lmcp-search/1.0' -o '%s' -w '%s' '%s'",
+            body_file, wfmt, url)
+    end
+    local body, http_code, exit, raw = ws_curl_run(cmd, body_file, 15)
+    if exit ~= 0 then
+        return nil, ws_curl_err(raw, http_code, exit, "searxng request failed")
+    end
+    if http_code ~= 200 then
+        return nil, string.format("searxng HTTP %d", http_code)
+    end
+
+    local pj_ok, d = pcall(require('json').decode, body)
+    if not pj_ok or type(d) ~= "table" or type(d.results) ~= "table" then
+        return nil, "searxng response is not valid JSON or missing 'results'"
+    end
+
+    local out = {}
+    for _, r in ipairs(d.results) do
+        if r.url and r.url ~= "" then
+            out[#out + 1] = {
+                title   = (r.title or ""):sub(1, 200),
+                url     = r.url,
+                snippet = (r.content or ""):sub(1, 280),
+                age     = r.publishedDate,
+            }
+            if #out >= n then break end
+        end
+    end
+    if #out == 0 then
+        return nil, "searxng returned 0 results"
+    end
+    return out, nil
+end
+
+-- ---- Tavily (JSON POST) ----
+local function ws_tavily(query, n)
+    local key = os.getenv("TAVILY_API_KEY")
+    if not key or key == "" then return nil, "tavily requires TAVILY_API_KEY" end
+    local ok, errmsg = ws_safe_key(key)
+    if not ok then return nil, "TAVILY_API_KEY: " .. errmsg end
+
+    local body_in = string.format(
+        '{"query":%s,"max_results":%d,"search_depth":"basic","include_answer":false}',
+        require('json').encode(query), n)
+
+    local in_file  = tmpname() .. ".json"
+    local out_file = tmpname() .. ".body"
+    local fw = io.open(in_file, 'wb')
+    if not fw then return nil, "could not write tavily request body" end
+    fw:write(body_in); fw:close()
+
+    local wfmt = "http_code=%{http_code}\\nexit=%{exitcode}\\n"
+    local cmd
+    if WINDOWS then
+        cmd = string.format(
+            'curl -sS --proto =https --max-time 20 -X POST -H "Content-Type: application/json" -H "Authorization: Bearer %s" --data-binary "@%s" -o "%s" -w "%s" "https://api.tavily.com/search"',
+            key, in_file, out_file, wfmt)
+    else
+        cmd = string.format(
+            "curl -sS --proto =https --max-time 20 -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer %s' --data-binary '@%s' -o '%s' -w '%s' 'https://api.tavily.com/search'",
+            key, in_file, out_file, wfmt)
+    end
+    local body, http_code, exit, raw = ws_curl_run(cmd, out_file, 20)
+    remove_silent(in_file)
+    if exit ~= 0 then
+        return nil, ws_curl_err(raw, http_code, exit, "tavily request failed")
+    end
+    if http_code ~= 200 then
+        return nil, string.format("tavily HTTP %d", http_code)
+    end
+
+    local pj_ok, d = pcall(require('json').decode, body)
+    if not pj_ok or type(d) ~= "table" or type(d.results) ~= "table" then
+        return nil, "tavily response is not valid JSON or missing 'results'"
+    end
+
+    local out = {}
+    for _, r in ipairs(d.results) do
+        if r.url and r.url ~= "" then
+            out[#out + 1] = {
+                title   = (r.title or ""):sub(1, 200),
+                url     = r.url,
+                snippet = (r.content or ""):sub(1, 280),
+            }
+            if #out >= n then break end
+        end
+    end
+    if #out == 0 then return nil, "tavily returned 0 results" end
+    return out, nil
+end
+
+-- ---- Brave Search (JSON GET, header auth) ----
+local function ws_brave(query, n, region, safesearch)
+    local key = os.getenv("BRAVE_API_KEY")
+    if not key or key == "" then return nil, "brave requires BRAVE_API_KEY" end
+    local ok, errmsg = ws_safe_key(key)
+    if not ok then return nil, "BRAVE_API_KEY: " .. errmsg end
+
+    local url = "https://api.search.brave.com/res/v1/web/search?q=" .. ws_url_encode(query)
+                .. "&count=" .. tostring(n)
+                .. "&safesearch=" .. (safesearch or "moderate")
+    if region and region ~= "" then url = url .. "&country=" .. ws_url_encode(region) end
+
+    local body_file = tmpname() .. ".body"
+    local wfmt = "http_code=%{http_code}\\nexit=%{exitcode}\\n"
+    local cmd
+    if WINDOWS then
+        cmd = string.format(
+            'curl -sS --proto =https --max-time 15 -A "lmcp-search/1.0" -H "Accept: application/json" -H "X-Subscription-Token: %s" -o "%s" -w "%s" "%s"',
+            key, body_file, wfmt, url)
+    else
+        cmd = string.format(
+            "curl -sS --proto =https --max-time 15 -A 'lmcp-search/1.0' -H 'Accept: application/json' -H 'X-Subscription-Token: %s' -o '%s' -w '%s' '%s'",
+            key, body_file, wfmt, url)
+    end
+    local body, http_code, exit, raw = ws_curl_run(cmd, body_file, 15)
+    if exit ~= 0 then
+        return nil, ws_curl_err(raw, http_code, exit, "brave request failed")
+    end
+    if http_code ~= 200 then
+        return nil, string.format("brave HTTP %d", http_code)
+    end
+
+    local pj_ok, d = pcall(require('json').decode, body)
+    if not pj_ok or type(d) ~= "table" or type(d.web) ~= "table" or type(d.web.results) ~= "table" then
+        return nil, "brave response is not valid JSON or missing 'web.results'"
+    end
+
+    local out = {}
+    for _, r in ipairs(d.web.results) do
+        if r.url and r.url ~= "" then
+            out[#out + 1] = {
+                title   = (r.title or ""):sub(1, 200),
+                url     = r.url,
+                snippet = (r.description or ""):sub(1, 280),
+                age     = r.age,
+            }
+            if #out >= n then break end
+        end
+    end
+    if #out == 0 then return nil, "brave returned 0 results" end
+    return out, nil
+end
+
+local function ws_pick_backend()
+    local explicit = os.getenv("LMCP_SEARCH_BACKEND") or ""
+    explicit = explicit:lower():match("^%s*(.-)%s*$") or ""
+    if explicit ~= "" then return explicit end
+    if (os.getenv("SEARXNG_URL")    or "") ~= "" then return "searxng" end
+    if (os.getenv("TAVILY_API_KEY") or "") ~= "" then return "tavily"  end
+    if (os.getenv("BRAVE_API_KEY")  or "") ~= "" then return "brave"   end
+    return "ddg"
+end
+
+server:tool("web_search",
+    "Web search returning [{title, url, snippet, age?}]. Backend selected " ..
+    "via LMCP_SEARCH_BACKEND env (searxng|tavily|brave|ddg); auto-picks the " ..
+    "first configured backend, falling back to ddg (best-effort, often anti-bot blocked).",
+    {
+        type = "object",
+        properties = {
+            query       = { type = "string",  description = "Search query" },
+            max_results = { type = "integer", description = "1..25", default = 8 },
+            region      = { type = "string",  description = "Backend-specific locale (e.g. 'de-de')", default = "" },
+            time_range  = { type = "string",  description = "'' | day | week | month | year", default = "" },
+            safesearch  = { type = "string",  description = "off | moderate | strict",       default = "moderate" },
+        },
+        required = { "query" },
+    },
+    function(a)
+        local query = (a.query or ""):match("^%s*(.-)%s*$") or ""
+        if query == "" then
+            return { ok = false, backend = "", query = "", results = {}, error = "query required" }
+        end
+        local n = tonumber(a.max_results) or 8
+        if n < 1 then n = 1 elseif n > 25 then n = 25 end
+
+        local backend = ws_pick_backend()
+        local region, time_range, safesearch = a.region or "", a.time_range or "", a.safesearch or "moderate"
+
+        local results, err
+        if backend == "ddg" then
+            results, err = ws_ddg(query, n, region, time_range, safesearch)
+        elseif backend == "searxng" then
+            results, err = ws_searxng(query, n, region, time_range, safesearch)
+        elseif backend == "tavily" then
+            results, err = ws_tavily(query, n)
+        elseif backend == "brave" then
+            results, err = ws_brave(query, n, region, safesearch)
+        else
+            return { ok = false, backend = backend, query = query, results = {},
+                     error = "unknown backend: " .. backend }
+        end
+
+        if err then
+            return { ok = false, backend = backend, query = query, results = {}, error = err }
+        end
+        return { ok = true, backend = backend, query = query, results = results }
+    end, {
+        annotations = {
+            title           = "Web search",
+            readOnlyHint    = true,
+            destructiveHint = false,
+            idempotentHint  = true,
+            openWorldHint   = true,
+        },
+    })
 
 if WINDOWS then
     server:tool("systeminfo", "Get Windows system information.", {
         type = "object", properties = {},
-    }, function() return run("systeminfo", 30) end)
+    }, function() return run("systeminfo", 30) end, {
+        annotations = {
+            title           = "Windows system info",
+            readOnlyHint    = true,
+            destructiveHint = false,
+            idempotentHint  = true,
+            openWorldHint   = false,
+        },
+    })
 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()
+-- ---- host-local tool plugins (issue #22) ----
+-- Load every .lua file in LMCP_TOOLS_DIR (default /opt/lmcp/tools.d on POSIX,
+-- %ProgramData%\lmcp\tools.d on Windows). Each file is invoked as a function
+-- receiving the configured `server` instance and the `run` helper:
+--
+--     local server, run = ...
+--     server:tool("my_local_tool", "...", {...}, function(a) return run(...) end)
+--
+-- This is the standard plugin pattern (nginx conf.d/, systemd-tmpfiles.d, …).
+-- Hosts can ship their own tools alongside the packaged generics without
+-- forking the upstream server.lua.
+local plugin_dir = os.getenv("LMCP_TOOLS_DIR")
+    or (WINDOWS and (os.getenv("ProgramData") or "C:\\ProgramData") .. "\\lmcp\\tools.d"
+                 or "/opt/lmcp/tools.d")
+local list_cmd = WINDOWS
+    and ('dir /b "' .. plugin_dir .. '\\*.lua" 2>nul')
+    or  ('ls -1 "'  .. plugin_dir ..  '"/*.lua 2>/dev/null')
+local lh = io.popen(list_cmd)
+if lh then
+    for path in lh:lines() do
+        -- On Windows `dir /b` emits bare filenames; prefix the dir.
+        local full = path:match("[/\\]") and path
+                  or (plugin_dir .. (WINDOWS and "\\" or "/") .. path)
+        local chunk, err = loadfile(full)
+        if chunk then
+            local ok, perr = pcall(chunk, server, run)
+            if ok then
+                io.stderr:write("lmcp: loaded plugin " .. full .. "\n")
+            else
+                io.stderr:write("lmcp: plugin " .. full .. " errored: "
+                    .. tostring(perr) .. "\n")
+            end
+        else
+            io.stderr:write("lmcp: plugin " .. full .. " load error: "
+                .. tostring(err) .. "\n")
+        end
+    end
+    lh:close()
+end
+
+local transport = os.getenv("LMCP_TRANSPORT") or "http"
+if transport == "stdio" then
+    if os.getenv("LMCP_PORT") then
+        io.stderr:write("lmcp: LMCP_PORT ignored in stdio mode\n")
+    end
+    server:run_stdio()
+else
+    io.stderr:write(string.format("lmcp %s starting on port %d (%s)\n",
+        server_name, server.port, WINDOWS and "Windows" or "POSIX"))
+    server:run()
+end

windows/README.md

@@ -0,0 +1,57 @@
+# lmcp Windows MSI build
+
+This directory contains the WiX manifest and packaging files for the
+Windows MSI build of lmcp.
+
+## Recommended: cross-build on Linux (one command)
+
+```sh
+./build-msi.sh /path/to/output/dir
+```
+
+Downloads Lua 5.4 Win64 binaries from LuaBinaries, cross-compiles
+LuaSocket via `mingw-w64`, stages `pkg/lua/`, and runs `wixl` to
+produce `lmcp-<version>.msi`. No Windows VM required.
+
+Prereqs on a Debian/Ubuntu builder:
+```sh
+sudo apt install wixl unzip gcc-mingw-w64-x86-64 \
+                 binutils-mingw-w64-x86-64 mingw-w64-x86-64-dev curl
+```
+
+Version comes from `lmcp.wxs` `Version="…"`. Bump that before
+building a release.
+
+## Alternative: build on Windows via WiX toolset
+
+```cmd
+sync.sh                                  REM see "tracked vs. generated"
+REM ensure pkg/lua/ has the runtime — see below
+candle.exe lmcp.wxs
+light.exe lmcp.wixobj -o lmcp-1.x.y.msi
+```
+
+## What's tracked vs. generated
+
+- **Tracked** (edit in git):
+  - `lmcp.wxs` — WiX MSI manifest
+  - `sync.sh` — copies root .lua sources → `pkg/`
+  - `README.md` — this file
+  - `pkg/install_service.bat` — Windows service installer
+  - `pkg/start.bat` — manual launcher
+
+- **Generated / external** (gitignored):
+  - `pkg/lmcp.lua`, `pkg/server.lua`, `pkg/json.lua` — produced by
+    `sync.sh`. Never edit directly; edit the root files and re-sync.
+  - `pkg/lua/` — the Lua + LuaSocket runtime drop-in. Download
+    separately and place here. Suggested source: the lua-binaries
+    project (https://github.com/rjpcomputing/luaforwindows) or a
+    similar pre-built bundle. The MSI expects `pkg/lua/lua.exe`,
+    `pkg/lua/lua54.dll`, and the `pkg/lua/socket/` + `pkg/lua/mime/`
+    subdirectories per the manifest.
+
+## Issue history
+
+Issue #18 (closed in v1.1.0) introduced this workflow after the
+`pkg/` lua sources had silently drifted ~6 months out of date,
+missing every feature added since April 2026.

windows/build-msi.sh

@@ -0,0 +1,100 @@
+#!/bin/sh
+# windows/build-msi.sh — produce lmcp-<ver>.msi on Linux via wixl.
+#
+# This is the first-time-discovered cross-build path: download Lua 5.4
+# Win64 binaries from LuaBinaries, cross-compile LuaSocket with mingw-w64,
+# stage windows/pkg/lua/, then invoke wixl on the WiX manifest.
+#
+# Avoids the VM106-clone + WiX-on-Windows path entirely. ~1 minute on a
+# warm cache; ~3-5 minutes cold (downloads ~700 KB + cross-compiles).
+#
+# Prereqs (apt install on Debian aarch64):
+#   apt-get install -y wixl unzip gcc-mingw-w64-x86-64 binutils-mingw-w64-x86-64 \
+#                      mingw-w64-x86-64-dev
+#
+# Usage: ./build-msi.sh [output_dir]
+#   Output: $output_dir/lmcp-<ver>.msi (default: $PWD)
+#
+# Version comes from windows/lmcp.wxs Version="…" attribute.
+set -eu
+
+here=$(dirname "$(readlink -f "$0")")
+root=$(cd "$here/.." && pwd)
+out_dir=${1:-$PWD}
+work=$(mktemp -d /tmp/lmcp-msi-XXXXXX)
+trap "rm -rf $work" EXIT
+
+# Versions — bump as upstream releases.
+LUA_VER=5.4.2
+LUASOCKET_VER=3.1.0
+
+# Pull current lmcp version from the WiX manifest.
+lmcp_ver=$(sed -n 's/.*Version="\([^"]*\)".*/\1/p' "$here/lmcp.wxs" | head -1)
+[ -n "$lmcp_ver" ] || { echo "build-msi.sh: cannot parse Version from lmcp.wxs" >&2; exit 1; }
+
+echo "build-msi.sh: lmcp $lmcp_ver, lua $LUA_VER, luasocket $LUASOCKET_VER"
+
+echo "==> 1/5 sync lmcp .lua sources into pkg/"
+"$here/sync.sh"
+
+echo "==> 2/5 fetch lua $LUA_VER win64 binaries + dev library"
+cd "$work"
+curl -sSLf -o lua-bin.zip \
+    "https://downloads.sourceforge.net/project/luabinaries/${LUA_VER}/Tools%20Executables/lua-${LUA_VER}_Win64_bin.zip"
+curl -sSLf -o lua-lib.zip \
+    "https://downloads.sourceforge.net/project/luabinaries/${LUA_VER}/Windows%20Libraries/Dynamic/lua-${LUA_VER}_Win64_dllw6_lib.zip"
+mkdir -p luabin lualib include/lua/54 include/lua54 bin/lua/54 bin/lua54 lib/lua/54 lib/lua54
+unzip -q -o lua-bin.zip -d luabin
+unzip -q -o lua-lib.zip -d lualib
+cp lualib/include/*.h include/lua/54/
+cp lualib/include/*.h include/lua54/
+cp lualib/liblua54.a lib/lua/54/
+cp lualib/liblua54.a lib/lua54/
+cp lualib/lua54.dll bin/lua/54/
+cp lualib/lua54.dll bin/lua54/
+
+echo "==> 3/5 cross-compile LuaSocket $LUASOCKET_VER for win64"
+curl -sSLf -o luasocket.tar.gz \
+    "https://github.com/lunarmodules/luasocket/archive/refs/tags/v${LUASOCKET_VER}.tar.gz"
+tar xzf luasocket.tar.gz
+cd "luasocket-${LUASOCKET_VER}"
+make -s PLAT=mingw \
+    CC=x86_64-w64-mingw32-gcc \
+    LD=x86_64-w64-mingw32-gcc \
+    LUAV=54 \
+    LUAINC_mingw_base="$work/include" \
+    LUALIB_mingw_base="$work/bin" \
+    > /dev/null
+
+echo "==> 4/5 stage pkg/lua/"
+pkg_lua="$here/pkg/lua"
+rm -rf "$pkg_lua"
+mkdir -p "$pkg_lua/socket" "$pkg_lua/mime"
+
+# WiX manifest expects "lua.exe" (not "lua54.exe").
+cp "$work/luabin/lua54.exe"        "$pkg_lua/lua.exe"
+cp "$work/luabin/lua54.dll"        "$pkg_lua/lua54.dll"
+cp src/socket.lua                  "$pkg_lua/"
+cp src/mime.lua                    "$pkg_lua/"
+cp src/ltn12.lua                   "$pkg_lua/"
+cp src/socket-3.0.0.dll            "$pkg_lua/socket/core.dll"
+cp src/ftp.lua                     "$pkg_lua/socket/"
+cp src/headers.lua                 "$pkg_lua/socket/"
+cp src/http.lua                    "$pkg_lua/socket/"
+cp src/smtp.lua                    "$pkg_lua/socket/"
+cp src/tp.lua                      "$pkg_lua/socket/"
+cp src/url.lua                     "$pkg_lua/socket/"
+cp src/mime-1.0.3.dll              "$pkg_lua/mime/core.dll"
+
+echo "==> 5/5 wixl: produce MSI"
+# wixl wants forward slashes; rewrite Windows-style backslashes in Source=.
+wxs_tmp="$work/lmcp.wxs"
+sed 's|Source="pkg\\|Source="pkg/|g; s|\\\([a-zA-Z]\)|/\1|g' "$here/lmcp.wxs" > "$wxs_tmp"
+mkdir -p "$out_dir"
+out_msi="$out_dir/lmcp-${lmcp_ver}.msi"
+(cd "$here" && wixl -v "$wxs_tmp" -o "$out_msi")
+
+echo ""
+echo "==> done: $out_msi"
+ls -la "$out_msi"
+sha256sum "$out_msi"

windows/lmcp.wxs

@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
+  <!-- Bump Version on every release. See windows/README.md. -->
+  <Product Id="*"
+           Name="lmcp — Lua MCP Server"
+           Language="1033"
+           Version="1.1.0"
+           Manufacturer="QAP'LA Project"
+           UpgradeCode="A7F3E2D1-4B5C-6D7E-8F9A-0B1C2D3E4F5A">
+
+    <Package InstallerVersion="200"
+             Compressed="yes"
+             InstallScope="perMachine"
+             Description="Lightweight MCP server in Lua. 2MB RSS."
+             Comments="Zero-dependency MCP server." />
+
+    <MediaTemplate EmbedCab="yes" />
+
+    <MajorUpgrade DowngradeErrorMessage="A newer version is already installed." />
+
+    <Directory Id="TARGETDIR" Name="SourceDir">
+      <Directory Id="ProgramFiles64Folder">
+        <Directory Id="INSTALLFOLDER" Name="lmcp">
+          <Directory Id="LUA_DIR" Name="lua">
+            <Directory Id="SOCKET_DIR" Name="socket" />
+            <Directory Id="MIME_DIR" Name="mime" />
+          </Directory>
+        </Directory>
+      </Directory>
+    </Directory>
+
+    <!-- lmcp application files -->
+    <DirectoryRef Id="INSTALLFOLDER">
+      <Component Id="JsonLua" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567890">
+        <File Id="json.lua" Source="pkg\json.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="LmcpLua" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567891">
+        <File Id="lmcp.lua" Source="pkg\lmcp.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="ServerLua" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567892">
+        <File Id="server.lua" Source="pkg\server.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="StartBat" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567893">
+        <File Id="start.bat" Source="pkg\start.bat" KeyPath="yes" />
+      </Component>
+      <Component Id="InstallService" Guid="B1A2C3D4-E5F6-7890-ABCD-EF1234567894">
+        <File Id="install_service.bat" Source="pkg\install_service.bat" KeyPath="yes" />
+      </Component>
+    </DirectoryRef>
+
+    <!-- Lua runtime -->
+    <DirectoryRef Id="LUA_DIR">
+      <Component Id="LuaExe" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678900">
+        <File Id="lua.exe" Source="pkg\lua\lua.exe" KeyPath="yes" />
+      </Component>
+      <Component Id="LuaDll" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678901">
+        <File Id="lua54.dll" Source="pkg\lua\lua54.dll" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketLua" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678902">
+        <File Id="socket.lua" Source="pkg\lua\socket.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="MimeLua" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678903">
+        <File Id="mime.lua" Source="pkg\lua\mime.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="Ltn12Lua" Guid="C2B3D4E5-F6A7-8901-BCDE-F12345678904">
+        <File Id="ltn12.lua" Source="pkg\lua\ltn12.lua" KeyPath="yes" />
+      </Component>
+    </DirectoryRef>
+
+    <!-- LuaSocket native DLLs -->
+    <DirectoryRef Id="SOCKET_DIR">
+      <Component Id="SocketCoreDll" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789010">
+        <File Id="socket_core.dll" Name="core.dll" Source="pkg\lua\socket\core.dll" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketFtp" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789011">
+        <File Id="ftp.lua" Source="pkg\lua\socket\ftp.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketHeaders" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789012">
+        <File Id="headers.lua" Source="pkg\lua\socket\headers.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketHttp" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789013">
+        <File Id="http.lua" Source="pkg\lua\socket\http.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketTp" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789014">
+        <File Id="tp.lua" Source="pkg\lua\socket\tp.lua" KeyPath="yes" />
+      </Component>
+      <Component Id="SocketUrl" Guid="D3C4E5F6-A7B8-9012-CDEF-123456789015">
+        <File Id="url.lua" Source="pkg\lua\socket\url.lua" KeyPath="yes" />
+      </Component>
+    </DirectoryRef>
+
+    <DirectoryRef Id="MIME_DIR">
+      <Component Id="MimeCoreDll" Guid="E4D5F6A7-B8C9-0123-DEFA-234567890120">
+        <File Id="mime_core.dll" Name="core.dll" Source="pkg\lua\mime\core.dll" KeyPath="yes" />
+      </Component>
+    </DirectoryRef>
+
+    <Feature Id="MainFeature" Title="lmcp Server" Level="1">
+      <ComponentRef Id="JsonLua" />
+      <ComponentRef Id="LmcpLua" />
+      <ComponentRef Id="ServerLua" />
+      <ComponentRef Id="StartBat" />
+      <ComponentRef Id="InstallService" />
+      <ComponentRef Id="LuaExe" />
+      <ComponentRef Id="LuaDll" />
+      <ComponentRef Id="SocketLua" />
+      <ComponentRef Id="MimeLua" />
+      <ComponentRef Id="Ltn12Lua" />
+      <ComponentRef Id="SocketCoreDll" />
+      <ComponentRef Id="SocketFtp" />
+      <ComponentRef Id="SocketHeaders" />
+      <ComponentRef Id="SocketHttp" />
+      <ComponentRef Id="SocketTp" />
+      <ComponentRef Id="SocketUrl" />
+      <ComponentRef Id="MimeCoreDll" />
+    </Feature>
+
+  </Product>
+</Wix>

windows/pkg/install_service.bat

@@ -0,0 +1,24 @@
+@echo off
+REM Install lmcp as a Windows service using NSSM (Non-Sucking Service Manager)
+REM Download nssm from https://nssm.cc if not present
+
+if not exist "%~dp0nssm.exe" (
+    echo ERROR: nssm.exe not found in %~dp0
+    echo Download from https://nssm.cc and place nssm.exe here.
+    exit /b 1
+)
+
+set INSTALL_DIR=%~dp0
+set SERVICE_NAME=lmcp
+
+echo Installing lmcp as Windows service...
+%INSTALL_DIR%nssm.exe install %SERVICE_NAME% "%INSTALL_DIR%lua\lua.exe" "%INSTALL_DIR%server.lua"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% AppDirectory "%INSTALL_DIR%"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% AppEnvironmentExtra "LMCP_PORT=8080"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% DisplayName "lmcp MCP Server"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% Description "Lightweight MCP server in Lua"
+%INSTALL_DIR%nssm.exe set %SERVICE_NAME% Start SERVICE_AUTO_START
+%INSTALL_DIR%nssm.exe start %SERVICE_NAME%
+
+echo Done. Service '%SERVICE_NAME%' installed and started.
+echo Check: sc query %SERVICE_NAME%

windows/pkg/start.bat

@@ -0,0 +1,7 @@
+@echo off
+REM lmcp — Lua MCP Server
+REM Start the server on port 8080 (or LMCP_PORT if set)
+cd /d "%~dp0"
+if not defined LMCP_PORT set LMCP_PORT=8080
+echo Starting lmcp on port %LMCP_PORT%...
+lua\lua.exe server.lua

windows/sync.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+# windows/sync.sh — refresh windows/pkg/ from root .lua sources (issue #18).
+#
+# Run BEFORE invoking the WiX build so the MSI bundles whatever is in
+# master. The .lua files in windows/pkg/ are regenerated on every run
+# and are gitignored — never edit them directly.
+#
+# Idempotent: re-running just re-copies. Safe to call from a Makefile,
+# a CI step, or by hand before `candle.exe + light.exe`.
+
+set -eu
+
+here=$(dirname "$(readlink -f "$0")")
+root=$(cd "$here/.." && pwd)
+
+for f in lmcp.lua server.lua json.lua; do
+    if [ ! -f "$root/$f" ]; then
+        echo "windows/sync.sh: missing source $root/$f" >&2
+        exit 1
+    fi
+    cp "$root/$f" "$here/pkg/$f"
+    echo "  synced $f"
+done
+
+echo "windows/sync.sh: done — pkg/ matches root .lua at $(date +%Y-%m-%dT%H:%M:%S)"