documentation for remote MCP access

scripts/README.md

@@ -13,6 +13,16 @@ This file is generated from `scripts/catalog.json`.
 
 ---
 
+## Docs
+
+### mcp-http-howto.md
+
+HTTP MCP endpoints and usage notes for controlling imagej-elphel via MCP.
+
+Path: `scripts/mcp-http-howto.md`
+
+---
+
 ## mcp_filter_list_by_model_version.py
 
 Filter a .list file to keep only sequences with an existing model version subdir.

scripts/catalog.json

 {
   "version": 1,
+  "docs": [
+    {
+      "name": "mcp-http-howto.md",
+      "path": "scripts/mcp-http-howto.md",
+      "purpose": "HTTP MCP endpoints and usage notes for controlling imagej-elphel via MCP."
+    }
+  ],
   "scripts": [
     {
       "name": "mcp_filter_list_by_model_version.py",

scripts/catalog_to_md.py

@@ -27,6 +27,22 @@ lines = [
     "",
 ]
 
+docs = data.get("docs", [])
+if docs:
+    lines.append("## Docs")
+    lines.append("")
+    for d in docs:
+        lines.append(f"### {d.get('name')}")
+        lines.append("")
+        if d.get("purpose"):
+            lines.append(d["purpose"])
+            lines.append("")
+        if d.get("path"):
+            lines.append(f"Path: `{d['path']}`")
+            lines.append("")
+    lines.append("---")
+    lines.append("")
+
 for s in data.get("scripts", []):
     lines.append(f"## {s.get('name')}")
     lines.append("")

scripts/mcp-http-howto.md

+# MCP HTTP quick how-to (imagej-elphel)
+
+This is a minimal HTTP interface for interacting with the GUI logic without blocking dialogs.
+The MCP server runs **inside the ImageJ JVM**, so it starts/stops with the plugin.
+
+## Start
+The server auto-starts when `Eyesis_Correction` runs.
+
+Default:
+- URL: `http://127.0.0.1:48888`
+
+Optional JVM system properties:
+- `-Delphel.mcp.port=PORT` (override port, default 48888)
+- `-Delphel.mcp.mode=true|false` (enable/disable MCP dialog mode; default true)
+- `-Delphel.mcp.dialogTimeoutMs=30000` (MCP dialog submit wait; 0 = wait forever)
+- `-Delphel.slf4j.level=ERROR|WARN|INFO|DEBUG|TRACE` (override SLF4J/logback + JUL root level to reduce OME/Bio-Formats noise)
+- `-Delphel.mcp.allowed.config=/path/to/config.corr-xml` (enable MCP file access rooted from list in config)
+- `-Delphel.mcp.allowed.configdir=/path/to/configs` (allow any `*.corr-xml` in this directory)
+- `-Delphel.mcp.allowed.extra=/path/a,/path/b` (comma/semicolon-separated extra allowed roots)
+
+If `mcp.mode=false`, dialogs behave normally (GUI dialogs appear).
+
+## Endpoints
+
+### 1) Status
+```
+curl http://127.0.0.1:48888/mcp/status
+```
+Response (example):
+```
+{"running":false,"stopRequested":0,"confirmPending":false,"confirmConvenient":false,"buttonLabel":""}
+```
+
+### 2) Current dialog schema
+```
+curl http://127.0.0.1:48888/mcp/dialog
+```
+Response (example):
+```
+{"ok":true,"dialog":{"id":"...","title":"Set CLT parameters","fields":[...]} }
+```
+Each field includes:
+- `type`: message | boolean | number | string | choice
+- `label`: dialog label string
+- `tab`: tab name
+- `tooltip`: original tooltip
+- `units`: numeric units (if any)
+- `default`: default value as string
+- `choices`: for choice fields
+
+### 3) Set a dialog value
+Set by **label** (labels must match exactly):
+```
+curl -X POST -d "label=Nominal (rectilinear) disparity between side of square cameras (pix)&value=12.5" \
+  http://127.0.0.1:48888/mcp/dialog/values
+```
+Notes:
+- Values are strings; numeric/boolean are parsed by the code.
+- For choice fields, `value` can be an index (`0`, `1`, ...) or the exact choice text.
+- If you open multiple dialogs, include the dialog `id` from `/mcp/dialog` to avoid cross-talk.
+
+### 3b) Submit dialog (MCP “OK/Cancel”)
+After setting values, submit the dialog:
+```
+curl -X POST -d "ok=1" http://127.0.0.1:48888/mcp/dialog/submit
+```
+Use `ok=0` to cancel.
+
+With dialog id:
+```
+curl -X POST -d "id=...&ok=1" http://127.0.0.1:48888/mcp/dialog/submit
+```
+
+### 3a) MCP file selection (Restore/Save)
+Some file pickers use MCP instead of the Swing file chooser when MCP mode is enabled. In that case a single string field
+is exposed via `/mcp/dialog` with label `Selected path`. Provide it like this:
+```
+curl -X POST -d "label=Selected path&value=/path/to/file.corr-xml" \
+  http://127.0.0.1:48888/mcp/dialog/values
+```
+
+For multi-select pickers, the field label is `Selected paths`. Use comma or newline separated paths:
+```
+curl -X POST -d "label=Selected paths&value=/path/a.tif,/path/b.tif" \
+  http://127.0.0.1:48888/mcp/dialog/values
+```
+
+### 4) Trigger any button
+```
+curl -X POST -d "label=Setup CLT parameters" http://127.0.0.1:48888/mcp/button
+```
+This uses the same label as the GUI button.
+
+### 5) Interrupt long-running commands
+Request a stop (confirm=1 means pause and wait for confirmation):
+```
+curl -X POST -d "confirm=1&asap=0" http://127.0.0.1:48888/mcp/interrupt
+```
+
+Confirm or cancel a pending stop:
+```
+curl -X POST -d "stop=1" http://127.0.0.1:48888/mcp/interrupt/confirm
+curl -X POST -d "stop=0" http://127.0.0.1:48888/mcp/interrupt/confirm
+```
+
+### 6) Read-only file access (allowed roots only)
+Get allowed roots:
+```
+curl "http://127.0.0.1:48888/mcp/fs/roots"
+```
+
+List directory:
+```
+curl "http://127.0.0.1:48888/mcp/fs/list?path=/media/elphel/btrfs-data/lwir16-proc/NC"
+```
+
+Read file slice:
+```
+curl "http://127.0.0.1:48888/mcp/fs/read?path=/path/to/file.log&offset=0&maxBytes=16384"
+```
+
+Head/tail:
+```
+curl "http://127.0.0.1:48888/mcp/fs/head?path=/path/to/file.log&lines=50"
+curl "http://127.0.0.1:48888/mcp/fs/tail?path=/path/to/file.log&lines=50"
+```
+
+Glob (within allowed roots):
+```
+curl "http://127.0.0.1:48888/mcp/fs/glob?pattern=**/*-SYSTEM_OUT.log&max=200"
+```
+
+Read a single column from a delimited file (1-based column index, default tab):
+```
+curl "http://127.0.0.1:48888/mcp/fs/csvcol?path=/path/to/file.csv&col=3"
+curl "http://127.0.0.1:48888/mcp/fs/csvcol?path=/path/to/file.csv&col=3&sep=,"
+```
+
+Example (config directory):
+```
+-Delphel.mcp.allowed.configdir=/media/elphel/btrfs-data/lwir16-proc/NC/config
+```
+
+Note: list parsing currently calls `getSourceSets(...)`, which has `mkdirs()` side-effects (marked with `// codex 2026-01-28`).
+If you want MCP to be strictly read-only, consider removing or guarding those `mkdirs()` calls.
+
+## Behavior notes
+- MCP dialogs **do not block** in this version. If MCP doesn’t set a value, defaults are used.
+- `Abort` and `Stop` labels are handled specially (set stopRequested).
+
+## Troubleshooting
+- If a dialog field isn’t found, check the exact label in `/mcp/dialog` output.
+- If the server doesn’t respond, verify the plugin is running and the port is open.
+
+## Forward plan (single host → multi-host)
+- **Single host first**: keep MCP local and use it to supervise runs and inspect outputs.
+- **Health checks**: add a small run‑state file (timestamp, last scene, ok/error) and/or MCP status summary.
+- **Work units**: define a scene‑level boundary so each unit is independent and outputs don’t conflict.
+- **Idempotent commands**: prefer “process scene X with config Y” so retries are safe.
+- **Distributed later**: add a lightweight work queue or task‑stealing in the program; MCP stays for monitoring each host.
+- **Supervision**: codex can watch CSV/log indicators and stop/restart on anomalies.
+
+## Notes: mkdirs side-effects in list parsing
+`EyesisCorrectionParameters.CorrectionParameters.getSourceSets(...)` creates directories as part of parsing.
+These calls were marked with `// codex 2026-01-28`:
+- `rootDirectory` resolved base dir `mkdirs()`
+- `sourceDirectory` `mkdirs()`
+- per-`KEY_DIRS` (linkedModels, linkedCenters, videoDirectory, x3dDirectory, resultsDirectory, cuasSeedDir) `mkdirs()`
+
+If you want to remove side-effects for MCP-only parsing, consider guarding or removing those `mkdirs()` calls.
+
+## Quick test sequence (minimal MCP flow)
+
+1) **Start in MCP mode**
+   - In Eclipse VM args, remove `-Delphel.mcp.mode=false` (or set `-Delphel.mcp.mode=true`).
+
+2) **Check server is up**
+```
+curl http://127.0.0.1:48888/mcp/status
+```
+
+3) **Trigger a dialog**
+   Use MCP to click a button that normally opens a dialog (example):
+```
+curl -X POST -d "label=Setup CLT parameters" http://127.0.0.1:48888/mcp/button
+```
+   In MCP mode, no GUI dialog appears; schema should be published.
+
+4) **Fetch dialog schema**
+```
+curl http://127.0.0.1:48888/mcp/dialog
+```
+
+5) **Set a value by label**
+```
+curl -X POST -d "label=Nominal (rectilinear) disparity between side of square cameras (pix)&value=12.5" \
+  http://127.0.0.1:48888/mcp/dialog/values
+```
+
+6) **Run a command**
+```
+curl -X POST -d "label=CLT batch process" http://127.0.0.1:48888/mcp/button
+```
+
+If a value does not take, re-check exact label text via `/mcp/dialog`.
+- `-Delphel.ome.singleton=true|false` (toggle OMEXMLService singleton reuse; default false)