mcp

Documentation

Overview

Package mcp implements a minimal Model Context Protocol server over stdio.

The implementation hand-rolls JSON-RPC 2.0 framing (newline-delimited JSON objects on stdin/stdout) and the small subset of MCP methods we need:

• initialize
• tools/list
• tools/call
• notifications/initialized (accepted, ignored)
• ping

All log/diagnostic output goes to stderr so the JSON-RPC stream on stdout stays clean. Concurrent tool calls are serialized through a single mutex around the underlying browser handle.

Index

• Variables
• type Browser
  • func NewBrowser(opts BrowserOptions) *Browser
  • func (b *Browser) Click(selector string, nth int, timeoutMs int) (map[string]any, error)
  • func (b *Browser) Close()
  • func (b *Browser) Eval(expression string) (map[string]any, error)
  • func (b *Browser) Extract(selector, attribute string, all bool) (map[string]any, error)
  • func (b *Browser) GetURL() (map[string]any, error)
  • func (b *Browser) Goto(rawURL string, waitForLoad bool) (map[string]any, error)
  • func (b *Browser) Screenshot(selector string, fullPage bool) (string, error)
  • func (b *Browser) SessionInfo() (map[string]any, error)
  • func (b *Browser) Type(selector, text string, clearFirst, submit bool) (map[string]any, error)
  • func (b *Browser) WaitFor(selector, expression string, timeoutMs int) (map[string]any, error)
• type BrowserOptions
• type Config
• type Server
  • func NewServer(cfg Config) *Server
  • func (s *Server) Run(ctx context.Context, in io.Reader, out io.Writer) error

Variables

var ErrIdleTimeout = errors.New("mcp: idle timeout")

ErrIdleTimeout is reported when the idle watchdog fires.

Types

type Browser

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

Browser wraps a single rod browser/page pair, providing a serialized API for tool calls. It lazy-launches Chrome on first use and can be torn down idempotently from any goroutine (EOF, idle timer, signal).

func NewBrowser

func NewBrowser(opts BrowserOptions) *Browser

NewBrowser returns an unstarted handle. Chrome is not launched until the first tool call that needs it (e.g. browser_goto).

func (*Browser) Click

func (b *Browser) Click(selector string, nth int, timeoutMs int) (map[string]any, error)

Click clicks the nth match of selector. nth defaults to 0.

func (*Browser) Close

func (b *Browser) Close()

Close tears down the browser if it was started. Safe to call multiple times.

func (*Browser) Eval

func (b *Browser) Eval(expression string) (map[string]any, error)

Eval evaluates a JS expression and returns its JSON-encoded result.

The expression is evaluated verbatim. To get a strict-bool, wrap it yourself: `Boolean(document.querySelector('a'))`. This avoids the rod MustEval bool gotcha by never assuming a type.

func (*Browser) Extract

func (b *Browser) Extract(selector, attribute string, all bool) (map[string]any, error)

Extract returns matches for selector. all=false returns at most one match. attribute, if set, returns the named attribute instead of text/html.

func (*Browser) GetURL

func (b *Browser) GetURL() (map[string]any, error)

GetURL returns the current URL and title.

func (*Browser) Goto

func (b *Browser) Goto(rawURL string, waitForLoad bool) (map[string]any, error)

Goto navigates the active page to url. wait_for_load defaults to true.

func (*Browser) Screenshot

func (b *Browser) Screenshot(selector string, fullPage bool) (string, error)

Screenshot captures either the full page or a single selector. Returns base64-encoded PNG.

func (*Browser) SessionInfo

func (b *Browser) SessionInfo() (map[string]any, error)

SessionInfo reports cookie count, URL, viewport, and UA.

func (*Browser) Type

func (b *Browser) Type(selector, text string, clearFirst, submit bool) (map[string]any, error)

Type focuses selector and types text. clear_first wipes existing input first. submit presses Enter after typing.

func (*Browser) WaitFor

func (b *Browser) WaitFor(selector, expression string, timeoutMs int) (map[string]any, error)

WaitFor blocks until either selector becomes visible or expression returns truthy, with a timeout. Exactly one of selector/expression must be set.

type BrowserOptions

type BrowserOptions struct {
	Headed     bool
	ProfileDir string
	Debug      bool
}

BrowserOptions configure how the lazy browser is launched.

type Config

type Config struct {
	Browser     *Browser
	IdleTimeout time.Duration // 0 = disabled
	Logger      *log.Logger   // defaults to stderr
}

Config configures the Server before Run.

type Server

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

Server is the MCP JSON-RPC server. One Server per `brz mcp` process.

func NewServer

func NewServer(cfg Config) *Server

NewServer constructs a Server with the registered tools.

func (*Server) Run

func (s *Server) Run(ctx context.Context, in io.Reader, out io.Writer) error

Run reads JSON-RPC messages from in and writes responses to out until in returns EOF or ctx is canceled. Browser teardown happens in Run's caller (cmd/brz/mcp.go) so signal handlers also work.