From 6c194deea0574aa15d25aca596c4bf3d6b14c90a Mon Sep 17 00:00:00 2001 From: Markus Fritsche Date: Tue, 12 May 2026 13:06:39 +0000 Subject: [PATCH] =?UTF-8?q?mcp:=20JSON-RPC=20client=20+=20ffi/curl=20statu?= =?UTF-8?q?s=5Fcode;=20PHASE0=20=C2=A74=20amended?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First commit of Phase 2 per docs/PHASE2.md §12. Three changes bundled: mcp.lua (new, 153 lines): - M.connect(url, opts) returns a Session. - Session:initialize() round-trips initialize + notifications/initialized + tools/list. Caches tools for session lifetime (lmcp announces capabilities.tools.listChanged = false; no refetch). - Session:list_tools() returns the cached tool list. - Session:call_tool(name, args) returns (result_table, kind) where kind ∈ {"ok", "handler_error", "rpc_error", "transport_error"} per the §4 error split. Folded HTTP-level failure into transport_error. - Per-server Bearer auth via opts.auth_token or opts.auth_env env-var indirection. - Captures protocolVersion mismatch as a warning string rather than aborting (lmcp doesn't negotiate — N3 in review). ffi/curl.lua extension: - Add curl_easy_getinfo to ffi.cdef. - Pre-cast as getinfo_long; helper get_response_code() fetches CURLINFO_RESPONSE_CODE (decimal 2097154 = CURLINFOTYPE_LONG | 2). - M.post now returns (body, status_code) on transport success; (nil, errmsg) on libcurl failure stays unchanged. Phase 1 callers reading only the first slot are unaffected. docs/PHASE0.md §4: - Insert `mcp.lua` between broker.lua and router.lua per PHASE2.md §9. - Module-stability invariant clarified: rename prohibition is what matters; adding new files is additive. Smoke-test passes for all four kinds against boltzmann lmcp v0.5.4: - initialize: ok (7 tools cached) - list_dir /tmp: ok (1.2KB content) - read_file /nonexistent: ok (boltzmann's baseline §3 quirk — isError:false even on failure; content is authoritative) - nope_tool: rpc_error (code=-32601) - wrong auth: transport_error (HTTP 401) - unreachable host: transport_error (DNS failure) Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/PHASE0.md | 3 +- ffi/curl.lua | 33 +++++++++-- mcp.lua | 153 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 184 insertions(+), 5 deletions(-) create mode 100644 mcp.lua diff --git a/docs/PHASE0.md b/docs/PHASE0.md index e338586..56cd917 100644 --- a/docs/PHASE0.md +++ b/docs/PHASE0.md @@ -59,6 +59,7 @@ aish/ ├── main.lua # Entry point: arg parsing, config load, REPL start ├── repl.lua # Readline loop, input dispatch, prompt rendering ├── broker.lua # llama.cpp HTTP client; Phase 0: blocking POST +├── mcp.lua # MCP JSON-RPC 2.0 client (Phase 2; added 2026-05-12) ├── router.lua # Task classifier: shell / AI / meta ├── executor.lua # Command execution; Phase 0: io.popen ├── context.lua # In-memory conversation history, token budget @@ -73,7 +74,7 @@ aish/ └── libc.lua # Shared: errno, signal, write, read, misc ``` -All modules are required explicitly from `main.lua`. No module autoloading. File names are stable across phases — later phases fill in bodies, not rename files. +All modules are required explicitly from `main.lua`. No module autoloading. File names are stable across phases — later phases fill in bodies, not rename files. Adding new files is permitted and additive (e.g. `mcp.lua` was inserted at Phase 2 per docs/PHASE2.md §9); the rename prohibition is what keeps cross-phase wiring stable. --- diff --git a/ffi/curl.lua b/ffi/curl.lua index 2143bd4..bb2fd0a 100644 --- a/ffi/curl.lua +++ b/ffi/curl.lua @@ -25,6 +25,7 @@ struct curl_slist *curl_slist_append(struct curl_slist *list, const char *string void curl_slist_free_all(struct curl_slist *list); int curl_easy_setopt(CURL *handle, int option, ...); +int curl_easy_getinfo(CURL *handle, int info, ...); ]] -- libcurl-dev's unversioned `libcurl.so` symlink isn't assumed; fall back to @@ -64,13 +65,36 @@ local setopt_str = ffi.cast("int(*)(void*, int, const char*)", C.curl_easy_seto local setopt_long = ffi.cast("int(*)(void*, int, long)", C.curl_easy_setopt) local setopt_ptr = ffi.cast("int(*)(void*, int, void*)", C.curl_easy_setopt) +-- curl_easy_getinfo is variadic too. The Phase 2 caller only needs the +-- CURLINFO_LONG family (HTTP response code); pre-cast to that signature. +-- CURLINFO_RESPONSE_CODE = CURLINFO_LONG (0x200000) + 2 = 2097154. +local getinfo_long = ffi.cast("int(*)(void*, int, long*)", C.curl_easy_getinfo) +local INFO_RESPONSE_CODE = 2097154 + +local function get_response_code(handle) + local out = ffi.new("long[1]") + if getinfo_long(handle, INFO_RESPONSE_CODE, out) == 0 then + return tonumber(out[0]) + end + return 0 -- 0 = no response (e.g. couldn't connect) +end + local M = {} -- POST `body` to `url` with `headers` (list of "Name: value" strings) and an -- optional `timeout_ms`. -- Returns: --- string response body on success --- nil, errmsg on libcurl failure (non-zero CURLcode) +-- body, status_code on transport success — body is the raw response +-- string (may be empty); status_code is the HTTP +-- response code (2xx success, 4xx/5xx surface as +-- transport-level failure for callers that care, +-- e.g. mcp.lua treating 401 as auth failure). +-- FAILONERROR is intentionally NOT set so the body +-- is observable on non-2xx (lmcp's 401 returns a +-- non-JSON-RPC body that callers need to recognise). +-- nil, errmsg on libcurl-level failure (non-zero CURLcode) +-- Phase 1 callers reading only the first slot stay correct: success +-- returns truthy body, failure returns nil — same disjunction as before. function M.post(url, body, headers, timeout_ms) local handle = C.curl_easy_init() if handle == nil then return nil, "curl_easy_init returned NULL" end @@ -101,9 +125,10 @@ function M.post(url, body, headers, timeout_ms) end local rc = C.curl_easy_perform(handle) - local result, err + local result, status, err if rc == 0 then result = table.concat(chunks) + status = get_response_code(handle) else err = ffi.string(C.curl_easy_strerror(rc)) end @@ -112,7 +137,7 @@ function M.post(url, body, headers, timeout_ms) if slist ~= nil then C.curl_slist_free_all(slist) end write_cb:free() - if rc == 0 then return result end + if rc == 0 then return result, status end return nil, err end diff --git a/mcp.lua b/mcp.lua new file mode 100644 index 0000000..5684b0f --- /dev/null +++ b/mcp.lua @@ -0,0 +1,153 @@ +-- mcp.lua — MCP (Model Context Protocol) JSON-RPC 2.0 client. +-- Phase 2 v1: HTTP POST per RPC against lmcp servers; no long-lived SSE +-- channel (lmcp doesn't push — capabilities.tools.listChanged = false). +-- See docs/PHASE2.md §3 (module changes) and §4 (transport). + +local curl = require("ffi.curl") +local json = require("dkjson") + +local M = {} +local Session = {} +Session.__index = Session + +local MCP_PROTOCOL_VERSION = "2025-03-26" + +-- ---------------------------------------------------------------- M.connect +-- Open a session. No network traffic yet — call session:initialize() +-- to actually round-trip initialize + tools/list. +-- opts: +-- alias short name for this server (defaults to URL hostname) +-- auth_token literal Bearer token +-- auth_env env-var name to read the token from (used if auth_token nil) +function M.connect(url, opts) + opts = opts or {} + local auth = opts.auth_token + if (not auth or auth == "") and opts.auth_env then + local env = os.getenv(opts.auth_env) + if env and env ~= "" then auth = env end + end + return setmetatable({ + url = url, + alias = opts.alias or url:match("https?://([^:/]+)") or url, + auth = auth, + next_id = 1, + tools = nil, -- populated by initialize() + server_info = nil, + server_caps = nil, + version_warning = nil, -- non-nil string if server returned different protocolVersion + }, Session) +end + +-- ---------------------------------------------------------------- headers +function Session:_headers() + local h = { "Content-Type: application/json", "Accept: application/json" } + if self.auth and self.auth ~= "" then + h[#h + 1] = "Authorization: Bearer " .. self.auth + end + return h +end + +-- ---------------------------------------------------------------- _rpc +-- One round-trip. Returns: +-- result_table, "ok" — JSON-RPC success +-- nil, "rpc_error", error_obj — JSON-RPC envelope error +-- nil, "transport_error", msg — HTTP >=400 / libcurl / parse +-- If has_id == false this is a notification: lmcp returns HTTP 202 empty +-- body and we synthesize (true, "ok") on transport success. +function Session:_rpc(method, params, has_id) + local req = { jsonrpc = "2.0", method = method, params = params or {} } + if has_id ~= false then + req.id = self.next_id + self.next_id = self.next_id + 1 + end + local body, status = curl.post(self.url, json.encode(req), self:_headers()) + if not body then + return nil, "transport_error", tostring(status) -- 2nd slot is errmsg + end + if status >= 400 then + return nil, "transport_error", + ("HTTP %d: %s"):format(status, body:sub(1, 200)) + end + if has_id == false then + return true, "ok" + end + local doc, _, derr = json.decode(body) + if not doc then + return nil, "transport_error", "malformed JSON: " .. tostring(derr) + end + if doc.error then + return nil, "rpc_error", doc.error + end + return doc.result or {}, "ok" +end + +-- ---------------------------------------------------------------- initialize +-- Round-trips initialize + sends notifications/initialized + caches tools/list. +-- Returns: +-- true, "ok" — session ready +-- false, kind, err — first failing RPC (caller logs) +function Session:initialize() + local r, kind, err = self:_rpc("initialize", { + protocolVersion = MCP_PROTOCOL_VERSION, + capabilities = {}, + clientInfo = { name = "aish", version = "phase2" }, + }) + if not r then return false, kind, err end + self.server_info = r.serverInfo + self.server_caps = r.capabilities + local sv = r.protocolVersion + if sv and sv ~= MCP_PROTOCOL_VERSION then + self.version_warning = + ("protocol version mismatch (sent %s, got %s); proceeding") + :format(MCP_PROTOCOL_VERSION, tostring(sv)) + end + + -- notifications/initialized — fire-and-forget; failure non-fatal. + self:_rpc("notifications/initialized", nil, false) + + -- Eagerly fetch tools (cache for session lifetime per + -- capabilities.tools.listChanged = false). + local tr, tkind, terr = self:_rpc("tools/list", {}) + if not tr then return false, tkind, terr end + self.tools = tr.tools or {} + return true, "ok" +end + +-- ---------------------------------------------------------------- list_tools +-- Cached. Returns the tool list captured at initialize() time; +-- empty table if not initialized. +function Session:list_tools() + return self.tools or {} +end + +-- ---------------------------------------------------------------- call_tool +-- Returns: +-- result_table, "ok" — tool succeeded (content[]) +-- result_table, "handler_error" — tool ran but result.isError = true +-- (caller passes content through +-- to the model regardless; +-- PHASE2-baseline.md §3 also +-- notes isError may be false on +-- actual failure — content is +-- authoritative) +-- nil, "rpc_error", error_obj — JSON-RPC envelope error +-- nil, "transport_error", msg — HTTP/libcurl/parse failure +function Session:call_tool(name, args) + local r, kind, err = self:_rpc("tools/call", + { name = name, arguments = args or {} }) + if not r then return nil, kind, err end + if r.isError then return r, "handler_error" end + return r, "ok" +end + +-- ---------------------------------------------------------------- close +-- Drops cached state. lmcp has no session teardown — every RPC was +-- already Connection: close. +function Session:close() + self.tools = nil + self.server_info = nil + self.server_caps = nil + self.version_warning = nil +end + +return M