MCP bridge

Agents talk to the window over the Model Context Protocol, through a Unix socket and a small sidecar. There is no network port, no account and no cloud relay.

Chain

agent client ──stdio JSON-RPC──► spark-mcp (sidecar)
                                      │ Unix socket
                                      ▼
                             Spark window (attachMcp)
                                      │
                                      ▼
                             runtime / registry / workspace
  • src-tauri/src/bin/spark-mcp.rs is declared as an external binary and shipped inside the bundle.
  • The Rust server creates run/mcp.sock in the app configuration directory, mode 0600.
  • attachMcp forwards each line to the window and returns the reply.
  • When Spark is closed, the bridge answers spark_not_running and serves the last cached tool list, so a client does not have to restart.

Tools

ToolJob
spark_briefShort summary of the active or targeted tab.
spark_tabsTabs and their layout mode.
spark_tilesCompact catalogue of tile types, actions and availability; detail: "full" adds descriptions and schemas.
spark_tab_openCreates a tab in the background.
spark_tab_closeCloses a tab; refused when an unsaved document objects.
spark_tab_focusActivates a tab.
spark_tile_openOpens a tile and returns its reference.
spark_tile_readReads a tile's surface, data and available actions.
spark_tile_callRuns a declared action.
spark_tile_closeCloses a tile.
spark_tile_movePlaces a tile next to another one, or as a tab in its group.
spark_tile_resizeGives a tile a width or height as a fraction of the tab.
spark_undoUndoes a layout operation.
spark_redoRedoes a layout operation.
spark_events_sinceResumes the journal from a sequence number.

The list is deliberately stable: a client caches it and refreshes it badly. What varies is theactions, discovered per tile with spark_tiles andspark_tile_read.

Contracts

  • Bounded results. An action returning more than 16,000 characters is refused; it must return an identifier or a summary.
  • Surfaces. api.tiles.publish is a volatile 2,000-character summary, never persisted.
  • Guides. A tile type's guide is at most 1,200 characters and is delivered once per agent session, at the first catalogue or the first read.
  • Services. An action declaring requires is hidden when that service is absent, and refused when called.
  • Mutations. An action flagged mutates is announced as such and executed; asking for confirmation belongs to the calling client.
  • Attribution. Every action called through spark_tile_call is journaled with source: "agent".
  • Focus. Tabs opened by an agent stay in the background and show a discreet dot in the bar until opened.
  • Content. No MCP action reads or writes a terminal's content, and no action returns a document.

Connect a client

{
  "mcpServers": {
    "spark": {
      "command": "/Applications/Spark.app/Contents/MacOS/spark-mcp"
    }
  }
}

The absolute path is the one shown by the gear menu at the bottom of the rail, underConnect an agent…, with a copy button. Spark also detects a known agent command in a terminal and offers to write the client's configuration in one click; the running session sees the server on its next start.

Lifecycle

  • registry.subscribeTools emits notifications/tools/list_changed when an extension is activated, disabled or imported.
  • spark_tiles is recomputed on every call, so a new extension appears without restarting the client.
  • The sidecar caches the tool list for closed-window replies. A new core tool still needs a new session on the client side.