penecho-mcp

Resolve an explicit local/production/UAT destination or already-bound workspace first. If the user has explicitly selected UAT testing for the current workflow, follow penecho-canvas-uat when available. Otherwise route ordinary new untargeted canvas demonstrations to production https://penecho.ai/mcp, using the installed penecho-canvas workflow when available. A stale installed UAT skill alone does not select UAT. Explicit local/manual work retains its configured local connection; preserve that configuration. Report selected-environment connection failures without silently substituting another server.

Use connected tools; search only missing deferred tools. Bind once with start_session; retain sessionId/documentId and stable client/sessionKey. For local/manual connections, use target:current for the user's current Canvas.

For Cloud MCP without an explicit target, use penecho_open_workspace with one unique stable conversation sessionKey. Retain workspaceId and open its returned url once, preferably in the host's embedded side browser (Codex's exposed open_in_codex browser target with placement:right, or the host's actual equivalent). Reuse an already connected tab. Preserve mode=companion. Check penecho_workspace_status with at most five bounded retries and bind its exact startSession target. Launch tickets expire after 120 seconds; automatically renew an expired link with open_workspace and the same key, navigating the same tab without an extra question (at most two renewals per opening attempt); a different browser profile requires the original draft. Never choose the latest unrelated Canvas. Guests need no PenEcho account, Dashboard visit, MCP toggle or token copy. Save prompts sign-in/registration in the same browser and resumes the user's explicit save. Installation or first Cloud use authorizes adding its missing native HTTP MCP connection through the actual host setup capability and normal OAuth, without an extra conversational permission request. Prefer supported live reconnect/reload, then continue the same task; report a precise manual step only if necessary. A Skill cannot create host browser capabilities. Use Claude desktop preview_start only when exposed with existing-URL support; otherwise use the actual native/default browser opener. Never send a ticket URL to fetch/search. If Cloud is unavailable, report that blocker; an explicit local/manual workflow keeps its own connection.

Follow live schemas; get_guidance only for the needed topic. Keep artifact IDs. Read source/contentHash before patching. Retry uncertain writes with identical arguments/requestId. Capture when visual evidence is needed; combine final mutation and completion. Inbox reads do not acknowledge.

For Cloud uploads, follow the live HTTP upload schema and existing connection credentials; no local bridge is required. The following upload instructions apply only to a configured local stdio connection.

For file uploads, use the same client.js configured as the PenEcho stdio MCP entry. Its required installation location is ~/.penecho/mcp/client.js on macOS/Linux or %USERPROFILE%\.penecho\mcp\client.js on Windows, not the skill or application directory. Do not choose another directory or filename. The PenEcho MCP entry and upload command must both use this fixed path expanded against the current user home. If the entry points elsewhere, correct it through setup before uploading. Read the configured Node executable and --host-id from the PenEcho MCP entry; reuse its environment and state-directory option. Run node "ABSOLUTE_CLIENT_JS_PATH" --host-id HOST_ID --upload-image "ABSOLUTE_IMAGE_PATH" --canvas-id CANVAS_ID --document-id DOCUMENT_ID --request-id UNIQUE_ID, substituting the configured Node executable. Obtain both IDs from start_session target:current. Follow upload_image source parameters for formats, limits and returned source usage.

HOST_ID identifies the PenEcho server: copy the setup prompt hostId or the value after --host-id in this Agent's MCP entry. It is not canvasId, documentId or sessionId; never guess or derive it. The client resolves the server address/port automatically through saved state and discovery, so do not inspect its source or parse port mappings. When creating this local skill during setup, record the actual server hostId and resolved fixed client.js/Node paths for subsequent uploads. Never store access tokens in the skill.

For a Cloud workspace request about the current Canvas, re-read penecho_workspace_status before editing and use its exact startSession arguments. The companion rail can create and select multiple documents in the same tab. Retain one stable session handle per document: selecting a Canvas never retargets an existing session. Explicit requests for an older Canvas keep that document’s handle. Only use penecho_select_workspace_canvas when the user requests a target switch; read the current selection revision first. Ordinary website URLs do not expose the companion Compact/Full Canvas switch.