Skip to main content
Glama
HaidarESBER

ecobrowser MCP server

by HaidarESBER

🌐 ecobrowser β€” AI-Native Browser Framework

The AI's hands and eyes on the web

A browser built to be driven by an AI β€” the perception and action layer that gives an agent fast, complete, verifiable control of the web. Ships on npm as ecobrowser: a TypeScript library and an MCP server in one package.

npm TypeScript Node Playwright MCP Tools Tests License

Structured (no-pixel) perception Β· verified self-healing actions Β· incremental diff perception Β· a live view to watch it work.


Table of contents


Related MCP server: Playwright MCP Server

What is this?

Most "AI browsers" are one of two things: a chat sidebar bolted onto a browser, or a headless scraping API with no feedback loop. This is neither. It's the layer that makes a real browser usable by a model β€” the primary "user" is an AI, and a human just supervises.

It gives an agent a compact, structured view of a page (an addressable list of interactive elements, not a screenshot), lets it act on those elements by stable id, tells it whether each action actually worked, and streams the whole thing to a live view a human can watch. It's model-agnostic and downloadable β€” not tied to one vendor's extension.

The design principle, everywhere: do work in code so the model doesn't spend tokens and reasoning on it β€” verifying outcomes, diffing pages, recovering from failures, finding elements.

⚠️ Scope & honesty. This is a fast, local, single-user developer tool, built to be pointed at your own or authorized sites. It's young β€” thoroughly tested on its own paths, but not battle-hardened across thousands of real websites the way mature tools are. See Security & scope.


✨ Highlights

πŸ‘οΈ Structured perception

The AI sees a compact list of interactive elements with stable ids — no screenshot→vision round-trip.

🎯 Act by id

Click/type/select by e3, never by guessed CSS selectors or pixel coordinates.

βœ… Verified actions

Every action returns did it work and did the page change β€” success / silent no-op / failure, not a guess.

🩹 Self-healing

If an element's id moved (page re-rendered), it re-locates the element by identity and retries.

πŸ”— Durable ids

An element keeps its id across snapshots, so the AI can reference something it saw steps ago.

⚑ Incremental perception

changes() returns only the delta; snapshots are cached until the DOM actually changes.

πŸ”Ž find(description)

Ask for "the search box" and get just the match β€” not a whole-page dump.

πŸ› First-class debugging

Console logs, page errors, and network requests captured β€” errors scoped to the action that caused them.

πŸ–₯️ Live view

Watch a headless run in your browser β€” refreshing screenshot + colour-coded action trace.

πŸ”Œ MCP + npm

One engine, two front doors: an MCP server (zero-code) and a typed TypeScript library.


πŸ— Architecture

flowchart TD
    AI["πŸ€– AI client<br/>Claude Desktop Β· Cursor Β· your agent"]
    MCP["<b>mcp.ts</b><br/>MCP server Β· 13 tools"]
    LIVE["<b>live.ts</b><br/>live-view server"]
    ENGINE["<b>browser.ts</b><br/>AIBrowser / AIPage<br/><i>the whole product</i>"]
    CHROME["Chromium<br/>(headless by default)"]
    HUMAN["πŸ§‘ human<br/>watches &amp; supervises"]

    AI -- "JSON-RPC 2.0 / stdio" --> MCP
    MCP -- "method calls" --> ENGINE
    ENGINE -- "Chrome DevTools Protocol" --> CHROME
    ENGINE -- "events + frames" --> LIVE
    LIVE -- "screenshot + action trace" --> HUMAN

    classDef eng fill:#6E56CF,stroke:#4C3A9E,color:#fff;
    classDef srv fill:#1e2a3a,stroke:#89b4fa,color:#cdd6f4;
    class ENGINE eng;
    class MCP,LIVE srv;

One engine, two front doors. All the real logic lives in browser.ts. mcp.ts is a thin adapter that exposes the engine's methods as protocol tools; live.ts is a read-only window for a human. The same engine could be wrapped as a CLI or REST API β€” MCP is just one adapter.


🧠 How it works

Perception β†’ action β†’ verification

flowchart LR
    A["act by id<br/>(click / type / select)"] --> B{"element<br/>found?"}
    B -- yes --> C["smart-wait<br/>+ act"]
    B -- "no · id moved" --> H["🩹 self-heal:<br/>re-locate by identity"]
    H --> C
    C --> D{"effect<br/>verified?"}
    D -- yes --> OK["βœ… ActionResult<br/>ok Β· changed?"]
    D -- "no Β· error" --> R{"retries<br/>left?"}
    R -- yes --> C
    R -- no --> F["⚠️ ActionResult<br/>fail + heal hint"]

    classDef ok fill:#1e3a2e,stroke:#a6e3a1,color:#a6e3a1;
    classDef bad fill:#3a1e26,stroke:#f38ba8,color:#f38ba8;
    class OK ok;
    class F bad;

Perception runs a script inside the page that collects interactive elements, stamps each with a durable data-ai-id, and captures role / name / value / state. A MutationObserver tracks a DOM version, so unchanged snapshots are served from cache and changes() can return just the delta.

The MCP conversation

sequenceDiagram
    participant AI as πŸ€– AI client
    participant S as mcp.ts (server)
    participant E as browser.ts (engine)
    AI->>S: initialize
    S-->>AI: capabilities
    AI->>S: tools/list
    S-->>AI: 13 tools + JSON schemas
    Note over AI: the model now knows what it can do
    AI->>S: tools/call Β· browser_navigate {url}
    S->>E: goto() + snapshot()
    E-->>S: structured elements
    S-->>AI: content:[ text ]
    AI->>S: tools/call Β· browser_click {id}
    S->>E: clickById() β†’ verify β†’ heal
    E-->>S: ActionResult + delta
    S-->>AI: content:[ text ]

It's an MCP server because it registers schema-typed tools and answers initialize / tools/list / tools/call as JSON-RPC 2.0 over stdio β€” the browser control is just what those tools happen to do.


πŸš€ Quick start

Prerequisites: Node.js 18+.

npm install ecobrowser

Chromium is downloaded automatically on install (a postinstall hook). If you install with --ignore-scripts, fetch it manually: npx playwright install chromium.

Option A β€” as an MCP server (drive it from an AI)

Claude Desktop β€” add to claude_desktop_config.json:

{
  "mcpServers": {
    "ecobrowser": {
      "command": "npx",
      "args": ["-y", "ecobrowser-mcp"],
      "env": { "AI_BROWSER_HEADED": "1" }
    }
  }
}

Claude Code:

claude mcp add ecobrowser -- npx -y ecobrowser-mcp

Restart the client, then just ask: "navigate to example.com and list the links."

Run npx ecobrowser-mcp --help for setup, the full tool list, and environment variables.

(Working from a clone instead of the published package? Point the client at the source directly: npx tsx <repo>/src/mcp.ts.)

Option B β€” as a TypeScript library

import { AIBrowser } from "ecobrowser";

const browser = await AIBrowser.launch({ headless: true });
const page = await browser.newPage();

await page.goto("https://example.com");

const snap = await page.snapshot();          // { url, title, elements: [{ id, tag, role, name, value?, state? }] }
const [search] = await page.find("search box");

const result = await page.clickById(snap.elements[0].id);
console.log(result.detail);                  // "click e0 succeeded (page changed)."

const diff = await page.changes();           // { added, removed, changed, unchanged }
console.log(page.console(), page.network()); // first-class debugging

await browser.close();

🧰 MCP tools

The server exposes 13 tools; an MCP client discovers them (name + JSON schema) via tools/list.

Tool

What it does

browser_navigate

Open a URL, return a structured snapshot.

browser_snapshot

Structured snapshot of the current page (cached until it changes).

browser_changes

Only what changed since your last snapshot β€” cheap re-perception.

browser_find

Find interactive elements matching a description; get just the matches.

browser_read_text

Visible text of the page.

browser_back

Go back in history.

browser_click

Click an element by id (verified, self-healing); returns the delta.

browser_type

Type into a field by id (verifies the value landed).

browser_console

Console logs + page errors on the current page.

browser_network

Network responses (status, method, url).

browser_evaluate

Run a JS expression in the page, return the result.

browser_extract_links

All links as name/href pairs.

browser_reset

Discard the session; the next action starts fresh (crash recovery).


πŸ“Š How it compares (measured)

Head-to-head vs Playwright MCP on the same page (npm run bench), measuring bytes returned to the model and tool latency.

Full page snapshot β€” smaller is better

This framework   β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘   41 KB   (~10K tokens)
Playwright MCP   β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ  128 KB   (~32K tokens)

Re-perceive latency β€” smaller is better

This framework   ▏                           5 ms   (cache hit)
Playwright MCP   β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ  150 ms   (re-serializes every time)

Incremental re-perceive after an action

This framework   ▏  delta only (bytes)
Playwright MCP   β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ  full page again  (no diff primitive)

Honest caveats. This measures perception payload + tool latency, not end-to-end LLM wall-clock (no live model ran). Part of the size gap is scope β€” we capture interactive elements only, Playwright MCP captures the full accessibility tree. And we're faster than Playwright MCP (the wrapper), not Playwright (the shared engine under both) β€” the wins are caching, diffing, and a leaner format, all ideas a competitor could adopt.


βš™οΈ Configuration

Env var

Effect

AI_BROWSER_HEADED=1

Show the native browser window (default: headless).

AI_BROWSER_LIVE=0

Disable the live-view server.

AI_BROWSER_LIVE_PORT=N

Preferred live-view port (default 7333, steps to the next free port if busy).

AI_BROWSER_ALLOW_LOCAL=1

Allow file:// / privileged-scheme navigation (blocked by default).

Live view: when the MCP server starts it also serves a loopback-only page (default http://localhost:7333) β€” a refreshing screenshot plus a colour-coded action trace β€” so you can watch a headless run.


πŸ“œ Scripts

npm test           # unit tests (diff, find, state, url-guard) β€” no browser needed
npm run build      # compile the publishable package to dist/ (library + MCP bin)
npm run typecheck  # tsc --noEmit over everything, dev scripts included
npm run demo       # exercises the engine directly (headed; AI_BROWSER_HEADED=0 for headless)
npm run smoke      # spawns the MCP server as a real MCP client and drives it
npm run live       # starts the live view and verifies its endpoints
npm run bench      # head-to-head vs Playwright MCP
npm run mcp        # run the MCP server on stdio

Benchmark note: Playwright MCP is a devDependency; install its browser once with npx @playwright/mcp install-browser chrome-for-testing before npm run bench.


πŸ—‚ Project layout

src/
  index.ts         # public package entry β€” re-exports the engine + LiveView
  browser.ts       # the core engine β€” AIBrowser / AIPage (this is the whole product)
  mcp.ts           # MCP server: registers the engine's methods as 13 tools (the ecobrowser-mcp bin)
  live.ts          # live-view server (screenshot + action trace)
  demo.ts          # in-code engine demo (5 parts, incl. self-healing)
  mcp-smoke.ts     # end-to-end MCP client test
  live-smoke.ts    # live-view endpoint test
  bench-h2h.ts     # head-to-head benchmark vs Playwright MCP
  test.ts          # unit tests for the pure logic
tsconfig.build.json # build config β€” compiles only the public surface to dist/
SPEC.md            # full technical specification, north star, roadmap

Only dist/ (plus README, SPEC, LICENSE) ships in the npm tarball β€” the dev scripts stay in the repo.


πŸ”’ Security & scope

Because it's a downloadable tool you run yourself, how it's used is your responsibility. Built-in guards:

  • Loopback-only live view β€” never exposed to the LAN; the trace is rendered XSS-safely (textContent, never innerHTML).

  • Navigation guard β€” file://, chrome://, javascript: and other privileged schemes blocked by default (AI_BROWSER_ALLOW_LOCAL=1 to opt out).

  • Bounded & recoverable β€” capped logs, per-tool timeouts, automatic crash recovery, graceful shutdown, port fallback.

Deliberately not in scope: multi-tenant hosting, auth/session isolation between users, or sandboxing browser_evaluate (which runs arbitrary JS in the page β€” appropriate only for sites you trust). Point it at your own or authorized sites.


πŸ—Ί Roadmap

flowchart LR
    M0["M0 Β· spike"] --> M1["M1 Β· engine"] --> REL["reliability<br/>+ self-heal"] --> M3["M3 Β· MCP"] --> M4["M4 Β· speed"] --> M5["M5 Β· live view"] --> AIF["AI-friendliness"] --> HARD["hardening"] --> M2["M2 Β· npm<br/>package"] --> M6["M6 Β· auth/proxy<br/>(BYO) πŸ“¦ next"]

    classDef done fill:#1e3a2e,stroke:#a6e3a1,color:#a6e3a1;
    classDef next fill:#3a2e1e,stroke:#f9e2af,color:#f9e2af;
    class M0,M1,REL,M3,M4,M5,AIF,HARD,M2 done;
    class M6 next;

Built and tested: the engine, reliability + self-healing, the MCP server, caching + diff perception, the live view, the AI-friendliness pass, the hardening pass, and the npm package (ecobrowser, with the ecobrowser-mcp bin). Next β€” M6: opt-in, BYO-key auth/proxy/CAPTCHA for authorized sites.

See SPEC.md for the full specification and north star.



πŸ‘€ Author

Built by Haidar Esber β€” Lebanese software & web developer based in France.

Portfolio Β· GitHub Β· LinkedIn

Available Tools

13 tools
browser_backA

Go back in the browser history.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description only states the basic function. It does not disclose behavioral traits such as what happens if no history exists, whether it preserves scroll position, or if it triggers page reloads. With no annotations, the description carries the full burden but adds minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, using a single sentence with no wasted words. It is front-loaded and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (no parameters, no output schema), the description is adequate but misses some contextual details like error states (e.g., no history to go back to) or interaction with other browser tools. It meets the minimum viable but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the description doesn't need to add paramenter meaning. Baseline for 0 parameters is 4. The description is sufficient for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: going back in browser history. It specifies the resource (browser history) and distinguishes from siblings like browser_navigate (which goes to a specific URL) and browser_reset (which resets state).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidance is provided. The description does not mention when to use this tool versus alternatives like browser_navigate or browser_forward, nor does it indicate when not to use it (e.g., if there is no history).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_changesA

Return ONLY what changed since your last snapshot (added/removed/changed elements). Cheaper than a full snapshot β€” prefer this after an action.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses return of diffs and cost benefit, but does not mention side effects like snapshot state reset or read-only nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences with no wasted words. Action and key differentiator front-loaded, cost hint follows.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate given no output schema and no annotations. Describes return type, compares to sibling, and gives usage guidance. Could mention safety (read-only) but not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters with 100% schema coverage; description adds value by explaining output and usage context, meeting baseline for param-free tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Return' and resource 'changed since your last snapshot', specifying added/removed/changed elements. Distinguishes from full snapshot with cost and usage preference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'prefer this after an action', guiding when to use. Implicitly contrasts with browser_snapshot for full analysis, but no explicit list of when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_clickA

Click an element by its snapshot id. Returns a fresh snapshot after the action.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesElement id from a snapshot, e.g. 'e0'

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must carry full burden. It mentions state change (click action) and return of a fresh snapshot, but lacks details on prerequisites (e.g., element visibility), error handling, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with essential information front-loaded. No unnecessary words or details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple click action with one parameter and no output schema, the description is nearly complete. It specifies input (id) and output (fresh snapshot), though it could mention error conditions or element visibility.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema provides full description for the single parameter 'id' (e.g., 'e0'). The description adds no further meaning, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly specifies the action (click), target (element by snapshot id), and outcome (returns fresh snapshot). It distinguishes well from sibling tools like browser_type and browser_find.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance. Usage is implied by the action, but no alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_consoleA

Return console logs and page errors captured on the current page.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states what it returns but does not disclose side effects, read-only behavior, or whether calling this clears the logs. For a tool that likely consumes resources, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that clearly conveys the tool's purpose without extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description tells what it returns but does not specify the format (e.g., array of strings, structured objects). No output schema exists. Without annotations or context, the agent must infer return type, which is a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100% (vacuously). Per calibration, baseline is 4. No additional parameter info is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns console logs and page errors, which is a specific verb+resource. This distinguishes it from siblings like browser_snapshot (visual) and browser_network (network logs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like browser_network or browser_read_text. The description does not mention when it is appropriate to call this function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_evaluateA

Run a JavaScript EXPRESSION in the page and return its JSON-serialized result (e.g. document.title or [...document.links].length). Not a statement body.

ParametersJSON Schema
NameRequiredDescriptionDefault
jsYesA JS expression to evaluate in the page

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It clarifies the tool evaluates expressions (not statements) and returns JSON-serialized results. However, it does not disclose whether the expression can modify the page or what happens on errors (e.g., thrown exceptions). This is a moderate level of transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with an illustrative example, efficiently conveying the core functionality without redundancy. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately mentions the return format (JSON-serialized). It covers the main use case and constraint (expression vs statement). Minor gaps include error handling and side-effect disclosure, but it is largely complete for a simple read-oriented tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds context with examples of valid expressions, but the parameter description itself ('A JS expression to evaluate in the page') adds little beyond what is already stated in the tool description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool evaluates a JavaScript expression and returns JSON-serialized results, with concrete examples like `document.title`. It distinguishes itself from statement execution by explicitly saying 'Not a statement body', which differentiates from potentially similar tools like browser_console.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for reading dynamic page values, but does not explicitly state when to use this tool versus siblings like browser_console (which may run statements) or browser_read_text (which reads visible text). No alternative or exclusion criteria are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_findA

Find interactive elements matching a description (e.g. 'search box', 'Sign in button') and get just the matches with their ids β€” far cheaper than reading a full snapshot when you know what you want.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesWhat to look for, e.g. 'login button'

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the burden. It describes the action (find) and output (matches with ids), but omits details like whether it modifies state, searches hidden elements, or requires a loaded page. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action. It is slightly verbose due to examples and comparison, but remains efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description covers the input, action, output, and rationale. It is sufficiently complete for an agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear parameter description. The tool description reinforces the schema with additional examples. Since the schema already provides the necessary semantics, the description adds only marginal value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Find interactive elements matching a description' and gives concrete examples ('search box', 'Sign in button'). It distinguishes from siblings by highlighting cost savings over a full snapshot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly advises when to use this tool: 'far cheaper than reading a full snapshot when you know what you want.' It does not explicitly name alternatives or state when not to use, but the context suggests it is for targeted element discovery.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_navigateA

Open a URL and return a structured snapshot of the page's interactive elements.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to open

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the action (open URL) and output (snapshot), but does not disclose side effects like page loading behavior, potential errors, or whether it resets existing page state. This is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with key information (action and result). No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, no-output-schema tool, the description covers the essential aspects: what it does and what it returns. It could mention whether it waits for page load or handles errors, but is otherwise sufficient for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully covers the single parameter 'url' with a clear description. The description adds minimal extra meaning, which is acceptable for a simple parameter. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Open' and resource 'URL', clearly distinguishing it from sibling tools like browser_back or browser_click. It also states the return value: a structured snapshot of interactive elements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for navigating to a new URL, which is clear from context. However, it does not explicitly mention when not to use it (e.g., when already on a page), nor does it provide alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_networkA

Return the network responses (status, method, url) captured on the current page.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It explains that data is 'captured on the current page', suggesting a read-only retrieval. However, it does not disclose whether all network responses are included, if data persists, or any permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the verb and resource, and contains no wasted words or extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no parameters and no output schema, the description is mostly complete. It could mention that it returns only captured responses so far, but the current description is sufficient for basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the description adds value by specifying what is returned (status, method, url). Per guidelines, 0 parameters baseline is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'network responses' with specific details (status, method, url) and context 'captured on the current page'. It distinguishes from sibling tools like browser_console (console logs) or browser_navigate (page loading).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when network request data is needed, but does not explicitly state when to use it over alternatives or mention exclusions. No guidance on prerequisites or context for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_read_textA

Return the visible text content of the current page (truncated).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavior. It mentions truncation but does not specify truncation limits or whether the method is non-destructive. For a read operation, basic safety is implied but not stated, and dynamic content behavior is unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, front-loaded with the core action. Highly concise and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters, no output schema, and no annotations, the description is adequate but could elaborate on truncation behavior or indicate that returns plain text. Sibling tools are present but not compared. Slightly incomplete for full context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters (schema has no properties), and schema description coverage is 100%. Description adds no parameter information, but baseline is 4 for zero-parameter tools since there is nothing to explain.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool returns visible text content of the current page, with truncation noted. Verb 'Return' and resource 'visible text content' are specific, and 'truncated' adds an important detail. It distinguishes well from siblings like browser_snapshot or browser_find.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like browser_snapshot or browser_changes. No when-not-to-use or prerequisites are mentioned, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_resetA

Close and discard the current browser session; the next action starts a fresh one. Use to recover from a wedged or crashed page.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description fully discloses the destructive behavior: closing and discarding the session, losing state. Mentions it starts a fresh session. No contradictions. Provides appropriate behavioral context for a reset operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each essential. First describes action, second gives use case. No extraneous words. Perfectly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, no parameters, and no annotations, the description fully explains the tool's purpose and behavior. Adequate for an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters (schema is empty with 100% coverage). For zero-parameter tools, baseline is 4. Description adds no parameter info because none needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'close and discard' and resource 'current browser session'. Distinguishes from sibling tools (browser_navigate, browser_back, etc.) which manipulate the same session rather than resetting it. No ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'recover from a wedged or crashed page'. Implies this is not for normal navigation or back/forward actions. Does not provide explicit when-not-to-use or alternatives, but context with sibling tools makes it clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_snapshotA

Get a structured snapshot of the current page β€” each interactive element has a stable id you can act on. Cached until the page changes.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses caching behavior ('Cached until the page changes') which is useful. However, it does not mention that the tool is read-only, nor does it describe the format of the snapshot or any potential cost (e.g., memory or time). Since no annotations are provided, the description carries burden but is somewhat vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences that front-load the purpose and then add key behavioral detail. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description covers the main point (snapshot with stable IDs) and adds caching info. It could be more specific about what 'structured' means, but it's sufficient for simple use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100%. Description adds no parameter information, which is acceptable. Baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it gets a structured snapshot of the current page and that each interactive element has a stable ID. This distinguishes it from sibling tools like browser_read_text or browser_find.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance. It implies using it before interactions to get stable IDs, but does not mention alternatives or conditions where another tool might be better.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser_typeA

Type text into a field by its snapshot id (clears the field first).

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesElement id from a snapshot
textYesText to type

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the clearing behavior, which is key, but does not mention side effects like triggering events or requiring focus. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Essential information is front-loaded and concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 2 parameters and no output schema, the description covers the main action, target identification, and a key behavior (clearing). Minor omission: does not specify the page context (currently focused page).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions. The description adds extra meaning by specifying 'by its snapshot id' and 'clears the field first', enhancing understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Type text into a field by its snapshot id' with the additional behavior 'clears the field first'. This provides a specific verb, resource, and method, effectively distinguishing from siblings like browser_click or browser_find.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for typing into a field identified by snapshot id, but does not explicitly state when to use vs alternatives or provide context on prerequisites. Sibling tools are different actions, so some guidance is implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 13 tool updatesv0.1.1
    • First observedbrowser_back
    • First observedbrowser_changes
    • First observedbrowser_click
    • First observedbrowser_console
    • First observedbrowser_evaluate
    • First observedbrowser_extract_links
    • First observedbrowser_find
    • First observedbrowser_navigate
    • First observedbrowser_network
    • First observedbrowser_read_text
    • First observedbrowser_reset
    • First observedbrowser_snapshot
    • First observedbrowser_type

TDQS

A4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: navigation, clicking, typing, snapshotting, finding elements, evaluating JavaScript, checking console/network, resetting, etc. Overlap is minimal (e.g., snapshot vs. changes are complementary, not ambiguous).

Naming Consistency5/5

All tools follow the 'browser_' prefix with snake_case verb_noun pattern (e.g., browser_navigate, browser_click, browser_snapshot). The naming is uniform and predictable.

Tool Count5/5

13 tools cover the core browser automation actions without being too many or too few. The count is well-scoped for the domain, providing necessary functionality without bloat.

Completeness4/5

The set covers essential browser interactions: navigation, clicking, typing, state inspection, JS evaluation, console/network monitoring, and session reset. Minor gaps exist (e.g., no explicit scrolling or screenshot), but these can be worked around via JS evaluation.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to control Chrome browser actions like navigation, clicking, form filling, screenshots, and console/network logging via an MCP server and Chrome extension.
    717
    MIT
  • A
    license
    B
    quality
    A
    maintenance
    Provides AI agents with a real browser environment for web automation, memory, and secure credential management through 15 MCP tools.
    15
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/HaidarESBER/ai-browser'

If you have feedback or need assistance with the MCP directory API, please join our Discord server