Checkbox detector
Read checkbox states and structured data out of scanned Test Request Forms using template-based pixel classification
Overview
The checkbox-detector integration reads scanned forms. It was built for TRF (Test Request Form) documents, where the useful signal is which boxes a person ticked rather than free text.
It works by template-based pixel classification. An administrator stores a template that annotates where each checkbox sits on the form. At run time the server compares the uploaded image against that template and reports each box's state. Because the checkbox reading is pixel comparison rather than a model's guess, the same form produces the same answer every time.
This is a template-driven integration, not a general-purpose OCR tool. It needs a stored template for the form layout you are processing. For general document text extraction, use file-tools or a vision model on an Agent node.
Capabilities
The checkbox-detector MCP server exposes two tools.
detect_checkboxes
Detect checkbox states in a TRF image using a pre-stored template of annotated checkbox positions. Use this when you only need the ticked boxes.
extract_trf
Extract all data from a TRF image in one call. Combines VLM-based extraction of the written fields with the same template-driven checkbox detection, so an agent gets both the typed or handwritten values and the box states from a single tool call.
Configuration
Checkbox detection is configured by an administrator and locked, so project members use it without touching its settings. It needs three things wired up:
- A vision model — base URL, model name, and API key, used by
extract_trfto read the written fields. - Object storage — endpoint, access key, secret key, and the bucket holding the annotated templates.
- A stored template — the annotated checkbox positions for the form layout you are processing.
Accuracy depends entirely on the template matching the form. A revised form layout, a different scan resolution, or a rotated page will misread boxes rather than fail loudly. Re-annotate the template whenever the form changes, and route low-confidence results to a person.
Use cases
Lab test intake
A scanned Test Request Form arrives as a workflow input. extract_trf returns the patient fields and the requested tests in one call, a Condition node routes anything incomplete, and the rest flows straight into the downstream system.
Human review on low confidence
Pair the detector with a Human Task node. Forms that read cleanly continue automatically; anything ambiguous goes to a reviewer with the scan attached.