# MCP

Connect AI agents like Claude Code, Codex, and Cursor to your GalaxyBrain workspace. Read, write, search, and monitor your pages, templates, and layout in real time.

## Setup

### Prerequisites

- [Bun](https://bun.sh/) runtime installed
- GalaxyBrain open in a Chromium-based browser (Chrome or Edge)

### Install

Ask your AI assistant to install the GalaxyBrain MCP server (`galaxybrain-mcp`).

Or install manually. Add to your tool's MCP settings:

```
{
  "mcpServers": {
    "galaxybrain": {
      "command": "npx",
      "args": ["-y", "galaxybrain-mcp"]
    }
  }
}
```

The MCP server starts a local API server automatically if one isn't already running. It communicates with GalaxyBrain browser tabs over a local WebSocket connection (default port 1924).

#### Port override

```
{
  "mcpServers": {
    "galaxybrain": {
      "command": "npx",
      "args": ["-y", "galaxybrain-mcp"],
      "env": { "GB_API_PORT": "3000" }
    }
  }
}
```

If you override the port, also pass `?gb_port=3000` in the GalaxyBrain browser URL.

## How It Works

AI Tool (Claude Code, Cursor, etc.)
↕ MCP protocol (stdio)GalaxyBrain MCP Server↕ WebSocket (localhost:1924)GalaxyBrain API Server↕ WebSocketGalaxyBrain Browser Tab(s)

The MCP server is a thin translation layer. It receives tool calls from your AI assistant, converts them to WebSocket commands, sends them to the API server, and formats the responses.

Multiple MCP server processes can connect simultaneously. The API server is started automatically if not already running. When the MCP session that spawned the API server exits, it terminates the API server. Other connected MCP sessions will automatically re-spawn it on their next command.

### Version Checking

The MCP server performs two version checks:

1. **Protocol compatibility** — Before connecting to an API server, the MCP server checks the API server's protocol version. If the versions don't match, it returns an error with instructions.
2. **npm update check** — On startup, the MCP server checks the npm registry for newer versions of `galaxybrain-mcp`. If an update is available, it logs a warning.

## Tools Overview

The MCP server provides 13 tools. Use `galaxybrain_help` to look up detailed schemas for complex nested payloads.

#### galaxybrain_status

Check whether the API server is running and list connected browser tabs. Shows each tab's state, project, and connection details. Use this first to confirm connectivity.

#### galaxybrain_project

Manage the project lifecycle: **list available folders, open folder by ID, open demo by name, close the current project.**

#### galaxybrain_read_pages

Read full serialized content of pages or templates. Manage selection by ID or read all open tabs. Control returned fields with `icon`, `title`, `subtitle`, `blocks` flags.

#### galaxybrain_query

Search and filter pages with text search, error search, references search, graph filters, count filters, field projection, sorting, and pagination.

#### galaxybrain_traverse

Build a recursive page-link tree starting from a root page:

- **down** (MAP) — walks outbound links.
- **up** (ANCESTORS) — walks inbound links.

#### galaxybrain_write_pages

Create, update, or delete pages or templates. Supports full replacement, surgical block-level edits, and image uploads via base64.

#### galaxybrain_create_from_template

Create a page from a template with automatic value resolution. A page link is inserted into the specified source block.

#### galaxybrain_items

Push (insert) or pop (remove) items from specific blocks. Useful for appending tasks, inserting links, or removing items.

#### galaxybrain_workspace

Read or write the workspace tab layout. Supports optimistic concurrency via `readVersion`.

#### galaxybrain_watch

Start watching for real-time events. Returns a shell command to run with your AI tool's process monitor.

#### galaxybrain_update

Warm the npx cache for `galaxybrain-mcp@latest`. On success, returns a message instructing the user to restart their MCP host.

#### galaxybrain_help

Look up detailed documentation on a specific topic during a session. Available topics include overview of tools, styles, units, errors, and troubleshooting.

## Typical Workflow

1. `galaxybrain_status` → check connectivity, see open instances
2. `galaxybrain_orient` → understand the project structure
3. `galaxybrain_read_pages` → read content
4. `galaxybrain_query` → search and filter
5. `galaxybrain_traverse` → explore link structure
6. `galaxybrain_write_pages` → create/update/delete pages
7. `galaxybrain_items` → insert/remove items
8. `galaxybrain_create_from_template` → create from template

If no project is open, use `galaxybrain_project` to list and open one first.

## Data Model

GalaxyBrain organizes content in a hierarchy: **Pages → Blocks → Items → Units**.

### Pages

| Field | Description |
| --- | --- |
| `pageId` | 20-character alphanumeric ID |
| `icon` | Single emoji |
| `title` | Array of title units |
| `subtitle` | Array of units |
| `blocks` | Array of blocks |

### Blocks

| Field | Description |
| --- | --- |
| `blockId` | Non-negative integer, unique within the page |
| `items` | Non-empty array of items |
| `linkOrder` | Optional sort rule for page-link items |

### Items

| Type | Description |
| --- | --- |
| `text` | Styled text content |
| `var` | Named variable |
| `image` | Referenced image |
| `pageLink` | Standalone link to another page |

### Units

| Type | Description |
| --- | --- |
| `text` | Plain or styled text |
| `webLink` | Hyperlink with display text and URL |
| `pageLink` | Inline reference to another page |
| `metaRef` | Live computed value |
| `templateValue` | Placeholder resolved when creating from a template |

### Templates

Templates are special pages that serve as blueprints. They use the same structure as regular pages but can contain `templateValue` units.

## Writing Content

### Creating a Page

Pass a full page body to `galaxybrain_write_pages` with `action: "create"`:

```
{
  "action": "create",
  "pages": [{
    "icon": "📝",
    "title": [{ "type": "text", "text": "My Page" }],
    "blocks": [{
      "blockId": 0,
      "items": [{
        "type": "text",
        "content": [{ "type": "text", "text": "Hello world" }]
      }]
    }]
  }]
}
```

### Updating a Page

For a full replacement, pass the complete page body with a `pageId`:

```
{
  "action": "update",
  "pages": [{
    "pageId": "AbcDef1234567890GhIj",
    "icon": "🔥",
    "title": [{ "type": "text", "text": "Updated Title" }],
    "blocks": [{ "blockId": 0, "items": [...] }]
  }]
}
```

### Push and Pop

Use `galaxybrain_items` for targeted insertions and removals:

##### Push (insert items)

```
{
  "action": "push",
  "operations": [{
    "pageId": "AbcDef1234567890GhIj",
    "blockId": 0,
    "items": [{
      "type": "text",
      "content": [{ "type": "text", "text": "New task" }]
    }]
  }]
}
```

##### Pop (remove items)

```
{
  "action": "pop",
  "operations": [{
    "pageId": "AbcDef1234567890GhIj",
    "blockId": 0,
    "count": 1
  }]
}
```

### Normalization

Written content is normalized automatically; adjacent compatible units are merged.

## Output Modes

| Mode | Description |
| --- | --- |
| `summary` | Human-readable formatted text |
| `raw` | Full JSON response from the API |
| `full` | Summary text with raw JSON appended |

## Versions & Conflict Detection

Each page has an independent integer version that increments on every mutation. Pass `readVersion` with mutations for optimistic concurrency.

## Troubleshooting

### Prerequisites

- GalaxyBrain MCP requires [Bun](https://bun.sh/).

### Updating

The MCP server checks for updates on startup.

### Common Errors

| Error | Cause | Fix |
| --- | --- | --- |
| `GalaxyBrain MCP requires Bun` | Bun not installed | Install Bun |
| `No GalaxyBrain browser tabs connected` | No browser tab connected | Open GalaxyBrain in Chrome |