0
Fork 0
mirror of https://github.com/zeronsh/comet.git synced 2026-11-16 18:57:19 +00:00
comet/docs/mcp.md
Alexandre V.L 5d2b91901b
Agents can show local images in chat: show_image, and Markdown images in replies (#1036)
* Agents can show local images in chat: show_image, and Markdown images in replies

show_image {path} (Zeron MCP) copies a PNG/JPEG/WebP/GIF into uploads and
publishes the image part Codex's generated images use, so every client
already renders it and it outlives the file.

An agent reply's ![alt](path) now draws the image in place, read live by the
chat's host through ReadChatImageChunk: strictly inside that chat's folder,
no link followed, no URL fetched, extension and bytes checked, decoded within
the shared raster limits. Anything refused keeps today's link.

* Chat image folder tests: refuse the filesystem root portably

On Windows `/` isn't absolute, so it was refused as "not an absolute
path" instead of as the root. Test the root of the temp dir's own path
(`/`, or a drive like `C:\`) instead.

* Retrigger CI: cursor_shim frame timeout on the Windows runner

* Reply images: right-click copies the original, and narrow columns scale them whole

Rebased onto main (Origin's new side_chats_only in the show_image test).

- A Markdown image in a reply now opens the shared Copy path / Copy image
  menu, like generated images and tool previews. Copy image reads the
  original through ReadChatImageChunk under that chat's jail, not the wider
  ReadAttachmentChunk, and not the downscaled preview.
- The image row keeps its aspect ratio when the column is narrower than the
  image, instead of keeping its height and letterboxing.
- docs/image-preview.md: the menu, the sizing, and what the cache means for a
  Markdown image whose file changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

---------

Co-authored-by: Wing <44917547+wingleeio@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>
2026-10-27 02:55:52 +00:00

26 KiB

Zeron MCP server

zeron mcp serves the Model Context Protocol on stdin/stdout and proxies every tool into the running engine's localhost IPC (ws://127.0.0.1:$ZERON_IPC_PORT, default 27654) — the same zeron_rpc surface the headed app and zeron sync dial. It is a subcommand of the one zeron binary: no Node runtime, no extra install, a few MB resident.

Crate: crates/mcp (zeron-mcp). The protocol layer is hand-rolled (initialize, ping, tools/list, tools/call; newline-delimited JSON-RPC 2.0) — the repo already owns JSON-RPC framing for the Codex and ACP drivers and the stdio tool-server subset is tiny, so no SDK dependency was taken.

Identity

The engine can inject this server into a harness's MCP config with the originating chat in the environment:

Variable Meaning
ZERON_IPC_PORT Engine to proxy (default 27654).
ZERON_IPC_TOKEN_FILE The engine's IPC bearer file (see below).
ZERON_CHAT_ID The chat whose agent spawned this server.
ZERON_DEVICE_ID That chat's host device.
ZERON_SIDE_CHATS_ONLY 1: the agent has no subagent tools of its own (below).

ZERON_SIDE_CHATS_ONLY=1: the host device turned the provider's native subagents off (Settings → Providers), so initialize tells the agent to delegate with create_chats. Never set for a chat that has a parent, nor for one whose host doesn't know its parent yet.

IPC authentication

The IPC port is loopback-only, but loopback is not an identity: any local process could otherwise drive the engine (start agents, broker Cloud vault grants). Every engine start that binds the port mints a fresh 32-byte token and writes it to {data_dir}/ipc-token (owner-only 0600, atomic replace; on Windows the file inherits %LOCALAPPDATA%\Zeron's per-user ACL). The WebSocket handshake must carry Authorization: Bearer <token> (compared in constant time) and is refused with 401 otherwise; the browser Origin rejection (403) still applies on top. In-process (in-memory) transports are unaffected.

Clients resolve the token at every dial — $ZERON_IPC_TOKEN, then the file named by $ZERON_IPC_TOKEN_FILE, then {ZERON_DATA_DIR or ~/.zeron}/ipc-token (zeron_rpc::connect_ipc) — so they follow the rotation across engine restarts. The engine hands injected servers the file PATH (ZERON_IPC_TOKEN_FILE), never the token itself: Claude receives this env on its command line (--mcp-config <inline json>), which other local users can read with ps. A client run against a different data dir (e.g. a viewport on a daemon's port) sets ZERON_IPC_TOKEN_FILE to the daemon's file.

When ZERON_CHAT_ID is set, every send_message is prefixed with a [Message from Zeron chat <title> (<id8>) …] line so the receiving agent and the human reading that transcript can tell an agent-to-agent message from a typed one, and the server refuses to message its own chat. The transcript renders this routing header as “Message from chat name”, keeping the full routing instructions in the stored prompt for agents.

create_chat and each request in create_chats accept kind:

Input Placement
kind: "chat" Standalone session, visible in the left Sessions sidebar; no parentChatId is written.
kind: "side" Child of the explicit parent or origin chat. Requires one of those.
Kind omitted, origin or parent supplied Child, preserving the previous default.
Kind omitted, no origin or parent Standalone, preserving terminal usage.

kind: "chat" with a nonempty parent, kind: "side" without an origin/parent, and unknown kinds fail before any writes. Empty parent uses the default. The creation result includes the effective kind, chatId, deviceId, project and parentChatId. Kind is derived from the parent; it is not persisted.

Children record Chat.parent_chat_id (proto) ⇄ parentChatId on the registry row (Mutate createChat { parentChatId? }). Any chat may delegate to any provider. Delegation is one level deep: a chat that has a parent creates no chats at all, and a new chat's parent (the origin, or an explicit parent) must be top-level. Standalone sessions have no parent.

cloud: true runs the child on a Cloud machine of its own (Codex or Claude Code), cloning the project's GitHub repository; from a Cloud chat, the parent's repository. Without it, a child of a Cloud chat shares the parent's machine. A Cloud machine starts children only for the chat it runs, and sees and manages only those children (docs/design/cloud-device.md, "Delegation").

For children, parent (id, prefix, or title) overrides the origin (ZERON_CHAT_ID). list_chats { parent } returns children, and chat summaries carry parentChatId. Rows from older engines read as parentless; a dangling parent id is tolerated.

The left sidebar hides chats that have a parent: AppState::visible_chats (the Sessions list, project tabs, jump slots) and the Archived section both require parent_chat_id == None. Children remain addressable by id, deep link, and every MCP tool; list_chats { parent } is how an orchestrator finds them.

Injection

The host engine stamps this server onto every run it drives (RunRequest.mcp, additive): the same zeron binary with args: ["mcp"] and the variables above, pointed at the port the engine itself serves (never a port it lost the bind race for). Each driver spells it in its own dialect and leaves the user's configured servers alone:

Harness Where
Claude --mcp-config <inline json> (no --strict-mcp-config)
ACP (Devin, Grok, Hermes, Antigravity) session/new and session/load → mcpServers: [{name, command, args, env}]
Pi Per-run --extension bridges stdio MCP into Pi tools in the native RPC process
OpenCode Child-only OPENCODE_CONFIG_CONTENT: mcp.zeron on 1.x, mcp.servers.zeron on 2.x
Codex thread/start config overrides mcp_servers.zeron.{command,args,env}
Cursor SDK Agent.create / Agent.resume → inline mcpServers.zeron, plus local.settingSources: ["user", "team", "mdm", "plugins"] so ~/.cursor/mcp.json and plugin servers load (not project: the SDK skips MCP approvals, so repo-defined servers would run unprompted)

OpenCode preserves inherited inline configuration and other servers. Its config shape follows the installed binary's major version. Cursor uses the SDK's inline MCP configuration; OpenCode's 1.x config layer and 2.x MCP format differ. Pi's temporary extension lives only for the native RPC process lifetime; user settings, extensions, and session arguments remain intact. The bridge registers zeron_<tool> tools, propagates cancellation and errors, and closes the MCP child when the Pi session shuts down.

Title runs never carry it. A run with no served port (embedded engine that lost the bind) gets no Zeron tools rather than a dead server.

Forks and the session card

ForkSideChat { chatId, sourceChatId, parentChatId? } copies a chat's history through its latest completed response into a new chat and appends a fork part (a system entry: sourceChatId, sourceTitle) as the seam; the transcript draws it as "This chat was forked from