Doop MCP 工具面：设计画布的 Agent API

16const INSTRUCTIONS = `Doop is a shared multiplayer design canvas: humans and AI agents design together in real time. Canvases contain frames — artboards that render complete HTML documents live for everyone viewing.
17
18You MUST call get_guide({ topic: "doop-instructions" }) once before using other Doop tools. Call it again if a long conversation may have compressed or dropped the guide text.
19
20- Context first: call get_canvas before adding or editing frames.
21- Identity: pick an agent_name and reuse the SAME name on every call — your presence and edits are attributed live.
22- Narrate: call set_status with a one-line summary when you start a task and whenever your focus shifts — people watching the canvas see it live next to your name.
23- Creating: create_frame, then stream the design with append_frame_html in ~300–500 character chunks (start=true on the first, done=true on the last). Viewers watch you work.
24- Review: after every create or significant edit you MUST call get_frame_screenshot and fix what looks wrong before moving on.
25- Small edits: edit_frame_html (exact find/replace — the change morphs into the rendered frame in place). Full redesigns: set_frame_html or a new stream. Rename/move/resize: update_frame.
26- Images: real imagery makes designs. search_images finds stock photos (you SEE thumbnails and pick), search_icons finds 200k+ UI icons as hotlinkable SVGs, search_logos finds real company logos by brand name or domain, upload_asset stores your own file (remote file → source_url; local file → local_file=true, returns a curl command) and returns a permanent URL. Never inline images as data: URIs.
27- Feedback: humans reply to your tasks; their notes arrive inside your tool results as HUMAN FEEDBACK blocks — address them before continuing.
28- Guidelines: canvases can carry named style guides (brand rules, style recipes). get_canvas lists them with one-line summaries — read the relevant ones with get_guidelines BEFORE designing and follow them.
29- Memory: canvases can also carry pinned style references — exemplar designs humans marked as "more like this". get_canvas lists them; read the relevant one with get_reference and match its look. When your human gives you design feedback in conversation and you address it, record it with save_decision so the canvas remembers their taste.`

153export function buildMcpServer(owner?: string, ownerId?: string): McpServer {
154  const actorFrom = (agent_name?: string) => actions.resolveActor({ name: agent_name, kind: 'agent', owner })
155  /* Canvas access for agents mirrors the web UI: the OAuth user's id runs
156     through the same canAccessCanvas gate as browser sessions. Every tool
157     that takes a canvas or frame id resolves it through these. */
158  const canvasFor = (canvasId: string) => {
159    const c = store.getCanvas(canvasId)
160    return c && canAccessCanvas(ownerId, c) ? c : undefined
161  }
162  const frameFor = (frameId: string) => {
163    const f = store.getFrame(frameId)
164    if (!f) return undefined
165    return canvasFor(f.canvasId) ? f : undefined
166  }
167  const noCanvas = (id: string) => err(`no canvas with id ${id} accessible to this account`)
168  const noFrame = (id: string) => err(`no frame with id ${id} accessible to this account`)
169  /* Reads count as arrival: presence (and with it every "your agent is
170     connected" confirmation in the UI) must appear on an agent's FIRST
171     canvas-scoped call, not only once it mutates something. */
172  const arrive = (canvasId: string, agent_name?: string) => {
173    if (agent_name) actions.heartbeatAgent(canvasId, actorFrom(agent_name))
174  }
175  const server = new McpServer({ name: 'doop-canvas', version: '0.1.0' }, { instructions: INSTRUCTIONS })

868  server.registerTool(
869    'get_frame_screenshot',
870    {
871      description:
872        'Render a frame and return a PNG screenshot of it — this is how you SEE your design. Always review your work with this after creating or updating a frame, then fix what looks wrong (spacing, overflow, contrast, alignment) and check again. Iterate until it actually looks good, not just until the HTML seems right.',
873      inputSchema: {
874        frame_id: z.string(),
875        scale: z
876          .union([z.literal(1), z.literal(2)])
877          .optional()
878          .describe('Device scale factor: 1 (default) or 2 for a retina-resolution image'),
879        agent_name: agentName.optional(),
880      },
881    },
882    async ({ frame_id, scale, agent_name }) => {
883      const f = frameFor(frame_id)
884      if (!f) return noFrame(frame_id)
885      arrive(f.canvasId, agent_name)
886      try {
887        const png = await renderFrame(f, scale ?? 1)
888        return withFeedback(
889          {
890            content: [
891              { type: 'image' as const, data: png.toString('base64'), mimeType: 'image/png' },
892              {
893                type: 'text' as const,
894                text: `Screenshot of “${f.name}” (${f.width}×${f.height}@${scale ?? 1}x, html ${f.html.length} bytes)`,
895              },
896            ],
897          },
898          f.canvasId,
899          agent_name ? actorFrom(agent_name) : undefined,
900        )
901      } catch (e) {
902        return err(`screenshot failed: ${e instanceof Error ? e.message : String(e)}`)
903      }
904    },
905  )
906
907  server.registerTool(
908    'append_frame_html',
909    {
910      description:
911        'Stream a design into a frame chunk by chunk, so viewers watch it build up live — prefer this over set_frame_html when creating or reworking a whole design. Send the HTML in order, in chunks of roughly 200–600 characters (e.g. head/styles first, then section by section). Set start=true on the FIRST chunk (replaces any existing content and shows a live "designing…" badge) and done=true on the LAST chunk. Partial HTML renders progressively, so structure chunks to end at reasonable boundaries when you can.',
912      inputSchema: {
913        frame_id: z.string(),
914        html_chunk: z.string().describe('The next piece of HTML, appended to what has been sent so far.'),
915        start: z.boolean().optional().describe('true on the first chunk — clears the frame and starts the live stream'),
916        done: z.boolean().optional().describe('true on the final chunk — ends the live stream'),
917        agent_name: agentName,
918      },
919    },
920    async ({ frame_id, html_chunk, start, done, agent_name }) => {
921      if (!frameFor(frame_id)) return noFrame(frame_id)
922      const frame = actions.appendFrameHtml(frame_id, html_chunk, actorFrom(agent_name), { start, done })
923      if (!frame) return noFrame(frame_id)
924      const result = done
925        ? textWithNudge(
926            { ok: true, streaming: false, htmlBytes: frame.html.length },
927            `Stream complete. ${REVIEW_NUDGE}`,
928          )
929        : text({ ok: true, streaming: true, htmlBytes: frame.html.length })
930      /* nudge only on the first chunk — mid-stream results should stay lean */
931      const nudged = start ? withGuidelinesNudge(result, frame.canvasId, actorFrom(agent_name)) : result
932      return withStatusNudge(
933        withFeedback(nudged, frame.canvasId, actorFrom(agent_name)),
934        frame.canvasId,
935        actorFrom(agent_name),
936      )
937    },