Skip to main content

qualia_client_core/
remote_mcp.rs

1//! Remote-MCP inference backend — reach an external provider (Claude / Google / X, or another
2//! Webizen node) over the Model Context Protocol to run a completion on the person's behalf.
3//!
4//! Local inference is PREFERRED; this is the opt-in, costly path (Timothy's directive: local-first,
5//! external-via-MCP when wanted/needed; future provider credentials slot in behind the same seam).
6//! Native-only — it does network / process I/O and is never part of the wasm bundle.
7//!
8//! It issues an MCP `tools/call` to a configured inference tool (default `llm_infer`) and extracts the
9//! text from the MCP content result. Three transports, mirroring how the rest of the platform speaks
10//! MCP: **TCP** (newline-delimited JSON-RPC, exactly what the Webizen desktop MCP server on `:4245`
11//! serves), **Stdio** (spawn an MCP server command), and **HTTP** (JSON-RPC POST).
12
13use crate::agent_registry::McpTransport;
14use std::io::{BufRead, BufReader, Write};
15use std::time::Duration;
16
17/// Default MCP tool name to call for inference (the Webizen MCP surface exposes `llm_infer`).
18pub const DEFAULT_INFER_TOOL: &str = "llm_infer";
19
20/// Outcome of one remote inference call: the text plus the lowering receipt
21/// describing how the request reached the tool's schema.
22#[derive(Debug)]
23pub struct RemoteInferOutcome {
24    pub text: String,
25    pub lowering: crate::conditioning::McpLoweringReceipt,
26}
27
28/// Build the JSON-RPC `tools/call` request body for an inference call.
29///
30/// When the tool's schema supports a dedicated `system` argument the request
31/// keeps role separation (`supports_system_role == Some(true)`); otherwise the
32/// system text is flattened into `prompt` and the returned receipt records the
33/// degradation. `None` means the capability was not declared or discoverable —
34/// conservative flattening, reported as such.
35fn build_infer_request(
36    infer_tool: &str,
37    model: Option<&str>,
38    system: Option<&str>,
39    prompt: &str,
40    supports_system_role: Option<bool>,
41) -> (serde_json::Value, crate::conditioning::McpLoweringReceipt) {
42    let (mut args, mut receipt) = crate::conditioning::lower_mcp_tool_arguments(
43        system,
44        prompt,
45        supports_system_role.unwrap_or(false),
46    );
47    if supports_system_role.is_none() && system.is_some() {
48        receipt.degradation_reason =
49            Some("system-role capability not declared or discoverable; flattened into prompt");
50    }
51    if let Some(m) = model {
52        if !m.is_empty() {
53            args["model"] = serde_json::json!(m);
54        }
55    }
56    (
57        serde_json::json!({
58            "jsonrpc": "2.0",
59            "id": 1,
60            "method": "tools/call",
61            "params": { "name": infer_tool, "arguments": args }
62        }),
63        receipt,
64    )
65}
66
67/// Extract the text output from an MCP `tools/call` JSON-RPC response, tolerant of shape variation.
68fn parse_infer_response(resp: &serde_json::Value) -> Result<String, String> {
69    if let Some(err) = resp.get("error") {
70        let msg = err
71            .get("message")
72            .and_then(|v| v.as_str())
73            .unwrap_or("remote MCP error");
74        return Err(format!("remote MCP error: {msg}"));
75    }
76    let result = resp
77        .get("result")
78        .ok_or_else(|| "remote MCP response missing `result`".to_string())?;
79
80    // Canonical MCP content format: result.content = [{ type:"text", text:"…" }, …]
81    if let Some(content) = result.get("content").and_then(|c| c.as_array()) {
82        let mut out = String::new();
83        for part in content {
84            if let Some(t) = part.get("text").and_then(|v| v.as_str()) {
85                out.push_str(t);
86            }
87        }
88        if !out.is_empty() {
89            return Ok(out);
90        }
91    }
92    // Fallbacks for simpler servers.
93    if let Some(t) = result.as_str() {
94        return Ok(t.to_string());
95    }
96    for k in ["text", "output", "completion", "response"] {
97        if let Some(t) = result.get(k).and_then(|v| v.as_str()) {
98            return Ok(t.to_string());
99        }
100    }
101    if result
102        .get("isError")
103        .and_then(|v| v.as_bool())
104        .unwrap_or(false)
105    {
106        return Err("remote MCP tool reported an error".to_string());
107    }
108    Err("remote MCP response had no text content".to_string())
109}
110
111/// Run one inference over the configured MCP transport and return the
112/// completion plus the role-lowering receipt.
113///
114/// `infer_tool` defaults to [`DEFAULT_INFER_TOOL`] when `None`.
115/// `supports_system_role` is the tool-schema capability: `Some` from the
116/// agent's declared configuration or [`remote_mcp_tool_supports_system_role`]
117/// discovery, `None` to flatten conservatively. This is a blocking call — the
118/// caller should run it off the UI thread (the desktop command wrapper uses
119/// `spawn_blocking`).
120pub fn remote_mcp_infer(
121    transport: &McpTransport,
122    infer_tool: Option<&str>,
123    model: Option<&str>,
124    system: Option<&str>,
125    prompt: &str,
126    supports_system_role: Option<bool>,
127) -> Result<RemoteInferOutcome, String> {
128    let tool = infer_tool.unwrap_or(DEFAULT_INFER_TOOL);
129    let (req, lowering) = build_infer_request(tool, model, system, prompt, supports_system_role);
130    let resp = match transport {
131        McpTransport::Tcp { host, port } => call_tcp(host, *port, &req)?,
132        McpTransport::Stdio { command, args } => call_stdio(command, args, &req)?,
133        McpTransport::Http { url, credential_id } => {
134            call_http(url, credential_id.as_deref(), &req)?
135        }
136    };
137    Ok(RemoteInferOutcome {
138        text: parse_infer_response(&resp)?,
139        lowering,
140    })
141}
142
143/// Discover whether the named inference tool's declared `inputSchema` accepts
144/// a dedicated `system` argument, via a `tools/list` round-trip.
145/// `None` = capability unknown (endpoint error or tool absent); callers fall
146/// back to flattened arguments.
147pub fn remote_mcp_tool_supports_system_role(
148    transport: &McpTransport,
149    tool_name: &str,
150) -> Option<bool> {
151    let req = serde_json::json!({
152        "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}
153    });
154    let response = match transport {
155        McpTransport::Tcp { host, port } => call_tcp(host, *port, &req).ok()?,
156        McpTransport::Stdio { command, args } => call_stdio(command, args, &req).ok()?,
157        McpTransport::Http { url, credential_id } => {
158            call_http(url, credential_id.as_deref(), &req).ok()?
159        }
160    };
161    let tools = response
162        .get("result")
163        .and_then(|result| result.get("tools"))
164        .and_then(|tools| tools.as_array())?;
165    let tool = tools
166        .iter()
167        .find(|tool| tool.get("name").and_then(|n| n.as_str()) == Some(tool_name))?;
168    let properties = tool
169        .get("inputSchema")
170        .and_then(|schema| schema.get("properties"))
171        .and_then(|props| props.as_object())?;
172    Some(properties.contains_key("system"))
173}
174
175fn call_tcp(host: &str, port: u16, req: &serde_json::Value) -> Result<serde_json::Value, String> {
176    use std::net::TcpStream;
177    let stream =
178        TcpStream::connect((host, port)).map_err(|e| format!("connect {host}:{port}: {e}"))?;
179    stream.set_read_timeout(Some(Duration::from_secs(120))).ok();
180    stream.set_write_timeout(Some(Duration::from_secs(30))).ok();
181    let mut writer = stream.try_clone().map_err(|e| e.to_string())?;
182    let mut reader = BufReader::new(stream);
183    let line = serde_json::to_string(req).map_err(|e| e.to_string())?;
184    writer
185        .write_all(line.as_bytes())
186        .map_err(|e| e.to_string())?;
187    writer.write_all(b"\n").map_err(|e| e.to_string())?;
188    writer.flush().ok();
189    // Read JSON-RPC response lines until one carries our result/error (skip any notifications).
190    let mut buf = String::new();
191    for _ in 0..100 {
192        buf.clear();
193        let n = reader
194            .read_line(&mut buf)
195            .map_err(|e| format!("read: {e}"))?;
196        if n == 0 {
197            break;
198        }
199        let t = buf.trim();
200        if t.is_empty() {
201            continue;
202        }
203        if let Ok(v) = serde_json::from_str::<serde_json::Value>(t) {
204            if v.get("result").is_some() || v.get("error").is_some() {
205                return Ok(v);
206            }
207        }
208    }
209    Err("no JSON-RPC response from remote MCP (TCP)".into())
210}
211
212fn call_stdio(
213    command: &str,
214    args: &[String],
215    req: &serde_json::Value,
216) -> Result<serde_json::Value, String> {
217    use std::process::{Command, Stdio};
218    let mut child = Command::new(command)
219        .args(args)
220        .stdin(Stdio::piped())
221        .stdout(Stdio::piped())
222        .stderr(Stdio::null())
223        .spawn()
224        .map_err(|e| format!("spawn {command}: {e}"))?;
225    {
226        let stdin = child.stdin.as_mut().ok_or("no stdin on MCP child")?;
227        let line = serde_json::to_string(req).map_err(|e| e.to_string())?;
228        stdin
229            .write_all(line.as_bytes())
230            .map_err(|e| e.to_string())?;
231        stdin.write_all(b"\n").map_err(|e| e.to_string())?;
232        stdin.flush().ok();
233    }
234    let stdout = child.stdout.take().ok_or("no stdout on MCP child")?;
235    let mut reader = BufReader::new(stdout);
236    let mut buf = String::new();
237    let mut found = None;
238    for _ in 0..200 {
239        buf.clear();
240        let n = reader
241            .read_line(&mut buf)
242            .map_err(|e| format!("read: {e}"))?;
243        if n == 0 {
244            break;
245        }
246        let t = buf.trim();
247        if t.is_empty() {
248            continue;
249        }
250        if let Ok(v) = serde_json::from_str::<serde_json::Value>(t) {
251            if v.get("result").is_some() || v.get("error").is_some() {
252                found = Some(v);
253                break;
254            }
255        }
256    }
257    let _ = child.kill();
258    let _ = child.wait();
259    found.ok_or_else(|| "no JSON-RPC response from stdio MCP server".to_string())
260}
261
262fn call_http(
263    url: &str,
264    credential_id: Option<&str>,
265    req: &serde_json::Value,
266) -> Result<serde_json::Value, String> {
267    let client = reqwest::blocking::Client::builder()
268        .timeout(Duration::from_secs(180))
269        .build()
270        .map_err(|e| e.to_string())?;
271    let mut request = client
272        .post(url)
273        .header("content-type", "application/json")
274        .header("accept", "application/json")
275        .json(req);
276    if let Some(connection) = credential_id.filter(|value| !value.trim().is_empty()) {
277        // The credential exists only in the platform keychain and is read at
278        // dispatch time after the caller has obtained consent.
279        let secret = crate::provider_credentials::bearer_credential(connection)?;
280        request = request.bearer_auth(secret);
281    }
282    let resp = request.send().map_err(|e| format!("http post: {e}"))?;
283    let status = resp.status();
284    let text = resp.text().map_err(|e| e.to_string())?;
285    if !status.is_success() {
286        let snippet: String = text.chars().take(240).collect();
287        return Err(format!("remote MCP HTTP {status}: {snippet}"));
288    }
289    serde_json::from_str(&text).map_err(|e| format!("parse http json: {e}"))
290}
291
292/// Test an MCP endpoint without asking it to generate text.  It sends the
293/// standard `tools/list` request and only reports that a response was received.
294pub fn remote_mcp_probe(transport: &McpTransport) -> Result<usize, String> {
295    let req = serde_json::json!({
296        "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}
297    });
298    let response = match transport {
299        McpTransport::Tcp { host, port } => call_tcp(host, *port, &req)?,
300        McpTransport::Stdio { command, args } => call_stdio(command, args, &req)?,
301        McpTransport::Http { url, credential_id } => {
302            call_http(url, credential_id.as_deref(), &req)?
303        }
304    };
305    if let Some(error) = response.get("error") {
306        let message = error
307            .get("message")
308            .and_then(|value| value.as_str())
309            .unwrap_or("MCP error");
310        return Err(format!("MCP tools/list failed: {message}"));
311    }
312    let tools = response
313        .get("result")
314        .and_then(|result| result.get("tools"))
315        .and_then(|tools| tools.as_array())
316        .ok_or_else(|| "MCP tools/list response had no tools array".to_string())?;
317    Ok(tools.len())
318}
319
320#[cfg(test)]
321mod tests {
322    use super::*;
323
324    #[test]
325    fn request_is_valid_tools_call() {
326        let (req, receipt) =
327            build_infer_request("llm_chat", Some("phi-3"), Some("Be terse."), "hi", None);
328        assert_eq!(req["jsonrpc"], "2.0");
329        assert_eq!(req["method"], "tools/call");
330        assert_eq!(req["params"]["name"], "llm_chat");
331        assert_eq!(req["params"]["arguments"]["model"], "phi-3");
332        let prompt = req["params"]["arguments"]["prompt"].as_str().unwrap();
333        assert!(prompt.starts_with("Be terse."));
334        assert!(prompt.ends_with("hi"));
335        assert_eq!(
336            receipt.mode,
337            crate::conditioning::McpLoweringMode::Flattened
338        );
339        assert!(receipt.role_degraded);
340        assert_eq!(
341            receipt.degradation_reason,
342            Some("system-role capability not declared or discoverable; flattened into prompt")
343        );
344    }
345
346    #[test]
347    fn request_omits_empty_model_and_system() {
348        let (req, receipt) = build_infer_request(DEFAULT_INFER_TOOL, None, None, "just this", None);
349        assert!(req["params"]["arguments"].get("model").is_none());
350        assert_eq!(req["params"]["arguments"]["prompt"], "just this");
351        assert!(!receipt.role_degraded);
352    }
353
354    #[test]
355    fn structured_request_keeps_roles_when_schema_supports_system() {
356        let (req, receipt) =
357            build_infer_request("llm_chat", None, Some("Be terse."), "hi", Some(true));
358        assert_eq!(req["params"]["arguments"]["system"], "Be terse.");
359        assert_eq!(req["params"]["arguments"]["prompt"], "hi");
360        assert_eq!(
361            receipt.mode,
362            crate::conditioning::McpLoweringMode::Structured
363        );
364        assert!(!receipt.role_degraded);
365        assert!(receipt.degradation_reason.is_none());
366    }
367
368    #[test]
369    fn declared_unsupported_schema_flattens_with_reason() {
370        let (req, receipt) =
371            build_infer_request("llm_chat", None, Some("Be terse."), "hi", Some(false));
372        assert!(req["params"]["arguments"].get("system").is_none());
373        assert!(req["params"]["arguments"]["prompt"]
374            .as_str()
375            .unwrap()
376            .starts_with("Be terse."));
377        assert!(receipt.role_degraded);
378        assert_eq!(
379            receipt.degradation_reason,
380            Some("MCP tool schema lacks dedicated system parameter; flattened into prompt")
381        );
382    }
383
384    #[test]
385    fn parses_mcp_content_array() {
386        let resp = serde_json::json!({
387            "jsonrpc": "2.0", "id": 1,
388            "result": { "content": [ {"type":"text","text":"Hello"}, {"type":"text","text":", world"} ] }
389        });
390        assert_eq!(parse_infer_response(&resp).unwrap(), "Hello, world");
391    }
392
393    #[test]
394    fn parses_simple_fallbacks() {
395        let a = serde_json::json!({ "result": "plain string" });
396        assert_eq!(parse_infer_response(&a).unwrap(), "plain string");
397        let b = serde_json::json!({ "result": { "text": "keyed text" } });
398        assert_eq!(parse_infer_response(&b).unwrap(), "keyed text");
399    }
400
401    #[test]
402    fn surfaces_errors() {
403        let e = serde_json::json!({ "error": { "code": -32000, "message": "boom" } });
404        assert!(parse_infer_response(&e).unwrap_err().contains("boom"));
405        let ie = serde_json::json!({ "result": { "isError": true, "content": [] } });
406        assert!(parse_infer_response(&ie).is_err());
407    }
408}