# spendolas/grip architecture

> Architecture diagram of the GitHub repository spendolas/grip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spendolas/grip
- Repository: https://github.com/spendolas/grip

## Overview

Grip lets an MCP agent inspect and edit a Figma canvas: the agent connects to the local bridge, which routes requests to the Figma plugin over WebSocket; the plugin performs the canvas work. The bridge supports both direct HTTP MCP and a local IPC/stdio path, and can serve multiple agents and Figma windows. The graph also preserves installation and update capabilities. Several connections are supported by README statements or source references; unsampled plugin internals and tool-specific execution details are not expanded.

Main entry points: [`src/bridge/src/mcp-server.ts`](https://github.com/spendolas/grip/blob/main/src/bridge/src/mcp-server.ts) (MCP sessions), [`src/bridge/src/index.ts`](https://github.com/spendolas/grip/blob/main/src/bridge/src/index.ts) (Bridge startup), [`src/bridge/src/ipc-server.ts`](https://github.com/spendolas/grip/blob/main/src/bridge/src/ipc-server.ts) (IPC transport), [`src/bridge/src/ws-server.ts`](https://github.com/spendolas/grip/blob/main/src/bridge/src/ws-server.ts) (Plugin WebSocket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Agent access"]
  node_agent(("MCP agent"))
end

subgraph group_bridge["Bridge runtime"]
  node_entry["Bridge startup<br/>[index.ts]"]
  node_http["HTTP transport<br/>[http-server.ts]"]
  node_ipc["IPC transport<br/>[ipc-server.ts]"]
  node_proxy["Stdio proxy<br/>[proxy.ts]"]
  node_socket["Socket transport"]
  node_mcp["MCP sessions<br/>[mcp-server.ts]"]
  node_ws["Plugin WebSocket<br/>[ws-server.ts]"]
  node_types["Bridge contracts<br/>[types.ts]"]
end

subgraph group_figma["Figma operations"]
  node_tools["Canvas tool catalog<br/>[tools.ts]"]
  node_plugin["Figma plugin<br/>[code.ts]"]
  node_serializer["Canvas serialization<br/>[serializer.ts]"]
end

subgraph group_lifecycle["Install and updates"]
  node_install["Installer<br/>[install.ts]"]
  node_updatecli["Update CLI<br/>[update-cli.ts]"]
  node_updates["Update manager<br/>[update.ts]"]
end

node_agent -->|"connects by HTTP"| node_http
node_agent -->|"uses stdio"| node_proxy
node_entry -->|"starts"| node_http
node_entry -->|"starts"| node_ipc
node_entry -->|"starts"| node_ws
node_entry -->|"runs"| node_proxy
node_http -->|"creates sessions"| node_mcp
node_ipc -->|"creates sessions"| node_mcp
node_ipc -->|"wraps sockets"| node_socket
node_proxy -->|"forwards MCP traffic"| node_ipc
node_mcp -->|"reads definitions"| node_tools
node_mcp -->|"dispatches requests"| node_ws
node_tools -->|"defines plugin commands"| node_plugin
node_ws -->|"exchanges messages"| node_plugin
node_ws -->|"uses contracts"| node_types
node_mcp -->|"checks updates"| node_updates
node_install -->|"records install"| node_updates
node_updatecli -->|"runs update actions"| node_updates

click node_entry "https://github.com/spendolas/grip/blob/main/src/bridge/src/index.ts"
click node_http "https://github.com/spendolas/grip/blob/main/src/bridge/src/http-server.ts"
click node_ipc "https://github.com/spendolas/grip/blob/main/src/bridge/src/ipc-server.ts"
click node_proxy "https://github.com/spendolas/grip/blob/main/src/bridge/src/proxy.ts"
click node_socket "https://github.com/spendolas/grip/blob/main/src/bridge/src/socket-transport.ts"
click node_mcp "https://github.com/spendolas/grip/blob/main/src/bridge/src/mcp-server.ts"
click node_tools "https://github.com/spendolas/grip/blob/main/src/bridge/src/tools.ts"
click node_ws "https://github.com/spendolas/grip/blob/main/src/bridge/src/ws-server.ts"
click node_plugin "https://github.com/spendolas/grip/blob/main/src/plugin/code.ts"
click node_types "https://github.com/spendolas/grip/blob/main/src/bridge/src/types.ts"
click node_serializer "https://github.com/spendolas/grip/blob/main/src/bridge/src/serializer.ts"
click node_install "https://github.com/spendolas/grip/blob/main/src/bridge/src/install.ts"
click node_updatecli "https://github.com/spendolas/grip/blob/main/src/bridge/src/update-cli.ts"
click node_updates "https://github.com/spendolas/grip/blob/main/src/bridge/src/update.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent toneBlue
class node_entry,node_http,node_ipc,node_proxy,node_socket,node_mcp,node_ws,node_types toneAmber
class node_tools,node_plugin,node_serializer toneMint
class node_install,node_updatecli,node_updates toneRose
```

## Components

### Agent access

- **MCP agent**

### Bridge runtime

- [Bridge startup](https://github.com/spendolas/grip/blob/main/src/bridge/src/index.ts): `src/bridge/src/index.ts`
- [HTTP transport](https://github.com/spendolas/grip/blob/main/src/bridge/src/http-server.ts): `src/bridge/src/http-server.ts`
- [IPC transport](https://github.com/spendolas/grip/blob/main/src/bridge/src/ipc-server.ts): `src/bridge/src/ipc-server.ts`
- [Stdio proxy](https://github.com/spendolas/grip/blob/main/src/bridge/src/proxy.ts): `src/bridge/src/proxy.ts`
- [Socket transport](https://github.com/spendolas/grip/blob/main/src/bridge/src/socket-transport.ts): `src/bridge/src/socket-transport.ts`
- [MCP sessions](https://github.com/spendolas/grip/blob/main/src/bridge/src/mcp-server.ts): `src/bridge/src/mcp-server.ts`
- [Plugin WebSocket](https://github.com/spendolas/grip/blob/main/src/bridge/src/ws-server.ts): `src/bridge/src/ws-server.ts`
- [Bridge contracts](https://github.com/spendolas/grip/blob/main/src/bridge/src/types.ts): `src/bridge/src/types.ts`

### Figma operations

- [Canvas tool catalog](https://github.com/spendolas/grip/blob/main/src/bridge/src/tools.ts): `src/bridge/src/tools.ts`
- [Figma plugin](https://github.com/spendolas/grip/blob/main/src/plugin/code.ts): `src/plugin/code.ts`
- [Canvas serialization](https://github.com/spendolas/grip/blob/main/src/bridge/src/serializer.ts): `src/bridge/src/serializer.ts`

### Install and updates

- [Installer](https://github.com/spendolas/grip/blob/main/src/bridge/src/install.ts): `src/bridge/src/install.ts`
- [Update CLI](https://github.com/spendolas/grip/blob/main/src/bridge/src/update-cli.ts): `src/bridge/src/update-cli.ts`
- [Update manager](https://github.com/spendolas/grip/blob/main/src/bridge/src/update.ts): `src/bridge/src/update.ts`

## Connections

- MCP agent → HTTP transport: connects by HTTP (evidence: `README.md`)
- MCP agent → Stdio proxy: uses stdio (evidence: `README.md`)
- Bridge startup → HTTP transport: starts (evidence: `src/bridge/src/index.ts`)
- Bridge startup → IPC transport: starts (evidence: `src/bridge/src/index.ts`)
- Bridge startup → Plugin WebSocket: starts (evidence: `src/bridge/src/index.ts`)
- Bridge startup → Stdio proxy: runs (evidence: `src/bridge/src/index.ts`)
- HTTP transport → MCP sessions: creates sessions (evidence: `src/bridge/src/http-server.ts`)
- IPC transport → MCP sessions: creates sessions (evidence: `src/bridge/src/ipc-server.ts`)
- IPC transport → Socket transport: wraps sockets (evidence: `src/bridge/src/ipc-server.ts`)
- Stdio proxy → IPC transport: forwards MCP traffic (evidence: `src/bridge/src/proxy.ts`)
- MCP sessions → Canvas tool catalog: reads definitions (evidence: `src/bridge/src/mcp-server.ts`)
- MCP sessions → Plugin WebSocket: dispatches requests (evidence: `src/bridge/src/mcp-server.ts`)
- Canvas tool catalog → Figma plugin: defines plugin commands (evidence: `src/bridge/src/tools.ts`)
- Plugin WebSocket → Figma plugin: exchanges messages (evidence: `README.md`)
- Plugin WebSocket → Bridge contracts: uses contracts (evidence: `src/bridge/src/ws-server.ts`)
- MCP sessions → Update manager: checks updates (evidence: `src/bridge/src/mcp-server.ts`)
- Installer → Update manager: records install (evidence: `src/bridge/src/install.ts`)
- Update CLI → Update manager: runs update actions (evidence: `src/bridge/src/update-cli.ts`)