mcp

Documentation

Overview

Package mcp exposes ghostchrome as a Model Context Protocol server so that LLM agents (Claude Code, Codex, Cursor, ...) can drive the browser via stdio JSON-RPC instead of forking the CLI per call.

The server holds a single long-lived *engine.Browser + *rod.Page across tool calls so refs (@1, @2) extracted by one tool stay valid for the next click/type.

Index

• Constants
• type Options
• type Server
  • func New(opts Options) *Server
  • func (s *Server) Build(name, version string) *mcpsrv.MCPServer
  • func (s *Server) Close()
  • func (s *Server) PrewarmAsync()

Constants

const TraceEnvVar = "GHOSTCHROME_MCP_TRACE"

TraceEnvVar names the env var that activates session tracing. When set to a writable path, the MCP server appends one JSONL entry per tool call.

const TraceShotsEnvVar = "GHOSTCHROME_MCP_TRACE_SHOTS"

TraceShotsEnvVar enables per-tool-call WebP screenshots stored next to the JSONL trace. Significantly increases latency (~150ms per state-changing tool call) and disk usage; opt-in only.

Types

type Options

type Options struct {
	Connect        string // ws:// URL or "auto" to discover, empty = auto-launch
	Headless       bool
	Invisible      bool
	UserProfile    string
	Stealth        bool
	DismissCookies bool
	Proxy          string
	TimeoutSec     int
	// BlockTrackers enables the curated anti-bot script blocker
	// (engine.AntiBotPatterns). Auto-enabled when Stealth is true unless
	// GHOSTCHROME_MCP_NO_BLOCKER=1 is set.
	BlockTrackers bool
}

Options configure the shared browser the MCP server attaches to. Mirrors the global flags exposed by the ghostchrome CLI.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server holds the shared browser and exposes tool handlers backed by the engine package. Methods are concurrency-safe via mu.

func New

func New(opts Options) *Server

New returns a Server that lazy-initializes the browser on the first tool call. Build registers all tools on a fresh MCP server and returns it. Tracing auto-activates when the GHOSTCHROME_MCP_TRACE env var is set.

func (*Server) Build

func (s *Server) Build(name, version string) *mcpsrv.MCPServer

Build returns an MCP server with every ghostchrome tool registered. Caller is expected to call mcpsrv.ServeStdio on it.

func (*Server) Close

func (s *Server) Close()

Close releases the underlying browser. Safe to call multiple times.

func (*Server) PrewarmAsync

func (s *Server) PrewarmAsync()

PrewarmAsync spawns Chrome in the background so the first user-facing tool call doesn't pay the ~1.3s cold-start. Safe to call from main(): if the browser is already up it's a no-op; if init fails, the next withPage() will surface the error normally.