MCP & CLI Reference

Complete reference for Blueberry’s MCP server and CLI commands.

Architecture

Blueberry provides two interfaces for AI agent integration:

MCP Tool (blueberry_get_context): a single MCP tool that returns the full workspace state
CLI (blueberry): a command-line tool with 16+ commands for taking actions

When an AI agent starts in a Blueberry terminal, the MCP server connects automatically and the blueberry CLI is available on PATH. The typical workflow is: call blueberry_get_context to understand the workspace, then use CLI commands via bash to take actions.

MCP Tool

blueberry_get_context

Get the current IDE context organized by panel with visibility status.

Returns a structured object:

project: Current project path
editor: { isVisible, activeFile, openTabs, cursor, selection, diffView }
terminal: { isVisible, tabs (with id/name for terminal commands) }
preview: { isVisible, activeUrl, tabs (with id/url/title for screenshots) }
pinnedApps: [{ id, url, title, isVisible }] - pinned web apps
sidebar: { isVisible, activePanel }
worktrees: { current, list (path/head/branch/isMain), defaultBranch } - only present when git worktrees exist

Each section has ‘isVisible’ at the top so you know immediately what’s showing.

Parameters: None

CLI Commands

The blueberry CLI is available on PATH in all Blueberry terminal sessions. Run blueberry help for the full list.

Editor

Command	Description
`blueberry open <file> [--line N]`	Open a file in the editor, optionally jumping to a line

Preview Browser

Command	Description
`blueberry preview <url>`	Open a URL in the preview panel
`blueberry capture:webview [--output FILE]`	Screenshot the preview (saves to file)
`blueberry capture:content [--tab ID] [--app ID]`	Get page text as accessibility tree
`blueberry console-logs [--tab ID] [--level LEVEL]`	Get console logs from a preview tab

Terminal

Command	Description
`blueberry terminal <command> [--session ID]`	Send a command to a terminal tab
`blueberry terminal:create [--name NAME]`	Create a new terminal tab
`blueberry terminal-logs [--session ID] [--limit N]`	Get terminal output

Canvas

Command	Description
`blueberry canvas:data`	Get all canvas elements as JSON
`blueberry canvas:draw <file.json>`	Draw elements from a JSON file
`blueberry canvas:draw-guide`	Get the style guide for canvas:draw (run before first use)
`blueberry canvas:mermaid <file>`	Render a Mermaid diagram onto the canvas
`blueberry canvas:remove <id> [id2 ...]`	Remove elements by ID
`blueberry canvas:update <id> <props.json>`	Update properties of an element
`blueberry capture:canvas [--output FILE]`	Screenshot the canvas

Pinned Apps

Command	Description
`blueberry pinned-app <appId>`	Open a pinned web app panel

App Mode

Command	Description
`blueberry startup-config:guide`	Get the format guide for startup configs

Canvas CLI Usage

Mermaid Diagrams

Write a temp file with Mermaid syntax, then render it:


blueberry canvas:mermaid /tmp/canvas-mermaid-abc.md

Supports flowcharts, sequence diagrams, class diagrams, and ER diagrams. New diagrams auto-position next to existing canvas content.

Custom Drawing

Run the style guide first, then write a JSON file with element definitions:


blueberry canvas:draw-guide
blueberry canvas:draw /tmp/canvas-layout-xyz.json

Elements within a batch are positioned relative to each other. The API auto-offsets the entire batch away from existing content.

Important Notes

Never remove or clear existing canvas elements unless the user explicitly asks
Always use unique temp file paths (e.g., /tmp/canvas-mermaid-a1b2.md) to avoid conflicts
For Mermaid: keep labels short (1-3 words), avoid <br> tags
For canvas:draw: run canvas:draw-guide before your first drawing

Getting Started

Open a terminal tab in Blueberry
Start your AI agent (e.g., claude, codex, gemini)
The agent automatically has MCP access and the blueberry CLI on PATH
Run blueberry help to see all available commands

Best Practices

Always call blueberry_get_context first to understand the current workspace state
Check isVisible flags before interacting with panels
Use blueberry capture:content instead of screenshots when you need to read page text
Prefer named terminal tabs for organization (e.g., “Dev Server”, “Tests”)

Error Handling

Commands may return errors in these situations:

“Blueberry is not running”: Start Blueberry and open your project
“Not running in a Blueberry terminal”: Run your AI agent from a Blueberry terminal
“No context available”: Open a project folder in Blueberry