# halcon-mcp — the HALCON MCP server

A local MCP server that exposes common HALCON algorithms + script runners as
tools, for driving HALCON experiments without hand-writing Python each time. It
lives at the **project root** (outside this skill): `halcon-mcp/`. Source of truth
is `halcon-mcp/README.md`; this file is the pointer from the skill.

## What it is

- Python + official `mcp` SDK (FastMCP), **stdio** transport.
- Runs **in-process** in the shared HALCON venv (`import halcon`), so algorithm
  tools call operators directly and return structured JSON + the **equivalent
  HDevelop code** + an **overlay PNG**.
- Errors return `{ok:false, error:...}` (no crash) so the model can self-correct.

## Tools (11)

Run/experiment: `halcon_check_env`, `halcon_run_script` (inline HDevelop snippet),
`halcon_run_program` (.hdev), `halcon_run_procedure` (.hdvp), `halcon_run_hrun`
(headless, GBK-decoded), `halcon_open_in_hdevelop` (GUI), `halcon_teach_roi`
(interactive pan/zoom/box-select ROI → `.hobj`, or headless via `box`; runs
`halcon-mcp/roi_picker.py` in a subprocess and returns the saved bbox).

Algorithms: `halcon_enhance_image`, `halcon_find_circles` (edge-fit + metrology,
same chain as `examples/find_circles.hdvp`), `halcon_measure_metrology`
(circle/line/rectangle2), `halcon_match_shape` (2D shape-based matching).

`halcon_teach_roi`'s output feeds `halcon_find_circles` / `halcon_match_shape` /
`halcon_measure_metrology` as their `roi_file` / `template_roi`.

## Prerequisite (one-time)

Add `mcp` to the shared venv (mvtec-halcon is already there):

```bash
/mnt/c/Users/NAURA/.local/bin/uv.exe pip install mcp
```

## Register in Claude Code (this WSL)

A ready config is at the project root as `.mcp.json` (copied from
`halcon-mcp/.mcp.json.example`). Or via CLI:

```bash
claude mcp add halcon -- /mnt/c/Users/NAURA/.local/bin/uv.exe run \
  --directory C:/workspace/agent-studio/halcon-001 python halcon-mcp/server.py
```

Then `/mcp` lists `halcon`. The server is a Windows process launched from WSL;
it speaks JSON-RPC over stdio across the interop boundary (verified working).

## Test without a client

```bash
/mnt/c/Users/NAURA/.local/bin/uv.exe run python halcon-mcp/examples/smoke_test.py
```

## Relationship to this skill

The skill is the **knowledge** (how to run HALCON here, the manuals, recipes);
the MCP server is the **executable surface** built from that knowledge. When a
task needs repeatable, parameterized calls (enhance / find circles / metrology /
matching / run a script), prefer the `halcon_*` MCP tools; for one-off custom
pipelines, use the skill's `scripts/` runners or write an `.hdvp`.