marfrit/lmcp
0
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

initial import: lmcp 0.1.0

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