skills-market/plugins/halcon/references/remote-mcp.md

Remote HALCON over MCP (halcon-remote)

A remote HALCON compute service exposed as an MCP server. Use it when there is no local HALCON (e.g. MacOS, a plain Linux box, a colleague's machine) — it runs HALCON 24.11 on a headless Linux server and is reachable over the public internet. Client needs only network + a bearer token; no HALCON, no minio creds, no VPN/tailnet.

• Endpoint: https://halcon-mcp.totoro.studio/mcp (Streamable HTTP, Bearer auth)
• Token: server-side /opt/halcon-mcp/.env (HALCON_MCP_TOKEN); in configs reference ${HALCON_MCP_TOKEN}, never hardcode.
• Source/ops: repo halcon-mcp-remote/; server 192.168.1.13:/opt/halcon-mcp (systemd halcon-mcp). Full deploy facts: repo halcon-tools.yaml → halcon_mcp_remote.

Register the server (client side)

# user scope (works across all projects)
claude mcp add --scope user --transport http halcon-remote \
  https://halcon-mcp.totoro.studio/mcp --header "Authorization: Bearer $HALCON_MCP_TOKEN"
claude mcp list   # expect: halcon-remote ... ✔ Connected

Or project .mcp.json: { "type":"http", "url":".../mcp", "headers":{"Authorization":"Bearer ${HALCON_MCP_TOKEN}"} }.

Tools (full names: mcp__halcon-remote__<tool>)

Tool	Does	Key args
halcon_get_env	Self-check: version/hostid/arch	—
halcon_create_upload	Presigned PUT URL to upload one file (image or zip), no creds	filename, expires_minutes
halcon_find_circles	Subpixel find circles → list + preview	image or image_b64
halcon_measure_overlay	Bullseye overlay: Top/Bottom center deviation (µm)	image or image_b64, apply_registration
halcon_overlay_batch	Batch overlay over a minio prefix → CSV	prefix, max_images
halcon_find_circles_zip	Batch find circles: image zip → 4 ring-mark centers (TL/TR/BL/BR) → CSV	zip_key, min/max_radius
halcon_exec_hdev	Run an HDevelop script via hrun → stdout (destructive)	script_text

Image I/O — how images get in and results out

An image argument accepts one of:

• file:/abs/path — a file on the server (testing only; e.g. file:/tmp/amm_test/2-zuoshang.bmp).
• <key> — a minio object key in the default bucket halcon (e.g. inbox/die.png).
• minio://<bucket>/<key> — explicit bucket.

Or pass image_b64 (inline base64, may include data: prefix) — best for a single small image, no upload step.

Results: numeric metrics come back inline (structuredContent). Heavy artifacts (preview jpg, CSV) are uploaded to minio and returned as a key + presigned URL on the public host minio-home.totoro.studio (openable from anywhere). Small files (preview/CSV) — just GET the URL.

Three usage patterns (pick by size)

1. Single small image → inline (simplest).

halcon_measure_overlay(image_b64="<base64 of the bullseye image>")
→ {status:"ok", overlay_dX_um, overlay_dY_um, top/bottom centers, n_circles}

2. Single/few images from an external client → presigned PUT (no creds).

k = halcon_create_upload(filename="die.bmp")        # → {put_url, key}
curl -T die.bmp "<put_url>"                          # public PUT, no creds
halcon_measure_overlay(image=k.key)

3. Large batch (hundreds–thousands) → zip once, then process (recommended). Zip is the right move: one file = one upload = works with presigned PUT (external users too), vs mirroring many files (needs minio creds).

zip -0 -q -j batch.zip *.png                         # store mode (PNG already compressed)
k = halcon_create_upload(filename="batch.zip")
curl -T batch.zip "<k.put_url>"                       # one PUT
halcon_find_circles_zip(zip_key=k.key)               # server unzips + batch + CSV
→ {total, ok, seconds, per_image_ms, csv_key, csv_url}
# then GET csv_url

CSV columns: file,status,n_found,TL_col,TL_row,TL_r,TR_...,BL_...,BR_... (4 ring-mark centers per image, ordered by position).

D2W overlay conventions (this project's domain)

• Axes: X = image right +, Y = image up +; pixel size 271.048 nm/px; overlay = Bottom − Top.
• Mark grouping: outer thick ring = Top Die Mark; inner dot + mid ring = Bottom Die Mark.
• apply_registration=True adds the +13.5/+9.6 nm offset (0627-JC 2-point calibration; drop for other tools/batches).
• Sanity values (die-2 four corners, raw dev µm): TL −0.778/+0.794 · TR −0.265/+0.391 · BL −0.171/+1.022 · BR +0.230/+0.435.

Performance (measured, single HALCON process, 16 threads)

• find_circles on 5312×4608 (24MP): ~92 ms/image (~11 img/s). 1920 images ≈ 176 s compute.
• 90 MB zip public PUT: ~20 s. End-to-end 1920 images ≈ 3.3 min.
• Circle-center repeatability across 1920 shots: std 0.01–0.04 px.

Gotchas

• Sync execution. halcon_find_circles_zip / halcon_overlay_batch run synchronously. ~1920 images (~3 min) is near the comfortable ceiling — set a long client timeout. For much larger jobs, chunk or use async (not yet built).
• License SESSIONS=1 → cannot multi-process; rely on HALCON's internal 16-thread parallelization (already fast).
• Preview/CSV URLs use minio-home.totoro.studio (public), not the internal 192.168.1.2:9000 — openable off-LAN.
• Big batches: always zip (one PUT). Per-file create_upload for N files is N round-trips — only for a handful.
• file: paths are server-side, not the client's filesystem — only for images already on 192.168.1.13.
• Tool errors return isError + an actionable message (e.g. "先用 halcon_create_upload 传图") — read it and self-correct.