Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_net/src/mcp.rs

31.9 KiB, 14 runs

created by r1870400018:79729, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! A client of the Model Context Protocol, revision 2025-06-18: JSON-RPC 2.0 with a server
2//! started as a child and spoken to over its stdin and stdout, or one reached over streamable
3//! HTTP, directly or through a local proxy's Unix socket.
4//!
5//! Tools are listed and called, resources listed and read, prompts listed and got. Every
6//! request waits no longer than its caller says, a message is bounded in bytes, and a child that
7//! ends fails every request still waiting on it. How the child is started, its environment
8//! included, is the caller's: it hands over the `Command`.
9
10use crate::http::{
11 client::{
12 request_over,
13 url_request,
14 },
15 fields::HeaderName,
16 header::{
17 HttpHeadline,
18 HttpMethod,
19 },
20 loc::Url,
21 msg::{
22 HttpMessage,
23 ReadLimits,
24 },
25};
26
27use oxedyne_fe2o3_core::prelude::*;
28use oxedyne_fe2o3_jdat::{
29 prelude::*,
30 bdat::limits::DecodeLimits,
31};
32
33use std::{
34 collections::BTreeMap,
35 path::PathBuf,
36 process::Stdio as Piped,
37 sync::{
38 Arc,
39 Mutex,
40 Weak,
41 atomic::{
42 AtomicBool,
43 AtomicU64,
44 Ordering,
45 },
46 },
47 time::Duration,
48};
49
50use tokio::{
51 io::{
52 AsyncBufReadExt,
53 AsyncRead,
54 AsyncReadExt,
55 AsyncWriteExt,
56 BufReader,
57 },
58 net::UnixStream,
59 process::{
60 Child,
61 ChildStdin,
62 Command,
63 },
64 sync::{
65 oneshot,
66 Mutex as AsyncMutex,
67 },
68};
69use tokio_rustls::rustls::ClientConfig;
70
71
72pub const PROTOCOL: &str = "2025-06-18"; // fixed: the revision this client speaks
73const NO_METHOD: i64 = -32601; // fixed: JSON-RPC 2.0's "Method not found"
74
75#[derive(Clone, Debug)]
76pub struct Limits {
77 pub line_max: usize, // bytes of one message either way
78 pub stderr_max: u64, // bytes of a child's stderr kept in its file
79 pub wait: Duration, // for the server to answer `initialize`
80}
81
82/// How the server is reached.
83pub enum Transport {
84 /// A child, its stdin, stdout and stderr piped here; its stderr is kept in `stderr`, up to
85 /// `Limits::stderr_max` bytes, or read and dropped when that is `None`.
86 Stdio { cmd: Command, stderr: Option<PathBuf> },
87 /// A streamable HTTP endpoint, each message one POST. With `via`, the POST goes in plain
88 /// HTTP to that Unix socket, a proxy that carries it on; else to the URL's own host.
89 Http { url: Url, headers: Vec<(String, String)>, via: Option<PathBuf>, tls: Option<Arc<ClientConfig>> },
90}
91
92/// What the server said of itself in its answer to `initialize`.
93#[derive(Clone, Debug, Default)]
94pub struct Server {
95 pub name: String,
96 pub version: String,
97 pub protocol: String,
98 pub instructions: String,
99 pub tools: bool,
100 pub resources: bool,
101 pub prompts: bool,
102}
103
104#[derive(Clone, Debug)]
105pub struct Tool {
106 pub name: String,
107 pub title: String,
108 pub description: String,
109 pub schema: Dat, // its `inputSchema`
110 pub read_only: bool, // its `readOnlyHint`, a hint the server gives and nothing proves
111}
112
113#[derive(Clone, Debug, Default)]
114pub struct Resource {
115 pub uri: String,
116 pub name: String,
117 pub title: String,
118 pub description: String,
119 pub mime: String,
120}
121
122#[derive(Clone, Debug, Default)]
123pub struct Prompt {
124 pub name: String,
125 pub title: String,
126 pub description: String,
127 pub arguments: Vec<(String, String, bool)>, // each its name, description and whether required
128}
129
130/// One piece of a result, base64 decoded. A piece whose base64 does not decode is said in words.
131#[derive(Clone, Debug, PartialEq, Eq)]
132pub enum Content {
133 Text(String),
134 Image { data: Vec<u8>, mime: String },
135 Audio { data: Vec<u8>, mime: String },
136 Resource { uri: String, mime: String, text: Option<String>, blob: Option<Vec<u8>> },
137 Link { uri: String, name: String, mime: String },
138}
139
140/// A tool's answer: its content, and whether the tool says it failed.
141#[derive(Clone, Debug, PartialEq, Eq)]
142pub struct Called {
143 pub content: Vec<Content>,
144 pub error: bool,
145}
146
147type Waiting = Arc<Mutex<BTreeMap<u64, oneshot::Sender<Outcome<Dat>>>>>;
148
149pub struct Client {
150 conn: Conn,
151 next: AtomicU64,
152 changed: Arc<AtomicBool>,
153 pub server: Server,
154}
155
156enum Conn {
157 Stdio(Stdio),
158 Http(Http),
159}
160
161impl Client {
162
163 /// Starts or reaches the server and opens the session, within `limits.wait`.
164 pub async fn connect(t: Transport, limits: &Limits, name: &str, version: &str) -> Outcome<Self> {
165 let changed = Arc::new(AtomicBool::new(false));
166 let decode = DecodeLimits { max_bytes: limits.line_max, ..Default::default() };
167 let conn = match t {
168 Transport::Stdio { cmd, stderr } => Conn::Stdio(res!(Stdio::start(cmd, stderr, limits, &changed, decode))),
169 Transport::Http { url, headers, via, tls } => Conn::Http(Http {
170 url, headers, via, tls, line_max: limits.line_max, decode,
171 session: Mutex::new(String::new()), protocol: Mutex::new(String::new()), refused: Mutex::new(String::new()),
172 }),
173 };
174 let mut c = Self { conn, next: AtomicU64::new(1), changed, server: Server::default() };
175 let hello = fmt!("{{\"protocolVersion\":{},\"capabilities\":{{}},\"clientInfo\":{{\"name\":{},\"version\":{}}}}}",
176 res!(quote(PROTOCOL)), res!(quote(name)), res!(quote(version)));
177 let r = match c.request("initialize", &hello, limits.wait).await {
178 Ok(r) => r,
179 Err(e) => return Err(c.ended_with(e).await),
180 };
181 let caps = member(&r, "capabilities");
182 c.server = Server {
183 name: text(member(&r, "serverInfo"), "name"),
184 version: text(member(&r, "serverInfo"), "version"),
185 protocol: text(Some(&r), "protocolVersion"),
186 instructions: text(Some(&r), "instructions"),
187 tools: caps.and_then(|m| member(m, "tools")).is_some(),
188 resources: caps.and_then(|m| member(m, "resources")).is_some(),
189 prompts: caps.and_then(|m| member(m, "prompts")).is_some(),
190 };
191 if let Conn::Http(h) = &c.conn {
192 *lock_mutex!(h.protocol) = c.server.protocol.clone();
193 }
194 res!(c.notify("notifications/initialized", "{}").await);
195 Ok(c)
196 }
197
198 /// One request's result, or the server's error in words. `params` is a JSON object's text.
199 pub async fn request(&self, method: &str, params: &str, wait: Duration) -> Outcome<Dat> {
200 let id = self.next.fetch_add(1, Ordering::Relaxed);
201 let msg = fmt!("{{\"jsonrpc\":\"2.0\",\"id\":{},\"method\":{},\"params\":{}}}", id, res!(quote(method)), params);
202 let answer = match &self.conn {
203 Conn::Stdio(s) => s.request(id, &msg, method, wait).await,
204 Conn::Http(h) => h.request(id, &msg, method, wait, &self.changed).await,
205 };
206 match answer {
207 Ok(a) => answered(a, method),
208 Err(e) if is_timeout(&e) => {
209 let note = fmt!("{{\"requestId\":{},\"reason\":\"timed out\"}}", id);
210 let _ = self.notify("notifications/cancelled", &note).await;
211 Err(e)
212 },
213 Err(e) => Err(e),
214 }
215 }
216
217 pub async fn notify(&self, method: &str, params: &str) -> Outcome<()> {
218 let msg = fmt!("{{\"jsonrpc\":\"2.0\",\"method\":{},\"params\":{}}}", res!(quote(method)), params);
219 match &self.conn {
220 Conn::Stdio(s) => s.send(&msg).await,
221 Conn::Http(h) => h.post(&msg, NOTE_WAIT).await.map(|_| ()),
222 }
223 }
224
225 /// The server's tools, at most `max` of them, its pages followed.
226 pub async fn tools(&self, max: usize, wait: Duration) -> Outcome<Vec<Tool>> {
227 self.changed.store(false, Ordering::Relaxed);
228 let mut out = Vec::new();
229 for d in res!(self.pages("tools/list", "tools", max, wait).await) {
230 let ann = member(&d, "annotations");
231 out.push(Tool {
232 name: text(Some(&d), "name"),
233 title: text(Some(&d), "title"),
234 description: text(Some(&d), "description"),
235 schema: member(&d, "inputSchema").cloned().unwrap_or_else(|| mapdat!{ "type" => "object" }),
236 read_only: matches!(ann.and_then(|a| member(a, "readOnlyHint")), Some(Dat::Bool(true))),
237 });
238 }
239 Ok(out)
240 }
241
242 /// Calls the tool `name` with `args`, a JSON object's text.
243 pub async fn call(&self, name: &str, args: &str, wait: Duration) -> Outcome<Called> {
244 let params = fmt!("{{\"name\":{},\"arguments\":{}}}", res!(quote(name)), args);
245 let r = res!(self.request("tools/call", &params, wait).await);
246 let mut content = contents(member(&r, "content"));
247 // A result given only as structured content is read as its JSON.
248 if content.is_empty() {
249 if let Some(s) = member(&r, "structuredContent") {
250 content.push(Content::Text(res!(s.json_canonical())));
251 }
252 }
253 Ok(Called { content, error: matches!(member(&r, "isError"), Some(Dat::Bool(true))) })
254 }
255
256 pub async fn resources(&self, max: usize, wait: Duration) -> Outcome<Vec<Resource>> {
257 Ok(res!(self.pages("resources/list", "resources", max, wait).await).iter().map(|d| Resource {
258 uri: text(Some(d), "uri"),
259 name: text(Some(d), "name"),
260 title: text(Some(d), "title"),
261 description: text(Some(d), "description"),
262 mime: text(Some(d), "mimeType"),
263 }).collect())
264 }
265
266 pub async fn read(&self, uri: &str, wait: Duration) -> Outcome<Vec<Content>> {
267 let r = res!(self.request("resources/read", &fmt!("{{\"uri\":{}}}", res!(quote(uri))), wait).await);
268 Ok(member(&r, "contents").and_then(list).unwrap_or_default().iter().map(resource).collect())
269 }
270
271 pub async fn prompts(&self, max: usize, wait: Duration) -> Outcome<Vec<Prompt>> {
272 Ok(res!(self.pages("prompts/list", "prompts", max, wait).await).iter().map(|d| Prompt {
273 name: text(Some(d), "name"),
274 title: text(Some(d), "title"),
275 description: text(Some(d), "description"),
276 arguments: member(d, "arguments").and_then(list).unwrap_or_default().iter().map(|a| (
277 text(Some(a), "name"), text(Some(a), "description"), matches!(member(a, "required"), Some(Dat::Bool(true))),
278 )).collect(),
279 }).collect())
280 }
281
282 /// The prompt `name` filled with `args`, a JSON object's text: each message's role and content.
283 pub async fn prompt(&self, name: &str, args: &str, wait: Duration) -> Outcome<Vec<(String, Content)>> {
284 let params = fmt!("{{\"name\":{},\"arguments\":{}}}", res!(quote(name)), args);
285 let r = res!(self.request("prompts/get", &params, wait).await);
286 Ok(member(&r, "messages").and_then(list).unwrap_or_default().iter().filter_map(|m| {
287 let c = contents(member(m, "content").map(|c| Dat::List(vec![c.clone()])).as_ref());
288 c.into_iter().next().map(|c| (text(Some(m), "role"), c))
289 }).collect())
290 }
291
292 /// Has the server said its tools changed since they were last listed?
293 pub fn changed(&self) -> bool {
294 self.changed.load(Ordering::Relaxed)
295 }
296
297 /// Why the server can no longer answer, none while it can. A server over HTTP is asked each time,
298 /// and its session is over once it refuses the authorisation sent.
299 pub fn ended(&self) -> Option<String> {
300 match &self.conn {
301 Conn::Stdio(s) => s.ended(),
302 Conn::Http(h) => h.refused.lock().ok().map(|r| r.clone()).filter(|r| !r.is_empty()),
303 }
304 }
305
306 /// The child's process id, for a caller that ends its process group.
307 pub fn pid(&self) -> Option<u32> {
308 match &self.conn {
309 Conn::Stdio(s) => s.pid,
310 Conn::Http(_) => None,
311 }
312 }
313
314 /// Ends the session: a child's stdin is closed and it is killed if it has not ended within
315 /// `grace`; an HTTP session is deleted.
316 pub async fn close(&self, grace: Duration) {
317 match &self.conn {
318 Conn::Stdio(s) => s.close(grace).await,
319 Conn::Http(h) => h.delete(grace).await,
320 }
321 }
322
323 // A start that failed says what the child left, where it ended.
324 async fn ended_with(&self, e: Error<ErrTag>) -> Error<ErrTag> {
325 match self.ended() {
326 Some(why) => err!(e, "{}", why; IO, Network),
327 None => e,
328 }
329 }
330
331 // Every item of a paged list, at most `max`.
332 async fn pages(&self, method: &str, key: &str, max: usize, wait: Duration) -> Outcome<Vec<Dat>> {
333 let mut out = Vec::new();
334 let mut cursor = String::new();
335 loop {
336 let params = match cursor.is_empty() {
337 true => "{}".to_string(),
338 false => fmt!("{{\"cursor\":{}}}", res!(quote(&cursor))),
339 };
340 let r = res!(self.request(method, &params, wait).await);
341 out.extend(member(&r, key).and_then(list).unwrap_or_default().into_iter().take(max.saturating_sub(out.len())));
342 cursor = text(Some(&r), "nextCursor");
343 if cursor.is_empty() || out.len() >= max {
344 return Ok(out);
345 }
346 }
347 }
348}
349
350const NOTE_WAIT: Duration = Duration::from_secs(10); // fixed: the most a notification over HTTP is waited on
351
352// ┌───────────────────────────────────────────────────────────────────────────┐
353// │ STDIO │
354// └───────────────────────────────────────────────────────────────────────────┘
355
356struct Stdio {
357 child: AsyncMutex<Child>,
358 stdin: Arc<AsyncMutex<Option<ChildStdin>>>,
359 waiting: Waiting,
360 ended: Arc<Mutex<Option<String>>>,
361 stderr: Option<PathBuf>,
362 pid: Option<u32>,
363}
364
365impl Stdio {
366
367 fn start(mut cmd: Command, stderr: Option<PathBuf>, limits: &Limits, changed: &Arc<AtomicBool>, decode: DecodeLimits)
368 -> Outcome<Self>
369 {
370 cmd.stdin(Piped::piped()).stdout(Piped::piped()).stderr(Piped::piped()).kill_on_drop(true);
371 let mut child = res!(cmd.spawn().map_err(|e| err!(e, "The MCP server {:?} did not start.",
372 cmd.as_std().get_program(); IO, Init)));
373 let (out, err, inp) = (child.stdout.take(), child.stderr.take(), child.stdin.take());
374 let (Some(out), Some(err), Some(inp)) = (out, err, inp) else {
375 return Err(err!("The MCP server's pipes were not given."; IO, Init, Missing));
376 };
377 let s = Self {
378 pid: child.id(),
379 child: AsyncMutex::new(child),
380 stdin: Arc::new(AsyncMutex::new(Some(inp))),
381 waiting: Arc::new(Mutex::new(BTreeMap::new())),
382 ended: Arc::new(Mutex::new(None)),
383 stderr: stderr.clone(),
384 };
385 tokio::spawn(read(BufReader::new(out), limits.line_max, decode, s.waiting.clone(), s.ended.clone(),
386 changed.clone(), Arc::downgrade(&s.stdin)));
387 tokio::spawn(keep(err, stderr, limits.stderr_max));
388 Ok(s)
389 }
390
391 async fn send(&self, msg: &str) -> Outcome<()> {
392 let mut g = self.stdin.lock().await;
393 let w = res!(g.as_mut().ok_or_else(|| err!("The MCP server's stdin is closed."; IO, Write, Missing)));
394 let line = fmt!("{}\n", msg);
395 match w.write_all(line.as_bytes()).await {
396 Ok(()) => w.flush().await.map_err(|e| err!(e, "Writing to the MCP server."; IO, Write)),
397 Err(e) => Err(err!(e, "Writing to the MCP server: {}", self.ended().unwrap_or_default(); IO, Write)),
398 }
399 }
400
401 async fn request(&self, id: u64, msg: &str, method: &str, wait: Duration) -> Outcome<Dat> {
402 let (tx, rx) = oneshot::channel();
403 lock_mutex!(self.waiting).insert(id, tx);
404 if let Some(why) = self.ended() {
405 lock_mutex!(self.waiting).remove(&id);
406 return Err(err!("{}", why; IO, Network, Missing));
407 }
408 if let Err(e) = self.send(msg).await {
409 lock_mutex!(self.waiting).remove(&id);
410 return Err(e);
411 }
412 match tokio::time::timeout(wait, rx).await {
413 Ok(Ok(a)) => a,
414 Ok(Err(_)) => Err(err!("{}", self.ended().unwrap_or_else(|| "The MCP server ended.".to_string());
415 IO, Network, Missing)),
416 Err(_) => {
417 lock_mutex!(self.waiting).remove(&id);
418 Err(err!("The MCP server did not answer {} within {} ms.", method, wait.as_millis(); IO, Network, Timeout))
419 },
420 }
421 }
422
423 fn ended(&self) -> Option<String> {
424 let kept = self.stderr.as_ref().map(|p| fmt!(" Its stderr is kept in {}.", p.display())).unwrap_or_default();
425 self.ended.lock().ok().and_then(|g| g.clone()).map(|why| fmt!("{}{}", why, kept))
426 }
427
428 async fn close(&self, grace: Duration) {
429 self.stdin.lock().await.take();
430 let mut c = self.child.lock().await;
431 if tokio::time::timeout(grace, c.wait()).await.is_err() {
432 let _ = c.start_kill();
433 let _ = c.wait().await;
434 }
435 }
436}
437
438// The child's stdout read to its end: each answer handed to the request waiting on it, a ping
439// answered, any other request of the server's refused, a change of its tools noted.
440async fn read<R: AsyncRead + Unpin>(mut r: BufReader<R>, max: usize, decode: DecodeLimits, waiting: Waiting,
441 ended: Arc<Mutex<Option<String>>>, changed: Arc<AtomicBool>, stdin: Weak<AsyncMutex<Option<ChildStdin>>>)
442{
443 let mut buf = Vec::new();
444 let why = loop {
445 match line(&mut r, max, &mut buf).await {
446 Ok(None) => break "The MCP server ended its output.".to_string(),
447 Ok(Some(false)) => continue, // a line over `max`, dropped
448 Ok(Some(true)) => (),
449 Err(e) => break fmt!("Reading the MCP server failed: {}.", e),
450 }
451 let msg = match std::str::from_utf8(&buf).map(|s| Dat::decode_json_strict(s.trim(), &decode)) {
452 Ok(Ok(m)) => m,
453 _ => continue, // a line that is no JSON, such as a stray log line
454 };
455 if let Some(reply) = heard(&msg, Some(&waiting), &changed) {
456 if let Some(w) = stdin.upgrade() {
457 if let Some(s) = w.lock().await.as_mut() {
458 let _ = s.write_all(fmt!("{}\n", reply).as_bytes()).await;
459 let _ = s.flush().await;
460 }
461 }
462 }
463 };
464 if let Ok(mut g) = ended.lock() {
465 *g = Some(why.clone());
466 }
467 if let Ok(mut w) = waiting.lock() {
468 for (_, tx) in std::mem::take(&mut *w) {
469 let _ = tx.send(Err(err!("{}", why; IO, Network, Missing)));
470 }
471 }
472}
473
474// One message from the server: an answer goes to its request; a request of the server's gets the
475// reply returned here.
476fn heard(msg: &Dat, waiting: Option<&Waiting>, changed: &AtomicBool) -> Option<String> {
477 let id = member(msg, "id");
478 let method = text(Some(msg), "method");
479 match (id, method.as_str()) {
480 (Some(id), "") => {
481 let tx = id.get_u64().zip(waiting).and_then(|(n, w)| w.lock().ok().and_then(|mut w| w.remove(&n)));
482 if let Some(tx) = tx {
483 let _ = tx.send(Ok(msg.clone()));
484 }
485 None
486 },
487 (Some(id), m) => id.json_canonical().ok().map(|id| match m {
488 "ping" => fmt!("{{\"jsonrpc\":\"2.0\",\"id\":{},\"result\":{{}}}}", id),
489 _ => fmt!("{{\"jsonrpc\":\"2.0\",\"id\":{},\"error\":{{\"code\":{},\"message\":\"This client does not \
490 answer {}.\"}}}}", id, NO_METHOD, m.replace(['"', '\\'], "")),
491 }),
492 (None, "notifications/tools/list_changed") => { changed.store(true, Ordering::Relaxed); None },
493 (None, _) => None,
494 }
495}
496
497// One line into `buf`, its end dropped: `None` at the end of the stream, `Some(false)` for a line
498// over `max`, read on to its end and dropped, so that no line is held past `max`.
499async fn line<R: AsyncRead + Unpin>(r: &mut BufReader<R>, max: usize, buf: &mut Vec<u8>) -> std::io::Result<Option<bool>> {
500 buf.clear();
501 let mut over = false;
502 loop {
503 let got = match r.fill_buf().await {
504 Ok(b) => b,
505 Err(e) => return Err(e),
506 };
507 if got.is_empty() {
508 return Ok(if buf.is_empty() && !over { None } else { Some(!over) });
509 }
510 let (n, end) = match got.iter().position(|b| *b == b'\n') {
511 Some(i) => (i + 1, true),
512 None => (got.len(), false),
513 };
514 if !over && buf.len() + n <= max.saturating_add(1) {
515 buf.extend_from_slice(&got[..n]);
516 } else {
517 over = true;
518 buf.clear();
519 }
520 r.consume(n);
521 if end {
522 return Ok(Some(!over));
523 }
524 }
525}
526
527// The child's stderr kept in `to` up to `max` bytes, the rest read and dropped, so the child never
528// blocks on a full pipe.
529async fn keep<R: AsyncRead + Unpin>(mut err: R, to: Option<PathBuf>, max: u64) {
530 let mut file = match &to {
531 Some(p) => tokio::fs::File::create(p).await.ok(),
532 None => None,
533 };
534 let (mut kept, mut b) = (0u64, vec![0u8; 8192]);
535 loop {
536 let n = match err.read(&mut b).await {
537 Ok(0) | Err(_) => return,
538 Ok(n) => n,
539 };
540 if let Some(f) = file.as_mut() {
541 let room = max.saturating_sub(kept).min(n as u64) as usize;
542 // A tokio file holds a write until flushed: flush each, so the file says what was said.
543 if room > 0 && f.write_all(&b[..room]).await.is_ok() && f.flush().await.is_ok() {
544 kept += room as u64;
545 }
546 if kept >= max {
547 let _ = f.write_all(fmt!("\n[stderr cut at {} bytes]\n", max).as_bytes()).await;
548 let _ = f.flush().await;
549 file = None;
550 }
551 }
552 }
553}
554
555// ┌───────────────────────────────────────────────────────────────────────────┐
556// │ STREAMABLE HTTP │
557// └───────────────────────────────────────────────────────────────────────────┘
558
559struct Http {
560 url: Url,
561 headers: Vec<(String, String)>,
562 via: Option<PathBuf>,
563 tls: Option<Arc<ClientConfig>>,
564 line_max: usize,
565 decode: DecodeLimits,
566 session: Mutex<String>, // `Mcp-Session-Id`, once the server gives one
567 protocol: Mutex<String>, // the revision agreed, sent after `initialize`
568 refused: Mutex<String>, // why the server refused its authorisation, once it has
569}
570
571impl Http {
572
573 async fn request(&self, id: u64, msg: &str, method: &str, wait: Duration, changed: &AtomicBool) -> Outcome<Dat> {
574 let reply = res!(self.post(msg, wait).await);
575 // An answer may come as the one JSON body, or among the events of a stream.
576 let msgs = res!(self.messages(&reply));
577 for m in &msgs {
578 if member(m, "method").is_some() {
579 let _ = heard(m, None, changed);
580 } else if member(m, "id").and_then(|i| i.get_u64()) == Some(id) {
581 return Ok(m.clone());
582 }
583 }
584 Err(err!("The MCP server at {} gave no answer to {}.", self.url.host, method; IO, Network, Missing))
585 }
586
587 async fn post(&self, msg: &str, wait: Duration) -> Outcome<HttpMessage> {
588 let (session, protocol) = (lock_mutex!(self.session).clone(), lock_mutex!(self.protocol).clone());
589 let mut h: Vec<(&str, &str)> = vec![
590 ("Content-Type", "application/json"),
591 ("Accept", "application/json, text/event-stream"), // fixed: the transport's two answers
592 ];
593 if !session.is_empty() {
594 h.push(("Mcp-Session-Id", &session));
595 }
596 if !protocol.is_empty() {
597 h.push(("MCP-Protocol-Version", &protocol));
598 }
599 h.extend(self.headers.iter().map(|(n, v)| (n.as_str(), v.as_str())));
600 let r = res!(self.send(HttpMethod::POST, &h, msg.as_bytes(), wait).await);
601 let status = match &r.header.headline {
602 HttpHeadline::Response { status } => status.clone() as u16,
603 _ => 0,
604 };
605 if let Some(s) = r.header.fields.get_one(&HeaderName::from("mcp-session-id")) {
606 *lock_mutex!(self.session) = s.to_string();
607 }
608 match status {
609 200..=299 => Ok(r),
610 404 if !session.is_empty() => Err(err!("The MCP server at {} ended the session.", self.url.host;
611 IO, Network, Missing)),
612 // A sign-in is the caller's (`oauth`): its challenge is read there, never here.
613 401 => {
614 let why = fmt!("The MCP server at {} asks for authorisation (401).", self.url.host);
615 *lock_mutex!(self.refused) = why.clone();
616 Err(err!("{}", why; IO, Network, Unauthorised))
617 },
618 _ => Err(err!("The MCP server at {} answered {}: {}", self.url.host, status,
619 String::from_utf8_lossy(&r.body[..r.body.len().min(512)]).trim(); IO, Network)), // fixed: enough of a refusal to read
620 }
621 }
622
623 async fn send(&self, method: HttpMethod, headers: &[(&str, &str)], body: &[u8], wait: Duration) -> Outcome<HttpMessage> {
624 let limits = ReadLimits { max_body_bytes: Some(self.line_max), ..Default::default() };
625 match &self.via {
626 None => url_request(&self.url, method, &self.url.target, headers, body, self.tls.clone(),
627 Some(&limits), wait).await,
628 Some(sock) => {
629 let host = fmt!("{}", self.url.host);
630 let go = async {
631 let mut s = res!(UnixStream::connect(sock).await.map_err(|e| err!(e,
632 "The proxy's socket {} cannot be reached.", sock.display(); IO, Network, Init)));
633 request_over(&mut s, &host, method, &self.url.target, headers, body, Some(&limits)).await
634 };
635 match tokio::time::timeout(wait, go).await {
636 Ok(r) => r,
637 Err(_) => Err(err!("The MCP server at {} did not answer within {} ms.", host, wait.as_millis();
638 IO, Network, Timeout)),
639 }
640 },
641 }
642 }
643
644 fn messages(&self, r: &HttpMessage) -> Outcome<Vec<Dat>> {
645 let kind = r.header.fields.get_one(&HeaderName::ContentType).map(|v| v.to_string().to_ascii_lowercase())
646 .unwrap_or_default();
647 let body = String::from_utf8_lossy(&r.body);
648 if !kind.contains("text/event-stream") {
649 return match body.trim().is_empty() {
650 true => Ok(Vec::new()),
651 false => Ok(vec![res!(Dat::decode_json_strict(body.trim(), &self.decode))]),
652 };
653 }
654 // Server-sent events: each event's data lines joined, an event ended by a blank line.
655 let mut out = Vec::new();
656 let mut data = String::new();
657 for l in body.lines().chain(std::iter::once("")) {
658 match l.strip_prefix("data:") {
659 Some(d) => { if !data.is_empty() { data.push('\n'); } data.push_str(d.strip_prefix(' ').unwrap_or(d)); },
660 None if l.is_empty() => {
661 if let Ok(m) = Dat::decode_json_strict(data.trim(), &self.decode) {
662 out.push(m);
663 }
664 data.clear();
665 },
666 None => (),
667 }
668 }
669 Ok(out)
670 }
671
672 async fn delete(&self, wait: Duration) {
673 let session = match self.session.lock() {
674 Ok(s) if !s.is_empty() => s.clone(),
675 _ => return,
676 };
677 let _ = self.send(HttpMethod::DELETE, &[("Mcp-Session-Id", &session)], &[], wait).await;
678 }
679}
680
681// ┌───────────────────────────────────────────────────────────────────────────┐
682// │ MESSAGES │
683// └───────────────────────────────────────────────────────────────────────────┘
684
685// An answer's result, or its error in words.
686fn answered(a: Dat, method: &str) -> Outcome<Dat> {
687 if let Some(e) = member(&a, "error") {
688 let code = member(e, "code").and_then(|c| c.get_i64()).unwrap_or(0);
689 return Err(err!("The MCP server refused {} ({}): {}", method, code, text(Some(e), "message"); Invalid, Input));
690 }
691 match member(&a, "result") {
692 Some(r) => Ok(r.clone()),
693 None => Err(err!("The MCP server's answer to {} holds neither a result nor an error.", method; Invalid, Input)),
694 }
695}
696
697fn contents(d: Option<&Dat>) -> Vec<Content> {
698 d.and_then(list).unwrap_or_default().iter().filter_map(|c| match text(Some(c), "type").as_str() {
699 "text" => Some(Content::Text(text(Some(c), "text"))),
700 "image" => Some(match base64::decode(text(Some(c), "data")) {
701 Ok(data) => Content::Image { data, mime: text(Some(c), "mimeType") },
702 Err(_) => Content::Text("[an image whose data is not base64]".to_string()),
703 }),
704 "audio" => Some(match base64::decode(text(Some(c), "data")) {
705 Ok(data) => Content::Audio { data, mime: text(Some(c), "mimeType") },
706 Err(_) => Content::Text("[audio whose data is not base64]".to_string()),
707 }),
708 "resource" => member(c, "resource").map(resource),
709 "resource_link" => Some(Content::Link { uri: text(Some(c), "uri"), name: text(Some(c), "name"),
710 mime: text(Some(c), "mimeType") }),
711 _ => None,
712 }).collect()
713}
714
715fn resource(r: &Dat) -> Content {
716 let (uri, opt) = (text(Some(r), "uri"), |k: &str| member(r, k).and_then(|v| v.get_string()));
717 match opt("blob").map(base64::decode) {
718 Some(Err(_)) => Content::Text(fmt!("[the resource {} whose blob is not base64]", uri)),
719 blob => Content::Resource { uri, mime: text(Some(r), "mimeType"), text: opt("text"), blob: blob.and_then(|b| b.ok()) },
720 }
721}
722
723fn member<'a>(m: &'a Dat, k: &str) -> Option<&'a Dat> {
724 match m.map_get(&dat!(k)) {
725 Ok(Some(Dat::Opt(o))) if o.is_none() => None, // JSON's null
726 Ok(v) => v,
727 Err(_) => None,
728 }
729}
730
731fn text(m: Option<&Dat>, k: &str) -> String {
732 m.and_then(|m| member(m, k)).and_then(|v| v.get_string()).unwrap_or_default()
733}
734
735fn list(d: &Dat) -> Option<Vec<Dat>> {
736 match d {
737 Dat::List(l) => Some(l.clone()),
738 _ => None,
739 }
740}
741
742/// A string as JSON text.
743pub fn quote(s: &str) -> Outcome<String> {
744 Dat::Str(s.to_string()).json_canonical()
745}
746
747fn is_timeout(e: &Error<ErrTag>) -> bool {
748 e.tags().contains(&ErrTag::Timeout)
749}