From dfd51a3cdc073b6dad10e7685cc7101aa9299ccb Mon Sep 17 00:00:00 2001 From: Martin Ball <98639962+benandez@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:19:16 +0100 Subject: [PATCH] #778: land the picture-probe and MCP cutovers (#6955, #6956) on main (#6960) * #778: take craft-libs integration/wordcraft-778 at beeea924 Every craft-libs git dependency (workspace, ui-egui, wordcraft, wordcraft-web, krilla patch) moves from 453b0da782 to beeea92451 (craft-libs main 0649a07aa plus open PRs #2061-#2064). Cargo.lock: only craft-libs sources move, plus windows-sys edge changes inside craft-libs crates; no crates.io versions change. Co-Authored-By: Claude Opus 5.5 * #778: docx stacking-order test follows the shared reader's one-more z craft-libs 5f453efa9 (craft-docx: a relativeHeight of 0 stays the lowest stacking order) reads Float::z as one more than the file's relativeHeight and writes stored orders one less, so a file's 0 is no longer "none". The test expected the old values; relative order and the round trip are unchanged. Co-Authored-By: Claude Opus 5.5 * #778: take craft-libs integration/wordcraft-778 at 24a15211 Co-Authored-By: Claude Opus 5.5 * deps: pin craft-libs to the merged shared cutover prerequisites * #778: pin craft-libs main at 93dac78c (with #2061-#2064) Co-Authored-By: Claude Opus 5.5 * #778: picture probes use craft-image-codecs (DIB wrapping, JPEG budget, PNG/WebP) (#6955) * #778: picture: wrap clipboard DIBs with craft-image-codecs' bmp_probe probe_dib's local dib_to_bmp and dib_layout are replaced by craft_image_codecs::bmp_probe::{dib_to_bmp, dib_layout}. The shared copies are the same code; the only change is that they reserve their output fallibly. A failed reservation in dib_to_bmp (the BMP's bytes can't be allocated) is Refusal::TooLarge with the size the DIB header declares, the refusal a picture too large to hold already gets; dib_layout leaves the DIB unchanged then. The local dib_to_bmp name stays as a thin wrapper returning Result<_, Refusal>. The old code is kept in the tests as an oracle: wrapping and layout are byte-equal on thousands of crafted DIBs (core, info, V4, V5 headers, bit fields, alpha with BI_RGB, every truncation), and probe_dib agrees. Co-Authored-By: Claude Opus 5.5 * #778: picture: budget JPEG coefficients with craft-image-codecs probe's JPEG held-coefficient estimate (jpeg_coefficients, frame_coefficients, worst_coefficients) is replaced by craft_image_codecs::jpeg_worst_case_coefficients, which returns the larger of that same estimate and the shared held_coefficients. So the charge can only grow, never shrink. It grows for: a SOF0/SOF1 8-bit first frame whose first scan has fewer components than the frame (the decoder holds the coefficients until the other scans); and a first-frame SOF2 with sampling factors above 4 (the old rule clamped them to 4). A real baseline JPEG with all components in its first scan is charged nothing, as before. With the 512 MiB budget, a 4:4:4 non-interleaved baseline JPEG is now refused from about 59.6 Mpx instead of 67 Mpx; 4:2:0 and 4:2:2 stay under the RGBA8 conversion and are unchanged. The old code is kept in the tests as an oracle: the new charge is never less (crafted headers, every prefix, random damage), equal where the shared rule adds nothing, and one test pins a case where it grows. Co-Authored-By: Claude Opus 5.5 * #778: picture: read PNG and WebP probes with craft-image-codecs The local png_chunks header read is replaced by craft_image_codecs::png_probe::pixel_model, and the VP8X alpha check in probe by webp_probe::has_alpha (an error reads as no alpha, as non-RIFF input did). PNG: for every valid colour type and bit depth, with and without tRNS and an iCCP chunk, the size, bytes a pixel and alpha are what the old read gave (PixelModel::bytes_per_pixel is channels * 2 for 16 bits, else channels, with a palette as RGB and tRNS adding a channel to grey, RGB and palette). pixel_model is stricter, so these are now refused (probe: Refusal::Broken, dimensions: None) where the old read measured them: an invalid colour type and bit depth pair, a zero or past-i32::MAX side, and more than 65,536 chunks before the image data. None is a valid PNG. WebP: a bare lossless (VP8L) picture whose header sets alpha_is_used now reports alpha; the old rule only knew the VP8X flag. The old PNG read and WebP rule are kept in the tests as oracles. Co-Authored-By: Claude Opus 5.5 * #778: picture tests follow craft-image-codecs' DIB fixes The shared dib_to_bmp no longer adds 12 appended mask bytes to the pixel offset of 52/56-byte BI_BITFIELDS headers, and dib_layout treats the bytes after the header as a mask copy only when the payload is longer than the pixel rows need. The differential test excludes exactly those inputs by named predicate, asserts the new output for them, and stays byte-equal elsewhere. Co-Authored-By: Claude Opus 5.5 * #778: dib_header_dims uses the shared fallible dib_to_bmp Calls the shared probe directly so a failed allocation cannot recurse through the refusal wrapper. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * #778: WordCraft's MCP stdio server runs on craft-mcp-server (#6956) The JSON-RPC framing, bounded line reading, initialize, ping, tools/* and resources/* now come from craft_mcp_server::Server; WordCraft keeps its tools, resources, instructions and backends. The old server.rs stays as a test-only oracle for a differential test. click/key schemas list every argument the app accepts, since the shared check refuses unlisted ones. Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 Co-authored-by: Dylan M. Taylor --- Cargo.lock | 9 + Cargo.toml | 1 + crates/geom/src/picture.rs | 834 +++++++++++++++++++++------ crates/mcp/Cargo.toml | 1 + crates/mcp/src/server.rs | 193 ++----- crates/mcp/src/tests.rs | 10 +- crates/mcp/src/tests/differential.rs | 452 +++++++++++++++ crates/mcp/src/tests/oracle.rs | 174 ++++++ crates/mcp/src/tools.rs | 10 +- docs/mcp.md | 13 +- 10 files changed, 1374 insertions(+), 323 deletions(-) create mode 100644 crates/mcp/src/tests/differential.rs create mode 100644 crates/mcp/src/tests/oracle.rs diff --git a/Cargo.lock b/Cargo.lock index 5b6389efca..a720a0bc46 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1282,6 +1282,14 @@ dependencies = [ "serde", ] +[[package]] +name = "craft-mcp-server" +version = "0.1.0" +source = "git+https://github.com/storytold/craft-libs?rev=93dac78c93a7f1fd66e2022edeb089233b1dc45a#93dac78c93a7f1fd66e2022edeb089233b1dc45a" +dependencies = [ + "serde_json", +] + [[package]] name = "craft-metadata" version = "0.1.0" @@ -7547,6 +7555,7 @@ dependencies = [ name = "wordcraft-mcp" version = "0.18.1" dependencies = [ + "craft-mcp-server", "log", "serde_json", "wordcraft-control-key", diff --git a/Cargo.toml b/Cargo.toml index 45d2ca8a2f..e9a7630354 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -76,6 +76,7 @@ craft-pdf = { git = "https://github.com/storytold/craft-libs", rev = "93dac78c93 craft-update = { git = "https://github.com/storytold/craft-libs", version = "=0.1.0", rev = "93dac78c93a7f1fd66e2022edeb089233b1dc45a", features = ["egui"] } craft-wordmodel = { git = "https://github.com/storytold/craft-libs", rev = "93dac78c93a7f1fd66e2022edeb089233b1dc45a", version = "=0.1.0" } craft-docx = { git = "https://github.com/storytold/craft-libs", rev = "93dac78c93a7f1fd66e2022edeb089233b1dc45a", version = "=0.1.0" } +craft-mcp-server = { git = "https://github.com/storytold/craft-libs", rev = "93dac78c93a7f1fd66e2022edeb089233b1dc45a", version = "=0.1.0" } craft-rtf = { git = "https://github.com/storytold/craft-libs", rev = "93dac78c93a7f1fd66e2022edeb089233b1dc45a", version = "=0.1.0", features = ["doc"] } craft-doc-binary = { git = "https://github.com/storytold/craft-libs", rev = "93dac78c93a7f1fd66e2022edeb089233b1dc45a", version = "=0.1.0" } craft-flow = { git = "https://github.com/storytold/craft-libs", rev = "93dac78c93a7f1fd66e2022edeb089233b1dc45a", version = "=0.1.0" } diff --git a/crates/geom/src/picture.rs b/crates/geom/src/picture.rs index 67de79e076..52a43dddeb 100644 --- a/crates/geom/src/picture.rs +++ b/crates/geom/src/picture.rs @@ -9,7 +9,8 @@ use std::borrow::Cow; use craft_image_codecs::{ ChannelLayout, CodecError, DecodeOptions, EncodeOptions, Format as CodecFormat, Image as CodecImage, Limits as CodecLimits, RasterColorType, - SampleType, decode_as_with, detect, encode as codec_encode, inspect_raster, probe_size, + SampleType, bmp_probe, decode_as_with, detect, encode as codec_encode, inspect_raster, jpeg_worst_case_coefficients, png_probe, probe_size, + webp_probe, }; use image::{DynamicImage, ImageBuffer, ImageFormat}; @@ -147,7 +148,7 @@ pub fn encode_jpeg(rgb: &[u8], width: u32, height: u32, quality: u8) -> Result Option<(u32, u32)> { let format = detect(bytes)?; match format { - CodecFormat::Png => png_chunks(bytes).map(|(w, h, _, _)| (w, h)), + CodecFormat::Png => png_probe::pixel_model(bytes).ok().map(|m| (m.width, m.height)), CodecFormat::Jpeg | CodecFormat::Tiff | CodecFormat::Gif | CodecFormat::Bmp => { inspect_raster(bytes).ok().flatten().map(|i| (i.width, i.height)) } @@ -197,7 +198,7 @@ pub fn probe(bytes: &[u8]) -> Result, Refusal> { let format = from_codec_format(codec_fmt).ok_or(Refusal::NotAPicture)?; let held = match format { ImageFormat::Png | ImageFormat::Gif | ImageFormat::WebP | ImageFormat::Bmp => 0, - ImageFormat::Jpeg => jpeg_coefficients(bytes), + ImageFormat::Jpeg => jpeg_worst_case_coefficients(bytes), ImageFormat::Tiff => { if !tiff_compression(bytes).is_some_and(|c| TIFF_COMPRESSIONS.contains(&c)) { return Err(Refusal::Unsupported("TIFF pictures with JPEG or an unknown compression can't be read")); @@ -207,14 +208,17 @@ pub fn probe(bytes: &[u8]) -> Result, Refusal> { _ => return Err(Refusal::NotAPicture), }; if format == ImageFormat::Png { - let (width, height, native, alpha) = png_chunks(bytes).ok_or_else(|| Refusal::Broken("its PNG header can't be read".into()))?; + // Measured from `IHDR` and the chunk headers: an ICC profile (`iCCP`) isn't inflated, though the + // decoder's own header read inflates one up to its 512 MiB limit. + let m = png_probe::pixel_model(bytes).map_err(|_| Refusal::Broken("its PNG header can't be read".into()))?; + let (width, height, native, alpha) = (m.width, m.height, u64::from(m.bytes_per_pixel()), m.has_alpha()); let (width, height, peak) = sized(width, height, native, 0)?; return Ok(Probe { bytes: Cow::Borrowed(bytes), format, width, height, peak, alpha }); } if format == ImageFormat::WebP { let (width, height) = probe_size(bytes).map_err(broken)?; let (width, height, peak) = sized(width, height, 4, 0)?; - let alpha = bytes.get(12..16) == Some(b"VP8X") && bytes.get(20).is_some_and(|b| b & 0x10 != 0); + let alpha = webp_probe::has_alpha(bytes).unwrap_or(false); return Ok(Probe { bytes: Cow::Borrowed(bytes), format, width, height, peak, alpha }); } let info = inspect_raster(bytes).map_err(broken)?.ok_or_else(|| Refusal::Broken("its header can't be read".into()))?; @@ -225,84 +229,26 @@ pub fn probe(bytes: &[u8]) -> Result, Refusal> { Ok(Probe { bytes: Cow::Borrowed(bytes), format, width, height, peak, alpha }) } -/// A PNG's width, height, the bytes a pixel its decoder gives (samples under 8 bits widened to 8, -/// a palette to RGB, `tRNS` to an alpha channel) and whether it has transparency, from `IHDR` and -/// the chunk headers before the image data. The decoder's own header read inflates an ICC profile -/// (`iCCP`) up to its 512 MiB default limit, for a picture that may only be measured. -fn png_chunks(bytes: &[u8]) -> Option<(u32, u32, u64, bool)> { - let be = |at: usize| bytes.get(at..at.checked_add(4)?).and_then(|b| <[u8; 4]>::try_from(b).ok()).map(u32::from_be_bytes); - // The 8-byte signature, then IHDR: length, type, width, height, bit depth, colour type. - if bytes.get(12..16) != Some(b"IHDR".as_slice()) { - return None; - } - let (width, height) = (be(16)?, be(20)?); - let (depth, color) = (*bytes.get(24)?, *bytes.get(25)?); - let mut trns = false; - let mut at = 8usize; - loop { - let len = usize::try_from(be(at)?).ok()?; - match bytes.get(at.checked_add(4)?..at.checked_add(8)?)? { - b"IDAT" => break, - b"IEND" => return None, - b"tRNS" => trns = true, - _ => {} - } - at = at.checked_add(12)?.checked_add(len)?; - } - let (channels, alpha) = match color { - 0 => (1 + u64::from(trns), trns), - 2 | 3 => (3 + u64::from(trns), trns), - 4 => (2, true), - 6 => (4, true), - _ => return None, - }; - Some((width, height, channels * if depth == 16 { 2 } else { 1 }, alpha)) -} - -/// Prepend a 14-byte `BITMAPFILEHEADER` to a normalized DIB so `craft-image-codecs` can inspect and decode it as BMP. -fn dib_to_bmp(dib: &[u8]) -> Vec { - let u16_at = |at: usize| dib.get(at..at + 2).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes); - let u32_at = |at: usize| dib.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); - let bi_size = u32_at(0).unwrap_or(40); - let offset = if bi_size == 12 { - let bpp = u16_at(10).unwrap_or(24); - let palette = if bpp <= 8 { (1u32 << bpp) * 3 } else { 0 }; - 14 + bi_size + palette - } else { - let bpp = u16_at(14).unwrap_or(24); - let compression = u32_at(16).unwrap_or(0); - let clr_used = u32_at(32).unwrap_or(0); - let palette_entries = if clr_used != 0 { - clr_used - } else if bpp <= 8 { - 1u32 << bpp - } else { - 0 - }; - let masks = if compression == 3 && bi_size >= 40 { 12 } else { 0 }; - 14u32.saturating_add(bi_size).saturating_add(masks).saturating_add(palette_entries.saturating_mul(4)) - }; - let file_size = u32::try_from(14 + dib.len()).unwrap_or(u32::MAX); - let mut bmp = Vec::with_capacity(14 + dib.len()); - bmp.extend_from_slice(b"BM"); - bmp.extend_from_slice(&file_size.to_le_bytes()); - bmp.extend_from_slice(&[0u8; 4]); - bmp.extend_from_slice(&offset.to_le_bytes()); - bmp.extend_from_slice(dib); - bmp +/// [`bmp_probe::dib_to_bmp`], its failure (the BMP's bytes can't be allocated) as the refusal a +/// picture too large to hold gets, with the size its header declares (0 × 0 when it can't be read). +fn dib_to_bmp(dib: &[u8]) -> Result, Refusal> { + bmp_probe::dib_to_bmp(dib).map_err(|_| { + let (width, height) = dib_header_dims(dib).unwrap_or((0, 0)); + Refusal::TooLarge { width, height } + }) } /// Read a DIB's header: a BMP without its 14-byte file header, as the Windows clipboard holds /// one (`CF_DIB`, `CF_DIBV5`). Its layout is first made the one the decoder reads (see -/// [`dib_layout`]). +/// [`bmp_probe::dib_layout`]). /// /// # Errors /// /// Returns `Refusal::Broken` for an invalid DIB header and `Refusal::TooLarge` on size arithmetic /// overflow. pub fn probe_dib(dib: Vec) -> Result, Refusal> { - let dib = dib_layout(dib); - let bmp = dib_to_bmp(&dib); + let dib = bmp_probe::dib_layout(dib); + let bmp = dib_to_bmp(&dib)?; let (width, height, native, alpha) = match inspect_raster(&bmp) { Ok(Some(info)) => { let native = u64::from(info.channels.max(1)) * u64::from(info.bits_per_sample.max(8) / 8); @@ -329,7 +275,7 @@ fn dib_header_dims(dib: &[u8]) -> Option<(u32, u32)> { } // Only the first 12 header bytes are read, so only they are wrapped: this runs for DIBs too // big to decode, which must not be copied whole. - craft_image_codecs::bmp_probe::dimensions(&dib_to_bmp(dib.get(..12).unwrap_or(dib))) + craft_image_codecs::bmp_probe::dimensions(&bmp_probe::dib_to_bmp(dib.get(..12).unwrap_or(dib)).ok()?) } /// A `width` × `height` picture of `native` bytes a pixel, with its peak (see [`peak_bytes`]). @@ -474,64 +420,6 @@ fn peak_bytes(width: u32, height: u32, native: u64, held: u64) -> Option { Some(decoding.max(converting).max(premultiplying)) } -/// Bytes of DCT coefficients a progressive JPEG's decoder keeps for the whole picture while it -/// reads the scans: zune-jpeg holds an `i16` per coefficient of every component, in whole MCUs. -/// 0 for a baseline JPEG, decoded an MCU row at a time. Each frame header before the first scan -/// counts and the largest wins; headers this can't follow are charged as the costliest frame. -fn jpeg_coefficients(bytes: &[u8]) -> u64 { - let mut at = 2; - let mut most = 0u64; - loop { - if bytes.get(at) != Some(&0xFF) { - return worst_coefficients(bytes).max(most); - } - while bytes.get(at) == Some(&0xFF) { - at += 1; - } - let Some(&code) = bytes.get(at) else { return worst_coefficients(bytes).max(most) }; - at += 1; - match code { - // Markers without a length: start of image, TEM, restarts. - 0xD8 | 0x01 | 0xD0..=0xD7 => continue, - // End of image, start of scan: every frame header is behind. - 0xD9 | 0xDA => return most, - _ => {} - } - let len = match (bytes.get(at), bytes.get(at + 1)) { - (Some(&hi), Some(&lo)) => usize::from(u16::from_be_bytes([hi, lo])), - _ => 0, - }; - let Some(segment) = bytes.get(at + 2..at + len).filter(|_| len >= 2) else { return worst_coefficients(bytes).max(most) }; - // SOF2, SOF6, SOF10 and SOF14 are the progressive frames. - if matches!(code, 0xC2 | 0xC6 | 0xCA | 0xCE) { - let Some(held) = frame_coefficients(segment) else { return worst_coefficients(bytes).max(most) }; - most = most.max(held); - } - at += len; - } -} - -/// [`jpeg_coefficients`] of one progressive frame header (after its length): the components' -/// blocks per MCU (horizontal × vertical sampling) times the MCUs that cover the picture. -fn frame_coefficients(sof: &[u8]) -> Option { - let height = u64::from(u16::from_be_bytes([*sof.get(1)?, *sof.get(2)?])); - let width = u64::from(u16::from_be_bytes([*sof.get(3)?, *sof.get(4)?])); - let n = usize::from(*sof.get(5)?); - let sampling: Vec<(u64, u64)> = - sof.get(6..6 + 3 * n)?.as_chunks::<3>().0.iter().map(|&[_, s, _]| (u64::from(s >> 4).clamp(1, 4), u64::from(s & 15).clamp(1, 4))).collect(); - let (h_max, v_max) = sampling.iter().fold((1, 1), |(h, v), &(a, b)| (h.max(a), v.max(b))); - let mcus = width.div_ceil(8 * h_max).checked_mul(height.div_ceil(8 * v_max))?; - sampling.iter().try_fold(0u64, |sum, &(h, v)| sum.checked_add(mcus.checked_mul(2 * 64 * h * v)?)) -} - -/// The coefficients of the costliest progressive frame of the size the image crate reads from -/// `bytes`: four components, each sampled 4 × 4, in MCUs of 32 pixels a side. -fn worst_coefficients(bytes: &[u8]) -> u64 { - let Some((w, h)) = dimensions(bytes) else { return 0 }; - let mcus = u64::from(w).div_ceil(32) * u64::from(h).div_ceil(32); - mcus.saturating_mul(2 * 64 * 16 * 4) -} - /// The compression of a classic TIFF's first image (the one the image crate decodes): 1 when the /// tag is missing. None when the header can't be read, or when the tag appears more than once: /// the decoder keeps the last copy, so a harmless first one must not hide a JPEG one after it. @@ -539,37 +427,6 @@ fn tiff_compression(bytes: &[u8]) -> Option { craft_tiff::probe::first_image_compression(bytes) } -/// A DIB with a V4 or V5 header in the layout the decoder reads. A 32-bit one whose alpha mask -/// is set but whose compression says `BI_RGB` is marked `BI_BITFIELDS` (with the usual colour -/// masks when it gives none), so its alpha is kept as Windows programs mean it; arboard makes the -/// same change. Bit fields then need the colour masks after the header too, where Windows puts a -/// copy and the decoder skips them; a DIB without that copy (arboard writes one) gets it. -fn dib_layout(mut dib: Vec) -> Vec { - let u32_at = |d: &[u8], at: usize| d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); - let Some(size) = u32_at(&dib, 0).filter(|&s| s >= 108).and_then(|s| usize::try_from(s).ok()) else { return dib }; - let put = |d: &mut Vec, at: usize, v: u32| { - if let Some(b) = d.get_mut(at..at + 4) { - b.copy_from_slice(&v.to_le_bytes()); - } - }; - if dib.get(14..16) == Some(&[32, 0]) && u32_at(&dib, 16) == Some(0) && u32_at(&dib, 52) == Some(0xFF00_0000) { - put(&mut dib, 16, 3); - if (40..52).step_by(4).all(|at| u32_at(&dib, at) == Some(0)) { - put(&mut dib, 40, 0x00FF_0000); - put(&mut dib, 44, 0x0000_FF00); - put(&mut dib, 48, 0x0000_00FF); - } - } - if u32_at(&dib, 16) == Some(3) - && size <= dib.len() - && let Some(masks) = dib.get(40..52).map(<[u8]>::to_vec) - && dib.get(size..size + 12) != Some(masks.as_slice()) - { - dib.splice(size..size, masks); - } - dib -} - #[cfg(test)] mod tests { use super::*; @@ -768,33 +625,120 @@ mod tests { assert_eq!(probe(&baseline).unwrap().peak_bytes(), 64 * 64 * 8); } + /// A JPEG's headers up to the first scan: frames `(marker, precision, w, h, components)`, then + /// a scan of `scan` components (none: no scan, the end of the image). + fn jpeg_headers(frames: &[(u8, u8, u16, u16, &[u8])], scan: Option) -> Vec { + let mut b = vec![0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0]; + for &(marker, prec, w, h, comps) in frames { + b.extend_from_slice(&[0xFF, marker]); + #[expect(clippy::cast_possible_truncation, reason = "Fixtures hold at most four components.")] + let (n, len) = ((comps.len() / 3) as u8, (8 + comps.len()) as u16); + b.extend(len.to_be_bytes()); + b.push(prec); + b.extend(h.to_be_bytes()); + b.extend(w.to_be_bytes()); + b.push(n); + b.extend_from_slice(comps); + } + if let Some(n) = scan { + b.extend_from_slice(&[0xFF, 0xDA, 0, 6 + 2 * n, n]); + (1..=n).for_each(|c| b.extend_from_slice(&[c, 0])); + b.extend_from_slice(&[0, 63, 0]); + } + b.extend_from_slice(&[0xFF, 0xD9]); + b + } + + const C444: &[u8] = &[1, 0x11, 0, 2, 0x11, 0, 3, 0x11, 0]; + const C420: &[u8] = &[1, 0x22, 0, 2, 0x11, 0, 3, 0x11, 0]; + const GREY: &[u8] = &[1, 0x11, 0]; + + /// The JPEG budget before the cutover to the shared rule, as the oracle: the shared charge is + /// never less, and is equal wherever it adds nothing. #[test] - fn coefficients_follow_sampling_and_mcu_padding() { - // P, height, width, components (id, sampling, table). - let sof = |w: u16, h: u16, comps: &[u8]| { - let mut s = vec![8]; - s.extend(h.to_be_bytes()); - s.extend(w.to_be_bytes()); - #[expect(clippy::cast_possible_truncation, reason = "These fixtures contain at most four three-byte component records.")] - s.push((comps.len() / 3) as u8); - s.extend(comps); - s - }; - // Four components, no subsampling: 2 bytes a coefficient, 8 a pixel. - assert_eq!(frame_coefficients(&sof(64, 64, &[1, 0x11, 0, 2, 0x11, 0, 3, 0x11, 0, 4, 0x11, 0])), Some(64 * 64 * 8)); - // 4:2:0: MCUs of 16 × 16 holding 4 + 1 + 1 blocks; a 1-pixel-wide picture still takes one. - assert_eq!(frame_coefficients(&sof(1, 16, &[1, 0x22, 0, 2, 0x11, 0, 3, 0x11, 0])), Some(128 * 6)); - let mut short = sof(1, 16, &[1, 0x22, 0, 2, 0x11, 0]); - short[5] = 3; - assert_eq!(frame_coefficients(&short), None, "three components declared, two there"); - // A marker walk over SOI, an APP0 segment, SOF2, then the scan. - let mut jpeg = vec![0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0, 0xFF, 0xC2]; - let f = sof(64, 64, &[1, 0x11, 0]); - #[expect(clippy::cast_possible_truncation, reason = "This fixture's nine-byte frame header and length field fit u16.")] - jpeg.extend(((f.len() + 2) as u16).to_be_bytes()); - jpeg.extend(&f); - jpeg.extend([0xFF, 0xDA]); - assert_eq!(jpeg_coefficients(&jpeg), 64 * 64 * 2); + fn jpeg_charge_is_never_less_than_the_local_one_it_replaced() { + let wide = &[1, 0xFF, 0, 2, 0xFF, 0, 3, 0xFF, 0]; + let cmyk = &[1, 0x11, 0, 2, 0x11, 0, 3, 0x11, 0, 4, 0x11, 0]; + let zero = &[1, 0x00, 0, 2, 0x00, 0, 3, 0x00, 0]; + // (case, whether the shared rule is expected to charge more). + let cases: Vec<(Vec, bool)> = vec![ + (jpeg_headers(&[(0xC0, 8, 640, 480, C420)], Some(3)), false), + (jpeg_headers(&[(0xC0, 8, 640, 480, GREY)], Some(1)), false), + (jpeg_headers(&[(0xC0, 8, 640, 480, C444)], Some(1)), true), + (jpeg_headers(&[(0xC1, 8, 640, 480, C420)], Some(2)), true), + (jpeg_headers(&[(0xC0, 8, 640, 480, C444)], None), false), + (jpeg_headers(&[(0xC2, 8, 640, 480, C420)], Some(1)), false), + (jpeg_headers(&[(0xC2, 8, 640, 480, C444)], Some(3)), false), + (jpeg_headers(&[(0xC2, 12, 640, 480, C444)], Some(1)), false), + (jpeg_headers(&[(0xC2, 8, 640, 480, cmyk)], Some(1)), false), + (jpeg_headers(&[(0xC2, 8, 640, 480, wide)], None), true), + (jpeg_headers(&[(0xC2, 8, 640, 480, zero)], None), false), + (jpeg_headers(&[(0xC6, 8, 640, 480, C444)], None), false), + (jpeg_headers(&[(0xCA, 8, 640, 480, C444)], None), false), + (jpeg_headers(&[(0xCE, 8, 640, 480, C444)], None), false), + (jpeg_headers(&[(0xC0, 8, 64, 64, GREY), (0xC2, 8, 6000, 4000, C444), (0xC2, 8, 100, 100, C444)], Some(1)), false), + (jpeg_headers(&[(0xC2, 8, 65535, 65535, cmyk)], None), false), + (jpeg_headers(&[], None), false), + (vec![0xFF, 0xD8], false), + (vec![], false), + (b"not a jpeg at all".to_vec(), false), + ]; + let mut grew = 0; + for (b, expect_more) in &cases { + let (old, new) = (oracle_jpeg_coefficients(b), jpeg_worst_case_coefficients(b)); + assert!(new >= old, "{b:02x?}: {new} < {old}"); + assert_eq!(new > old, *expect_more, "{b:02x?}: {old} -> {new}"); + grew += usize::from(new > old); + } + assert_eq!(grew, 3); + // Every prefix of a frame with a cut header, and pseudo-random damage: never less. + let full = jpeg_headers(&[(0xC2, 8, 3000, 2000, C420), (0xC0, 8, 100, 100, C444)], Some(1)); + for n in 0..=full.len() { + assert!(jpeg_worst_case_coefficients(&full[..n]) >= oracle_jpeg_coefficients(&full[..n]), "prefix {n}"); + } + let mut seed = 0x9e37_79b9u32; + for _ in 0..3000 { + let mut f = full.clone(); + for _ in 0..3 { + seed = seed.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + let (i, v) = ((seed >> 8) as usize % f.len(), (seed >> 24) as u8); + f[i] = v; + } + assert!(jpeg_worst_case_coefficients(&f) >= oracle_jpeg_coefficients(&f), "{f:02x?}"); + } + } + + #[test] + fn a_baseline_jpeg_with_a_short_first_scan_is_charged_its_coefficients() { + // 3-component 4:4:4 SOF0 of 8000 x 8000 (64 Mpx) whose first scan has one component: the + // decoder holds 2 bytes a coefficient of all three until the other scans, 6 bytes a pixel. + let b = jpeg_headers(&[(0xC0, 8, 8000, 8000, C444)], Some(1)); + let (old, new) = (oracle_jpeg_coefficients(&b), jpeg_worst_case_coefficients(&b)); + assert_eq!((old, new), (0, 8000 * 8000 * 6)); + // 3 + 6 bytes a pixel beside the output passes the 512 MiB budget; it fit as 7 (the RGBA8 conversion). + let (before, after) = (peak_bytes(8000, 8000, 3, old), peak_bytes(8000, 8000, 3, new)); + assert_eq!((before, after), (Some(8000 * 8000 * 8), Some(8000 * 8000 * 9))); + assert!(before.is_some_and(|p| p <= crate::MAX_DECODED_BYTES) && after.is_some_and(|p| p > crate::MAX_DECODED_BYTES)); + // The same through `probe`, on a real JPEG whose headers are made so. + let mut jpeg = encode(image::RgbImage::from_pixel(16, 16, image::Rgb([200, 30, 30])), ImageFormat::Jpeg); + let sof = jpeg.windows(2).position(|m| m == [0xFF, 0xC0]).unwrap(); + jpeg[sof + 5..sof + 7].copy_from_slice(&8000u16.to_be_bytes()); + jpeg[sof + 7..sof + 9].copy_from_slice(&8000u16.to_be_bytes()); + (0..3).for_each(|c| jpeg[sof + 11 + 3 * c] = 0x11); + let sos = jpeg.windows(2).position(|m| m == [0xFF, 0xDA]).unwrap(); + jpeg.splice(sos..sos + 14, [0xFF, 0xDA, 0, 8, 1, 1, 0, 0, 63, 0]); + let p = probe(&jpeg).unwrap(); + assert_eq!((p.width, p.height, p.peak_bytes()), (8000, 8000, 8000 * 8000 * 9)); + assert!(!p.fits(crate::MAX_DECODED_BYTES)); + } + + #[test] + fn jpeg_coefficients_follow_a_marker_walk() { + // SOI, an APP0 segment, SOF2, then the scan. + let jpeg = jpeg_headers(&[(0xC2, 8, 64, 64, GREY)], Some(1)); + assert_eq!(jpeg_worst_case_coefficients(&jpeg), 64 * 64 * 2); + // 4:2:0: MCUs of 16 x 16 holding 4 + 1 + 1 blocks; a 1-pixel-wide picture still takes one. + assert_eq!(jpeg_worst_case_coefficients(&jpeg_headers(&[(0xC2, 8, 1, 16, C420)], None)), 128 * 6); } /// A little-endian TIFF header whose first IFD holds just a compression tag. @@ -898,4 +842,516 @@ mod tests { assert!(probe_dib(d).and_then(|p| p.decode(1 << 20)).is_err()); } } + + // The local JPEG budget before it moved to `craft_image_codecs::jpeg_worst_case_coefficients` (#778), kept as the oracle. + /// Bytes of DCT coefficients a progressive JPEG's decoder keeps for the whole picture while it + /// reads the scans: zune-jpeg holds an `i16` per coefficient of every component, in whole MCUs. + /// 0 for a baseline JPEG, decoded an MCU row at a time. Each frame header before the first scan + /// counts and the largest wins; headers this can't follow are charged as the costliest frame. + fn oracle_jpeg_coefficients(bytes: &[u8]) -> u64 { + let mut at = 2; + let mut most = 0u64; + loop { + if bytes.get(at) != Some(&0xFF) { + return oracle_worst_coefficients(bytes).max(most); + } + while bytes.get(at) == Some(&0xFF) { + at += 1; + } + let Some(&code) = bytes.get(at) else { return oracle_worst_coefficients(bytes).max(most) }; + at += 1; + match code { + // Markers without a length: start of image, TEM, restarts. + 0xD8 | 0x01 | 0xD0..=0xD7 => continue, + // End of image, start of scan: every frame header is behind. + 0xD9 | 0xDA => return most, + _ => {} + } + let len = match (bytes.get(at), bytes.get(at + 1)) { + (Some(&hi), Some(&lo)) => usize::from(u16::from_be_bytes([hi, lo])), + _ => 0, + }; + let Some(segment) = bytes.get(at + 2..at + len).filter(|_| len >= 2) else { return oracle_worst_coefficients(bytes).max(most) }; + // SOF2, SOF6, SOF10 and SOF14 are the progressive frames. + if matches!(code, 0xC2 | 0xC6 | 0xCA | 0xCE) { + let Some(held) = oracle_frame_coefficients(segment) else { return oracle_worst_coefficients(bytes).max(most) }; + most = most.max(held); + } + at += len; + } + } + + /// `oracle_jpeg_coefficients` of one progressive frame header (after its length): the components' + /// blocks per MCU (horizontal × vertical sampling) times the MCUs that cover the picture. + fn oracle_frame_coefficients(sof: &[u8]) -> Option { + let height = u64::from(u16::from_be_bytes([*sof.get(1)?, *sof.get(2)?])); + let width = u64::from(u16::from_be_bytes([*sof.get(3)?, *sof.get(4)?])); + let n = usize::from(*sof.get(5)?); + let sampling: Vec<(u64, u64)> = sof + .get(6..6 + 3 * n)? + .as_chunks::<3>() + .0 + .iter() + .map(|&[_, s, _]| (u64::from(s >> 4).clamp(1, 4), u64::from(s & 15).clamp(1, 4))) + .collect(); + let (h_max, v_max) = sampling.iter().fold((1, 1), |(h, v), &(a, b)| (h.max(a), v.max(b))); + let mcus = width.div_ceil(8 * h_max).checked_mul(height.div_ceil(8 * v_max))?; + sampling.iter().try_fold(0u64, |sum, &(h, v)| sum.checked_add(mcus.checked_mul(2 * 64 * h * v)?)) + } + + /// The coefficients of the costliest progressive frame of the size the image crate reads from + /// `bytes`: four components, each sampled 4 × 4, in MCUs of 32 pixels a side. + fn oracle_worst_coefficients(bytes: &[u8]) -> u64 { + let Some((w, h)) = dimensions(bytes) else { return 0 }; + let mcus = u64::from(w).div_ceil(32) * u64::from(h).div_ceil(32); + mcus.saturating_mul(2 * 64 * 16 * 4) + } + + // The local DIB wrapping before it moved to `craft_image_codecs::bmp_probe` (#778), kept as the oracle. + /// Prepend a 14-byte `BITMAPFILEHEADER` to a normalized DIB so `craft-image-codecs` can inspect and decode it as BMP. + fn oracle_dib_to_bmp(dib: &[u8]) -> Vec { + let u16_at = |at: usize| dib.get(at..at + 2).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes); + let u32_at = |at: usize| dib.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let bi_size = u32_at(0).unwrap_or(40); + let offset = if bi_size == 12 { + let bpp = u16_at(10).unwrap_or(24); + let palette = if bpp <= 8 { (1u32 << bpp) * 3 } else { 0 }; + 14 + bi_size + palette + } else { + let bpp = u16_at(14).unwrap_or(24); + let compression = u32_at(16).unwrap_or(0); + let clr_used = u32_at(32).unwrap_or(0); + let palette_entries = if clr_used != 0 { + clr_used + } else if bpp <= 8 { + 1u32 << bpp + } else { + 0 + }; + let masks = if compression == 3 && bi_size >= 40 { 12 } else { 0 }; + 14u32.saturating_add(bi_size).saturating_add(masks).saturating_add(palette_entries.saturating_mul(4)) + }; + let file_size = u32::try_from(14 + dib.len()).unwrap_or(u32::MAX); + let mut bmp = Vec::with_capacity(14 + dib.len()); + bmp.extend_from_slice(b"BM"); + bmp.extend_from_slice(&file_size.to_le_bytes()); + bmp.extend_from_slice(&[0u8; 4]); + bmp.extend_from_slice(&offset.to_le_bytes()); + bmp.extend_from_slice(dib); + bmp + } + + /// A DIB with a V4 or V5 header in the layout the decoder reads. A 32-bit one whose alpha mask + /// is set but whose compression says `BI_RGB` is marked `BI_BITFIELDS` (with the usual colour + /// masks when it gives none), so its alpha is kept as Windows programs mean it; arboard makes the + /// same change. Bit fields then need the colour masks after the header too, where Windows puts a + /// copy and the decoder skips them; a DIB without that copy (arboard writes one) gets it. + fn oracle_dib_layout(mut dib: Vec) -> Vec { + let u32_at = |d: &[u8], at: usize| d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let Some(size) = u32_at(&dib, 0).filter(|&s| s >= 108).and_then(|s| usize::try_from(s).ok()) else { return dib }; + let put = |d: &mut Vec, at: usize, v: u32| { + if let Some(b) = d.get_mut(at..at + 4) { + b.copy_from_slice(&v.to_le_bytes()); + } + }; + if dib.get(14..16) == Some(&[32, 0]) && u32_at(&dib, 16) == Some(0) && u32_at(&dib, 52) == Some(0xFF00_0000) { + put(&mut dib, 16, 3); + if (40..52).step_by(4).all(|at| u32_at(&dib, at) == Some(0)) { + put(&mut dib, 40, 0x00FF_0000); + put(&mut dib, 44, 0x0000_FF00); + put(&mut dib, 48, 0x0000_00FF); + } + } + if u32_at(&dib, 16) == Some(3) + && size <= dib.len() + && let Some(masks) = dib.get(40..52).map(<[u8]>::to_vec) + && dib.get(size..size + 12) != Some(masks.as_slice()) + { + dib.splice(size..size, masks); + } + dib + } + + /// The size and peak `probe_dib` reported before the cutover, as `(width, height, peak, alpha, bytes)`. + fn oracle_probe_dib(dib: Vec) -> Result<(u32, u32, u64, bool, Vec), Refusal> { + let dib = oracle_dib_layout(dib); + let bmp = oracle_dib_to_bmp(&dib); + let (width, height, native, alpha) = match inspect_raster(&bmp) { + Ok(Some(info)) => { + let native = u64::from(info.channels.max(1)) * u64::from(info.bits_per_sample.max(8) / 8); + (info.width, info.height, native, matches!(info.color_type, RasterColorType::GrayAlpha | RasterColorType::Rgba)) + } + Ok(None) => return Err(Refusal::Broken("its DIB header can't be read".into())), + Err(CodecError::LimitExceeded(_)) => { + let (w, h) = dib_header_dims(&dib).ok_or_else(|| Refusal::Broken("its DIB header can't be read".into()))?; + (w, h, 4, false) + } + Err(e) => return Err(broken(e)), + }; + let (width, height, peak) = sized(width, height, native, 0)?; + Ok((width, height, peak, alpha, bmp)) + } + + /// A DIB with a header of `size` bytes (12, 40, 52, 56, 64, 108 or 124), `bpp`, `compression` + /// and `clr_used`, followed by `tail` bytes. + fn dib_with(size: u32, bpp: u16, compression: u32, clr_used: u32, alpha_mask: u32, tail: &[u8]) -> Vec { + let mut d = vec![0u8; usize::try_from(size).unwrap()]; + d[0..4].copy_from_slice(&size.to_le_bytes()); + if size == 12 { + d[4..6].copy_from_slice(&3u16.to_le_bytes()); + d[6..8].copy_from_slice(&2u16.to_le_bytes()); + d[8..10].copy_from_slice(&1u16.to_le_bytes()); + d[10..12].copy_from_slice(&bpp.to_le_bytes()); + } else { + d[4..8].copy_from_slice(&3i32.to_le_bytes()); + d[8..12].copy_from_slice(&2i32.to_le_bytes()); + d[12..14].copy_from_slice(&1u16.to_le_bytes()); + d[14..16].copy_from_slice(&bpp.to_le_bytes()); + d[16..20].copy_from_slice(&compression.to_le_bytes()); + d[32..36].copy_from_slice(&clr_used.to_le_bytes()); + if size >= 56 { + d[52..56].copy_from_slice(&alpha_mask.to_le_bytes()); + } + if size >= 52 { + for (at, m) in [(40, 0x00FF_0000u32), (44, 0x0000_FF00), (48, 0x0000_00FF)] { + d[at..at + 4].copy_from_slice(&m.to_le_bytes()); + } + } + } + d.extend_from_slice(tail); + d + } + + fn crafted_dibs() -> Vec> { + let px = [[0u8, 0, 255, 128]; 6].concat(); + let masks = [0x00u8, 0, 0xFF, 0, 0, 0xFF, 0, 0, 0xFF, 0, 0, 0]; + let mut v = Vec::new(); + for size in [12u32, 40, 52, 56, 64, 108, 124] { + for bpp in [1u16, 4, 8, 16, 24, 32] { + for compression in [0u32, 1, 2, 3, 6] { + for clr_used in [0u32, 2, 300, u32::MAX] { + for alpha_mask in [0u32, 0xFF00_0000] { + for tail in [&[][..], &px[..], &masks[..], &[&masks[..], &px[..]].concat()[..]] { + v.push(dib_with(size, bpp, compression, clr_used, alpha_mask, tail)); + } + } + } + } + } + } + // Clipboard layouts: the V5 helper's three, and a lying header size. + let q = [[0, 0, 255, 128], [255, 0, 0, 255]]; + for (bitfields, copy) in [(false, false), (true, false), (true, true)] { + v.push(dib(2, 1, 0xFF00_0000, bitfields, copy, &q)); + v.push(dib(2, 1, 0, bitfields, copy, &q)); + } + v.push(dib(60_000, 60_000, 0xFF00_0000, false, false, &[])); + let mut lying = dib(2, 1, 0xFF00_0000, true, false, &q); + lying[0..4].copy_from_slice(&u32::MAX.to_le_bytes()); + v.push(lying); + v + } + + // craft-image-codecs fixed two DIB behaviours after the cutover (craft-libs #2062); the oracle + // keeps the old ones, so these predicates name the inputs where the two must differ. + + fn le32(d: &[u8], at: usize) -> Option { + d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes) + } + + /// A 52- or 56-byte `BI_BITFIELDS` header: its masks are inside the header, so the pixel offset + /// no longer counts 12 appended mask bytes. Returns the new, independently computed offset. + fn v2v3_bitfields_offset(d: &[u8]) -> Option { + let size = le32(d, 0).unwrap_or(40); + if !matches!(size, 52 | 56) || le32(d, 16).unwrap_or(0) != 3 { + return None; + } + let bpp = d.get(14..16).and_then(|b| b.try_into().ok()).map_or(24, u16::from_le_bytes); + let clr_used = le32(d, 32).unwrap_or(0); + let entries = if clr_used != 0 { + clr_used + } else if bpp <= 8 { + 1u32 << bpp + } else { + 0 + }; + Some(14u32.saturating_add(size).saturating_add(entries.saturating_mul(4))) + } + + /// A V4/V5 bit-fields DIB whose 12 bytes after the header equal the masks but whose payload is + /// no longer than the pixel rows need: those bytes are pixels, not a copy, so a copy is inserted. + /// Returns the masks the shared code inserts at `size`. + fn exact_payload_equal_to_masks(d: &[u8]) -> Option<(usize, [u8; 12])> { + let size = usize::try_from(le32(d, 0).filter(|&s| s >= 108)?).ok()?; + if size > d.len() { + return None; + } + let promote = d.get(14..16) == Some(&[32, 0][..]) && le32(d, 16) == Some(0) && le32(d, 52) == Some(0xFF00_0000); + let mut masks: [u8; 12] = d.get(40..52)?.try_into().ok()?; + if promote && masks == [0; 12] { + masks = [0x00, 0x00, 0xFF, 0x00, 0x00, 0xFF, 0x00, 0x00, 0xFF, 0x00, 0x00, 0x00]; + } + if !(promote || le32(d, 16) == Some(3)) || d.get(size..size + 12) != Some(masks.as_slice()) { + return None; + } + let w = u64::try_from(i32::from_le_bytes(d.get(4..8)?.try_into().ok()?)).ok()?; + let h = u64::from(i32::from_le_bytes(d.get(8..12)?.try_into().ok()?).unsigned_abs()); + let bpp = u64::from(u16::from_le_bytes(d.get(14..16)?.try_into().ok()?)); + let need = usize::try_from(w.checked_mul(bpp)?.div_ceil(32).checked_mul(4)?.checked_mul(h)?).ok()?; + (d.len() - size <= need).then_some((size, masks)) + } + + #[test] + fn dib_wrapping_is_byte_equal_to_the_local_one_it_replaced() { + let (mut n, mut v2v3, mut exact) = (0, 0, 0); + for d in crafted_dibs() { + // Every truncation point of the header region, then the whole. + let cuts = (0..=d.len().min(140)).chain([d.len()]); + for cut in cuts { + let d = &d[..cut]; + n += 1; + let (new, old) = (dib_to_bmp(d).unwrap(), oracle_dib_to_bmp(d)); + if let Some(offset) = v2v3_bitfields_offset(d) { + // New behaviour: only the offset differs, and it no longer counts the 12 mask bytes. + v2v3 += 1; + let mut expected = old; + expected[10..14].copy_from_slice(&offset.to_le_bytes()); + assert_eq!(new, expected, "wrap, 52/56-byte bit fields, cut {cut}"); + } else { + assert_eq!(new, old, "wrap, cut {cut}"); + } + let (new, old) = (bmp_probe::dib_layout(d.to_vec()), oracle_dib_layout(d.to_vec())); + if let Some((size, masks)) = exact_payload_equal_to_masks(d) { + // New behaviour: the bytes after the header are pixels, so a mask copy is inserted. + exact += 1; + let mut expected = old; + expected.splice(size..size, masks); + assert_eq!(new, expected, "layout, exact payload equal to the masks, cut {cut}"); + } else { + assert_eq!(new, old, "layout, cut {cut}"); + } + } + } + assert!(n > 100_000, "{n}"); + // The exclusions are small and present: a predicate that matched nothing would hide a regression. + eprintln!("DIB corpus: {n} cases, {v2v3} excluded as 52/56-byte bit fields, {exact} as exact payload equal to the masks"); + assert!(v2v3 > 0 && exact > 0 && v2v3 + exact < n / 10, "{v2v3} {exact}"); + } + + #[test] + fn probe_dib_is_unchanged_by_the_shared_wrapping() { + for d in crafted_dibs() { + for cut in [0, 4, 11, 12, 14, 40, 52, 100, 124, 130, d.len()] { + let d = d[..cut.min(d.len())].to_vec(); + // The two DIB fixes change the bytes handed to the decoder; the wrapping test above pins + // them, so skip those inputs here. + if v2v3_bitfields_offset(&d).is_some() || exact_payload_equal_to_masks(&d).is_some() { + continue; + } + let new = probe_dib(d.clone()); + match (new, oracle_probe_dib(d.clone())) { + (Ok(p), Ok((w, h, peak, alpha, bmp))) => { + assert_eq!((p.width, p.height, p.peak, p.alpha), (w, h, peak, alpha), "{d:02x?}"); + assert_eq!(&*p.bytes, bmp.as_slice()); + } + (Err(a), Err(b)) => assert_eq!(a, b, "{d:02x?}"), + (a, b) => panic!("{d:02x?}: {:?} vs {:?}", a.map(|p| p.width), b.map(|o| o.0)), + } + } + } + } + + // The local PNG header read before it moved to `craft_image_codecs::png_probe` (#778), kept as the oracle. + /// A PNG's width, height, the bytes a pixel its decoder gives (samples under 8 bits widened to 8, + /// a palette to RGB, `tRNS` to an alpha channel) and whether it has transparency, from `IHDR` and + /// the chunk headers before the image data. The decoder's own header read inflates an ICC profile + /// (`iCCP`) up to its 512 MiB default limit, for a picture that may only be measured. + fn oracle_png_chunks(bytes: &[u8]) -> Option<(u32, u32, u64, bool)> { + let be = |at: usize| bytes.get(at..at.checked_add(4)?).and_then(|b| <[u8; 4]>::try_from(b).ok()).map(u32::from_be_bytes); + // The 8-byte signature, then IHDR: length, type, width, height, bit depth, colour type. + if bytes.get(12..16) != Some(b"IHDR".as_slice()) { + return None; + } + let (width, height) = (be(16)?, be(20)?); + let (depth, color) = (*bytes.get(24)?, *bytes.get(25)?); + let mut trns = false; + let mut at = 8usize; + loop { + let len = usize::try_from(be(at)?).ok()?; + match bytes.get(at.checked_add(4)?..at.checked_add(8)?)? { + b"IDAT" => break, + b"IEND" => return None, + b"tRNS" => trns = true, + _ => {} + } + at = at.checked_add(12)?.checked_add(len)?; + } + let (channels, alpha) = match color { + 0 => (1 + u64::from(trns), trns), + 2 | 3 => (3 + u64::from(trns), trns), + 4 => (2, true), + 6 => (4, true), + _ => return None, + }; + Some((width, height, channels * if depth == 16 { 2 } else { 1 }, alpha)) + } + + /// WordCraft's WebP alpha rule before the cutover: the `VP8X` flag, nothing else. + fn oracle_webp_alpha(bytes: &[u8]) -> bool { + bytes.get(12..16) == Some(b"VP8X") && bytes.get(20).is_some_and(|b| b & 0x10 != 0) + } + + fn new_png(b: &[u8]) -> Option<(u32, u32, u64, bool)> { + png_probe::pixel_model(b).ok().map(|m| (m.width, m.height, u64::from(m.bytes_per_pixel()), m.has_alpha())) + } + + /// A PNG with the given IHDR fields and chunks before a (junk) `IDAT`. + fn png_with(width: u32, height: u32, depth: u8, color: u8, before_idat: &[(&[u8; 4], Vec)]) -> Vec { + let chunk = |out: &mut Vec, kind: &[u8; 4], data: &[u8]| { + out.extend((data.len() as u32).to_be_bytes()); + out.extend_from_slice(kind); + out.extend_from_slice(data); + out.extend_from_slice(&[0; 4]); + }; + let mut b = b"\x89PNG\r\n\x1a\n".to_vec(); + let mut ihdr = [width.to_be_bytes(), height.to_be_bytes()].concat(); + ihdr.extend_from_slice(&[depth, color, 0, 0, 0]); + chunk(&mut b, b"IHDR", &ihdr); + for (k, d) in before_idat { + chunk(&mut b, k, d); + } + chunk(&mut b, b"IDAT", &[1, 2, 3]); + chunk(&mut b, b"IEND", &[]); + b + } + + #[test] + fn png_pixel_model_matches_the_local_header_read_for_every_valid_header() { + let valid: [(u8, &[u8]); 5] = [(0, &[1, 2, 4, 8, 16]), (2, &[8, 16]), (3, &[1, 2, 4, 8]), (4, &[8, 16]), (6, &[8, 16])]; + let mut n = 0; + for (color, depths) in valid { + for &depth in depths { + for (trns, icc) in [(false, false), (true, false), (true, true), (false, true)] { + let mut extra: Vec<(&[u8; 4], Vec)> = vec![]; + if icc { + extra.push((b"iCCP", vec![0xAB; 300])); + } + if trns { + extra.push((b"tRNS", vec![0, 0])); + } + let b = png_with(5, 7, depth, color, &extra); + assert!(new_png(&b).is_some(), "colour {color} depth {depth}"); + assert_eq!(new_png(&b), oracle_png_chunks(&b), "colour {color} depth {depth} trns {trns}"); + // And `probe` reports what the old read gave it: the size and the peak. + let (w, h, native, alpha) = oracle_png_chunks(&b).unwrap(); + let p = probe(&b).unwrap(); + assert_eq!((p.width, p.height, p.has_alpha(), Some(p.peak_bytes())), (w, h, alpha, peak_bytes(w, h, native, 0))); + assert_eq!(dimensions(&b), Some((5, 7))); + n += 1; + } + } + } + assert_eq!(n, 4 * 15); + // Real encoder output, every layout the image types give. + for img in [ + DynamicImage::ImageLuma8(image::GrayImage::new(3, 2)), + DynamicImage::ImageLumaA8(image::GrayAlphaImage::new(3, 2)), + DynamicImage::ImageRgb8(image::RgbImage::new(3, 2)), + DynamicImage::ImageRgba8(image::RgbaImage::new(3, 2)), + DynamicImage::ImageRgb16(image::ImageBuffer::new(3, 2)), + DynamicImage::ImageRgba16(image::ImageBuffer::new(3, 2)), + ] { + let b = encode(img, ImageFormat::Png); + assert_eq!(new_png(&b), oracle_png_chunks(&b)); + } + } + + /// What the old read accepted and `pixel_model` refuses is a header the decoder can't use + /// either; `probe` then says the PNG header can't be read (`Broken`) and `dimensions` is None. + #[test] + fn png_pixel_model_is_stricter_only_on_headers_that_are_not_valid_pngs() { + let ok = png_with(5, 7, 8, 2, &[]); + let mut cases: Vec<(&str, Vec)> = vec![ + ("depth 3 for RGB", png_with(5, 7, 3, 2, &[])), + ("depth 16 for palette", png_with(5, 7, 16, 3, &[])), + ("depth 4 for RGBA", png_with(5, 7, 4, 6, &[])), + ("zero width", png_with(0, 7, 8, 2, &[])), + ("zero height", png_with(5, 0, 8, 2, &[])), + ("width past i32::MAX", png_with(1 << 31, 1, 8, 2, &[])), + ("height past i32::MAX", png_with(1, u32::MAX, 8, 2, &[])), + ]; + let many: Vec<(&[u8; 4], Vec)> = (0..70_000).map(|_| (b"tEXt", Vec::new())).collect(); + cases.push(("70,000 chunks before the image data", png_with(5, 7, 8, 2, &many))); + for (what, b) in &cases { + assert!(oracle_png_chunks(b).is_some(), "{what}: the old read accepted it"); + assert_eq!(new_png(b), None, "{what}"); + assert_eq!(dimensions(b), None, "{what}"); + assert!(matches!(probe(b), Err(Refusal::Broken(_))), "{what}"); + assert!(!header_has_alpha(b), "{what}"); + } + // Everything else the old read refused (no IHDR, unknown colour, a wrong IHDR length that + // throws its chunk walk off, no image data) is still refused. + let mut short_ihdr = ok.clone(); + short_ihdr[8..12].copy_from_slice(&12u32.to_be_bytes()); + for b in [png_with(5, 7, 8, 5, &[]), b"\x89PNG\r\n\x1a\n".to_vec(), ok[..33].to_vec(), short_ihdr] { + assert_eq!(new_png(&b), None); + assert_eq!(oracle_png_chunks(&b), None); + } + // Truncations and damage: where the new read answers, it answers as the old one did. + let full = png_with(5, 7, 8, 6, &[(b"tRNS", vec![0]), (b"gAMA", vec![0; 4])]); + for n in 0..=full.len() { + if new_png(&full[..n]).is_some() { + assert_eq!(new_png(&full[..n]), oracle_png_chunks(&full[..n]), "prefix {n}"); + } + } + let mut seed = 0x9e37_79b9u32; + for _ in 0..3000 { + let mut f = full.clone(); + for _ in 0..3 { + seed = seed.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + let (i, v) = ((seed >> 8) as usize % f.len(), (seed >> 24) as u8); + f[i] = v; + } + if new_png(&f).is_some() { + assert_eq!(new_png(&f), oracle_png_chunks(&f), "{f:02x?}"); + } + } + } + + /// A RIFF WebP with one chunk. + fn riff_webp(kind: &[u8; 4], payload: &[u8]) -> Vec { + let mut b = b"RIFF".to_vec(); + b.extend((4 + 8 + payload.len() as u32).to_le_bytes()); + b.extend_from_slice(b"WEBP"); + b.extend_from_slice(kind); + b.extend((payload.len() as u32).to_le_bytes()); + b.extend_from_slice(payload); + b + } + + #[test] + fn webp_alpha_follows_vp8x_and_now_vp8l() { + // VP8X: the flag, as before. + for flags in [0u8, 0x10, 0x20, 0x30] { + let mut payload = vec![flags, 0, 0, 0]; + payload.extend_from_slice(&[0, 0, 0, 0, 0, 0]); // 1 x 1 canvas + let b = riff_webp(b"VP8X", &payload); + assert_eq!(webp_probe::has_alpha(&b).unwrap(), oracle_webp_alpha(&b), "flags {flags:#x}"); + assert_eq!(oracle_webp_alpha(&b), flags & 0x10 != 0); + } + // A bare lossless picture (VP8L) says so in its header: 1 x 1, `alpha_is_used` (bit 28). + let with = riff_webp(b"VP8L", &[0x2f, 0, 0, 0, 0x10, 0, 0, 0]); + let without = riff_webp(b"VP8L", &[0x2f, 0, 0, 0, 0x00, 0, 0, 0]); + assert!(!oracle_webp_alpha(&with), "the old rule never saw it"); + assert!(webp_probe::has_alpha(&with).unwrap()); + assert!(!webp_probe::has_alpha(&without).unwrap()); + // A real encoder's lossless RGBA WebP. + let enc = encode(image::RgbaImage::from_pixel(4, 4, image::Rgba([9, 8, 7, 100])), ImageFormat::WebP); + assert_eq!(probe(&enc).unwrap().has_alpha(), webp_probe::has_alpha(&enc).unwrap()); + // Lossy VP8 never has alpha; and input that isn't a RIFF WebP reads as none, as before. + assert!(!webp_probe::has_alpha(&riff_webp(b"VP8 ", &[0; 10])).unwrap()); + for junk in [&b"not a webp at all"[..], b"", b"RIFF", b"RIFF\0\0\0\0WEBPVP8L"] { + assert!(!webp_probe::has_alpha(junk).unwrap_or(false)); + } + } } diff --git a/crates/mcp/Cargo.toml b/crates/mcp/Cargo.toml index a767a20221..b3d3a39c8d 100644 --- a/crates/mcp/Cargo.toml +++ b/crates/mcp/Cargo.toml @@ -13,5 +13,6 @@ wordcraft-doc = { workspace = true } wordcraft-engine = { workspace = true } wordcraft-render = { workspace = true } wordcraft-control-key = { workspace = true } +craft-mcp-server = { workspace = true } serde_json = { workspace = true } log = { workspace = true } diff --git a/crates/mcp/src/server.rs b/crates/mcp/src/server.rs index bd9616222d..204aa2800f 100644 --- a/crates/mcp/src/server.rs +++ b/crates/mcp/src/server.rs @@ -1,22 +1,16 @@ -//! JSON-RPC 2.0 framing and the MCP lifecycle / tools / resources methods. +//! WordCraft's MCP server: the shared `craft_mcp_server` core (JSON-RPC framing, the lifecycle, +//! `tools/*` and `resources/*`) around WordCraft's own tools, resources and instructions. use std::io::{BufRead, Read, Write}; +use craft_mcp_server::{Contents, Info, Options, Tools}; use serde_json::{Value, json}; use crate::backend::Backend; use crate::tools::{call_tool, tool_definitions}; /// The MCP revision we implement. -pub const PROTOCOL_VERSION: &str = "2025-06-18"; -const SUPPORTED_VERSIONS: &[&str] = &[PROTOCOL_VERSION, "2025-03-26", "2024-11-05"]; - -const PARSE_ERROR: i64 = -32700; -const INVALID_REQUEST: i64 = -32600; -const METHOD_NOT_FOUND: i64 = -32601; -const INVALID_PARAMS: i64 = -32602; -const INTERNAL_ERROR: i64 = -32603; -const RESOURCE_NOT_FOUND: i64 = -32002; +pub use craft_mcp_server::PROTOCOL_VERSION; const INSTRUCTIONS: &str = "WordCraft is a word processor (a Microsoft Word clone). Every action is a command: find ids and \ parameters with list_commands and run them with execute (or several with batch). Positions are \ @@ -74,149 +68,90 @@ pub(crate) fn read_bounded_line(reader: &mut impl BufRead, max: usize) -> std::i String::from_utf8(buf).map(BoundedLine::Line).map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e)) } +/// WordCraft's tools, resources and instructions over one backend, for the shared server. +struct WordcraftTools { + backend: Box, +} + +impl Tools for WordcraftTools { + fn instructions(&self) -> String { + format!( + "{INSTRUCTIONS} Backend: {}. Community: https://discord.gg/artcraft · https://getartcraft.com/apps/wordcraft · https://github.com/storytold/wordcraft", + self.backend.describe() + ) + } + + fn list(&mut self) -> Vec { + match tool_definitions() { + Value::Array(tools) => tools, + _ => Vec::new(), + } + } + + fn call(&mut self, name: &str, args: &Value) -> Value { + call_tool(self.backend.as_mut(), name, args).to_value() + } + + fn resources(&self) -> Vec { + vec![ + json!({"uri": DOC_URI, "name": "document", "title": "Active document", "description": "Blocks, text, formatting, sections, parts and selection of the document (document.inspect)", "mimeType": "application/json"}), + json!({"uri": COMMANDS_URI, "name": "commands", "title": "Commands", "description": "Every command: id, label, ribbon location, shortcut, params, enabled (engine.commands)", "mimeType": "application/json"}), + ] + } + + fn read_resource(&mut self, uri: &str) -> Option> { + let method = match uri { + DOC_URI => "document.inspect", + COMMANDS_URI => "engine.commands", + _ => return None, + }; + Some( + self.backend + .call(method, json!({})) + .map(|v| Contents::Text { mime_type: "application/json".into(), text: serde_json::to_string_pretty(&v).unwrap_or_default() }), + ) + } +} + /// An MCP server bound to one backend. pub struct Server { - backend: Box, - initialized: bool, -} - -fn response(id: Value, result: Value) -> Value { - json!({"jsonrpc": "2.0", "id": id, "result": result}) -} - -fn error(id: Value, code: i64, message: impl Into) -> Value { - json!({"jsonrpc": "2.0", "id": id, "error": {"code": code, "message": message.into()}}) + inner: craft_mcp_server::Server, } impl Server { pub fn new(backend: Box) -> Self { - Self { backend, initialized: false } + let info = Info { name: "wordcraft", title: "WordCraft", version: env!("CARGO_PKG_VERSION"), max_line: MAX_REQUEST_LINE }; + let options = Options { + website_url: Some("https://getartcraft.com/apps/wordcraft".into()), + // Clients read every tool failure from the result, as before the shared core. + tool_errors_as_results: true, + strict_request_ids: true, + }; + Self { inner: craft_mcp_server::Server::new(info, WordcraftTools { backend }).with_options(options) } } pub fn backend(&mut self) -> &mut dyn Backend { - self.backend.as_mut() + self.inner.tools().backend.as_mut() } /// Whether the client has sent `notifications/initialized`. pub fn is_initialized(&self) -> bool { - self.initialized + self.inner.is_initialized() } /// Serve newline-delimited JSON-RPC until `input` closes. Logs go to stderr only (stdout is /// the protocol stream). - pub fn serve(&mut self, mut input: impl BufRead, mut output: impl Write) -> std::io::Result<()> { - loop { - let reply = match read_bounded_line(&mut input, MAX_REQUEST_LINE) { - Ok(BoundedLine::Eof) => break, - Ok(BoundedLine::Line(line)) => self.handle_line(&line), - Ok(BoundedLine::TooLong) => Some(error(Value::Null, INVALID_REQUEST, "request line too long").to_string()), - Err(e) if e.kind() == std::io::ErrorKind::InvalidData => { - Some(error(Value::Null, PARSE_ERROR, "request line is not UTF-8").to_string()) - } - Err(e) => return Err(e), - }; - if let Some(reply) = reply { - output.write_all(reply.as_bytes())?; - output.write_all(b"\n")?; - output.flush()?; - } - } - Ok(()) + pub fn serve(&mut self, input: impl BufRead, output: impl Write) -> std::io::Result<()> { + self.inner.serve(input, output) } /// Handle one line; returns the reply line (None for notifications and blank lines). pub fn handle_line(&mut self, line: &str) -> Option { - let line = line.trim(); - if line.is_empty() { - return None; - } - let reply = match serde_json::from_str::(line) { - Ok(Value::Array(batch)) => { - // Batches were removed in 2025-06-18; still answer older clients sensibly. - if batch.is_empty() { - Some(error(Value::Null, INVALID_REQUEST, "empty batch")) - } else { - let replies: Vec = batch.into_iter().filter_map(|m| self.handle(m)).collect(); - (!replies.is_empty()).then_some(Value::Array(replies)) - } - } - Ok(msg) => self.handle(msg), - Err(e) => Some(error(Value::Null, PARSE_ERROR, format!("parse error: {e}"))), - }; - reply.map(|r| r.to_string()) + self.inner.handle_line(line) } /// Handle one JSON-RPC message; `None` for notifications and responses. pub fn handle(&mut self, msg: Value) -> Option { - let Value::Object(o) = &msg else { return Some(error(Value::Null, INVALID_REQUEST, "message must be an object")) }; - let id = o.get("id").cloned(); - let Some(method) = o.get("method").and_then(Value::as_str) else { - // A response to a server→client request (we send none): ignore. Anything else is invalid. - if o.contains_key("result") || o.contains_key("error") { - return None; - } - return Some(error(id.unwrap_or(Value::Null), INVALID_REQUEST, "missing `method`")); - }; - let params = o.get("params").cloned().unwrap_or(Value::Null); - let Some(id) = id else { - self.notification(method); - return None; - }; - if !(id.is_string() || id.is_number()) { - return Some(error(Value::Null, INVALID_REQUEST, "`id` must be a string or number")); - } - Some(match self.request(method, ¶ms) { - Ok(r) => response(id, r), - Err((code, m)) => error(id, code, m), - }) - } - - fn notification(&mut self, method: &str) { - match method { - "notifications/initialized" => self.initialized = true, - "notifications/cancelled" | "notifications/progress" | "notifications/roots/list_changed" => {} - other => log::debug!("ignoring notification {other}"), - } - } - - fn request(&mut self, method: &str, params: &Value) -> Result { - match method { - "initialize" => { - let asked = params.get("protocolVersion").and_then(Value::as_str).unwrap_or(PROTOCOL_VERSION); - let version = if SUPPORTED_VERSIONS.contains(&asked) { asked } else { PROTOCOL_VERSION }; - Ok(json!({ - "protocolVersion": version, - "capabilities": {"tools": {}, "resources": {}}, - "serverInfo": {"name": "wordcraft", "title": "WordCraft", "version": env!("CARGO_PKG_VERSION"), "websiteUrl": "https://getartcraft.com/apps/wordcraft"}, - "instructions": format!( - "{INSTRUCTIONS} Backend: {}. Community: https://discord.gg/artcraft · https://getartcraft.com/apps/wordcraft · https://github.com/storytold/wordcraft", - self.backend.describe() - ), - })) - } - "ping" => Ok(json!({})), - "tools/list" => Ok(json!({"tools": tool_definitions()})), - "tools/call" => { - let name = params.get("name").and_then(Value::as_str).ok_or((INVALID_PARAMS, "missing tool `name`".to_string()))?; - let args = params.get("arguments").cloned().unwrap_or(Value::Null); - Ok(call_tool(self.backend.as_mut(), name, &args).to_value()) - } - "resources/list" => Ok(json!({"resources": [ - {"uri": DOC_URI, "name": "document", "title": "Active document", "description": "Blocks, text, formatting, sections, parts and selection of the document (document.inspect)", "mimeType": "application/json"}, - {"uri": COMMANDS_URI, "name": "commands", "title": "Commands", "description": "Every command: id, label, ribbon location, shortcut, params, enabled (engine.commands)", "mimeType": "application/json"}, - ]})), - "resources/templates/list" => Ok(json!({"resourceTemplates": []})), - "resources/read" => { - let uri = params.get("uri").and_then(Value::as_str).ok_or((INVALID_PARAMS, "missing `uri`".to_string()))?; - let v = match uri { - DOC_URI => self.backend.call("document.inspect", json!({})), - COMMANDS_URI => self.backend.call("engine.commands", json!({})), - _ => return Err((RESOURCE_NOT_FOUND, format!("resource not found: {uri}"))), - } - .map_err(|e| (INTERNAL_ERROR, e))?; - Ok(json!({"contents": [{"uri": uri, "mimeType": "application/json", "text": serde_json::to_string_pretty(&v).unwrap_or_default()}]})) - } - other => Err((METHOD_NOT_FOUND, format!("method not found: {other}"))), - } + self.inner.handle(msg) } } diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rs index f554d4bb84..fd2951a7bb 100644 --- a/crates/mcp/src/tests.rs +++ b/crates/mcp/src/tests.rs @@ -4,6 +4,9 @@ use serde_json::{Value, json}; use crate::{Headless, Server}; +mod differential; +mod oracle; + fn call(s: &mut Server, id: u64, method: &str, params: Value) -> Value { let line = json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params}).to_string(); let r = s.handle_line(&line).expect("reply"); @@ -169,7 +172,9 @@ fn render_and_screenshot_through_the_app_use_no_temp_file() { let calls = std::sync::Arc::new(std::sync::Mutex::new(Vec::new())); let mut s = Server::new(Box::new(FakeApp { calls: calls.clone() })); for (tool, method) in [("render_page", "ui.render"), ("screenshot", "ui.screenshot")] { - let r = call(&mut s, 10, "tools/call", json!({"name": tool, "arguments": {"page": 1}})); + // `screenshot` takes no arguments (the shared check refuses ones its schema does not list). + let args = if tool == "render_page" { json!({"page": 1}) } else { json!({}) }; + let r = call(&mut s, 10, "tools/call", json!({"name": tool, "arguments": args})); let content = &r["result"]["content"]; assert_eq!(r["result"]["isError"], false, "{tool}: {r}"); assert_eq!(content[0]["type"], "image", "{tool}"); @@ -310,7 +315,8 @@ fn over_long_request_line_is_rejected_and_serving_continues() { let text = String::from_utf8(out).unwrap(); let lines: Vec<&str> = text.lines().collect(); assert_eq!(lines.len(), 2, "{text}"); - assert!(lines[0].contains("too long"), "{}", lines[0]); + // The shared core words it "request too large" (was "request line too long"); same -32600. + assert!(lines[0].contains("too large") && lines[0].contains("-32600"), "{}", lines[0]); assert!(lines[1].contains(r#""id":5"#), "{}", lines[1]); } diff --git a/crates/mcp/src/tests/differential.rs b/crates/mcp/src/tests/differential.rs new file mode 100644 index 0000000000..eb6fdb422c --- /dev/null +++ b/crates/mcp/src/tests/differential.rs @@ -0,0 +1,452 @@ +//! The shared server against the hand-written one it replaced (`oracle`): the same scripted +//! JSON-RPC session goes through both and the replies must be equal, after normalising only the +//! differences listed in `normalise`. Differences that cannot be normalised away are pinned by +//! their own tests below. Document ids (a process-wide counter) are zeroed before comparing. + +use serde_json::{Value, json}; + +use super::oracle; +use crate::{Headless, Server}; + +/// One input line of the session; `free_text` marks a tool call whose failure text is the +/// validator's own words (both sides must still say `isError: true`). +struct Step { + line: Vec, + free_text: bool, +} + +fn req(id: Value, method: &str, params: Value) -> Vec { + json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params}).to_string().into_bytes() +} + +fn step(line: Vec) -> Step { + Step { line, free_text: false } +} + +fn call(id: u64, name: &str, args: Value) -> Step { + step(req(json!(id), "tools/call", json!({"name": name, "arguments": args}))) +} + +fn call_free(id: u64, name: &str, args: Value) -> Step { + Step { free_text: true, ..call(id, name, args) } +} + +fn script() -> Vec { + let mut s = Vec::new(); + // initialize with each supported version, an unknown one, an odd one, and none. + for (i, v) in [json!("2025-06-18"), json!("2025-03-26"), json!("2024-11-05"), json!("1999-01-01"), json!(7), Value::Null].into_iter().enumerate() + { + s.push(step(req(json!(i + 1), "initialize", json!({"protocolVersion": v, "capabilities": {}})))); + } + s.push(step(req(json!(20), "initialize", json!({})))); + s.push(step(req(json!(21), "initialize", Value::Null))); + s.push(step(br#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#.to_vec())); + s.push(step(req(json!(30), "ping", json!({})))); + s.push(step(req(json!(31), "tools/list", json!({})))); + s.push(step(req(json!(32), "resources/templates/list", json!({})))); + // tools: a realistic session, an image, an error result, a doc-addressed call. + for (i, (name, args)) in [ + ("new_document", json!({})), + ("new_document", json!({"template": "sample"})), + ("type_text", json!({"text": "Hello there"})), + ("type_text", json!({"text": "a\nb", "paragraphs": true, "doc": null})), + ("select_text", json!({"text": "Hello", "occurrence": 1})), + ("execute", json!({"command": "format.bold"})), + ("execute", json!({"command": "no.such.command"})), + ("execute", json!({"command": "text.insert", "params": {"text": "x"}, "doc": 99})), + ("batch", json!({"commands": [{"command": "caret.docEnd"}, {"command": "text.insert", "params": {"text": "!"}}]})), + ("batch", json!({"commands": [{"command": "no.such"}, {"command": "caret.docEnd"}], "keepGoing": true})), + ("insert_table", json!({"values": [["a", 1], ["b", 2]], "header": true})), + ("list_commands", json!({"query": "bold"})), + ("list_documents", json!({})), + ("get_text", json!({})), + ("inspect_document", json!({})), + ("render_page", json!({"page": 1, "scale": 0.2})), + ("render_page", json!({"page": 99})), + ("screenshot", json!({})), + ("click", json!({"x": 1, "y": 2})), + ("key", json!({"key": "B", "cmd": true})), + ("parity", json!({})), + ("save_document", json!({"path": "/nonexistent-dir-wc/x.docx"})), + ] + .into_iter() + .enumerate() + { + s.push(call(100 + i as u64, name, args)); + } + // bad arguments: both sides fail with isError; the words are the validator's own. + s.push(call_free(200, "execute", json!({}))); + s.push(call_free(201, "execute", json!({"command": 5}))); + s.push(call_free(203, "insert_table", json!({"values": "x"}))); + s.push(call_free(204, "insert_table", json!({"values": null}))); + s.push(call_free(205, "get_text", json!({"doc": "1"}))); + s.push(call_free(206, "render_page", json!({"doc": 1.5}))); + s.push(call_free(207, "open_document", json!({}))); + s.push(call_free(208, "execute", json!("not an object"))); + // A missing or null `arguments` is `{}` to the shared server (it was null). + for (id, params) in [(209, json!({"name": "execute"})), (210, json!({"name": "execute", "arguments": null}))] { + s.push(Step { free_text: true, ..step(req(json!(id), "tools/call", params)) }); + } + s.push(step(req(json!(211), "tools/call", json!({"name": "nope", "arguments": {}})))); + s.push(step(req(json!(212), "tools/call", json!({})))); + s.push(step(req(json!(213), "tools/call", json!({"name": 5})))); + s.push(step(req(json!(214), "tools/call", Value::Null))); + // odd ids. + for id in [json!("abc"), json!(0), json!(-3), json!(1.5), json!(u64::MAX), json!(null), json!(true), json!([1]), json!({"a": 1})] { + s.push(step(req(id, "ping", json!({})))); + } + s.push(step(br#"{"jsonrpc":"2.0","method":"ping"}"#.to_vec())); + // resources. + s.push(step(req(json!(300), "resources/list", json!({})))); + s.push(step(req(json!(301), "resources/read", json!({"uri": "wordcraft://document"})))); + s.push(step(req(json!(302), "resources/read", json!({"uri": "wordcraft://commands"})))); + s.push(step(req(json!(303), "resources/read", json!({"uri": "wordcraft://nothing"})))); + // unknown methods, malformed messages, notifications. + s.push(step(req(json!(310), "nope", json!({})))); + s.push(step(req(json!(311), "tools/nope", Value::Null))); + for raw in [ + &br#"{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":1}}"#[..], + br#"{"jsonrpc":"2.0","method":"notifications/progress"}"#, + br#"{"jsonrpc":"2.0","method":"notifications/whatever"}"#, + br#"{"jsonrpc":"2.0","id":1,"result":{}}"#, + br#"{"jsonrpc":"2.0","id":1,"error":{"code":1,"message":"x"}}"#, + br#"{"jsonrpc":"2.0","id":7}"#, + br#"{"jsonrpc":"2.0","id":7,"method":5}"#, + br#"{"id":8,"method":"ping"}"#, + br#"[]"#, + br#"42"#, + br#""text""#, + br#"null"#, + br#"{not json"#, + br#" "#, + b"", + ] { + s.push(step(raw.to_vec())); + } + // batches: mixed requests and notifications, only notifications, bad members. + s.push(step( + json!([ + {"jsonrpc": "2.0", "id": 400, "method": "ping"}, + {"jsonrpc": "2.0", "method": "notifications/initialized"}, + {"jsonrpc": "2.0", "id": 401, "method": "tools/list"}, + 5, + {"jsonrpc": "2.0", "id": 402, "method": "nope"} + ]) + .to_string() + .into_bytes(), + )); + s.push(step(br#"[{"jsonrpc":"2.0","method":"notifications/initialized"}]"#.to_vec())); + // CRLF line ending, leading and trailing whitespace. + s.push(step(b" {\"jsonrpc\":\"2.0\",\"id\":500,\"method\":\"ping\"}\r".to_vec())); + s +} + +/// The documented differences, removed from a reply before comparing. Anything else must match. +fn normalise(mut v: Value, free_text: bool) -> Value { + if let Value::Array(items) = v { + return Value::Array(items.into_iter().map(|i| normalise(i, free_text)).collect()); + } + // 1. `capabilities` gains `listChanged: false` on tools and resources. + if let Some(c) = v.pointer_mut("/result/capabilities").and_then(Value::as_object_mut) { + for cap in c.values_mut() { + if let Some(o) = cap.as_object_mut() { + o.remove("listChanged"); + } + } + } + // 2. Error texts are reworded (too long/large, non-UTF-8, unknown method, unknown resource); + // the codes are compared. + if let Some(e) = v.get_mut("error").and_then(Value::as_object_mut) { + let code = e.get("code").and_then(Value::as_i64).unwrap_or(0); + if [-32601, -32002].contains(&code) || e.get("message").and_then(Value::as_str).is_some_and(|m| m.contains("too ") || m.contains("UTF-8")) { + e.insert("message".into(), json!("")); + } + } + // 3. Document ids come from a process-wide counter, so two sessions in one process differ. + if let Some(text) = v.pointer_mut("/result/content/0/text") + && let Some(Ok(mut j)) = text.as_str().map(serde_json::from_str::) + { + zero_ids(&mut j); + *text = json!(j.to_string()); + } + // 4. A tool call refused before the tool runs: the validator's own words. + if free_text && v.pointer("/result/isError") == Some(&json!(true)) { + v["result"]["content"] = json!(""); + } + v +} + +fn zero_ids(v: &mut Value) { + match v { + Value::Object(o) => { + for (k, x) in o.iter_mut() { + if k == "id" && x.is_number() { + *x = json!(0); + } else { + zero_ids(x); + } + } + } + Value::Array(a) => a.iter_mut().for_each(zero_ids), + _ => {} + } +} + +fn run_oracle(input: &[u8]) -> Vec { + let mut server = oracle::Server::new(Box::new(Headless::default())); + let mut out = Vec::new(); + server.serve(std::io::Cursor::new(input.to_vec()), &mut out).unwrap(); + lines(out) +} + +fn run_shared(input: &[u8]) -> Vec { + let mut server = Server::new(Box::new(Headless::default())); + let mut out = Vec::new(); + server.serve(std::io::Cursor::new(input.to_vec()), &mut out).unwrap(); + lines(out) +} + +fn lines(out: Vec) -> Vec { + String::from_utf8(out).unwrap().lines().map(|l| serde_json::from_str(l).unwrap_or_else(|e| panic!("{e}: {l}"))).collect() +} + +/// Both servers answer a line at a time, so each step is compared on its own reply (or lack of one). +fn compare(steps: &[Step]) { + let mut old = oracle::Server::new(Box::new(Headless::default())); + let mut new = Server::new(Box::new(Headless::default())); + for (i, s) in steps.iter().enumerate() { + let text = String::from_utf8_lossy(&s.line).into_owned(); + let (a, b) = (old.handle_line(&text), new.handle_line(&text)); + let parse = |r: Option| r.map(|r| normalise(serde_json::from_str::(&r).unwrap(), s.free_text)); + assert_eq!(parse(b), parse(a), "step {i}: {text}"); + } + assert_eq!(old.is_initialized(), new.is_initialized()); +} + +#[test] +fn shared_server_answers_the_scripted_session_like_the_old_one() { + compare(&script()); +} + +/// The same session as a byte stream through `serve`, with an oversize line and a line that is +/// not UTF-8 in the middle: same replies, same order. +#[test] +fn serve_matches_the_old_server_with_an_oversize_and_a_non_utf8_line() { + let mut input = Vec::new(); + for (i, s) in script().iter().enumerate() { + if i == 20 { + input.extend(vec![b'a'; (1 << 20) + 1]); + input.push(b'\n'); + input.extend_from_slice(b"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\",\"x\":\"\xff\xfe\"}\n"); + // Exactly at the limit is accepted (and is a parse error); one over is refused. + input.extend(vec![b' '; 1 << 20]); + input.push(b'\n'); + input.extend(vec![b'{'; 1 << 20]); + input.push(b'\n'); + } + input.extend_from_slice(&s.line); + input.push(b'\n'); + } + // An unterminated last line still counts. + input.extend_from_slice(br#"{"jsonrpc":"2.0","id":9,"method":"ping"}"#); + let (old, new) = (run_oracle(&input), run_shared(&input)); + let norm = |v: Vec| v.into_iter().map(|r| normalise(r, false)).collect::>(); + // The script's free-text failures are only compared in `compare`; drop their texts here. + let strip = |v: Vec| -> Vec { + v.into_iter() + .map(|mut r| { + if r.pointer("/result/isError") == Some(&json!(true)) + && r["result"]["content"][0]["text"].as_str().is_some_and(|t| !t.starts_with('{') && !t.starts_with('[')) + { + r["result"]["content"] = json!(""); + } + r + }) + .collect() + }; + let (old, new) = (strip(norm(old)), strip(norm(new))); + assert_eq!(new.len(), old.len()); + for (i, (n, o)) in new.iter().zip(&old).enumerate() { + assert_eq!(n, o, "reply {i}"); + } +} + +/// Difference 1 (accepted): the oversize and non-UTF-8 replies keep their codes, the words change. +#[test] +fn refused_lines_keep_their_codes_and_say_why() { + let mut input = vec![b'a'; (1 << 20) + 1]; + input.extend_from_slice(b"\n\xff\n"); + let old = run_oracle(&input); + let new = run_shared(&input); + assert_eq!(old[0]["error"]["code"], -32600); + assert_eq!(new[0]["error"]["code"], -32600); + assert_eq!(old[0]["error"]["message"], "request line too long"); + assert_eq!(new[0]["error"]["message"], "request too large"); + assert_eq!(old[1]["error"]["code"], -32700); + assert_eq!(new[1]["error"]["code"], -32700); + assert!(new[1]["error"]["message"].as_str().unwrap().contains("UTF-8")); + assert_eq!(new[0]["id"], Value::Null); +} + +/// Difference 2 (accepted): a request with no `uri` is "unknown resource" -32002, not -32602 +/// (the shared core hands the tools an empty uri); an unknown uri keeps -32002. +#[test] +fn resources_read_without_a_uri_is_not_found() { + let mut old = oracle::Server::new(Box::new(Headless::default())); + let mut new = Server::new(Box::new(Headless::default())); + let line = req(json!(1), "resources/read", json!({})); + let line = String::from_utf8(line).unwrap(); + let o: Value = serde_json::from_str(&old.handle_line(&line).unwrap()).unwrap(); + let n: Value = serde_json::from_str(&new.handle_line(&line).unwrap()).unwrap(); + assert_eq!(o["error"]["code"], -32602); + assert_eq!(n["error"]["code"], -32002); +} + +/// Difference 3 (accepted): the shared core serves `prompts/list` (empty) where the old server +/// said "method not found"; WordCraft has no prompts, and `prompts/get` stays not found. +#[test] +fn prompts_list_is_empty_and_prompts_get_is_not_found() { + let mut new = Server::new(Box::new(Headless::default())); + let r = new.handle(json!({"jsonrpc": "2.0", "id": 1, "method": "prompts/list"})).unwrap(); + assert_eq!(r["result"], json!({"prompts": []})); + let r = new.handle(json!({"jsonrpc": "2.0", "id": 2, "method": "prompts/get", "params": {"name": "x"}})).unwrap(); + assert_eq!(r["error"]["code"], -32601); + // And capabilities do not advertise prompts or completions. + let r = new.handle(json!({"jsonrpc": "2.0", "id": 3, "method": "initialize", "params": {}})).unwrap(); + assert_eq!(r["result"]["capabilities"], json!({"tools": {"listChanged": false}, "resources": {"listChanged": false}})); +} + +/// Difference 4 (accepted hardening): a batch of more than 1000 messages is refused whole; the old +/// server answered every member. +#[test] +fn batches_are_capped_at_a_thousand() { + let batch = |n: usize| Value::Array((0..n).map(|i| json!({"jsonrpc": "2.0", "id": i, "method": "ping"})).collect()).to_string(); + let mut old = oracle::Server::new(Box::new(Headless::default())); + let mut new = Server::new(Box::new(Headless::default())); + let (a, b) = (old.handle_line(&batch(1000)).unwrap(), new.handle_line(&batch(1000)).unwrap()); + assert_eq!(a, b); + let a: Value = serde_json::from_str(&old.handle_line(&batch(1001)).unwrap()).unwrap(); + let b: Value = serde_json::from_str(&new.handle_line(&batch(1001)).unwrap()).unwrap(); + assert_eq!(a.as_array().map(Vec::len), Some(1001)); + assert_eq!(b["error"]["code"], -32600); +} + +/// Difference 5 (accepted, stricter): arguments the tool's schema does not list, or of another +/// type, are a tool error before the tool runs. The old server passed them on and ignored them. +#[test] +fn unknown_and_mistyped_arguments_are_tool_errors() { + let mut new = Server::new(Box::new(Headless::default())); + for (name, args, needle) in [ + ("type_text", json!({"text": "x", "bogus": 1}), "unknown argument `bogus`"), + ("get_text", json!({"x": 1}), "unknown argument `x`"), + ("type_text", json!({"text": 5}), "must be of type"), + ("select_text", json!({"text": "x", "occurrence": "1"}), "must be of type"), + ] { + let r = new.handle(json!({"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": name, "arguments": args}})).unwrap(); + assert_eq!(r["result"]["isError"], true, "{r}"); + assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains(needle), "{r}"); + assert!(r.get("error").is_none(), "a tool failure is a result, not a JSON-RPC error: {r}"); + } +} + +/// Difference 6 (accepted, stricter): a required argument that is missing is refused before the +/// tool runs, where `type_text` and `select_text` used to treat a missing `text` as "". The +/// schemas have always listed `text` as required, so the call was never valid. +#[test] +fn a_missing_required_argument_is_refused_where_the_tool_defaulted_it() { + let mut old = oracle::Server::new(Box::new(Headless::default())); + let mut new = Server::new(Box::new(Headless::default())); + for name in ["type_text", "select_text"] { + let line = String::from_utf8(req(json!(1), "tools/call", json!({"name": name, "arguments": {}}))).unwrap(); + let o: Value = serde_json::from_str(&old.handle_line(&line).unwrap()).unwrap(); + let n: Value = serde_json::from_str(&new.handle_line(&line).unwrap()).unwrap(); + // type_text {} used to type nothing and succeed; select_text {} failed to find "". + assert_eq!(o["result"]["isError"], name == "select_text", "{name}: {o}"); + assert_eq!(n["result"]["isError"], true, "{name}: {n}"); + assert!(n["result"]["content"][0]["text"].as_str().unwrap().contains("missing required argument `text`"), "{n}"); + } +} + +/// Every argument the tools read, and every one the documentation shows, passes the check: the +/// schemas list what the tools accept, so no call that worked now fails. +#[test] +fn every_documented_call_passes_the_argument_check() { + use craft_mcp_server::check_arguments; + let defs = crate::tools::tool_definitions(); + let defs = defs.as_array().unwrap(); + for (name, args) in [ + ("list_commands", json!({"query": "x"})), + ("execute", json!({"command": "insert.table", "params": {"rows": 3, "cols": 4}, "doc": 3})), + ("insert_table", json!({"values": [["Month", "Cases"], ["January", 12]], "header": true, "style": "TableGrid", "doc": 1})), + ("batch", json!({"commands": [{"command": "a"}], "keepGoing": true, "doc": 0})), + ("new_document", json!({"template": "letter"})), + ("open_document", json!({"path": "a.docx", "password": "p"})), + ("save_document", json!({"path": "a.pdf", "doc": 2})), + ("type_text", json!({"text": "x", "paragraphs": true, "doc": 2})), + ("select_text", json!({"text": "x", "occurrence": 2, "doc": 2})), + ("get_text", json!({"doc": 2})), + ("inspect_document", json!({"doc": 2})), + ("render_page", json!({"page": 1, "scale": 0.5, "doc": 2})), + ("list_documents", json!({})), + ("parity", json!({})), + ("screenshot", json!({})), + ("click", json!({"x": 1, "y": 2, "count": 2, "button": "right", "shift": true, "alt": true, "cmd": true, "ctrl": true, "command": true})), + ("key", json!({"key": "B", "shift": true, "alt": true, "cmd": true, "ctrl": true, "command": true})), + ("ui_inspect", json!({})), + ] { + assert_eq!(check_arguments(defs, name, &args), Ok(()), "{name}"); + } + // Every tool is covered above. + assert_eq!(defs.len(), 18); +} + +/// Hostile and random input never panics or breaks the stream: every reply is one JSON line. +#[test] +fn random_lines_never_panic() { + let mut x: u64 = 0x9e37_79b9_7f4a_7c15; + let mut next = move || { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x + }; + let valid: Vec> = script().into_iter().map(|s| s.line).filter(|l| !l.is_empty()).collect(); + let toks: [&[u8]; 14] = + [b"{", b"}", b"[", b"]", b"\"", b":", b",", b"null", b"\"method\"", b"\"id\"", b"\"params\"", b"\"tools/call\"", b"\"arguments\"", b"\xff"]; + let mut input = Vec::new(); + for _ in 0..1500 { + let mut line = match next() % 3 { + // Random bytes. + 0 => (0..next() % 64).map(|_| (next() & 0xff) as u8).collect(), + // JSON-ish tokens. + 1 => (0..next() % 20).flat_map(|_| toks[(next() % 14) as usize].to_vec()).collect(), + // A valid request, mutated: bytes flipped, cut, or doubled. + _ => { + let mut l = valid[(next() % valid.len() as u64) as usize].clone(); + for _ in 0..next() % 4 { + if l.is_empty() { + break; + } + let at = (next() % l.len() as u64) as usize; + match next() % 3 { + 0 => l[at] = (next() & 0xff) as u8, + 1 => l.truncate(at), + _ => l.insert(at, toks[(next() % 14) as usize][0]), + } + } + l + } + }; + line.retain(|&b| b != b'\n'); + // Keep random lines from naming tools that touch the disk. + if String::from_utf8_lossy(&line).contains("save_document") || String::from_utf8_lossy(&line).contains("open_document") { + continue; + } + input.extend(line); + input.push(b'\n'); + } + let replies = run_shared(&input); + for r in replies { + assert!(r.is_object() || r.is_array(), "{r}"); + } +} diff --git a/crates/mcp/src/tests/oracle.rs b/crates/mcp/src/tests/oracle.rs new file mode 100644 index 0000000000..487865a7ee --- /dev/null +++ b/crates/mcp/src/tests/oracle.rs @@ -0,0 +1,174 @@ +//! The hand-written MCP server core WordCraft had before it moved to `craft_mcp_server`, kept +//! verbatim as the oracle the differential test compares the shared server against. + +use std::io::{BufRead, Write}; + +use serde_json::{Value, json}; + +use crate::backend::Backend; +use crate::server::{BoundedLine, MAX_REQUEST_LINE, read_bounded_line}; +use crate::server::{COMMANDS_URI, DOC_URI}; +use crate::tools::{call_tool, tool_definitions}; + +/// The MCP revision we implement. +pub(crate) const PROTOCOL_VERSION: &str = "2025-06-18"; +const SUPPORTED_VERSIONS: &[&str] = &[PROTOCOL_VERSION, "2025-03-26", "2024-11-05"]; + +const PARSE_ERROR: i64 = -32700; +const INVALID_REQUEST: i64 = -32600; +const METHOD_NOT_FOUND: i64 = -32601; +const INVALID_PARAMS: i64 = -32602; +const INTERNAL_ERROR: i64 = -32603; +const RESOURCE_NOT_FOUND: i64 = -32002; + +const INSTRUCTIONS: &str = "WordCraft is a word processor (a Microsoft Word clone). Every action is a command: find ids and \ +parameters with list_commands and run them with execute (or several with batch). Positions are \ +{story:\"body\", path:[block,(row,cell,block)...], off:byteOffset}. Typical flow: new_document → type_text \ +\"Hello\" → execute text.newParagraph → execute para.style {style:\"Heading 1\"} → select_text {text:\"Hello\"} → \ +execute format.bold → inspect_document to verify → render_page to look at the result → save {path:\"out.docx\"}. \ +Several documents can be open: new_document and open_document open another one and make it active; \ +list_documents gives their ids, and `doc` on execute, batch and the other document tools works on one \ +without switching."; + +/// An MCP server bound to one backend. +pub(crate) struct Server { + backend: Box, + initialized: bool, +} + +fn response(id: Value, result: Value) -> Value { + json!({"jsonrpc": "2.0", "id": id, "result": result}) +} + +fn error(id: Value, code: i64, message: impl Into) -> Value { + json!({"jsonrpc": "2.0", "id": id, "error": {"code": code, "message": message.into()}}) +} + +impl Server { + pub fn new(backend: Box) -> Self { + Self { backend, initialized: false } + } + + /// Whether the client has sent `notifications/initialized`. + pub fn is_initialized(&self) -> bool { + self.initialized + } + + /// Serve newline-delimited JSON-RPC until `input` closes. Logs go to stderr only (stdout is + /// the protocol stream). + pub fn serve(&mut self, mut input: impl BufRead, mut output: impl Write) -> std::io::Result<()> { + loop { + let reply = match read_bounded_line(&mut input, MAX_REQUEST_LINE) { + Ok(BoundedLine::Eof) => break, + Ok(BoundedLine::Line(line)) => self.handle_line(&line), + Ok(BoundedLine::TooLong) => Some(error(Value::Null, INVALID_REQUEST, "request line too long").to_string()), + Err(e) if e.kind() == std::io::ErrorKind::InvalidData => { + Some(error(Value::Null, PARSE_ERROR, "request line is not UTF-8").to_string()) + } + Err(e) => return Err(e), + }; + if let Some(reply) = reply { + output.write_all(reply.as_bytes())?; + output.write_all(b"\n")?; + output.flush()?; + } + } + Ok(()) + } + + /// Handle one line; returns the reply line (None for notifications and blank lines). + pub fn handle_line(&mut self, line: &str) -> Option { + let line = line.trim(); + if line.is_empty() { + return None; + } + let reply = match serde_json::from_str::(line) { + Ok(Value::Array(batch)) => { + // Batches were removed in 2025-06-18; still answer older clients sensibly. + if batch.is_empty() { + Some(error(Value::Null, INVALID_REQUEST, "empty batch")) + } else { + let replies: Vec = batch.into_iter().filter_map(|m| self.handle(m)).collect(); + (!replies.is_empty()).then_some(Value::Array(replies)) + } + } + Ok(msg) => self.handle(msg), + Err(e) => Some(error(Value::Null, PARSE_ERROR, format!("parse error: {e}"))), + }; + reply.map(|r| r.to_string()) + } + + /// Handle one JSON-RPC message; `None` for notifications and responses. + pub fn handle(&mut self, msg: Value) -> Option { + let Value::Object(o) = &msg else { return Some(error(Value::Null, INVALID_REQUEST, "message must be an object")) }; + let id = o.get("id").cloned(); + let Some(method) = o.get("method").and_then(Value::as_str) else { + // A response to a server→client request (we send none): ignore. Anything else is invalid. + if o.contains_key("result") || o.contains_key("error") { + return None; + } + return Some(error(id.unwrap_or(Value::Null), INVALID_REQUEST, "missing `method`")); + }; + let params = o.get("params").cloned().unwrap_or(Value::Null); + let Some(id) = id else { + self.notification(method); + return None; + }; + if !(id.is_string() || id.is_number()) { + return Some(error(Value::Null, INVALID_REQUEST, "`id` must be a string or number")); + } + Some(match self.request(method, ¶ms) { + Ok(r) => response(id, r), + Err((code, m)) => error(id, code, m), + }) + } + + fn notification(&mut self, method: &str) { + match method { + "notifications/initialized" => self.initialized = true, + "notifications/cancelled" | "notifications/progress" | "notifications/roots/list_changed" => {} + other => log::debug!("ignoring notification {other}"), + } + } + + fn request(&mut self, method: &str, params: &Value) -> Result { + match method { + "initialize" => { + let asked = params.get("protocolVersion").and_then(Value::as_str).unwrap_or(PROTOCOL_VERSION); + let version = if SUPPORTED_VERSIONS.contains(&asked) { asked } else { PROTOCOL_VERSION }; + Ok(json!({ + "protocolVersion": version, + "capabilities": {"tools": {}, "resources": {}}, + "serverInfo": {"name": "wordcraft", "title": "WordCraft", "version": env!("CARGO_PKG_VERSION"), "websiteUrl": "https://getartcraft.com/apps/wordcraft"}, + "instructions": format!( + "{INSTRUCTIONS} Backend: {}. Community: https://discord.gg/artcraft · https://getartcraft.com/apps/wordcraft · https://github.com/storytold/wordcraft", + self.backend.describe() + ), + })) + } + "ping" => Ok(json!({})), + "tools/list" => Ok(json!({"tools": tool_definitions()})), + "tools/call" => { + let name = params.get("name").and_then(Value::as_str).ok_or((INVALID_PARAMS, "missing tool `name`".to_string()))?; + let args = params.get("arguments").cloned().unwrap_or(Value::Null); + Ok(call_tool(self.backend.as_mut(), name, &args).to_value()) + } + "resources/list" => Ok(json!({"resources": [ + {"uri": DOC_URI, "name": "document", "title": "Active document", "description": "Blocks, text, formatting, sections, parts and selection of the document (document.inspect)", "mimeType": "application/json"}, + {"uri": COMMANDS_URI, "name": "commands", "title": "Commands", "description": "Every command: id, label, ribbon location, shortcut, params, enabled (engine.commands)", "mimeType": "application/json"}, + ]})), + "resources/templates/list" => Ok(json!({"resourceTemplates": []})), + "resources/read" => { + let uri = params.get("uri").and_then(Value::as_str).ok_or((INVALID_PARAMS, "missing `uri`".to_string()))?; + let v = match uri { + DOC_URI => self.backend.call("document.inspect", json!({})), + COMMANDS_URI => self.backend.call("engine.commands", json!({})), + _ => return Err((RESOURCE_NOT_FOUND, format!("resource not found: {uri}"))), + } + .map_err(|e| (INTERNAL_ERROR, e))?; + Ok(json!({"contents": [{"uri": uri, "mimeType": "application/json", "text": serde_json::to_string_pretty(&v).unwrap_or_default()}]})) + } + other => Err((METHOD_NOT_FOUND, format!("method not found: {other}"))), + } + } +} diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rs index 0dd2c734ab..02537c8b1a 100644 --- a/crates/mcp/src/tools.rs +++ b/crates/mcp/src/tools.rs @@ -169,14 +169,20 @@ pub fn tool_definitions() -> Value { "click", "Click", "Click at window coordinates (desktop app only).", - obj(json!({"x": n("x"), "y": n("y"), "count": n("1-3 clicks"), "shift": {"type": "boolean"}, "cmd": {"type": "boolean"}}), &["x", "y"]), + obj( + json!({"x": n("x"), "y": n("y"), "count": n("1-3 clicks"), "button": s("left (default) or right"), "shift": {"type": "boolean"}, "alt": {"type": "boolean"}, "cmd": {"type": "boolean"}, "ctrl": {"type": "boolean"}, "command": {"type": "boolean"}}), + &["x", "y"] + ), false ), tool( "key", "Press key", "Press a key with modifiers (desktop app only), e.g. {key:\"B\", cmd:true}.", - obj(json!({"key": s("Key name"), "shift": {"type": "boolean"}, "alt": {"type": "boolean"}, "cmd": {"type": "boolean"}}), &["key"]), + obj( + json!({"key": s("Key name"), "shift": {"type": "boolean"}, "alt": {"type": "boolean"}, "cmd": {"type": "boolean"}, "ctrl": {"type": "boolean"}, "command": {"type": "boolean"}}), + &["key"] + ), false ), tool( diff --git a/docs/mcp.md b/docs/mcp.md index 15b04ab989..5b0b8e1dee 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -1,6 +1,6 @@ # MCP server -> **Last updated:** 2026-11-14 · Keep the complete `type_text` description in one tool-table row; behavior wording unchanged. Delivery review fixes for #2596: unknown outcomes are not replayed, including image exports to a path; invalid UTF-8 returns a parse error without stopping later requests. +> **Last updated:** 2026-11-17 · The protocol core is the shared `craft-mcp-server` crate (#778); `click` and `key` list every argument they accept. Earlier: Keep the complete `type_text` description in one tool-table row; behavior wording unchanged. Delivery review fixes for #2596: unknown outcomes are not replayed, including image exports to a path; invalid UTF-8 returns a parse error without stopping later requests. WordCraft speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio, so Claude and other agents can write and edit documents. @@ -36,6 +36,17 @@ On stdio, an invalid UTF-8 request line returns JSON-RPC parse error `-32700`. I the backend, and the server continues with the next line instead of substituting characters in text or paths. +The protocol core (framing, lifecycle, `tools/*`, `resources/*`) is the shared `craft-mcp-server` +crate; WordCraft supplies the tools, resources and instructions. What that means for a client: + +- A request line over 1 MiB gets `-32600` "request too large" and the server keeps serving. +- A JSON-RPC batch holds at most 1000 messages; a larger one gets `-32600` "batch too large". +- A `tools/call` whose arguments do not match the tool's schema (a missing required argument, an + argument the tool does not list, or one of the wrong type) or that names an unknown tool returns + a tool result with `isError: true` naming the problem, not a JSON-RPC error. +- `resources/read` with no `uri` is `-32002` (unknown resource), like any unknown `uri`. +- `initialize` reports `listChanged: false` for tools and resources; `prompts/list` is empty. + ## Scripts from the command line `wordcraft-cli run --script job.json` (`--script -` reads standard input) runs the commands in a