Integration guide for
imaging services.

01 / ARCHITECTURE

Architecture and processing components

The institution prepares images on a workstation. A recipient opens the resulting self-contained HTML in a current browser. Local AI inference and the MCP service are separate workstation processes.

No viewer installation is required for a recipient. Python and the optional model runtime do require installation on the processing workstation. Test the browser capabilities and your managed desktops before delivery.

02 / SOURCE & INSTALLATION

Source installation and demonstration

The public repository URL has not been assigned for this release. Maintainer source profile ↗

The commands below are for macOS/Linux; the viewer itself is browser-based.

git clone REPOSITORY_URL mri-preread
cd mri-preread
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dicom-compressed]"
python3 -m http.server 8080 --bind 127.0.0.1 --directory site

Open http://127.0.0.1:8080/demo/. The bundled demo uses brain-masked T1 and FLAIR images from the CC0 OpenNeuro ds007401 dataset. Try measurements, notes, segmentation and JSON export. See its provenance and rebuild instructions.

py -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dicom-compressed]"
.venv\Scripts\mri-preread.exe extract "C:\path\to\export" data\pilot-study

Pin the repository commit and record pip freeze for your pilot. A viewer demo is a usability check, not a clinical evaluation.

03 / IMAGE PREPARATION

Prepare a brain MRI study

.venv/bin/mri-preread extract "/path/to/completed-export" data/pilot-study
# Check series.json and correct roles.json before continuing.
.venv/bin/mri-preread analyze data/pilot-study
.venv/bin/mri-preread build data/pilot-study

Keep one patient/study per input. The extractor groups classic DICOM series; compressed syntax decoders are optional dependencies. The watcher rejects enhanced multi-frame MRI. Verify sequence roles — T1, T2, FLAIR, SWI, DWI and ADC — against the actual acquisition, then inspect orientation, registration and image coverage.

.venv/bin/mri-preread import data/pilot-study \
  --flair "/path/to/flair.nii.gz" \
  --dwi "/path/to/dwi.nii.gz" \
  --adc "/path/to/adc.nii.gz"
.venv/bin/mri-preread analyze data/pilot-study
.venv/bin/mri-preread build data/pilot-study

The build produces data/pilot-study/brain_viewer.html. Statistical maps come from the analysis command, independently of a language model. Role guesses, ADC normalization and registration fallback need visual verification. Retain the original DICOM for authoritative interpretation; the browser uses prepared/downsampled arrays.

04 / IMAGE DELIVERY

Deliver through an institutional portal

Host the prepared HTML through your authenticated patient or clinician portal, or use an institution-approved sharing route. No Python server is needed to open that file. Set Content-Type: text/html; charset=utf-8; a gzip upload also needs Content-Encoding: gzip.

The current viewer embeds scripts and data images. Check your portal Content Security Policy; use a controlled route or adapt its script hashes/nonces without relaxing the whole portal policy. Authentication and authorization must cover both the page and underlying object storage.

Where a doctor's notes live

Clinician notes and masks save in IndexedDB in that browser, bound to the scan's reference content and affine. Export JSON to share or back up; import adds annotations to the same scan. These drafts do not synchronize across doctors, write back to PACS or establish authenticated authorship. An institutional record workflow needs central storage, identity, sign-off and audit integration.

Mask JSON uses lossless reference-grid voxel runs with an affine. It is not DICOM SEG/SR or a NIfTI export. Any clinical conversion needs explicit source-geometry mapping and verification.

05 / MCP

MCP tool configuration

Copy .mcp.json.example into the config location used by your MCP client and replace the executable/study paths. The client spawns one stdio process for one analyzed study.

{
  "mcpServers": {
    "mri-preread": {
      "command": "/absolute/path/mri-preread/.venv/bin/mri-preread",
      "args": ["serve", "/absolute/path/to/analyzed-study"]
    }
  }
}

Start with get_study_overview, then view_overview, view_region and region_stats. A model can compare mirrored evidence, move viewer focus or write MCP annotations. rebuild_standalone_viewer embeds those MCP annotations for later delivery.

The live viewer helper runs at http://127.0.0.1:8765/ while the stdio process is alive. For separate studies, use separate processes and set BRAIN_VIEWER_PORT to avoid listener collisions. This helper has no remote authentication or multi-tenant API. Keep it local.

06 / MODEL RUNTIMES

Model and runtime requirements

The viewer and MCP tools are independent of a particular inference device. Connect a compatible model through an MCP client or agent that can call tools and pass image results to a vision model. A model endpoint alone is not an MCP client. Text-only models can use metadata and statistics but cannot inspect MRI pixels.

llama-server -m /path/to/compatible-vision-model.gguf \
  --mmproj /path/to/matching-vision-projector.gguf \
  --host 127.0.0.1 --port 8082
# Configure your MCP-capable client to use this local model endpoint
# and the mri-preread stdio server from section 05.

Check the model format, vision encoder, runtime version and image handling together. These are external model-host integration paths, not newly implemented backends for the bundled mri-preread medgemma command.

MedGemma as a medical research model

MedGemma 1.5 4B is one multimodal option. It runs outside the browser, on hardware supported by the chosen runtime. Other compatible local or cloud models can use the same MCP tools. The repository also provides a fixed sampled-image MedGemma runner, with its installation, tested backend and reproducibility record described in the README and hardware guide.

That runner samples axial planes, renders aligned sequence images, and saves exact-input PNG hashes, prompts, responses, timing and model provenance. It does not produce automatic segmentation or inspect every voxel of the volume. Switching runtime or quantization requires a new evaluation.

Review the separate MedGemma terms. Model weights are not included in the source or website release.

07 / COMPLETED EXPORTS

Completed-export contract

Your existing scanner/PACS workflow supplies completed folders. A DICOM C-STORE receiver or DICOMweb client is not included. Write a .ready marker last, after every DICOM file has been written and closed. A folder that stops growing does not prove completeness.

incoming-dicom/
  study-opaque-id/
    series-a/...
    series-b/...
    roles.json   # optional verified extracted-series mapping
    .ready       # created LAST by the export integration

The integrated watcher uses the same extraction, analysis, viewer build and local MedGemma pipeline. Configure the bundled model backend according to the README first; select non-nested inbox/workspace paths writable on your processing workstation.

.venv/bin/mri-preread worklist \
  --inbox data/incoming-dicom \
  --workspace data/worklist \
  --model-dir models/medgemma-1.5-4b-it-4bit

Open http://127.0.0.1:8800/. The watcher checks study consistency, snapshots original DICOM, keeps durable job states, records failures and preserves technical warnings. It processes by receipt, and human review controls urgency. To use another inference runtime in the automatic queue, implement a worker adapter and evaluate its outputs. Viewer-only automation can call extract, analyze and build directly; the integrated watcher always invokes MedGemma.

08 / CAPACITY

Processing capacity and concurrency

A thousand DICOM images may be a few studies or many. Measure complete-export-to-viewer and complete-export-to-draft latency on representative protocols, not only model token generation. Record study dimensions, sequence count, sampled planes, memory/disk peaks, failures and recovery behavior.

The current watcher is single-worker and serial, and model weights load in each review process. Scaling requires an external durable queue, isolated study workspaces/workers, accelerator allocation, monitoring and backpressure. Viewer delivery can be decoupled from AI jobs. These are engineering extensions, not existing production controls.

Keep a pinned release and pilot environment record. An external NVIDIA or llama.cpp endpoint can be used by a compatible MCP client. Extending the included automatic-review worker to use that endpoint requires a separate inference adapter and evaluation.

09 / PILOT EVALUATION

Pilot evaluation and clinical boundaries

The repository includes a separate small point-based MCP feasibility benchmark and reproducible scoring scripts. Its findings cannot be transferred to this MedGemma configuration. Ten-millimetre sampling, small lesions, limited conditions and site variation remain key limits. The public MRI demo illustrates usability and does not provide lesion ground truth or measure accuracy.

1. Technical pilot: verify geometry, transfer syntaxes, sequence roles, image quality, measurement behavior and recovery using your protocols.
2. Retrospective evaluation: freeze predictions before expert reference access. Measure localization, missed lesions, false findings and exclusions across representative studies.
3. Reader assessment: test whether evidence-linked drafts and notes help clinicians, including time cost and misleading outputs.
4. AI shadow mode: keep the existing clinical queue and decisions authoritative. Have the institution evaluate intended use and operational/regulatory requirements before changing care.

Neither the application nor these research results establish a certified clinical product, reliable diagnosis or validated triage.

10 / SCOPE

Supported anatomy and integration gaps

The current asymmetry map mirrors the brain, aligns the hemispheres and compares local sequence intensities. Normal variation, artifacts and registration errors can create hotspots. Symmetric or diffuse changes may not be highlighted. Other anatomy needs a suitable mask, symmetry model and independent evaluation; do not apply the existing brain pipeline as a general MRI detector.

• No enhanced multi-frame MRI support in the watcher.
• No included PACS networking, DICOMweb, FHIR/HL7 write-back or DICOM SEG/SR export.
• No institution SSO, patient identity reconciliation, multi-tenancy or centralized clinician record.
• No validated diagnosis, urgency detector or high-volume performance guarantee.
• The bundled automatic review runner has a specific backend; other model hosts connect through an external MCP client or a new worker adapter.

Use the integration boundaries to scope a pilot and choose the parts you can adopt first. Contributions for tested adapters, data interoperability and model evaluation are welcome.

PUBLIC MRI / PROVENANCE

Public MRI provenance

The public demonstration, feature illustrations and MCP montage use T1w and FLAIR from OpenNeuro ds007401, IDEAS II, subject sub-4082, session 1. The publisher metadata specifies CC0. No private scan is used in these research assets. We selected two sequences, aligned and resampled them, removed outside-brain voxels and prepared browser display arrays. Brain masking is a display modification, not a general anonymization guarantee.

The four feature screenshots show actual viewer operations on this study. Written notes, rulers, ROIs and painted masks are demonstration actions, not expert lesion labels or AI findings. The MCP montage is an actual view_region response. No model prediction is embedded.

Image sources, authors, licensing and derivative records are listed in license.txt.

Credit does not imply dataset-author endorsement. Original NIfTIs stay outside the source and website packages. To reproduce the public viewer after installing the project:

.venv/bin/python examples/build_public_demo.py --download
# Verifies publisher SHA-256 keys before importing and preparing the scan.
# Rebuild invalidates the derivative manifest; review and reseal as documented.

See docs/open-demo.md in the source for full reproduction and screenshot capture instructions. Keep synthetic fixtures for regression tests; the public demo builder does not accept arbitrary private studies.

LICENSING & REFERENCES

Licensing and references

The application is MIT licensed, © 2026 Jordi Vallverdu. MedGemma weights are governed separately by Google's HAI-DEF terms; a community quantization does not make the weights MIT. Installation, workstation hardware, hosting and institutional integration still have costs. No subscription or licence fee is imposed by the application code.

• Google MedGemma 1.5 model card
• llama.cpp multimodal runtime documentation
• Health AI Developer Foundations terms
• Raspberry Pi AI HAT documentation
• Model Context Protocol documentation

Implementation and upstream sources reviewed 2 October 2026. See the repository README, hospital integration guide, hardware guide and contributor reference for details.