Linux: OpenCV never bundled into .mcpb — opencvLibDir() paths cannot match what extract.ts writes

[takusaito-ctrl]

Status: unverified — needs confirmation from someone with a Linux SDK zip.
This is a code-reading deduction, not an observed failure. Sony ships per-platform SDK zips and I only had CrSDK_v2.02.00_20260610a_Win64.zip, so I could not run the Linux path. Filing it because the Windows equivalent was confirmed and shipped a silently-broken bundle.

Context

While fixing the Windows OpenCV bundling bug (#31, PR #32), the same class of defect appears to exist on Linux. On Windows this was confirmed: pack:mcp printed OpenCV libs not found — assuming static/linked, omitted all four DLLs, and produced a .mcpb whose server died instantly with STATUS_DLL_NOT_FOUND — surfacing to users as "the MCP server won't auto-start."

The Windows cause was a mismatch between the path extract.ts writes and the path opencvLibDir() reads. macOS is fine. Linux looks like it has the same mismatch.

The mismatch

opencvLibDir() in cli/src/lib/mcp-build.ts requires one of these to exist as a directory:

[['Linux', 'Release', 'x64', 'lib'], ['Linux', 'Release', 'aarch64', 'lib']]

But extract.ts writes Linux OpenCV libs with:

opencv: [{
  fromRel: 'Linux',
  toRel: 'Linux',
  match: (f) => f.startsWith('libopencv_') && f.includes('.so'),
}]

and copyGlob is flat — readdirSync(srcDir) with no recursion, copying matched files directly into dstDir:

function copyGlob(srcDir, match, dstDir) {
  if (!existsSync(srcDir)) throw new Error(`missing expected SDK directory: ${srcDir}`);
  mkdirSync(dstDir, { recursive: true });
  let n = 0;
  for (const f of readdirSync(srcDir)) {
    if (match(f)) { copyFileSync(join(srcDir, f), join(dstDir, f)); n++; }
  }
  return n;
}

So the only directory the extractor can ever create here is shared/opencv/Linux/, with libs sitting flat inside it. Nothing in the extract path ever creates Linux/Release/x64/lib or Linux/Release/aarch64/lib, so existsSync() fails on both candidates, opencvLibDir() returns null, and pack:mcp takes the silent "assuming static/linked" branch.

Compare: why macOS is fine

macOS works because fromRel === toRel === 'Darwin/Release/macos/bin', and opencvLibDir()'s darwin candidate is that same string. They match by construction. Windows broke precisely because the two strings disagreed. Linux disagrees in the same way.

Two possible outcomes, both bad

Depending on how the Linux SDK zip is laid out under external/opencv/Linux/:

1. Libs flat in Linux/ — they extract fine to shared/opencv/Linux/, but opencvLibDir() never finds them → OpenCV silently omitted from the .mcpb, same end result as the Windows bug.
2. Libs nested (e.g. Linux/Release/x64/lib/) — as the Windows zip nests them (Windows/x86_64/Release/bin) — then the flat copyGlob sees only subdirectory names, match() rejects all of them, and it copies zero files while returning success. OpenCV is then missing from shared/ entirely, not just from the bundle.

Case 2 would also mean crsdk build on Linux relies on OpenCV coming from somewhere else (system package?), which would mask the extraction doing nothing.

What would confirm it

On Linux, after crsdk install --zip <linux-sdk.zip>:

find shared/opencv -name 'libopencv_*' | head
ls shared/opencv/Linux/

• If libs are flat in shared/opencv/Linux/ → case 1, opencvLibDir() needs ['Linux'] as a candidate.
• If that directory is empty → case 2, copyGlob/fromRel needs the real nested path.
• Then crsdk pack:mcp and check whether it prints OpenCV libs not found — assuming static/linked.

Also worth checking whether the built CameraWebApp on Linux actually has libopencv_* in its NEEDED entries (readelf -d CameraWebApp | grep NEEDED), which determines whether a missing lib is fatal at spawn as it is on Windows.

I did not blind-fix this, since the correct path depends on a layout I can't observe.

Related: the silent fallback

Underlying both this and #31: pack:mcp treats "OpenCV directory not found" as assuming static/linked and proceeds. That converts a missing-file bug into a broken artifact that only fails on the end user's machine, with no output from the dying process. Making that a hard failure (at least where OpenCV is known to be dynamically linked) would have caught the Windows bug at pack time instead of at connect time.

Happy to follow up with a PR once someone can confirm the actual Linux layout.

[takusaito-ctrl]

Confirmed on hardware — and it is outcome 1

Environment: linux-arm64 (Raspberry Pi, kernel 6.8.0-1051-raspi) · CrSDK_v2.02.00_20260610a_Linux64ARMv8.zip · Claude Desktop with the .mcpb installed.

The open question in this issue was which of the two outcomes applies. I had the Linux SDK zip, so here is the answer.

1. The SDK ships the libs flat — so extraction works

Inside the nested RemoteCli.zip:

external/opencv/Linux/libopencv_imgcodecs.so.408
external/opencv/Linux/libopencv_imgproc.so.408
external/opencv/Linux/libopencv_highgui.so.408
external/opencv/Linux/libopencv_core.so.408

Flat, exactly as copyGlob expects. So outcome 1, the milder branch — extract.ts copies all four correctly:

shared/opencv/Linux/libopencv_core.so.408
shared/opencv/Linux/libopencv_highgui.so.408
shared/opencv/Linux/libopencv_imgcodecs.so.408
shared/opencv/Linux/libopencv_imgproc.so.408

Outcome 2 (zero files copied) does not occur on Linux.

2. opencvLibDir() misses, exactly as predicted

Both candidates are absent:

MISSING: shared/opencv/Linux/Release/x64/lib
MISSING: shared/opencv/Linux/Release/aarch64/lib

→ returns null → pack:mcp takes the silent "assuming static/linked" branch.

3. The shipped .mcpb contains no OpenCV

$ unzip -l alpha-camera.mcpb | grep -i opencv
>>> NO OpenCV libs in bundle <<<

It bundles server/CameraWebApp plus all seven Sony libs (libCr_Core.so, CrAdapter/*, libmonitor_protocol*.so) and not one libopencv_*.

4. Why it still appeared to work — a second, independent bug

The bundle runs fine on the build machine, which makes this easy to mis-clear as a non-issue. The binary's RUNPATH has the developer's source tree baked in:

RUNPATH  $ORIGIN:/home/<user>/Desktop/Github/alpha-sdk-api/shared/sdk/lib:
                 /home/<user>/Desktop/Github/alpha-sdk-api/shared/opencv/Linux:

$ORIGIN has no OpenCV, so the loader falls through to the absolute path and finds it in the git checkout. Confirmed on the live process spawned by a real MCP tool call:

PID 64919
  exe: ~/.config/Claude/Claude Extensions/local.mcpb.alpha-camera.alpha-camera/server/CameraWebApp
  opencv mapped from:
    /home/<user>/Desktop/Github/alpha-sdk-api/shared/opencv/Linux/libopencv_core.so.408
    /home/<user>/Desktop/Github/alpha-sdk-api/shared/opencv/Linux/libopencv_imgcodecs.so.408
    /home/<user>/Desktop/Github/alpha-sdk-api/shared/opencv/Linux/libopencv_imgproc.so.408

The installed extension is reaching outside itself into the source tree. Every MCP tool worked in this state — that is a false negative, not evidence the bundle is sound. There is also no system OpenCV on this host (/usr/lib/aarch64-linux-gnu has none), so on a clean machine there is no fallback.

Note the second masking path: ServerManager.start() returns early if anything answers /api/server/status (server-manager.ts:42-51, 60). If a source-built server is already on the port, the bundled binary is never executed at all.

5. The actual symptom

Reproduced by rewriting only the dev-path prefix in a copy of the bundled binary (same byte length, offsets preserved) to simulate a clean machine:

./CameraWebApp: error while loading shared libraries:
libopencv_core.so.408: cannot open shared object file: No such file or directory
>>> exit code: 127

The three OpenCV libs are hard DT_NEEDED entries, so this fails in the loader before main(). The symptom is therefore not "OSD rendering breaks" — the server never starts and every camera tool fails.

Through the MCP layer: spawn() succeeds (the file exists and is executable), so the error handler at server-manager.ts:92 never fires. The child dies instantly, on("exit") nulls this.child, and awaitReady() throws at line 103:

camera-server exited during startup. Last output: ./CameraWebApp: error while
loading shared libraries: libopencv_core.so.408: cannot open shared object file:
No such file or directory

To the credit of the current code, that message is genuinely diagnostic — stderr is captured at line 86 and folded in by tail(). Unlike the Windows case this will not be a silent mystery. It is also fully deterministic, not intermittent.

Suggested fixes

1. Make opencvLibDir()'s Linux candidate ['Linux'], matching what extract.ts writes — the same by-construction agreement macOS already has.
2. Add a guard so pack:mcp cannot silently ship a bundle whose binary has a libopencv_* DT_NEEDED with no matching lib staged. The "assuming static/linked" branch should be reachable only when nothing needs OpenCV dynamically.
3. Strip the absolute developer paths from RUNPATH for redistributable builds — $ORIGIN alone should suffice, since the Sony libs already sit next to the binary in the bundle. Worth its own issue; it will keep masking this class of failure on any build machine.

[jordlee]

Fix implemented locally (not yet a PR) — and the silent fallback is closed too

Confirming the path mismatch independently on main @ 53333ef:

• cli/src/lib/mcp-build.ts:82-93 — Linux candidates are Linux/Release/x64/lib and Linux/Release/aarch64/lib.
• cli/src/lib/extract.ts:72-83 — linuxSpec() uses fromRel: 'Linux', toRel: 'Linux', and copyGlob is non-recursive.

The only directory the extractor can create is shared/opencv/Linux/, so the two can never agree — matching the hardware confirmation of outcome 1 above.

What I changed

1. ['Linux'] added as the first Linux candidate, with a comment stating the coupling to extract.ts (the Windows branch already carries one; Linux did not).
2. The silent fallback is gone. pack:mcp now reads the staged binary's own dynamic dependencies and fails if any OpenCV module it needs was not staged. Dependency names are read directly out of the binary (DT_NEEDED / LC_LOAD_DYLIB / PE import table are plain strings) rather than shelling out to readelf/otool/dumpbin, so it works on all three platforms with no toolchain assumption, and comparison is on the module name (core, imgproc, …) so library versioning cannot cause a false failure. Deliberately independent of RPATH — what the binary needs is the honest question, and RUNPATH is exactly what has been hiding the answer.
3. RUNPATH on the staged Linux copy is reset to $ORIGIN via patchelf, best-effort with a warning if patchelf is absent. This only touches the redistributable copy, so the dev build keeps the convenient rpath. Point 2 is the real guarantee; this just stops build machines being false negatives.

printKV no longer prints not found — assuming static/linked. It now reports either none needed — statically linked (backed by the binary) or 4 staged for 4 needed (core, highgui, imgcodecs, imgproc).

Verification

macOS (real): crsdk pack:mcp succeeds; detection matches otool -L exactly (4/4 modules, no false positives); the .mcpb contains all four dylibs. The previously working platform is unaffected.

Linux (simulated only): against a tree laid out the way linuxSpec() writes it (flat shared/opencv/Linux/libopencv_*.so.408) plus a binary carrying those DT_NEEDED strings — old candidates → null → silent ship (the bug); new candidates → directory found, libs staged, gate passes. With the libs removed, the gate fails instead of shipping.

What still needs a Linux host

I do not have one, so the following are unverified: that crsdk install --zip <linux-sdk.zip> populates shared/opencv/Linux/ as the confirmation above found; that patchelf behaves as expected on the produced binary; and the clean-machine end-to-end (no source tree, no system OpenCV) that is the only environment which genuinely tests this — as noted above, every build machine is a false negative.

Happy to open the PR, or to hand the patch to whoever has the Pi if you would rather it be validated on hardware before it lands.

[jordlee]

Superseded by #51 — my earlier comment described a fix I had written locally, but #51 does the same thing and is verified on real Linux hardware where mine was only simulated on macOS. I've dropped my commit from #54 so there is no competing implementation; #54 now touches no file that #51 or #53 touch.

The RUNPATH point from my comment is better handled by #52/#53 than by what I had (a patchelf call on the staged copy — that papers over the cause, where #53 fixes it in CMake).

Left one optional refinement on #51: its linksOpenCv() guard is a boolean, so it catches "zero OpenCV staged" but not partial staging — 3 of 4 libs present still ships a binary with an unsatisfied DT_NEEDED. Comparing per module name closes that; details and a verified snippet are in the PR comment.