ahttp-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
aihttp
aihttp is the AI-First Web Format. It turns a page into a compact, executable graph: the controls an agent can use, the text it can read, and the effect of each action. No screenshots, no raw DOM, no token bonfire.
One engine with no runtime dependencies. It ships as a browser file, a CLI, an HTTP server (aihttp-serve) and an MCP server. The package, the engine file, the browser global (window.aihttp) and the MCP tool names are all aihttp.
1.0.0, stable. The first stable release. The wire format is versioned (aihttp/1): additive changes are documented before any breaking one, and every release keeps the previous wire version readable. One maintainer, no third-party security audit yet; the repository's own suites pass. The spec is in docs/AIHTTP.md.
Should you use it?
Use it when an agent must interact: click, type, select, follow links, and handle rerenders without fragile selectors.
Skip it when an agent only reads static content: use Readability, Jina Reader, or Firecrawl for plain text and Markdown.
Related MCP server: Render & Verify MCP
Quick start
Userscript: 30 seconds
Install Tampermonkey or Violentmonkey.
Open
self/aihttp.user.jsand confirm the install.Open any
http(s)page, press Alt+Shift+A, type an id in the panel, press Act. No clone, no server, no upload.
MCP: 5 minutes
git clone https://github.com/ERETLY/aihttp.git
cd aihttp
npm ci
npx playwright install chromiumPaste this into Claude Desktop or Cursor, replacing /absolute/path/to/aihttp:
{
"mcpServers": {
"aihttp": {
"command": "node",
"args": ["/absolute/path/to/aihttp/bin/aihttp-mcp.js", "--browser"]
}
}
}Restart the client, call aihttp_open with a URL, then aihttp_snapshot or aihttp_act. The MCP tool names are aihttp_open, aihttp_snapshot, aihttp_act, aihttp_trace and aihttp_replay. --browser runs a real Chromium and page JavaScript; without it the server parses static HTML only. Node 18 or newer; the Playwright step is only needed for --browser.
CLI and local loop
node bin/aihttp-cli.js https://example.com --query "Buy"
node examples/agent-loop.jsThe CLI reads static HTML and never clicks. The local loop uses Chromium, clicks a control with an expect rule, and prints the diff. docs/DEMO.md is a terminal transcript; node scripts/demo.js regenerates it.
HTTP: the format as a service
npx aihttp-serve --port 8787
curl 'http://127.0.0.1:8787/?url=https%3A%2F%2Fexample.com'GET /?url=... returns application/aihttp+json with the same action graph as the engine. POST /act runs one action by id. GET /health reports the format version. Use --browser for JavaScript pages, --allow-private for local targets, and AIHTTP_TOKEN to require a bearer token. The wire format is in docs/AIHTTP.md.
What it looks like
aihttp | Widget shop | https://shop.test/cart
a1 input "Email" ph="you@example.com"
a2 button "Add to cart"
a3 a "Shipping help" -> /help
[text: untrusted]
Cart (1 item)
$49.00Each action has an id, a tag, a label, and optional state or target. Page text is marked untrusted because it comes from the page.
const step = await aihttp.act('a2') returns { ok: true, action, diff } plus a fresh snapshot. act waits for the page to settle; errors come back as values, not exceptions.
Record once, replay deterministically
This is the part you will not find in other DOM-to-LLM bridges. Every action is
recorded as a portable fingerprint, not as a12. Export the trace, reload the
page, redeploy the site, then replay it:
const trace = aihttp.trace(); // { steps: [...] }
const check = await aihttp.replay(trace, { dryRun: true });
// check.steps[0] => { status: 'would_run', signals: ['intent'], score: 100 }
const run = await aihttp.replay(trace); // follows navigations
// run.steps[1] => { status: 'ambiguous', candidates: [...] }Replay resolves intent, test ids, names, labels and hrefs with the same
scoring and margin rules as act, so a renamed button still matches while two
identical twins stop the run. The result says exactly what happened:
Status | Meaning |
| Step executed |
|
|
| The anchor disappeared |
| Several controls match; nothing was clicked |
| The step used a password and needs |
| The action is guarded; pass |
|
|
Over MCP the same feature is aihttp_trace and aihttp_replay. Password values
never enter a trace: only their length is recorded, and replay takes the value
from values.
Using it well
Put
data-aihttp-intenton controls that matter. Text labels change with copy; the intent attribute does not.Narrow the snapshot with
queryorscopeinstead of raisingmaxActions.Pass an
expectrule so a missing effect returnsno_effectinstead of a silent success.Keep the
pageIdand re-snapshot after each action instead of reusing old ids.For a SPA or any page that needs JavaScript, run the MCP server with
--browser.
How it works
Scan. Keep visible interactive elements, assign ids like
a12, record labels, roles, state, links, and page text.Act. Resolve the id, check policy and confirmation, dispatch the event, wait for the page to settle.
Diff. Rescan and return only changed text and actions, so the next step starts from the diff.
Identity does not depend on one CSS selector. The engine scores intent attributes, test ids, DOM ids, names, accessible names, text, titles, placeholders, alt text, and hrefs; position and DOM order are weak tie-breakers. If two candidates are too close, act returns status: 'ambiguous' and clicks nothing.
Loading the file does nothing. snapshot() is synchronous; act() returns a promise.
What it understands
The scanner is written against the web platform, not against a list of sites. There is no per-domain code.
Layer | Covered |
HTML controls |
|
Forms | labels, |
ARIA | roles and their kinds, |
Shadow DOM | open roots, |
CSS visibility |
|
Frames | same-origin iframes two levels deep; cross-origin frames are skipped and counted |
SVG | shapes are paint, not controls; |
Virtualized lists | the mounted viewport is measured; off-screen items kept at inline |
Overlays | native |
Text | main vs chrome regions, hidden-text sanitization, a token budget with a hard character cap |
For site owners
You do not have to change your markup. These attributes declare intent and limits:
Attribute | Effect |
| Stable name for policy and agent code |
| Requires confirmation |
| Readable, not writable |
| Removes the subtree from actions and text |
|
|
| Server-verified authorization endpoint |
| Policy filters |
| Hard action cap |
The data-aihttp-* namespace is part of the 1.0 contract. public is open. dev only works on localhost or file:. gate hides the graph behind a SHA-256 in the page; it is a hint, not authentication. owner is the production path: the agent authenticates with your backend, gets a short-lived token and policy, and the engine relocks when it expires.
Client-side JavaScript cannot enforce authorization. The server that performs the mutation must check agent, tenant, object, and intent. See docs/OWNER_MODE.md, docs/SECURITY.md, and examples/auth-server/.
Adopt it
Three levels, each useful on its own:
Proxy. Run
aihttp-servein front of any site. The agent gets the graph; the site stays untouched.Declare. Add
data-aihttp-*attributes to name actions, require confirmation, mark read-only controls and set a policy. This is the smallest change that makes an agent's actions auditable.Emit. Return
application/aihttp+jsonfrom your own app. The envelope is{ protocol: "aihttp/1", format: "aihttp", formatVersion: 1, ... }; the action schema and statuses are in docs/AIHTTP.md. You can also embed the engine: it is one dependency-free file andwindow.aihttp.snapshot()returns the same graph.
A site that emits the format natively does not need a browser or a proxy: it is the data the agent would have scraped, shaped for the context window.
Security
Locks, hidden actions, and
data-aihttp-confirmare not authorization;gateis a hint and the hash is in the page source.Treat labels, URLs, values, and text from the page as untrusted.
includeText: falsedrops the text block.The static backend does not run JavaScript. Use
--browserwhen scripts matter.confirmationTokenis one-time and expiring. It is not proof of human approval.No third-party audit. Report vulnerabilities privately; see SECURITY.md.
CDP mode attaches to a real browser.--cdp-use-existing-profile lets the agent act inside your signed-in profile and read its cookies. Use a dedicated profile.
Benchmarks
If you only need text, Jina or Firecrawl return plain Markdown. If an agent needs to interact (click, fill, navigate), only aihttp extracts the actionable control graph.
Token run: 2026-11-09T13:32:45.243Z. aihttp 1.0.0 on win32 x64, Node v26.13.0, Chromium 156.0.8078.4, gpt-tokenizer 4.1.0/o200k_base.
Tokens
Tokens an agent reads, lower is better. Checkout is five snapshots of one purchase flow, each page column is one snapshot of a pinned page, 20 tasks is every step of the scripted suite. Total adds the non-empty cells in a row.
Method | What you get | Can act | Checkout (5 steps) | Hacker News | Wikipedia | Lobsters | GitHub | MDN | Total | 20 tasks |
Raw HTML | serialized DOM | no | 3,983 | 11,771 | 191,129 | 17,909 | 105,767 | 59,787 | 390,346 | 25,896 |
Markdown | Readability + Turndown | no | 68 | 5,136 | 26,579 | 6,542 | 1,387 | 3,008 | 42,720 | n/a |
Jina Reader | hosted Markdown | no | n/a | 5,387 | 27,711 | 6,301 | 1,342 | 3,180 | 43,921 | n/a |
Accessibility tree | roles and names | no | 346 | 10,099 | 73,404 | 5,918 | 5,404 | 7,381 | 102,552 | 5,360 |
aihttp | actions, text, ids | yes | 289 | 1,162 | 1,130 | 1,105 | 1,286 | 1,156 | 6,128 | 5,104 |
aihttp self | actions, text, ids | yes | 289 | 1,170 | 1,138 | 1,116 | 1,288 | 882 | 5,883 | 5,104 |
Only the two aihttp rows can click; the baselines score 0/20 on the task suite because they only read. aihttp self is the same engine loaded as self/aihttp.user.js in Chromium.
Time
Wall-clock numbers from one machine, relative at best. Scan from 2026-11-08T13:12:53.661Z, live from 2026-11-08T13:12:53.661Z.
Checkout. Average per step over five local snapshots. The hosted readers cannot run it.
Method | Time per step |
Raw HTML | 5.1 ms |
Accessibility tree | 6.2 ms |
Markdown | 17.1 ms |
aihttp | 88.6 ms |
aihttp self | 86.4 ms |
Live. URL to content, one request per page, 2026-11-08:
Method | Hacker News | Wikipedia | Lobsters | GitHub | MDN |
aihttp | 1,222 ms | 1,201 ms | 1,973 ms | 2,423 ms | 1,368 ms |
aihttp self | 1,430 ms | 1,682 ms | 1,680 ms | 3,456 ms | 1,189 ms |
Jina Reader | 699 ms | 853 ms | 877 ms | 847 ms | 369 ms |
Firecrawl | 978 ms | 987 ms | 1,110 ms | 988 ms | 492 ms |
Single runs, not medians. aihttp fetches the page and its linked stylesheets in Node and scans it. aihttp self loads the page in Chromium with the userscript injected and takes a snapshot. The hosted readers return Markdown only.
Scan. One snapshot per pinned page. Raw HTML, the accessibility tree and aihttp self run in Chromium on the page served from localhost; Markdown and aihttp run in Node.
Method | Hacker News | Wikipedia | Lobsters | GitHub | MDN |
Raw HTML | 26 ms | 219 ms | 11 ms | 31 ms | 38 ms |
Markdown | 254 ms | 860 ms | 388 ms | 212 ms | 253 ms |
Accessibility tree | 81 ms | 280 ms | 57 ms | 90 ms | 59 ms |
aihttp | 16 ms | 97 ms | 5 ms | 21 ms | 23 ms |
aihttp self | 31 ms | 155 ms | 28 ms | 44 ms | 44 ms |
Hosted readers have no separate scan step; their time is in Live time.
Caveats
No LLM in the loop. The task runner is a script.
One win32 x64 machine. Scan time is the least portable number.
Accessibility token counts depend on the Chromium build.
Jina Reader (
r.jina.ai) and Firecrawl (v2 scrape) fetch the live page, not the pinned HTML.
Reproduce with Chromium: npm run bench (tokens, checkout, tasks), npm run bench:self (userscript), npm run bench:time (timings). npm run bench:render rewrites the block above.
Coverage matrix
npm run bench:web measures the engine against an independent oracle of reachable controls across 384 public sites (benchmark/web-sites.json).
npm run bench:web
node benchmark/web-matrix.js --category=forms
node benchmark/web-matrix.js --ids=mdn-input,wikipedia-enAccuracy: 99.8% weighted recall against ground-truth reachable controls (all categories > 98%: payments 100%, social 100%, forums 100%, ecommerce 100%, tables 99.5%, docs 99.5%, forms 98.3%).
Scan speed: median 37 ms, p95 188 ms. Total wall time is network page load, not engine scan.
Modals & Bot Walls: blocking dialogs (consent sheets, bot walls) are reported as the active page until dismissed.
Known limitations
Matching and rerenders
Matching is heuristic. Stable anchors are tried first; the old fingerprint is a low-weight fallback.
Two close candidates return
status: 'ambiguous'with no event. Re-snapshot, or adddata-aihttp-intent/data-testid.A disabled replacement is not an active target. With an
expectrule, a missing change returnsstatus: 'no_effect'aftertimeout(1200 ms by default).
Shadow DOM and iframes
Open shadow roots and slots are scanned. Closed roots are unreachable.
Same-origin iframes are scanned two levels deep. Cross-origin frames are skipped; the userscript skips all iframes.
Legacy
<frameset>documents are not scanned (only standard<iframe>tags).SVG shapes (
rect,path,circle) are paint, not controls; the button or link around the icon is the action.
Modals and consent
A dialog becomes the scan root only when it is actually blocking: a native open dialog, a backdrop, or a centered box covering a quarter of the viewport.
aria-modal="true"on a bottom cookie sheet is not enough.A modal that exposes no controls falls back to the document (
meta.modalFallback), so an empty consent shell cannot hide the page.A consent dialog with Accept/Reject controls is returned as the page, because the page behind it is not reachable until a decision. Dismiss it, then snapshot again.
Virtualized lists
Only mounted rows exist. An id from an unmounted row cannot be matched.
aihttp does not scroll the container to revive a row. Scroll it, then re-snapshot.
Other
Hover-only controls become
hoveractions when an inline handler or a CSS:hoverrule reveals a hidden descendant.act(id, { hover: true })applies the reveal; color-only rules are ignored.Hidden-text filtering is heuristic. Canvas text, background images, and stylesheets the page does not expose can be missed.
actlatency is the settle wait, not the scan: about 40 ms with no network, and at least 220 ms of network quiet after a request, so roughly 240 ms or more. A request that stays open can hold the action for most oftimeout.The static backend is a small HTML parser, not a full HTML5 tree builder. Use
--browserwhen exact parsing matters.
Breaking changes
1.0.0 renamed everything from ahttp to aihttp with no aliases. The npm package is aihttp, the engine file is aihttp.js, the browser global is window.aihttp, the binaries are aihttp/aihttp-mcp/aihttp-serve, the attributes are data-aihttp-*, and the MCP tool names are aihttp_*. The text snapshot header is now aihttp | title | url; JSON consumers should read protocol: "aihttp/1".
0.2.0 made ambiguity explicit. act no longer clicks a near-tie: it returns status: 'ambiguous'. Results also carry status, and expect can return status: 'no_effect'. Existing fields and error codes are unchanged.
Every PR that changes aihttp.js, aihttp.d.ts, bin/, or lib/ must include npm run bump -- patch (or minor/major). The maintainer tags after merge. See CONTRIBUTING.md.
Development
npm ci
npm test
npm run typecheck && npm run lint
npm run test:bench
npm run buildnpm test skips Playwright tests when Chromium is missing; AIHTTP_REQUIRE_BROWSER=1 makes that a failure. The corpus runs in jsdom against local HTML: npm run test:corpus writes bench/results.json and exits non-zero on a failure. Release with npm run bump -- patch|minor|major|X.Y.Z.
License
MIT, see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
Let your AI agent operate any website through a real, logged-in browser session.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environment10297MIT
- AlicenseAqualityCmaintenanceEnables AI coding agents to open and exercise web applications in an isolated Chromium browser, capture screenshots and runtime/network diagnostics, and run deterministic page checks with linked evidence.121MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to browse and interact with web pages through a persistent headless Chromium session, serving compact structured orientations, targeted element queries, and full detail only when explicitly requested. It supports navigation, observation, form filling, monitoring, and session management while cutting token overhead by up to ~140x versus raw accessibility-tree dumps.4 npm-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to control a browser via the Model Context Protocol using compact semantic DOM snapshots for navigation, clicking, and data extraction, with built-in SSRF and prompt-injection protection.2Apache 2.0