ocr_mcp/lib.rs
1// Copyright (c) 2026 Enzo Lombardi
2// SPDX-License-Identifier: MIT
3
4//! `ocr-mcp` — an MCP stdio server that transcribes images with a local
5//! GLM-OCR model, spawning `llama-server` on demand.
6//!
7//! The binary is the product; this library exists so the pieces can be tested
8//! without a model, a GPU, or a network, and it is documented here for anyone
9//! who wants to reuse or audit them.
10//!
11//! # How a transcription happens
12//!
13//! ```text
14//! host --stdio--> mcp::serve --> llama::LlamaOcr --> server::Child (llama-server)
15//! | | ^
16//! tools/call image_input::decode client::build_request
17//! ```
18//!
19//! [`mcp`] speaks newline-delimited JSON-RPC over stdin and stdout and is pure
20//! request-to-response translation over the [`ocr::OcrEngine`] trait.
21//! [`image_input`] turns the tool's `image` argument, either a filesystem path
22//! or a `data:` URI, into normalized bytes. [`llama::LlamaOcr`] is the real
23//! engine: it lazily spawns a [`server::Child`], calls it through
24//! [`client`], and lets a reaper thread drop the child once it has gone idle.
25//! [`ocr::StubOcr`] stands in for all of that in tests.
26//!
27//! # Two invariants worth knowing before you change anything
28//!
29//! **stdout carries JSON-RPC frames and nothing else.** It is the transport.
30//! Every diagnostic goes to stderr, and the `llama-server` child's own streams
31//! are piped and drained rather than inherited, because an inherited child
32//! writing a startup banner would corrupt the framing and wedge the host.
33//!
34//! **Oversized images are worse than slow.** Image tokens scale with pixel
35//! area, and past roughly 2700 of them this model stops transcribing and
36//! begins confabulating: fluent text with no relation to the picture, and
37//! nothing to signal it happened. An oversized image also poisons the child
38//! process, so every later request returns garbage too. [`image_input`] caps
39//! area to make both impossible; see `MAX_PIXELS` there for the measurements.
40
41pub mod client;
42pub mod config;
43pub mod download;
44pub mod image_input;
45pub mod llama;
46pub mod mcp;
47pub mod ocr;
48pub mod server;