mcp

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 28, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package mcp serves chrome-cdp's verbs to Model Context Protocol clients over stdio (RFC-0004).

It is a FRONT END, not a fork. A tool call is validated, turned into exactly the argv a user would type, and run through the same cobra command tree against the same chrome.Browser; the envelope that comes back is mapped onto the MCP result with its `code` and `exit` intact. Nothing about a verb is implemented twice, which is what keeps the two front ends from drifting — TestMCPParityWithCLI in internal/cli is the guard.

Two invariants are load-bearing:

  • stdout is protocol, stderr is diagnostics. Every byte this package writes to stdout is a JSON-RPC frame. The command tree's human output is redirected away from stdout for the life of the server (see internal/cli/mcp.go), because one stray byte corrupts the stream and surfaces as an unexplained client failure far from its cause.

  • Errors keep the typed contract. A failure is `isError` with structured content carrying `code` and `exit`, never prose, so an agent branches on target_timeout vs permission_denied vs usage exactly as a shell script does — including the recoverable signals (`tab_hidden`, `occluded`).

Index

Constants

View Source
const (
	SetDefault = "default"
	SetFull    = "full"
)

Tool set names for Options.Tools.

Variables

This section is empty.

Functions

func Bind

Bind returns b with every call scoped to req: when req is cancelled, the context the driver sees is cancelled too. Close is deliberately NOT bound — it tears down the shared connection, which outlives any one request.

Types

type ArgSpec

type ArgSpec struct {
	Name     string
	Type     string
	Flag     string
	Enum     []string
	Required bool
	Pos      bool
}

ArgSpec is one argument of a ToolSpec. Flag is the CLI flag it mirrors, empty for a positional or synthetic argument.

type Options

type Options struct {
	// ReadOnly exposes only tools that cannot modify page state. The decision
	// comes from the policy layer's verb classification (internal/policy), not
	// from a second table here: one classification table means `--read-only`
	// and a `read_only` policy origin can never disagree.
	ReadOnly bool
	// Tools is "default", "full", or a comma-separated list of tool names
	// (with or without the chrome_cdp_ prefix).
	Tools string
	// DenyVerbs lists the CLI verbs the effective policy refuses everywhere —
	// the configured `verbs_denied`, plus MCP mode's own eval/raw default. A
	// tool whose every verb is denied is not exposed: it would answer every
	// call with permission_denied, and an agent pays for its description
	// either way.
	DenyVerbs []string
	// Target pins every call to one tab. With it set, a call that names a
	// different tab is refused rather than silently redirected.
	Target string
	// Version is reported to the client in the initialize handshake.
	Version string
	// Log receives human diagnostics. It must never be stdout: stdout carries
	// the protocol.
	Log io.Writer
}

Options configure a server. The zero value exposes the default tool set with no pinned tab.

type Runner

type Runner interface {
	Run(ctx context.Context, argv []string) (envelope []byte, exit int)
}

Runner executes one CLI argv and hands back the JSON envelope it printed and the exit code it would have produced. It is the seam between this package and internal/cli; internal/cli implements it over a shared, connected App, and tests implement it with canned envelopes.

The envelope bytes are exactly what `--json` writes to stdout, so a Runner that reimplemented any of it would be a fork by another name.

type Server

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

Server is the MCP front end. Build one with New and serve it with Run.

func New

func New(r Runner, o Options) (*Server, error)

New builds a server exposing the tools o selects, backed by r.

func (*Server) Run

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

Run serves the protocol over r/w until ctx ends or the client disconnects. In production these are stdin and the process's real stdout, and nothing else is allowed to write to the latter.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, t sdk.Transport) error

Serve runs the server on any SDK transport. Tests use an in-memory pair rather than a subprocess.

type ToolSpec

type ToolSpec struct {
	Name  string
	Title string
	Verbs []string
	Args  []ArgSpec
}

ToolSpec is a read-only view of one registered tool, for callers that need to reason about the surface without invoking it — the docs, and the conformance test in internal/cli that checks every argument still mirrors a live CLI flag.

func Specs

func Specs(o Options) ([]ToolSpec, error)

Specs returns the tools a server built with o would expose, in listing order.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL