Lux3D MCP Server

This package is the authoritative implementation and release source for the Lux3D MCP. It exposes image-to-3D generation to Codex while delegating browser-authenticated Coohom API execution to the companion Executor page.

Repository boundary

Change this package when work affects:

• MCP tool names, input/output schemas, annotations, structured results, errors, or tool descriptions.
• prepare_workspace, _meta.threadId, executor_required, or task-specific executorUrl values.
• The shared loopback Broker, per-thread binding, page conflicts, request ownership, or MCP process restart recovery.
• stdio startup, package metadata, build output, or npm publishing.

Do not implement browser UI or authenticated page operations here. The companion Executor repository at i18n-fe/bim/ai-home/lux3d-mcp-server owns:

• The PUB page at /pub/tool/bim/ai-home/mcp-executor.
• Browser sign-in state and Coohom HTTP requests.
• Image upload, Credits payment UI, and balance lookup.
• Coohom iframe controls and connection-status UI.

The Codex plugin at i18n-fe/ai/coohom-freeform orchestrates this MCP with the Coohom Freeform MCP. It must consume the public contract without reimplementing the server or Executor.

Installation

Qunhe internal npm:

[mcp_servers.lux3d-mcp-server]
command = "npx"
args = ["-y", "@qunhe/lux3d-mcp-server@latest"]

[mcp_servers.lux3d-mcp-server.env]
npm_config_registry = "https://npm-registry.qunhequnhe.com/"

No Cookie, Authorization header, or site URL is configured in Codex. The user signs in through the Executor page.

Thread binding

The stdio server normally shares 127.0.0.1:18766 across Codex tasks:

• The first MCP process starts the local Broker; later processes reuse it.
• A tool request obtains the real Codex task ID from _meta.threadId. The server does not generate a replacement session ID.
• prepare_workspace returns the task-specific Executor URL with the matching codexThreadId.
• MCP and Executor connections bind only when their thread IDs match exactly.
• A second active Executor for the same thread receives PAGE_CONFLICT.
• Refreshing the matching page preserves its URL and reconnects after the previous socket closes.
• An MCP process restart can reconnect to the same page and thread without recreating the scene.
• Pending requests remain owned by their thread and are never silently transferred.

The Executor may run in the Codex browser, Chrome, or Safari, but it must run on the same computer as the MCP process to reach the loopback Broker.

Tools

prepare_workspace

Read-only and credit-free. Returns:

{
    "threadId": "codex-task-id",
    "status": "connected",
    "executorUrl": "https://www.coohom.com/pub/tool/bim/ai-home/mcp-executor?codexThreadId=codex-task-id"
}

When the matching Executor is not connected, status is executor_required. Open the returned URL unchanged and call prepare_workspace again after the page connects.

create_lux3d_model_task

Accepts exactly one HTTPS imageUrl or a PNG/JPEG/WEBP imageBase64 value and creates a Turbo / Lux3D G1 task. A successful submission returns { "taskId": "...", "status": "submitted" }.

If the Executor is not connected, the request is not forwarded and the tool returns the workspace result with status: "executor_required".

get_lux3d_model_task

Queries one generation task. Results distinguish queued, generating, archiving, succeeded, and failed. succeeded must include both generatedModelUrl and a nonempty obsBrandGoodId; missing either field is a protocol error.

archiving means model generation has completed but Coohom is still saving the asset. Poll every 3–5 seconds until a terminal status.

open_credits_payment

Opens the Credits payment dialog in the signed-in Executor after the user explicitly chooses to pay. { "opened": true } means only that the dialog opened; it does not claim that payment completed.

get_credits

Returns { "availableCredits": number } for the account signed in to the Executor. This balance is informational, may not include free generation allowances, and must not gate task creation. The result of create_lux3d_model_task is authoritative.

Recommended flow

1. Call prepare_workspace.
2. If it returns executor_required, open the complete executorUrl and wait for the matching page to connect.
3. Call prepare_workspace again and require connected.
4. Call create_lux3d_model_task.
5. Poll get_lux3d_model_task until succeeded or failed.

If task creation fails because Credits are insufficient, offer the user the workflow choices defined by the calling plugin. Only after the user chooses payment should the caller invoke open_credits_payment. The user completes payment in the browser and confirms completion to Codex. Codex may call get_credits to display the paid balance, but retries the original generation request once regardless of that number because free allowances are determined by the creation response.

Do not construct a thread ID, use a fixed Executor URL, or submit a generation task merely to test connectivity.

Local verification

From this package directory:

pnpm typecheck
pnpm build
npm pack --dry-run ./dist

LUX3D_MCP_EXECUTOR_URL may override the Executor page for Coohom HTTPS environments. LUX3D_MCP_BRIDGE_PORT may override the local port for diagnostics, but normal installations should use the default.