pixso-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

Pixso MCP Server — a bridge that lets LLMs (e.g., Codex) interact with Pixso design files via the Model Context Protocol. The project has two parts that communicate over WebSocket (port 3667):

1. MCP Server (server/) — Node.js server using @modelcontextprotocol/sdk, communicates with MCP clients via Streamable HTTP (port 3668, endpoint /mcp) and with the Pixso plugin via WebSocket (port 3667).
2. Pixso Plugin (plugin/) — runs inside Pixso; ui.html maintains the WebSocket connection, main.js handles commands in the plugin's main thread using the pixso API.

Commands

npm start          # Run the MCP server (node server/index.js)
npm run lint:all    # ESLint across the project

No build step — all source files are plain JS (ES modules, "type": "module").

Project Structure

server/
  index.js        — MCP server entry point, wires bridge + tool handlers
  bridge.js       — WebSocket bridge: connection management, callPlugin()
  tools.js        — MCP tool definitions and call handlers
plugin/
  main.js         — Pixso plugin main thread (sandbox, single-file)
  ui.html         — WebSocket client UI with auto-reconnect
  manifest.json   — Pixso plugin manifest
tokens.js         — статистика токенов для ответа MCP сервера
count-tokens.js   — утилита: запрашивает выделение и считает токены

Architecture & Data Flow

MCP Client (Codex) <--HTTP:3668/mcp--> server/index.js
                                     |
                              server/bridge.js <--WebSocket:3667--> plugin/ui.html <--postMessage--> plugin/main.js
                                     |
                              server/tools.js (tool definitions + dispatch)

• server/index.js: Entry point. Creates MCP server, starts WebSocket bridge, registers tool handlers.
• server/bridge.js: Manages WebSocket connection to the Pixso plugin. Exports startBridge() and callPlugin(command, params). Pending requests tracked in a Map<id, resolve>.
• server/tools.js: Определяет MCP-инструменты (get_selection, get_selection_png, get_selection_svg, diagnose_export, get_design_tokens). Экспортирует handleToolCall(name).
• plugin/ui.html: WebSocket client with auto-reconnect (5s). Forwards request messages from server to main.js via parent.postMessage, and sends mcp-response messages back to the server.
• plugin/main.js: Runs in Pixso's plugin sandbox. Handles getSelection, exportNodes, and getDesignTokens commands via the pixso global API. serializeNode(node, profile) extracts node properties with token-saving optimizations. getDesignTokens extracts design tokens (colors, typography, effects, variables) from the entire document.