initial import: lmcp 0.1.0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Security hardening: body size limit, JSON depth limit, timing-safe auth
2026-04-14 19:58:40 +00:00 · 2026-04-11 20:45:16 +02:00
4 changed files with 320 additions and 184 deletions
@@ -1,109 +1,33 @@
-# lmcp — Lightweight MCP Server in Lua
+# lmcp — Lua MCP server

-A minimal [Model Context Protocol](https://modelcontextprotocol.io/) server in pure Lua. ~350 lines, 2.4MB RSS, zero compiled dependencies beyond Lua + LuaSocket.
+Lightweight Model Context Protocol (MCP) server in pure Lua.

-## Features
+## Runtime dependencies

- MCP 2025-03-26 protocol (JSON-RPC over HTTP)
- Tool registration with JSON Schema validation
- Optional Bearer token authentication (config file or explicit)
- SSE and plain JSON response modes
- Non-blocking shell execution with timeout
- Runs on any Linux with Lua 5.4 + LuaSocket
-
-## Quick Start
-
-```sh
-# Install dependencies (Debian/Ubuntu)
-apt install lua5.4 lua-socket
-
-# Or use a self-contained archive (see releases)
-tar xzf lmcp-linux-amd64.tar.gz
-export PATH=$PWD/lmcp-linux-amd64/bin:$PATH
-
-# Run
-lua5.4 example_server.lua
-# lmcp: my-tools v0.1.0 listening on 0.0.0.0:8080/mcp
-```
+- Lua 5.1+
+- [luasocket](https://github.com/lunarmodules/luasocket) — needed for the TCP
+  listener. Packaged as `lua-socket` on Arch/ALARM, `lua-socket` on Debian.

 ## Files

-| File | Description |
-|------|-------------|
-| `lmcp.lua` | Core library — HTTP server, JSON-RPC, MCP protocol, auth |
-| `json.lua` | Minimal JSON encoder/decoder (bundled, no external dep) |
-| `example_server.lua` | Example server with shell, read/write file, list/search tools |
+| File | Role |
+|------|------|
+| `lmcp.lua`         | library: protocol handling, tool registration |
+| `server.lua`       | HTTP server loop |
+| `json.lua`         | vendored JSON encoder/decoder |
+| `example_server.lua` | sample server with a couple of tools |

-## Authentication
+## Install

-To require a Bearer token, create an `lmcp.conf` next to your server:
+Packaged as `lmcp` in the marfrit overlay repo:

 ```
-.godparticle = your-secret-token-here
+# Arch / ALARM
+sudo pacman -S lmcp
+
+# Debian
+sudo apt install lmcp
 ```

-Then reference it when creating the server:
-
-```lua
-local server = lmcp.new("my-tools", {
-    port = 8080,
-    conf = dir .. "lmcp.conf",
-})
-```
-
-Clients must send `Authorization: Bearer <token>` on every request. OPTIONS (CORS preflight) is exempt.
-
-You can also set the token directly:
-
-```lua
-local server = lmcp.new("my-tools", {
-    auth_token = "my-secret-token",
-})
-```
-
-## Claude Code Integration
-
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "my-host": {
-      "type": "url",
-      "url": "http://my-host:8080/mcp",
-      "headers": {
-        "Authorization": "Bearer your-token-here"
-      }
-    }
-  }
-}
-```
-
-## Adding Tools
-
-```lua
-server:tool("greet", "Say hello to someone.", {
-    type = "object",
-    properties = {
-        name = { type = "string", description = "Who to greet" },
-    },
-    required = { "name" },
-}, function(args)
-    return "Hello, " .. args.name .. "!"
-end)
-```
-
-Tool handlers return a string (wrapped as text content) or a table (encoded as JSON). Errors thrown via `error()` are caught and returned as MCP error responses.
-
-## Self-Contained Archives
-
-Pre-built archives with Lua 5.4 + LuaSocket for Linux:
-
- `lmcp-linux-amd64.tar.gz` — x86_64
- `lmcp-linux-aarch64.tar.gz` — ARM64 (Pi 5, RK3588, etc.)
-
-These include the Lua interpreter and LuaSocket shared library so no system packages are needed.
-
-## License
-
-MIT
+Files land under `/usr/share/lua/5.4/` (Lua LUA_PATH).
+The example server installs as `/usr/bin/lmcp-example`.
@@ -1,100 +1,73 @@
 #!/usr/bin/env lua
-- Example lmcp server — customize tools for your host
-local dir = arg[0]:match("(.*/)")  or "./"
-package.path = package.path .. ";" .. dir .. "?.lua"
-local lmcp = require("lmcp")
+-- Example lmcp server — shell tools
+-- Usage: lua example_server.lua [port]

-local server = lmcp.new("my-tools", {
-    port = tonumber(os.getenv("LMCP_PORT")) or 8080,
-    -- Optional: Bearer token auth from config file
-    -- conf = dir .. "lmcp.conf",
-    -- Or set directly:
-    -- auth_token = "my-secret-token",
+local dir = arg[0]:match('(.*/)')  or './'
+package.path = package.path .. ';' .. dir .. '?.lua'
+
+local lmcp = require('lmcp')
+
+local server = lmcp.new("example-tools", {
+    port = tonumber(arg[1]) or 8080,
 })

-- Non-blocking shell execution with timeout
-local function run(cmd, timeout_sec)
-    timeout_sec = timeout_sec or 120
-    local base = os.tmpname()
-    local out_file = base .. ".out"
-    local done_file = base .. ".done"
-    local sh_cmd = string.format("(%s) > '%s' 2>&1; echo $? > '%s'", cmd, out_file, done_file)
-    os.execute("sh -c ' " .. sh_cmd .. " ' &")
-    local elapsed = 0
-    local interval = 50
-    while elapsed < timeout_sec * 1000 do
-        local f = io.open(done_file, "r")
-        if f then f:close(); break end
-        if interval < 1000 then
-            os.execute("sleep 0." .. string.format("%03d", interval))
-        else
-            os.execute("sleep " .. math.ceil(interval / 1000))
-        end
-        elapsed = elapsed + interval
-        if interval < 2000 then interval = math.floor(interval * 1.5) end
-    end
-    local f = io.open(out_file, "r")
-    local output = f and f:read("*a") or ""
-    if f then f:close() end
-    os.remove(out_file); os.remove(done_file); os.remove(base)
-    if elapsed >= timeout_sec * 1000 then return "Error: timed out after " .. timeout_sec .. "s" end
-    return output ~= "" and output or "(no output)"
-end
-
-- Register tools
-server:tool("shell", "Execute a shell command.", {
+server:tool("shell", "Execute a shell command", {
    type = "object",
    properties = {
-        command = { type = "string" },
-        cwd = { type = "string" },
-        timeout = { type = "integer", default = 120 },
+        command = { type = "string", description = "Shell command to execute" },
+        timeout = { type = "integer", description = "Timeout in seconds", default = 30 },
    },
    required = { "command" },
-}, function(a)
-    local c = a.command
-    if a.cwd then c = "cd \"" .. a.cwd .. "\" && " .. c end
-    return run(c, a.timeout or 120)
+}, function(args)
+    local handle = io.popen(args.command .. ' 2>&1', 'r')
+    if not handle then return "Error: could not execute command" end
+    local result = handle:read('*a')
+    handle:close()
+    return result ~= '' and result or '(no output)'
 end)

-server:tool("read_file", "Read a file.", {
-    type = "object",
-    properties = { path = { type = "string" } },
-    required = { "path" },
-}, function(a)
-    local f = io.open(a.path, "r")
-    if not f then return "Error: could not read " .. a.path end
-    local c = f:read("*a"); f:close(); return c
-end)
-
-server:tool("write_file", "Write content to a file.", {
-    type = "object",
-    properties = { path = { type = "string" }, content = { type = "string" } },
-    required = { "path", "content" },
-}, function(a)
-    local f = io.open(a.path, "w")
-    if not f then return "Error: could not write " .. a.path end
-    f:write(a.content); f:close()
-    return string.format("Written %d bytes to %s", #a.content, a.path)
-end)
-
-server:tool("list_dir", "List directory contents.", {
-    type = "object",
-    properties = { path = { type = "string", default = "." } },
-}, function(a)
-    return run("ls -la '" .. (a.path or ".") .. "'", 10)
-end)
-
-server:tool("search_files", "Search for files by name.", {
+server:tool("read_file", "Read a file", {
    type = "object",
    properties = {
-        pattern = { type = "string" },
-        path = { type = "string", default = "/" },
-        max_depth = { type = "integer", default = 4 },
+        path = { type = "string", description = "File path to read" },
    },
-    required = { "pattern" },
-}, function(a)
-    return run(string.format("find '%s' -maxdepth %d -name '%s' 2>/dev/null",
-        a.path or "/", a.max_depth or 4, a.pattern), 30)
+    required = { "path" },
+}, function(args)
+    local f = io.open(args.path, 'r')
+    if not f then return "Error: could not open " .. args.path end
+    local content = f:read('*a')
+    f:close()
+    return content
 end)

+server:tool("write_file", "Write content to a file", {
+    type = "object",
+    properties = {
+        path = { type = "string", description = "File path to write" },
+        content = { type = "string", description = "Content to write" },
+    },
+    required = { "path", "content" },
+}, function(args)
+    local f = io.open(args.path, 'w')
+    if not f then return "Error: could not open " .. args.path .. " for writing" end
+    f:write(args.content)
+    f:close()
+    return string.format("Written %d bytes to %s", #args.content, args.path)
+end)
+
+server:tool("list_dir", "List directory contents", {
+    type = "object",
+    properties = {
+        path = { type = "string", description = "Directory path", default = "." },
+    },
+}, function(args)
+    local path = args.path or '.'
+    local handle = io.popen('ls -1 ' .. path:gsub("'", "'\\''") .. ' 2>&1')
+    if not handle then return "Error: could not list " .. path end
+    local result = handle:read('*a')
+    handle:close()
+    return result
+end)
+
+io.stderr:write("Starting lmcp example server...\n")
 server:run()
@@ -290,12 +290,19 @@ function lmcp:serve_request(client)
        return
    end

-    -- OPTIONS (CORS preflight)
+    -- OPTIONS (CORS preflight). Echo back whatever the client asked for
+    -- (MCP adds e.g. Mcp-Session-Id, Mcp-Protocol-Version); fall back to *.
    if req.method == 'OPTIONS' then
+        local acrh = req.headers and (req.headers['access-control-request-headers']
+                                      or req.headers['Access-Control-Request-Headers'])
        send_response(client, '204 No Content', {
            ['Access-Control-Allow-Origin'] = '*',
            ['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS',
-            ['Access-Control-Allow-Headers'] = 'Content-Type, Accept, Authorization',
+            -- CORS spec: '*' does NOT cover Authorization; must list it explicitly.
+            -- Echo back whatever the client requested plus Authorization.
+            ['Access-Control-Allow-Headers'] = acrh and (acrh .. ', Authorization')
+                or 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version',
+            ['Access-Control-Max-Age'] = '86400',
        }, '')
        client:close()
        return
@@ -341,4 +348,3 @@ function lmcp:run()
 end

 return lmcp
-
@@ -0,0 +1,233 @@
+#!/usr/bin/env lua
+-- lmcp server — cross-platform shell tools
+-- Works on Linux, macOS, and Windows without modification.
+-- SPDX-License-Identifier: MIT
+
+-- Resolve package paths relative to this script
+local dir = arg[0]:match('(.*[/\\])') or './'
+local sep = package.config:sub(1, 1)  -- '/' on Unix, '\\' on Windows
+package.path = package.path .. ';' .. dir .. '?.lua'
+
+-- Windows: add lua\ subdirectory for LuaSocket DLLs
+if sep == '\\' then
+    package.cpath = package.cpath .. ';' .. dir .. 'lua\\?.dll'
+        .. ';' .. dir .. 'lua\\socket\\?.dll'
+        .. ';' .. dir .. 'lua\\mime\\?.dll'
+end
+
+local lmcp = require('lmcp')
+
+-- ---- Platform detection ----
+local WINDOWS = sep == '\\'
+local function is_windows() return WINDOWS end
+
+-- ---- Non-blocking command execution with timeout ----
+-- io.popen blocks until the child exits. On any OS, a long-running
+-- process (like a daemon) will hang lmcp forever. We work around this
+-- by spawning into temp files and polling a sentinel.
+
+local function tmpname()
+    if WINDOWS then
+        local tmp = os.getenv("TEMP") or "C:\\Windows\\Temp"
+        return tmp .. "\\lmcp_" .. os.time() .. "_" .. math.random(10000, 99999)
+    else
+        return os.tmpname()
+    end
+end
+
+local function sleep_ms(ms)
+    if WINDOWS then
+        -- ping loopback: ~1s per -n count. For sub-second, use busy-wait.
+        if ms < 500 then
+            local target = os.clock() + ms / 1000
+            while os.clock() < target do end
+        else
+            local secs = math.ceil(ms / 1000)
+            os.execute("ping -n " .. (secs + 1) .. " 127.0.0.1 >nul 2>&1")
+        end
+    else
+        -- POSIX: use sleep command (supports fractional seconds on GNU)
+        if ms < 1000 then
+            os.execute("sleep 0." .. string.format("%03d", ms))
+        else
+            os.execute("sleep " .. math.ceil(ms / 1000))
+        end
+    end
+end
+
+local function file_exists(path)
+    local f = io.open(path, 'r')
+    if f then f:close(); return true end
+    return false
+end
+
+local function read_file(path)
+    local f = io.open(path, 'r')
+    if not f then return nil end
+    local c = f:read('*a'); f:close(); return c
+end
+
+local function remove_silent(path)
+    os.remove(path)
+end
+
+local function run(cmd, timeout_sec)
+    timeout_sec = timeout_sec or 120
+
+    local base = tmpname()
+    local out_file = base .. ".out"
+    local done_file = base .. ".done"
+
+    if WINDOWS then
+        -- Write a batch wrapper that runs the command and signals completion
+        local bat_file = base .. ".bat"
+        local bf = io.open(bat_file, 'w')
+        if not bf then return "Error: could not create temp file" end
+        bf:write("@echo off\r\n")
+        bf:write(cmd .. ' > "' .. out_file .. '" 2>&1\r\n')
+        bf:write('echo %ERRORLEVEL% > "' .. done_file .. '"\r\n')
+        bf:close()
+        os.execute('start /B cmd /C "' .. bat_file .. '"')
+
+        -- Poll for sentinel
+        local elapsed = 0
+        local interval = 100  -- ms
+        while elapsed < timeout_sec * 1000 do
+            if file_exists(done_file) then break end
+            sleep_ms(interval)
+            elapsed = elapsed + interval
+            if interval < 2000 then interval = math.floor(interval * 1.5) end
+        end
+
+        local output = read_file(out_file)
+        remove_silent(bat_file)
+        remove_silent(out_file)
+        remove_silent(done_file)
+
+        if elapsed >= timeout_sec * 1000 then
+            return output or ("Error: command timed out after " .. timeout_sec .. "s")
+        end
+        return output and output ~= "" and output or "(no output)"
+    else
+        -- POSIX: use shell backgrounding + wait with timeout
+        -- sh -c '(cmd > out 2>&1; echo $? > done) &' then poll
+        local sh_cmd = string.format(
+            "(%s) > '%s' 2>&1; echo $? > '%s'",
+            cmd, out_file, done_file
+        )
+        os.execute("sh -c '" .. sh_cmd:gsub("'", "'\\''") .. "' &")
+
+        local elapsed = 0
+        local interval = 50  -- ms
+        while elapsed < timeout_sec * 1000 do
+            if file_exists(done_file) then break end
+            sleep_ms(interval)
+            elapsed = elapsed + interval
+            if interval < 2000 then interval = math.floor(interval * 1.5) end
+        end
+
+        local output = read_file(out_file)
+        remove_silent(out_file)
+        remove_silent(done_file)
+
+        if elapsed >= timeout_sec * 1000 then
+            return output or ("Error: command timed out after " .. timeout_sec .. "s")
+        end
+        return output and output ~= "" and output or "(no output)"
+    end
+end
+
+-- ---- Server setup ----
+
+local server_name = os.getenv("LMCP_NAME") or (WINDOWS and "windows-tools" or "linux-tools")
+local server = lmcp.new(server_name, {
+    port = tonumber(os.getenv("LMCP_PORT") or arg[1]) or 8080,
+})
+
+-- ---- Tools ----
+
+server:tool("shell", "Execute a shell command.", {
+    type = "object",
+    properties = {
+        command = { type = "string", description = "Command to execute" },
+        cwd = { type = "string", description = "Working directory" },
+        timeout = { type = "integer", description = "Timeout in seconds", default = 120 },
+        powershell = { type = "boolean", description = "Use PowerShell (Windows only)", default = false },
+    },
+    required = { "command" },
+}, function(a)
+    local cmd = a.command
+    if a.cwd then
+        if WINDOWS then
+            cmd = 'cd /d "' .. a.cwd .. '" && ' .. cmd
+        else
+            cmd = 'cd "' .. a.cwd .. '" && ' .. cmd
+        end
+    end
+    if a.powershell and WINDOWS then
+        cmd = 'powershell -NoProfile -Command "' .. cmd:gsub('"', '\\"') .. '"'
+    end
+    return run(cmd, a.timeout or 120)
+end)
+
+server:tool("read_file", "Read a file.", {
+    type = "object",
+    properties = { path = { type = "string" } },
+    required = { "path" },
+}, function(a)
+    local c = read_file(a.path)
+    if not c then return "Error: could not read " .. a.path end
+    return c
+end)
+
+server:tool("write_file", "Write content to a file.", {
+    type = "object",
+    properties = {
+        path = { type = "string" },
+        content = { type = "string" },
+    },
+    required = { "path", "content" },
+}, function(a)
+    local f = io.open(a.path, 'w')
+    if not f then return "Error: could not write " .. a.path end
+    f:write(a.content); f:close()
+    return string.format("Written %d bytes to %s", #a.content, a.path)
+end)
+
+server:tool("list_dir", "List directory contents.", {
+    type = "object",
+    properties = { path = { type = "string", default = "." } },
+}, function(a)
+    local path = a.path or "."
+    if WINDOWS then
+        return run('dir /b "' .. path .. '"', 10)
+    else
+        return run("ls -1 '" .. path:gsub("'", "'\\''") .. "'", 10)
+    end
+end)
+
+server:tool("search_files", "Search for files by pattern.", {
+    type = "object",
+    properties = {
+        pattern = { type = "string", description = "File name pattern" },
+        path = { type = "string", default = WINDOWS and "C:\\" or "/" },
+    },
+    required = { "pattern" },
+}, function(a)
+    local path = a.path or (WINDOWS and "C:\\" or "/")
+    if WINDOWS then
+        return run('dir /b /s "' .. path .. '\\' .. a.pattern .. '"', 30)
+    else
+        return run("find '" .. path:gsub("'", "'\\''") .. "' -name '" .. a.pattern:gsub("'", "'\\''") .. "' 2>/dev/null", 30)
+    end
+end)
+
+if WINDOWS then
+    server:tool("systeminfo", "Get Windows system information.", {
+        type = "object", properties = {},
+    }, function() return run("systeminfo", 30) end)
+end
+
+io.stderr:write(string.format("lmcp %s starting on port %d (%s)\n",
+    server_name, server.port, WINDOWS and "Windows" or "POSIX"))
+server:run()