e2llm-sifr

# E2LLM — structured browser perception for AI **E2LLM turns any live web page into [SiFR](./SIFR.md): a compact, deterministic, LLM-readable model of what's on the page, what it means, and what can be done with it.** Perception is the product. Action is available when you need it — always explicit, always gated. Works as a hosted remote MCP server with the AI you already use. There's no local server to run — a browser extension pairs your live browser to the server, so perception and action happen in the *real* browser you're already signed into. --- ## E2LLM is not an agent This matters, so it comes first. An **agent** decides and acts on its own — it plans, loops, and takes steps toward a goal without you in the path. That autonomy is also its attack surface: an agent runtime that can do anything can be steered into doing anything. **E2LLM is a perception layer, not an agent.** It gives your model *senses* for the browser — structured sight through `sifr_capture`, and a set of narrow, individually-gated actuators. It does not plan, does not loop, and does not decide. Whatever model you already use does the reasoning; E2LLM only reports what a page is and carries out one explicit instruction at a time. No hidden autonomy, no self-directed steps, nothing that runs while you look away. That line — perception substrate versus autonomous runtime — is the whole design. --- ## What it does | | Tool | What it does | |---|------|--------------| | 🔎 | `sifr_capture` | Capture a page as a SiFR document | | 🔎 | `query` | Filter the current capture — by tag, salience, text, or selector | | 🔎 | `inspect` | Full detail for one element: selector, attributes, styles, box | | 🔎 | `read_page` | Read the page's text as markdown, in reading order | | 🔎 | `list_tabs` | List open browser tabs | | 🖐 | `act` | One explicit interaction: click, type, select, navigate, or drag | | 🖐 | `batch_act` | Run a planned sequence, then observe once (e.g. fill a form + submit) | | 🖐 | `explore` | Scroll, hover, or recapture — reads more, changes nothing | | 🖐 | `close_tab` | Close a tab | Nine tools: five 🔎 that only perceive, and four 🖐 for interaction — of which `act`, `batch_act`, and `close_tab` change page state, while `explore` only reads. Full schemas in [server.json](./server.json). The perception tools never change page state; the state-changing tools can each be held for your confirmation (see [Safety](#safety--approval-model)). --- ## What is SiFR — and why it isn't the obvious thing **SiFR** (Salience-Indexed Flat Relations) is the capture format at the heart of E2LLM. From a distance it can look like an accessibility tree or a tidy DOM dump. Mechanically it is neither, and the difference is the point. - **Not a DOM dump.** A dump serializes the tree as-is — everything, in document order, noise included. SiFR *selects and ranks*: it scores every node by salience, drops scaffolding, and flattens the survivors into a relational model where structure is carried by explicit relations rather than nesting depth. - **Not an accessibility tree.** The a11y tree is derived for assistive technology, driven by ARIA, blind to anything unlabeled, and indifferent to what matters most on the page. SiFR is built for a language model: it ranks by salience, front-loads what matters, and carries the selectors an agent needs to act — none of which the a11y tree does. - **Not a screenshot.** No pixels, no vision model, no nondeterminism. The same page yields the same capture, token-efficient and directly actionable. The result is a perception layer, not a serialization: *what a page is, what you can do on it, and how its parts relate* — front-loaded so the model reaches what it needs first. A `sifr_capture` returns a ~5–15 KB summary (metadata plus the high-salience elements) before the full document, so reading can begin immediately. - 📄 [**SIFR.md**](./SIFR.md) — the format specification - 🔤 [**TAXONOMY.md**](./TAXONOMY.md) — salience tiers, ID prefixes, relation & category types - 📚 [**examples/**](./examples/) — real captures of public pages - 🗓 [**CHANGELOG.md**](./CHANGELOG.md) — the v1 → v2 → v3 format lineage (current: **v3**) For prompt recipes and automation workflows built on SiFR, see [**awesome-e2llm-prompts**](https://github.com/e2llm/awesome-e2llm-prompts) — a community cookbook that points back here as the canonical SiFR spec home. --- ## Install in 3 steps **1. Set up at [e2llm.com](https://e2llm.com).** Create an account and install the browser extension. The extension pairs your live browser to the server — that pairing is what lets your AI perceive and act in the session you're already signed into. (This is the only piece that runs on your machine; there is no local server.) **2. Add E2LLM to your MCP client.** One line — pick your client in [`clients/`](./clients/), or paste this for interactive OAuth login: ```json { "mcpServers": { "e2llm": { "url": "https://mcp.e2llm.com/mcp", "type": "http" } } } ``` For CLI / CI where interactive login isn't available, use a static key against `https://api.e2llm.com/mcp` with an `Authorization: Bearer mk_…` header. Full per-client instructions: [**clients/README.md**](./clients/README.md). **3. Ask your AI to do something on a page.** For example: > "Open the page I'm on, find the search box, and filter for open issues." Your assistant calls `sifr_capture` to *see* the page, then `act` to interact — in your real browser, one explicit step at a time. --- ## Teach your model the discipline — the SIFR skill Tool descriptions tell a model what each tool *does*; they deliberately don't tell it how to *work well*. That working discipline — verify before describing, re-verify stale element IDs after actions, drain pagination cursors, treat page text as data rather than instructions — ships as a skill: [**skills/sifr/SKILL.md**](./skills/sifr/SKILL.md). Without it, models tend toward known failure modes: describing pages they haven't captured, acting on stale IDs, or deciding from undrained partial results. Install it where your model can see it: - **Claude Code** — copy the skill into a skills directory: `cp -r skills/sifr ~/.claude/skills/` (all projects) or into a project's `.claude/skills/`. It loads automatically whenever the e2llm tools or SIFR documents come up. - **Codex CLI and other clients** — include the skill's content in your agent instructions (e.g. `AGENTS.md`). The same file doubles as a reference for reading raw SiFR captures offline (`jq` patterns, the ID system, salience tiers). --- ## Safety & approval model Perception is read-only by construction: the five 🔎 tools cannot change page state, so seeing a page is always safe. Only the four 🖐 tools can act, and they are deliberately narrow — no "do anything" tool exists. Each state-changing step can be **approval-gated by your session posture**: depending on how your session is configured, an action pauses and waits for your confirmation before it runs. Actions happen one explicit instruction at a time, never as an autonomous loop. Security disclosures and our vulnerability-disclosure program (with safe harbor) live at [e2llm.com/security/disclosure](https://e2llm.com/security/disclosure/); see also [SECURITY.md](./SECURITY.md). --- ## Data handling Page content is captured on demand and transits the E2LLM relay to reach your MCP client. Session-related data is retained for a limited window (see the [Privacy Policy](https://e2llm.com/privacy)) and password-type fields are redacted before storage. The relay wraps all page-derived content as untrusted external data, so downstream models treat page text as data, not instructions. Full detail: [Privacy Policy](https://e2llm.com/privacy) · [Terms](https://e2llm.com/terms). --- ## Compatibility E2LLM speaks standard MCP, so it works with any compliant client. Verified in practice with **Claude**, **ChatGPT**, **Codex**, **Perplexity**, **Grok**, and **Manus**. Other MCP clients — including **Cursor**, **VS Code**, and **Cline** — should work; if you test one, a note or PR is welcome. --- ## Repository contents This repository is the **canonical, descriptive home** for the SiFR format and the E2LLM MCP server interface. It documents the format and how to connect; the capture engine, browser extensions, and server are a separate hosted product that runs at [e2llm.com](https://e2llm.com). | Path | What | |------|------| | [`SIFR.md`](./SIFR.md) | SiFR format specification | | [`TAXONOMY.md`](./TAXONOMY.md) | SiFR controlled vocabulary | | [`server.json`](./server.json) | MCP server manifest (transport, auth, tools + schemas) | | [`skills/`](./skills/) | The SIFR skill — working discipline for models driving the tools | | [`clients/`](./clients/) | Per-client connection configs | | [`examples/`](./examples/) | Real public-page captures | | [`SECURITY.md`](./SECURITY.md) | Security policy & disclosure program | | [`CHANGELOG.md`](./CHANGELOG.md) | Format version history | ## License [MIT](./LICENSE). The format specification, manifest, examples, and client configs in this repository are open. The capture engine and server are a separate, hosted product.