Expand description
ocr-mcp — an MCP stdio server that transcribes images with a local
GLM-OCR model, spawning llama-server on demand.
The binary is the product; this library exists so the pieces can be tested without a model, a GPU, or a network, and it is documented here for anyone who wants to reuse or audit them.
§How a transcription happens
host --stdio--> mcp::serve --> llama::LlamaOcr --> server::Child (llama-server)
| | ^
tools/call image_input::decode client::build_requestmcp speaks newline-delimited JSON-RPC over stdin and stdout and is pure
request-to-response translation over the ocr::OcrEngine trait.
image_input turns the tool’s image argument, either a filesystem path
or a data: URI, into normalized bytes. llama::LlamaOcr is the real
engine: it lazily spawns a server::Child, calls it through
client, and lets a reaper thread drop the child once it has gone idle.
ocr::StubOcr stands in for all of that in tests.
§Two invariants worth knowing before you change anything
stdout carries JSON-RPC frames and nothing else. It is the transport.
Every diagnostic goes to stderr, and the llama-server child’s own streams
are piped and drained rather than inherited, because an inherited child
writing a startup banner would corrupt the framing and wedge the host.
Oversized images are worse than slow. Image tokens scale with pixel
area, and past roughly 2700 of them this model stops transcribing and
begins confabulating: fluent text with no relation to the picture, and
nothing to signal it happened. An oversized image also poisons the child
process, so every later request returns garbage too. image_input caps
area to make both impossible; see MAX_PIXELS there for the measurements.
Modules§
- client
- Building and parsing the OpenAI-compatible
/v1/chat/completionsexchange. - config
- Configuration, read from the environment the MCP host provides.
- download
- Fetching the GLM-OCR weights, strictly opt-in.
- image_
input - Decoding and normalizing the
imagetool argument. - llama
- The real backend: a lazily spawned
llama-serverchild plus the HTTP call. - mcp
- Newline-delimited JSON-RPC over stdio.
- ocr
- The inference boundary.
- server
- Owning the
llama-serverchild process.