check_staging: return staged image inline in Claude chat (MCP image content block) alongside the download URL

[LarryWalkerDEV]

Context

All 4 registered tools return text-only. When staging completes, the client gets a URL string but never sees the image in the Claude Cowork conversation. The inline pattern already exists in this repo — the UNREGISTERED src/tools/floor-plan.ts:75-86 fetches the result and returns {type:'image', data, mimeType} via fetchImageAsBase64. Apply that pattern to check_staging.

Acceptance criteria

• When a staging job is completed, check_staging returns content [{type:'image', data:<base64>, mimeType:'image/jpeg'}, {type:'text', text:'Fertig! Download: <url>...'}] — inline preview PLUS the existing URL text.
• Preview payload budget: base64 data ≤ ~1 MB. If the original exceeds it, fetch a downscaled variant instead of the full-res file (Supabase Storage image-transform URL ?width=1024 on the render/image endpoint, or an app-provided thumbnail URL — builder's choice, but the budget is the gate).
• If the image fetch fails, degrade gracefully to today's text-only response (never fail the tool because the preview failed).
• In-progress and failed states unchanged (text-only).
• Test: unit test with a mocked completed-status app response asserting the content array contains an image block + text block; mocked fetch-failure asserts text-only fallback.
• npx tsc --noEmit exits 0.

Guardrails

German user-facing text. Do not register the deferred Phase-F tools as part of this work.

[LarryWalkerDEV]

ACCEPTANCE GATE ADDITION (applies to every review iteration of this issue): the final reviewer must judge the result through the eyes of a German Immobilienmakler (real-estate agent, DACH market, pays for this product): Would this person accept the output for their own listing and send it to their seller? Correct professional German (Sie-Form, no anglicisms, no truncated umlauts), correct prices/units (€, m², Zimmer), and visually presentable results. If the answer is "no" or "borderline" → NOT approved → iterate (max 3 iterations, then leave open with the Makler-objection listed). This gate is IN ADDITION to the mechanical criteria, not instead of them.

[LarryWalkerDEV]

Iteration 1 — build complete (two-part)

Part 1 — mcp-immostage (branch fix/issue-3-inline-image, commit 27900d7)

• src/tools/check-staging.ts: completed branch only — fetches the download URL via existing fetchImageAsBase64 and returns [{type:'image', data, mimeType}, {type:'text', text:'Fertig! Download: <url>'}] (image FIRST). Null fetch → byte-identical text-only fallback. In-progress/failed branches untouched (diff shows only the completed branch changed).
• src/tools/check-staging.test.ts (first test file in repo, TDD — new case failed before impl): 4 handler cases — image ok (order + mimeType + German text asserted), fetch-null → text-only no isError, processing, failed+isError.
• npm test: 4/4 passed. npx tsc --noEmit: exit 0. server.ts: zero new registrations (Phase-F tools stay unregistered).
• ponytail comment added: preview relies on app returning <=800KB Supabase JPEGs; ceiling = raw kie URLs degrade to text-only; upgrade = pure-JS resize in this repo.

Part 2 — immoapp (master, commit 77672727)

• src/app/api/mcp/status/route.ts only (webhook route untouched): both completed paths persist non-Supabase URLs via the wizard pipeline (fetchAndAddMetadata + applyAiLabel) → public staged bucket at mcp/<tenantId>/staged-<jobId>.jpg, staging_jobs.output_image_url updated to the durable URL; try/catch falls back to raw kie URL so polling never fails.
• npm run build: exit 0. Existing src/app/api/mcp/__tests__/stage-route.test.ts: 2/2 passed.

Live verification (real job, local prod server against prod DB)

• Job f19fd329-5336-4673-b231-9549d3ca228f (E2E tenant) had raw tempfile.aiquickdraw.com PNG, measured 1,940,238 bytes — the verified failure mode (fetchImageAsBase64 → null).
• After the new route: downloadUrl = .../staged/mcp/b945690a-.../staged-f19fd329-....jpg — JPEG 253,668 bytes → base64 338,224 chars (well under ~1,070,000 budget), fetchImageAsBase64 non-null.
• DB persisted; second poll short-circuits to the Supabase URL.
• Visual check of persisted JPEG: crisp 3:2 staged kitchen, furniture staging clearly recognizable, German 'AI bearbeitet' label bottom-left (wizard channel parity). Visual score 9/10.

Temporary MCP verify key deleted after test; local server stopped.

[LarryWalkerDEV]

Iteration 1 — gate results

• tester.allPass: true
• reviewer.approved: true
• compliance.compliant: true
• violations: []
• complianceViolations:
  • Advisory (deploy prerequisite, not a code defect): immoapp commit 77672727 (Part 2 persist logic) is on local master only — origin/master is still at 14aa7b49 — and the mcp branch fix/issue-3-inline-image is unmerged. Expected at pre-merge review stage, but until both are pushed/deployed, NEW production MCP jobs still return raw tempfile.aiquickdraw.com URLs and the preview degrades to text-only (the exact failure mode the playbook warns about). Merge + push both repos to go live.

[LarryWalkerDEV]

Closing summary (verified merge-ready — awaiting merge, issue stays open until merged)

What was done: check_staging now returns the staged image as an inline MCP image content block (image first, then the unchanged German download text), and the immoapp /api/mcp/status route persists kie.ai results through the wizard's existing fetchAndAddMetadata + applyAiLabel pipeline into the public Supabase staged bucket (mcp-immostage branch fix/issue-3-inline-image @ 27900d7; immoapp local master @ 77672727). This was necessary because every real MCP staging output measured today is a 1.77–2.08 MB PNG on kie's tempfile host — above the fetcher's hard cap — so without the app-side re-upload the "graceful degrade" would have silently masked a feature that never fires. The result: the Makler sees the staged room directly in Claude chat the instant polling completes (verified live: 1.94 MB tempfile PNG → 253 KB labeled Supabase JPEG, inline preview renders, visual score 9/10), with a durable download URL and AI labeling matching the app channel.

Status: All gates green (tests 4/4, tsc clean, build exit 0, live verification passed, Makler-gate approved). Merge-ready, awaiting merge of both parts: mcp-immostage fix/issue-3-inline-image and immoapp local master 77672727 (origin/master still at 14aa7b49). Until both ship, new production jobs still degrade to text-only.

---

Research critic — 10x opportunities (follow-up visibility)

1. IMPLEMENTED (this pass): Fix three problems with one change — re-upload the kie result to the Supabase staged bucket in /api/mcp/status (reusing the wizard's fetchAndAddMetadata + applyAiLabel pipeline), which simultaneously (a) makes the inline preview actually work (JPEG 137–349 KB fits the 800 KB budget with zero resize logic), (b) makes the Makler's download link durable instead of a temp-host URL, (c) delivers AI-labeled images through the MCP channel, matching the app's EU-AI-Act/portal-marking posture. The 10x move the research missed — turns a cosmetic preview feature into channel parity.
2. IMPLEMENTED (this pass): Image-first ordering (per AC) — the Makler sees the staged room the instant the poll completes, so the agent can immediately comment on the result ("Wohnzimmer im Skandi-Stil, gefällt Ihnen das?") instead of narrating a URL. The exact existing German string was preserved so nothing else changed.
3. IMPLEMENTED (this pass): The first test file in the repo sets the testing pattern for all future mcp-immostage work — a dependency-free stub of McpServer ({ tool: vi.fn() }) that captures the registered handler, reusable for every other tool test.
4. DEFERRED (intentionally, for a follow-up issue): Once previews work, a before/after pair (original + staged as two image blocks) is the natural next step for the sales-demo moment in chat. Not built in this pass.

Research critic — surprising angles

• The resize-param retry chain in the "reuse directly" helper is dead code for this feature: kie's tempfile host ignores ?w/?width/?quality entirely (verified by HEAD: identical content-length with and without params), and Supabase object/public URLs ignore them too. The helper only ever succeeds when the ORIGINAL file is small enough — which is exactly why the fix belongs on the app side (make the file small), not in the fetcher. (Informed the chosen architecture.)
• A mocked-test-green, tsc-clean, AC-compliant build of this issue would ship a feature that never fires: every real MCP staging output measured today is a 1.77–2.08 MB PNG above the fetcher's hard cap. The graceful-degrade requirement ("never fail the tool") is precisely what would mask the total failure. (Caught and addressed via live verification against a real job.)
• The wizard already solved this whole problem (PNG → labeled JPEG → public bucket, outputs measured at 137–349 KB) — the "already in this codebase" ponytail rung points at src/app/api/wizard/poll/route.ts, in the OTHER repo. The two-repo split (mcp-immostage vs immoapp) is why nobody connected them. (Exploited in this pass.)
• The MCP channel was delivering unlabeled AI-staged images while the app channel labels them — a silent compliance fork between two doors into the same product. (RESOLVED by this pass: MCP outputs now carry the "AI bearbeitet" label.)