Seer SnowBrowser MCP Interface

Purpose

Seer SnowBrowser exposes its local Model Context Protocol server over stdio. It gives an AI client a finite, typed control surface over one startup-scoped target or multiple projects explicitly registered in the local Console, while keeping target configuration, browser-native objects, physical paths, process authority, credentials, registry mutation, and confirmation capabilities outside the protocol.

This document describes manifest schema version 2. The server implementation uses the stable @modelcontextprotocol/sdk@1.30.0 line and Node.js 22.12 or newer. The version 1 manifest schema remains available as a documented schema resource.

Start And Discover

Install dependencies and prepare the resolved browser environment before starting the server:

npm install
. .\scripts\resolve-extension-runtime-env.ps1
node .\src\mcp\seer-snowbrowser-mcp.mjs --root E:\path\to\target
# Or reuse the Console registry across multiple projects:
node .\src\mcp\seer-snowbrowser-mcp.mjs --registry --max-concurrent-jobs 8

Options:

Option	Meaning
`--root <absolute-or-resolvable-path>`	Selects single-target mode and permanently scopes this process to one target root.
`--config <relative-path>`	Optional; defaults to `seer-snowbrowser.config.json` and must resolve inside the target root.
`--registry`	Selects multi-project mode using the existing local Console registry. Mutually exclusive with `--root` and `--config`.
`--max-concurrent-jobs <1-32>`	Bounds concurrent jobs in this MCP process; defaults to `4`. Shared jobs using the same profile name are serialized before launch.
`--manifest`	Prints the path-independent manifest and exits without loading a target or connecting stdio.
`--help`	Prints command help and exits.

The manifest validates against schemas/seer-snowbrowser.mcp-manifest.v2.schema.json. MCP clients can read it from seer-snowbrowser://schemas/mcp-manifest-v2 after connecting.

Generic MCP host configuration:

{
  "mcpServers": {
    "seer-snowbrowser": {
      "command": "node",
      "args": [
        "E:\\Codex\\SeerSnowBrowser\\src\\mcp\\seer-snowbrowser-mcp.mjs",
        "--registry"
      ]
    }
  }
}

Use an absolute script path because the host may start the process from another working directory. Register trusted projects once through seer-snowbrowser console; one registry-mode server can then select any available entry by logical projectId. Use --root instead when intentionally limiting one MCP configuration to one target.

Tool Result Contract

Every tool returns the same structured envelope in both MCP structuredContent and JSON text content. seer_snowbrowser_read_screenshot additionally returns one MCP image content item; its structured envelope contains only the verified path-free descriptor, not base64 data or a physical path.

Success:

{ "ok": true, "data": {} }

Failure sets MCP isError: true:

{
  "ok": false,
  "error": {
    "category": "BROWSER",
    "code": "BROWSER_LAUNCH_FAILED",
    "message": "launch failed",
    "retryable": false,
    "runId": "optional-logical-run-id"
  }
}

category is one of ENV, PROCESS, BROWSER, EXTENSION, TARGET, TEST, or POLICY. Optional error fields are phase, subsystem, evidenceRefs, and runId. Error details, physical paths, tokens, and credentials are not projected.

Tools

All input objects are strict: unknown fields are rejected.

Tool	Input	Result and authority
`seer_snowbrowser_list_projects`	`{}`	Lists path-free projects allowed by the startup scope or Console registry. Read-only.
`seer_snowbrowser_doctor`	`{}`	Finite path-free availability for `playwright-cft` and `puppeteer-chrome`. Read-only.
`seer_snowbrowser_run`	Optional `projectId`, `runtime`, `profileMode`, `profileName`, `headful`, `reason`, `externalWrite`, `testNames`, `maxParallelPages`	Runs one allowed project synchronously and returns its verified catalog DTO. Always finalizes. `testNames` selects 1-128 exact configured test names in request order; `maxParallelPages` overrides the v2 bounded page-worker capacity from 1-32. May open a browser or reach configured targets.
`seer_snowbrowser_start_debug`	Optional `projectId`, `profileName`, `headful`, `reason`, `externalWrite`, `interactionPolicy`	Starts an asynchronous debug-only `puppeteer-chrome` job for a project with configured extensions. It uses an explicit persistent shared Profile, skips normal tests, keeps only owned resources open, and returns a logical job DTO.
`seer_snowbrowser_extension_debug`	`runId`, `action`, `logicalName`; optional `projectId`, target/source/evaluation/breakpoint/event fields	Calls the authenticated finite extension-debug channel of an active run. Actions are `targets`, `scripts`, `reload`, `evaluate`, `pause`, `resume`, `setBreakpoint`, `removeBreakpoint`, `paused`, and `events`. Results are bounded and redacted; no CDP session, target ID, object ID, PID, physical path, or control token is exposed.
`seer_snowbrowser_start_runs`	`runs`: 1-32 strict run requests using the `seer_snowbrowser_run` fields; optional `profilePool`, `interactionPolicy`, `failurePolicy`	Validates all requested projects, freezes a batch plan, queues it, and immediately returns logical batch/job DTOs plus `maxConcurrentJobs`. `profilePool` round-robins otherwise-unspecified shared jobs over 1-32 explicit named lanes.
`seer_snowbrowser_list_jobs`	`{}`	Lists finite in-memory job state for runs started by this MCP process. Read-only.
`seer_snowbrowser_inspect_job`	`jobId`	Returns one finite in-memory job DTO without paths, PIDs, process handles, or control authority. Read-only.
`seer_snowbrowser_cancel_job`	`jobId`	Cancels one pending job. A running job is not force-killed and retains normal owned cleanup.
`seer_snowbrowser_list_batches`	`{}`	Lists finite in-memory batch state and aggregate counts. Read-only.
`seer_snowbrowser_inspect_batch`	`batchId`	Returns one batch DTO with its current path-free job DTOs. Read-only.
`seer_snowbrowser_cancel_batch`	`batchId`	Cancels the batch's pending jobs. Running jobs continue to normal finalization and cleanup.
`seer_snowbrowser_list_runs`	Optional `projectId` plus bounded filters: `statuses`, `qualifiers`, `runtimeIds`, `profileNames`, `from`, `to`, `limit`, `cursor`	Bounded verified run DTO page for one project. Read-only.
`seer_snowbrowser_inspect_run`	`runId`, optional `projectId`	Strict Artifact v1/v2 catalog DTO selected by logical IDs. Read-only.
`seer_snowbrowser_read_events`	`runId`, optional `projectId`, `cursor`, `limit`, `kinds`	Bounded redacted Artifact v2 event page. Read-only.
`seer_snowbrowser_read_screenshot`	`runId`, manifest `relativePath`, optional `projectId`	Returns one published PNG, JPEG, or WebP screenshot as MCP image content after strict run, manifest, type, directory-identity, size, and SHA-256 verification. Read-only; maximum 16 MiB.
`seer_snowbrowser_stop`	`runId`, optional `projectId`	Requests authenticated normal cleanup for an allowed kept-open run. There is no PID fallback.
`seer_snowbrowser_list_profiles`	`runtimeId`	Logical profile existence/lock metadata without physical paths or owner PID. Read-only.
`seer_snowbrowser_inspect_profile`	`runtimeId`, `name`	One logical profile's existence and lock metadata. Read-only.
`seer_snowbrowser_reset_profile`	`runtimeId`, `name`, non-empty `reason`	Destructively resets a Seer SnowBrowser-owned persistent profile only after a fresh visible target-bound confirmation.

In registry mode, project-specific tools require projectId; omitting it returns PROJECT_REQUIRED. In single-target mode, projectId is optional and defaults to the startup target, preserving v1.1 behavior. An unknown or unavailable registry entry returns PROJECT_NOT_FOUND or PROJECT_UNAVAILABLE without exposing its path.

Valid runtime values are auto, playwright-cft, and puppeteer-chrome. Profile operations remain global and require a concrete runtime. Valid profile names match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. profileMode is shared or isolated; an isolated request must not also supply profileName.

Background job states are pending, running, waiting, stopping, completed, failed, blocked, or cancelled. Batch states are pending, running, completed, failed, blocked, cancelled, partial, or expired. Job and batch state live only in the current MCP server process; completed run artifacts remain available through the catalog after a server restart. A shared profile name is a scheduling affinity key: jobs with the same name serialize, while distinct names can run concurrently up to the process bound. For version 2 targets, profilePool assigns explicit shared lanes round-robin without silently converting work to isolated mode; version 1 accepts only general or isolated. general is never silently replaced. testNames creates exact run-level shards; independently, maxParallelPages > 1 lets one eligible v2 run execute named page scenarios explicitly declared without external writes as bounded Page Workers inside its single profile owner. Ineligible combinations fail before browser launch. Configuration authors remain responsible for declaring interactions that can create remote side effects; eligibility is not static proof of page behavior.

interactionPolicy is unattended or prompt; batch and debug start default to unattended. Under unattended, any run that reaches a fresh-confirmation gate is immediately recorded as blocked without opening a dialog. prompt must be explicitly requested and preserves the visible, current-run confirmation flow. failurePolicy is continue or fail-fast; fail-fast cancels only jobs still pending after the first failed or blocked job. Explicit job/batch cancellation has the same pending-only boundary, so active owned processes are never abandoned or killed by a queue operation.

For extension debugging, first call seer_snowbrowser_start_debug, then poll seer_snowbrowser_inspect_job until its runId is available and the job is waiting in the owned keep-open phase. Call seer_snowbrowser_extension_debug with that runId and the configured extension's logical name. Target selectors are limited to service-worker and page; optional targetPath disambiguates a configured extension resource. Source lines and columns are one-based. Breakpoint IDs are logical Seer SnowBrowser IDs and are restored after a same-ID/same-path extension reload. paused projects a maximum of 16 call frames and finite scope properties; evaluate can use callFrameIndex from 0 through 15. Events are cursor-paged with a maximum limit of 100.

evaluate requests throwOnSideEffect by default. allowSideEffects: true is accepted only when the debug run has current external-write authority. Conditional breakpoints have the same gate because Chrome can evaluate their condition in the target realm. reload is an explicit mutating extension-lifecycle action: it closes only the configured extension's exact Service Worker target, re-installs the same unpacked path while asserting the extension ID is unchanged, wakes the worker if needed, and restores logical breakpoints. Wake-up uses a per-request random runtime message from a temporary owned extension page; Chrome therefore dispatches one application-visible message to the extension's generic runtime listeners, although no stable application command is reused. If Chrome unexpectedly returns a different extension ID, Seer SnowBrowser removes only that unexpected installation as rollback and fails the reload. It never uninstalls the configured extension ID, resets a Profile, attaches to daily Chrome, or exposes raw CDP.

Example unattended two-lane shard request:

{
  "runs": [
    { "testNames": ["desktop"], "reason": "desktop shard" },
    { "testNames": ["mobile"], "reason": "mobile shard" }
  ],
  "profilePool": ["batch-01", "batch-02"],
  "interactionPolicy": "unattended",
  "failurePolicy": "fail-fast"
}

The MCP surface deliberately has no project add/remove tool. Normal run tools have no arbitrary root, config path, keep-open, stored approval, shell, unrestricted script evaluation, raw CDP, or raw artifact parameter. The dedicated extension-debug tools can keep one owned debug-only job open and evaluate only inside a configured extension target through the finite contract above. externalWrite: true requests the existing current-run gate; it does not grant approval, persist it, or bypass the visible confirmation required by the validated target policy. Screenshot reading is a separate finite tool: callers choose only a relative path already present in the selected run's verified manifest, and non-screenshot, unpublished, oversized, escaped, replaced, linked, or hash-mismatched content is rejected. An isolated profile also requires its own fresh visible confirmation.

Resources

URI	MIME type	Contents
`seer-snowbrowser://project`	`application/json`	Path-free current scope: target metadata in single-target mode or registry summary in registry mode.
`seer-snowbrowser://projects`	`application/json`	Path-free list of projects allowed by the current scope.
`seer-snowbrowser://projects/{projectId}`	`application/json`	Path-free metadata for one allowed project.
`seer-snowbrowser://docs/user-guide-en`	`text/markdown`	English user guide.
`seer-snowbrowser://docs/user-guide-zh`	`text/markdown`	Independent Simplified Chinese user guide.
`seer-snowbrowser://docs/api`	`text/markdown`	This interface contract.
`seer-snowbrowser://docs/architecture`	`text/markdown`	Architecture and authority boundaries.
`seer-snowbrowser://schemas/config-v1`	`application/schema+json`	Version 1 target config schema.
`seer-snowbrowser://schemas/config-v2`	`application/schema+json`	Version 2 target config schema.
`seer-snowbrowser://schemas/mcp-manifest-v1`	`application/schema+json`	Version 1 manifest schema.
`seer-snowbrowser://schemas/mcp-manifest-v2`	`application/schema+json`	Current multi-project manifest schema.
`seer-snowbrowser://runs/{runId}`	`application/json`	Single-target run DTO selected by logical runId. Registry mode requires the project-qualified URI.
`seer-snowbrowser://projects/{projectId}/runs/{runId}`	`application/json`	One strict, verified Artifact v1/v2 run DTO selected by project and run IDs.

Resources do not raw-serve run directories. The screenshot tool is the only MCP image-byte seam and serves only verified published screenshot entries; traces, downloads, logs, credentials, physical profile directories, control records, process handles, native browser objects, and arbitrary local files remain outside the MCP surface.

Recommended AI Workflow

Read seer-snowbrowser://project; in registry mode call seer_snowbrowser_list_projects and select the intended projectId.
Call seer_snowbrowser_doctor before the first run or after an environment failure.
For one synchronous result, call seer_snowbrowser_run. For the zero-touch batch path, call seer_snowbrowser_start_runs with explicit testNames shards, a finite profilePool, the default interactionPolicy: "unattended", and the desired failurePolicy; headless execution, evidence, finalization, and cleanup do not require a Browser window or manual input. For extension development, call seer_snowbrowser_start_debug with a named persistent Profile, wait for its runId, then use seer_snowbrowser_extension_debug and finally seer_snowbrowser_stop.
Poll seer_snowbrowser_list_batches/seer_snowbrowser_inspect_batch for batch progress or the job-level tools for one lane. Use cancel only for queued work; after a job exposes runId, use the normal project-qualified run and event interfaces for durable evidence.
Read artifactManifest, select a published entry whose type is screenshot, and call seer_snowbrowser_read_screenshot with that exact relativePath to inspect the rendered evidence.
Treat blocked as a denied or unavailable policy gate, and never reinterpret relaxed-web as production-equivalent success.
Do not request manual interaction for normal jobs. Keep batch work unattended so consequence gates fail closed as blocked; use explicit prompt only when an isolated run or real external write is genuinely required. Destructive profile reset always remains a separate fresh visible confirmation.

Non-Goals

Manifest schema version 2 adds registry mode, project-qualified resources, verified screenshot delivery, background job/batch controls, the bounded maxParallelPages run input, and finite extension debugging. The current inventory contains twenty seer_snowbrowser_* tools and seer-snowbrowser:// resources. Additive result fields may appear when the underlying verified catalog evolves; clients should rely on named fields and the ok envelope.

The MCP surface is not a general browser remote-control API, file browser, terminal, unrestricted CDP bridge, unrestricted artifact download service, or replacement for target-owned business assertions. It intentionally supports verified screenshot delivery for Codex visual QA and a bounded DevTools-like interface for configured unpacked MV3 extensions; product-specific facts remain in the target config and tests.

FilesExpand file tree

API.md

Latest commit

History