From c6efc8f685fef4a807533705422f0aa6aad05ec8 Mon Sep 17 00:00:00 2001 From: Markus Fritsche Date: Tue, 14 Apr 2026 19:58:40 +0000 Subject: [PATCH] initial import: lmcp 0.1.0 Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 118 ++++------------------- example_server.lua | 141 +++++++++++---------------- json.lua | 21 ++-- lmcp.lua | 39 +++----- server.lua | 233 +++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 335 insertions(+), 217 deletions(-) create mode 100644 server.lua diff --git a/README.md b/README.md index 76b8ccc..6592f77 100644 --- a/README.md +++ b/README.md @@ -1,109 +1,33 @@ -# lmcp — Lightweight MCP Server in Lua +# lmcp — Lua MCP server -A minimal [Model Context Protocol](https://modelcontextprotocol.io/) server in pure Lua. ~350 lines, 2.4MB RSS, zero compiled dependencies beyond Lua + LuaSocket. +Lightweight Model Context Protocol (MCP) server in pure Lua. -## Features +## Runtime dependencies -- MCP 2025-03-26 protocol (JSON-RPC over HTTP) -- Tool registration with JSON Schema validation -- Optional Bearer token authentication (config file or explicit) -- SSE and plain JSON response modes -- Non-blocking shell execution with timeout -- Runs on any Linux with Lua 5.4 + LuaSocket - -## Quick Start - -```sh -# Install dependencies (Debian/Ubuntu) -apt install lua5.4 lua-socket - -# Or use a self-contained archive (see releases) -tar xzf lmcp-linux-amd64.tar.gz -export PATH=$PWD/lmcp-linux-amd64/bin:$PATH - -# Run -lua5.4 example_server.lua -# lmcp: my-tools v0.1.0 listening on 0.0.0.0:8080/mcp -``` +- Lua 5.1+ +- [luasocket](https://github.com/lunarmodules/luasocket) — needed for the TCP + listener. Packaged as `lua-socket` on Arch/ALARM, `lua-socket` on Debian. ## Files -| File | Description | -|------|-------------| -| `lmcp.lua` | Core library — HTTP server, JSON-RPC, MCP protocol, auth | -| `json.lua` | Minimal JSON encoder/decoder (bundled, no external dep) | -| `example_server.lua` | Example server with shell, read/write file, list/search tools | +| File | Role | +|------|------| +| `lmcp.lua` | library: protocol handling, tool registration | +| `server.lua` | HTTP server loop | +| `json.lua` | vendored JSON encoder/decoder | +| `example_server.lua` | sample server with a couple of tools | -## Authentication +## Install -To require a Bearer token, create an `lmcp.conf` next to your server: +Packaged as `lmcp` in the marfrit overlay repo: ``` -.godparticle = your-secret-token-here +# Arch / ALARM +sudo pacman -S lmcp + +# Debian +sudo apt install lmcp ``` -Then reference it when creating the server: - -```lua -local server = lmcp.new("my-tools", { - port = 8080, - conf = dir .. "lmcp.conf", -}) -``` - -Clients must send `Authorization: Bearer ` 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`. diff --git a/example_server.lua b/example_server.lua index 94eb4bd..b644a52 100644 --- a/example_server.lua +++ b/example_server.lua @@ -1,100 +1,73 @@ #!/usr/bin/env lua --- Example lmcp server — customize tools for your host -local dir = arg[0]:match("(.*/)") or "./" -package.path = package.path .. ";" .. dir .. "?.lua" -local lmcp = require("lmcp") +-- Example lmcp server — shell tools +-- Usage: lua example_server.lua [port] -local server = lmcp.new("my-tools", { - port = tonumber(os.getenv("LMCP_PORT")) or 8080, - -- Optional: Bearer token auth from config file - -- conf = dir .. "lmcp.conf", - -- Or set directly: - -- auth_token = "my-secret-token", +local dir = arg[0]:match('(.*/)') or './' +package.path = package.path .. ';' .. dir .. '?.lua' + +local lmcp = require('lmcp') + +local server = lmcp.new("example-tools", { + port = tonumber(arg[1]) or 8080, }) --- Non-blocking shell execution with timeout -local function run(cmd, timeout_sec) - timeout_sec = timeout_sec or 120 - local base = os.tmpname() - local out_file = base .. ".out" - local done_file = base .. ".done" - local sh_cmd = string.format("(%s) > '%s' 2>&1; echo $? > '%s'", cmd, out_file, done_file) - os.execute("sh -c ' " .. sh_cmd .. " ' &") - local elapsed = 0 - local interval = 50 - while elapsed < timeout_sec * 1000 do - local f = io.open(done_file, "r") - if f then f:close(); break end - if interval < 1000 then - os.execute("sleep 0." .. string.format("%03d", interval)) - else - os.execute("sleep " .. math.ceil(interval / 1000)) - end - elapsed = elapsed + interval - if interval < 2000 then interval = math.floor(interval * 1.5) end - end - local f = io.open(out_file, "r") - local output = f and f:read("*a") or "" - if f then f:close() end - os.remove(out_file); os.remove(done_file); os.remove(base) - if elapsed >= timeout_sec * 1000 then return "Error: timed out after " .. timeout_sec .. "s" end - return output ~= "" and output or "(no output)" -end - --- Register tools -server:tool("shell", "Execute a shell command.", { +server:tool("shell", "Execute a shell command", { type = "object", properties = { - command = { type = "string" }, - cwd = { type = "string" }, - timeout = { type = "integer", default = 120 }, + command = { type = "string", description = "Shell command to execute" }, + timeout = { type = "integer", description = "Timeout in seconds", default = 30 }, }, required = { "command" }, -}, function(a) - local c = a.command - if a.cwd then c = "cd \"" .. a.cwd .. "\" && " .. c end - return run(c, a.timeout or 120) +}, function(args) + local handle = io.popen(args.command .. ' 2>&1', 'r') + if not handle then return "Error: could not execute command" end + local result = handle:read('*a') + handle:close() + return result ~= '' and result or '(no output)' end) -server:tool("read_file", "Read a file.", { - type = "object", - properties = { path = { type = "string" } }, - required = { "path" }, -}, function(a) - local f = io.open(a.path, "r") - if not f then return "Error: could not read " .. a.path end - local c = f:read("*a"); f:close(); return c -end) - -server:tool("write_file", "Write content to a file.", { - type = "object", - properties = { path = { type = "string" }, content = { type = "string" } }, - required = { "path", "content" }, -}, function(a) - local f = io.open(a.path, "w") - if not f then return "Error: could not write " .. a.path end - f:write(a.content); f:close() - return string.format("Written %d bytes to %s", #a.content, a.path) -end) - -server:tool("list_dir", "List directory contents.", { - type = "object", - properties = { path = { type = "string", default = "." } }, -}, function(a) - return run("ls -la '" .. (a.path or ".") .. "'", 10) -end) - -server:tool("search_files", "Search for files by name.", { +server:tool("read_file", "Read a file", { type = "object", properties = { - pattern = { type = "string" }, - path = { type = "string", default = "/" }, - max_depth = { type = "integer", default = 4 }, + path = { type = "string", description = "File path to read" }, }, - required = { "pattern" }, -}, function(a) - return run(string.format("find '%s' -maxdepth %d -name '%s' 2>/dev/null", - a.path or "/", a.max_depth or 4, a.pattern), 30) + required = { "path" }, +}, function(args) + local f = io.open(args.path, 'r') + if not f then return "Error: could not open " .. args.path end + local content = f:read('*a') + f:close() + return content end) +server:tool("write_file", "Write content to a file", { + type = "object", + properties = { + path = { type = "string", description = "File path to write" }, + content = { type = "string", description = "Content to write" }, + }, + required = { "path", "content" }, +}, function(args) + local f = io.open(args.path, 'w') + if not f then return "Error: could not open " .. args.path .. " for writing" end + f:write(args.content) + f:close() + return string.format("Written %d bytes to %s", #args.content, args.path) +end) + +server:tool("list_dir", "List directory contents", { + type = "object", + properties = { + path = { type = "string", description = "Directory path", default = "." }, + }, +}, function(args) + local path = args.path or '.' + local handle = io.popen('ls -1 ' .. path:gsub("'", "'\\''") .. ' 2>&1') + if not handle then return "Error: could not list " .. path end + local result = handle:read('*a') + handle:close() + return result +end) + +io.stderr:write("Starting lmcp example server...\n") server:run() diff --git a/json.lua b/json.lua index 27ff534..6f2eb28 100644 --- a/json.lua +++ b/json.lua @@ -89,7 +89,6 @@ end -- Decode -- local decode_value -local MAX_DEPTH = 64 local ws_chars = { [' '] = true, ['\t'] = true, ['\n'] = true, ['\r'] = true } local function skip_ws(s, pos) @@ -144,14 +143,14 @@ local function decode_number(s, pos) return n, pos end -local function decode_array(s, pos, depth) +local function decode_array(s, pos) pos = pos + 1 -- skip [ local arr = {} pos = skip_ws(s, pos) if s:sub(pos, pos) == ']' then return arr, pos + 1 end while true do local val - val, pos = decode_value(s, pos, (depth or 0) + 1) + val, pos = decode_value(s, pos) arr[#arr + 1] = val pos = skip_ws(s, pos) local c = s:sub(pos, pos) @@ -161,7 +160,7 @@ local function decode_array(s, pos, depth) end end -local function decode_object(s, pos, depth) +local function decode_object(s, pos) pos = pos + 1 -- skip { local obj = {} pos = skip_ws(s, pos) @@ -175,7 +174,7 @@ local function decode_object(s, pos, depth) if s:sub(pos, pos) ~= ':' then error('expected : at ' .. pos) end pos = skip_ws(s, pos + 1) local val - val, pos = decode_value(s, pos, (depth or 0) + 1) + val, pos = decode_value(s, pos) obj[key] = val pos = skip_ws(s, pos) local c = s:sub(pos, pos) @@ -185,14 +184,12 @@ local function decode_object(s, pos, depth) end end -decode_value = function(s, pos, depth) - depth = depth or 0 - if depth > MAX_DEPTH then error("JSON nesting too deep") end +decode_value = function(s, pos) pos = skip_ws(s, pos) local c = s:sub(pos, pos) if c == '"' then return decode_string(s, pos) - elseif c == '{' then return decode_object(s, pos, depth) - elseif c == '[' then return decode_array(s, pos, depth) + elseif c == '{' then return decode_object(s, pos) + elseif c == '[' then return decode_array(s, pos) elseif c == 't' then if s:sub(pos, pos + 3) == 'true' then return true, pos + 4 end elseif c == 'f' then @@ -213,5 +210,9 @@ end -- Sentinel for JSON null json.null = setmetatable({}, { __tostring = function() return 'null' end }) +-- Helper: encode a table as a JSON array even if empty +function json.array(t) + return setmetatable(t or {}, { __is_array = true }) +end return json diff --git a/lmcp.lua b/lmcp.lua index dd16fa0..af66598 100644 --- a/lmcp.lua +++ b/lmcp.lua @@ -21,20 +21,8 @@ local function read_conf(path) end -- Protocol constants --- Constant-time string comparison (prevents timing oracle on auth token) -local function constant_time_eq(a, b) - if type(a) ~= "string" or type(b) ~= "string" then return false end - if #a ~= #b then return false end -- length leak is acceptable (token length is not secret) - local diff = 0 - for i = 1, #a do - diff = diff + (a:byte(i) ~ b:byte(i)) -- Lua 5.4 bitwise XOR - end - return diff == 0 -end - local MCP_VERSION = "2025-03-26" local JSONRPC = "2.0" -local MAX_BODY_SIZE = 65536 -- 64KB, generous for MCP JSON-RPC function lmcp.new(name, opts) opts = opts or {} @@ -46,9 +34,7 @@ function lmcp.new(name, opts) self.tools = {} self._session_id = nil -- Auth: explicit opt > conf file > nil (no auth) - if os.getenv("LMCP_TOKEN") then - self._auth_token = os.getenv("LMCP_TOKEN") - elseif opts.auth_token then + if opts.auth_token then self._auth_token = opts.auth_token elseif opts.conf then local conf = read_conf(opts.conf) @@ -145,8 +131,6 @@ function lmcp:handle_request(req) end else - -- Unknown notifications must be silently ignored (JSON-RPC spec) - if id == nil then return nil end return jsonrpc_error(id, -32601, "Method not found: " .. tostring(method)) end end @@ -173,9 +157,6 @@ local function parse_http_request(client) -- Read body local body = '' local content_length = tonumber(headers['content-length'] or 0) - if content_length > MAX_BODY_SIZE then - return nil, "body too large" - end if content_length > 0 then body, err = client:receive(content_length) if not body then return nil, err end @@ -221,7 +202,7 @@ function lmcp:serve_request(client) if self._auth_token and req.method ~= 'OPTIONS' then local auth = req.headers['authorization'] or '' local token = auth:match('^Bearer%s+(.+)$') - if not constant_time_eq(token, self._auth_token) then + if token ~= self._auth_token then send_response(client, '401 Unauthorized', { ['Content-Type'] = 'application/json', ['WWW-Authenticate'] = 'Bearer' }, @@ -232,7 +213,7 @@ function lmcp:serve_request(client) end -- GET /mcp — SSE endpoint (for session establishment) - if req.method == 'GET' and (path:match('^/mcp$') or path:match('^/mcp%?')) then + if req.method == 'GET' and path:match('^/mcp') then -- SSE stream — send headers and keep alive briefly local sse_headers = { 'HTTP/1.1 200 OK', @@ -259,7 +240,7 @@ function lmcp:serve_request(client) end -- POST /mcp — JSON-RPC endpoint - if req.method == 'POST' and (path:match('^/mcp$') or path:match('^/mcp%?')) then + if req.method == 'POST' and path:match('^/mcp') then if req.body == '' then send_response(client, '400 Bad Request', { ['Content-Type'] = 'application/json' }, @@ -309,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 @@ -360,4 +348,3 @@ function lmcp:run() end return lmcp - diff --git a/server.lua b/server.lua new file mode 100644 index 0000000..f0f85e5 --- /dev/null +++ b/server.lua @@ -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()