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