mcp: JSON-RPC client + ffi/curl status_code; PHASE0 §4 amended
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) <noreply@anthropic.com>
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user