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.

Package mcp tool registrations.

MCP v1.0 surface: 11 essential tools for an LLM-agent browser loop. Everything that isn't on the hot path (sniff/trace/cookies/storage/tabs/ viewport/dialog/blocker_stats) lives in the CLI only — adding tools here has a real token cost in every `tools/list` the model receives, so we stay deliberately small.

Index

• 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()

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.

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.