Package Exports

@apireno/domshell
@apireno/domshell/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@apireno/domshell) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@apireno/domshell

MCP server that turns your browser into a filesystem. AI agents use ls, cd, grep, find, click, and type to browse the web — the same way you'd navigate a Linux filesystem.

DOMShell maps Chrome's Accessibility Tree to a virtual filesystem. Every DOM element becomes a file or directory. Agents work with familiar commands instead of raw selectors and coordinates.

Install

npm install -g @apireno/domshell

Or run directly:

npx @apireno/domshell

You also need the DOMShell Chrome Extension — the MCP server talks to the browser through it.

Quick Start

npx @apireno/domshell init

The setup wizard detects installed MCP clients (Claude Desktop, Cursor, Windsurf), generates a secure token, and writes the config. Use --yes for non-interactive mode.

Then:

Install the DOMShell Chrome Extension
Open Chrome's side panel and start a DOMShell session
Restart your MCP client — DOMShell tools will appear
In the DOMShell terminal, run connect <token> (printed by the wizard)

Claude Desktop Config

Add this to your Claude Desktop MCP settings (claude_desktop_config.json):

{
  "mcpServers": {
    "domshell": {
      "command": "npx",
      "args": ["-y", "@apireno/domshell", "--allow-write"]
    }
  }
}

For the stdio proxy (required if your client needs command/args format):

{
  "mcpServers": {
    "domshell": {
      "command": "npx",
      "args": ["-y", "-p", "@apireno/domshell", "domshell-proxy", "--port", "3001", "--token", "YOUR_TOKEN"]
    }
  }
}

Benchmarks

We tested DOMShell against Computer-in-the-Cloud (CiC) — both using Claude as the underlying model — across 4 web tasks over 8 trials.

Metric	DOMShell	CiC
Avg API calls per task	4.3	8.6
Hardest task (T4)	6.0 calls	13.0 calls
Cold start vs CiC warm cache	4.5 calls	5.5 calls

DOMShell uses 2× fewer API calls to complete the same tasks. The filesystem metaphor gives the model a mental map of the page, so it spends less time exploring and more time extracting.

Full experiment data: experiments/claude_domshell_vs_cic

38 MCP Tools

Read (always available): ls, cd, pwd, cat, find, grep, tree, text, read, tabs, here, refresh, diff, eval, functions, watch, for, script, each, extract_links, extract_table

Write (--allow-write): click, focus, type, scroll, navigate, open, submit, back, forward, close, select, js, screenshot, wait, call

Sensitive (--allow-sensitive): whoami

Fallback: execute (run any command string)

CLI Flags

Flag	Description
`--allow-write`	Enable write-tier tools (click, type, navigate, etc.)
`--allow-sensitive`	Enable sensitive-tier tools (whoami)
`--allow-all`	Enable all tiers
`--port N`	WebSocket port (default: 9876)
`--mcp-port N`	HTTP MCP port (default: 3001)
`--domains a.com,b.com`	Restrict to specific domains
`--token TOKEN`	Set auth token (auto-generated if omitted)
`--log-file PATH`	Audit log location (default: audit.log)
`--no-confirm`	Skip confirmation prompts

Security

Every command goes through a 4-tier security model:

Read — always allowed (ls, find, grep, text)
Navigate — requires --allow-write (navigate, open, back, forward)
Write — requires --allow-write (click, type, js, select)
Sensitive — requires --allow-sensitive (whoami, cookie access)

All commands are logged to an audit file. Domain allowlists restrict which sites the agent can access. Auth tokens protect the HTTP endpoint.

Architecture

MCP Client (Claude, Cursor, etc.)
    ↓ HTTP :3001/mcp
DOMShell MCP Server (Express + WebSocket)
    ↓ WebSocket :9876
DOMShell Chrome Extension (CDP 1.3)
    ↓ Chrome Debugger Protocol
Browser DOM + Accessibility Tree

License

MIT