pointclick 0.1.0__py3-none-any.whl

pointclick/__init__.py

@@ -0,0 +1 @@
+"""pointclick: a browser MCP server that lists what you can click, by number."""

pointclick/server.py

@@ -0,0 +1,421 @@
+"""pointclick: jev's compact indexed snapshot for the fast path, Playwright for everything else."""
+
+import asyncio
+import functools
+import json
+import os
+from importlib.metadata import version
+from pathlib import Path
+
+from mcp.server.mcpserver import Image, MCPServer
+from playwright.async_api import Error as PWError
+from playwright.async_api import TimeoutError as PWTimeout
+from playwright.async_api import async_playwright
+
+SNAPSHOT = (Path(__file__).parent / "snapshot.js").read_text()
+OPS = {"click": "CLICK", "fill": "TYPE", "select": "SELECT"}
+VALUE_ROLES = {"textbox", "searchbox", "combobox", "spinbutton"}
+FINGERPRINT = (
+    "() => [location.href, document.title, document.body?.innerText.length,"
+    " document.querySelectorAll('a,button,input,select,textarea,[role]').length].join('|')"
+)
+# Two animation frames, or 150 ms, whichever first.
+SETTLE = (
+    "() => new Promise(r => { let n = 0; const f = () => ++n >= 2 ? r() : requestAnimationFrame(f);"
+    " requestAnimationFrame(f); setTimeout(r, 150); })"
+)
+
+# After an action: done once the DOM has been still for QUIET s and no request younger than YOUNG s is
+# pending, or after CAP s. Older requests (long-polls, streams) don't hold it up.
+QUIET, YOUNG, CAP = 0.15, 0.5, 2.0
+IGNORED_REQUESTS = {"image", "media", "font"}
+
+mcp = MCPServer("pointclick", version=version("pointclick"))
+S = {
+    "pw": None,
+    "browser": None,
+    "ctx": None,
+    "page": None,
+    "index": {},
+    "console": [],
+    "fp": None,
+    "notes": [],
+    "inflight": {},
+}
+
+
+# Clients may send tool calls in parallel; one browser and one current page serve them in turn.
+_lock = asyncio.Lock()
+
+
+def _one_at_a_time(tool):
+    @functools.wraps(tool)
+    async def run(*args, **kwargs):
+        async with _lock:
+            return await tool(*args, **kwargs)
+
+    return run
+
+
+def _track(page):
+    # Popups (OAuth, new tabs) become the current page.
+    S["page"] = page
+    page.on("console", lambda m: _log(f"[{m.type}] {m.text}"))
+    page.on("pageerror", lambda e: _log(f"[pageerror] {e}"))
+    page.on("request", _request_started)
+    page.on("requestfinished", _request_done)
+    page.on("requestfailed", _request_done)
+
+
+def _request_started(request):
+    if request.resource_type not in IGNORED_REQUESTS:
+        S["inflight"][request] = asyncio.get_running_loop().time()
+
+
+def _request_done(request):
+    S["inflight"].pop(request, None)
+
+
+def _log(line):
+    S["console"].append(line)
+    del S["console"][:-300]
+
+
+async def _launch(pw):
+    # Installed Chrome first; Playwright's bundled Chromium when it's missing.
+    headless = os.environ.get("HEADED") != "1"
+    channel = os.environ.get("BROWSER_CHANNEL", "chrome")
+    if channel == "chromium":
+        return await pw.chromium.launch(headless=headless)
+    try:
+        return await pw.chromium.launch(channel=channel, headless=headless)
+    except PWError as e:
+        try:
+            return await pw.chromium.launch(headless=headless)
+        except PWError as e2:
+            raise RuntimeError(
+                f"No browser. {channel!r}: {str(e).splitlines()[0]} Bundled Chromium: {str(e2).splitlines()[0]} "
+                "Install Chrome, or run: playwright install chromium"
+            ) from None
+
+
+async def _page():
+    if S["page"] and not S["page"].is_closed():
+        return S["page"]
+    if not S["pw"]:
+        S["pw"] = await async_playwright().start()
+        S["browser"] = await _launch(S["pw"])
+        S["ctx"] = await S["browser"].new_context(viewport={"width": 1280, "height": 800})
+        S["ctx"].on("page", _track)
+    open_pages = [p for p in S["ctx"].pages if not p.is_closed()]
+    if open_pages:
+        S["page"] = open_pages[-1]
+        return S["page"]
+    return await S["ctx"].new_page()
+
+
+async def _settle(page):
+    try:
+        await page.wait_for_load_state("domcontentloaded", timeout=5000)
+        await page.evaluate(SETTLE)
+    except (PWError, PWTimeout):
+        pass
+
+
+async def _frame_snapshot(frame, full):
+    if frame != frame.page.main_frame:
+        box = await (await frame.frame_element()).bounding_box()
+        if not box or not box["width"] or not box["height"]:
+            return None
+        vp = frame.page.viewport_size
+        if not full and (box["y"] >= vp["height"] or box["y"] + box["height"] <= 0):
+            return None
+    return await frame.evaluate(SNAPSHOT, full)
+
+
+async def _snapshot(full):
+    page = await _page()
+    for attempt in range(40):
+        try:
+            frames = []
+            for frame in page.frames:
+                if frame.is_detached():
+                    continue
+                try:
+                    snap = await _frame_snapshot(frame, full)
+                except PWError:
+                    if frame == page.main_frame:
+                        raise
+                    continue
+                if snap:
+                    frames.append((frame, snap))
+            if frames and frames[0][0] == page.main_frame:
+                return page, frames
+        except PWError:
+            pass
+        await asyncio.sleep(0.05)
+    raise RuntimeError("Page never settled")
+
+
+def _norm(label):
+    return " ".join(label.split())
+
+
+def _render(page, frames, full):
+    S["index"] = {}
+    main = frames[0][1]
+    lines = [f"url: {main['url']}", f"title: {main['title']}"]
+    n = 0
+    for frame, snap in frames:
+        if frame != page.main_frame:
+            lines.append(f"-- frame {snap['url'][:80]} --")
+        nodes = {}
+        for a in snap["actions"]:
+            if a["kind"] not in OPS:
+                continue
+            e = nodes.get(a["node"])
+            if e is None:
+                n += 1
+                label = _norm(a["label"].split(" → ")[0])
+                e = nodes[a["node"]] = {"i": str(n), "a": a, "label": label, "ops": [], "options": []}
+                S["index"][e["i"]] = {"frame": frame, "node": a["node"], "label": label, "options": e["options"]}
+            if OPS[a["kind"]] not in e["ops"]:
+                e["ops"].append(OPS[a["kind"]])
+            if a["kind"] == "select":
+                e["options"].append((a["value"], _norm(a["label"].split(" → ", 1)[-1])))
+        for e in nodes.values():
+            a = e["a"]
+            bits = [f"[{e['i']}]", a["role"], repr(e["label"][:120])]
+            value = a.get("current_value") if a["kind"] == "select" else a.get("value")
+            if value and a["role"] in VALUE_ROLES:
+                bits.append(f"value={value[:80]!r}")
+            bits += [k for k in ("checked", "selected", "expanded") if a.get(k) == "true"]
+            bits.append(f"<{','.join(e['ops'])}>")
+            lines.append(" ".join(bits))
+            for k, (_, label) in enumerate(e["options"], 1):
+                lines.append(f"    [{e['i']}:{k}] {label}")
+        if snap.get("omitted_actions"):
+            lines.append(f"({snap['omitted_actions']} more elements omitted)")
+    scroll = main["scroll"]
+    if not full and scroll["y"] + main["h"] < scroll["height"] - 2:
+        lines.append(f"(more below: {scroll['height'] - scroll['y'] - main['h']}px; SCROLL_DOWN or observe(full=true))")
+    text = (main.get("text") or "").strip()
+    if text:
+        lines += ["", "text:", text[: 4000 if full else 1500]]
+    return "\n".join(lines)
+
+
+async def _fingerprint(page):
+    try:
+        return await page.evaluate(FINGERPRINT)
+    except PWError:
+        return None
+
+
+async def _observe(full=False):
+    page, frames = await _snapshot(full)
+    S["fp"] = await _fingerprint(page)
+    return _render(page, frames, full)
+
+
+async def _quiet(page):
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + CAP
+    last, changed = await _fingerprint(page), loop.time()
+    while loop.time() < deadline:
+        await asyncio.sleep(0.05)
+        fp, now = await _fingerprint(page), loop.time()
+        if fp != last:
+            last, changed = fp, now
+        elif now - changed >= QUIET and not any(now - t < YOUNG for t in S["inflight"].values()):
+            return
+
+
+async def _wait_for_change(page, limit=3.0):
+    # Against the last observe, so a change that already landed returns at once.
+    deadline = asyncio.get_running_loop().time() + limit
+    while asyncio.get_running_loop().time() < deadline:
+        if await _fingerprint(page) != S["fp"]:
+            return
+        await asyncio.sleep(0.1)
+
+
+class Stale(Exception):
+    pass
+
+
+async def _resolve(target):
+    """Index from the last observe ("3", or "3:2" for a select option), or any Playwright selector."""
+    page = await _page()
+    idx, _, opt = target.partition(":")
+    if idx.isdigit() and (not opt or opt.isdigit()):
+        entry = S["index"].get(idx)
+        if not entry:
+            raise Stale(f"No element [{idx}] in the last observe.")
+        el = await _element(entry)
+        if el is None:
+            # Re-rendered (framework swapped the node). Only follow it when the label is unambiguous.
+            await _observe()
+            same = [k for k, v in S["index"].items() if v["label"] == entry["label"] and v["frame"] == entry["frame"]]
+            if len(same) != 1:
+                raise Stale(f"[{idx}] is gone from the page.")
+            idx, entry = same[0], S["index"][same[0]]
+            el = await _element(entry)
+            if el is None:
+                raise Stale(f"[{idx}] is gone from the page.")
+            S["notes"].append(f"The element was re-rendered; used [{idx}] {entry['label']!r}.")
+        option = entry["options"][int(opt) - 1][0] if opt else None
+        return el, option
+    return page.locator(target).first, None
+
+
+async def _element(entry):
+    handle = await entry["frame"].evaluate_handle(
+        "id => { const e = window.__jevFast?.nodes.get(id); return e?.isConnected ? e : null; }", entry["node"]
+    )
+    return handle.as_element()
+
+
+async def _run(coro):
+    page = await _page()
+    S["notes"] = []
+    before = await _fingerprint(page)
+    try:
+        await coro
+    except Stale as e:
+        return f"Stale: {e} Fresh table:\n\n" + await _observe()
+    except ValueError as e:
+        return f"Error: {e}\n\n" + await _observe()
+    except (PWError, PWTimeout) as e:
+        if before is None or await _fingerprint(page) == before:
+            return f"Failed: {str(e).splitlines()[0][:300]}\n\n" + await _observe()
+        S["notes"].append(
+            "The action timed out, but the page changed since. Check whether it took effect before retrying."
+        )
+    await _settle(page)
+    await _quiet(page)
+    table = await _observe()
+    return "".join(f"Note: {n}\n" for n in S["notes"]) + ("\n" if S["notes"] else "") + table
+
+
+@mcp.tool()
+@_one_at_a_time
+async def navigate(url: str) -> str:
+    """Open url and return the indexed element table."""
+    page = await _page()
+    await page.goto(url, wait_until="domcontentloaded", timeout=30000)
+    await _settle(page)
+    await _quiet(page)
+    return await _observe()
+
+
+@mcp.tool()
+@_one_at_a_time
+async def observe(full: bool = False) -> str:
+    """Indexed table of interactive elements (all frames) plus visible text.
+    Default: viewport only (compact). full=true: whole page."""
+    return await _observe(full)
+
+
+@mcp.tool()
+@_one_at_a_time
+async def act(operation: str, target: str = "", text: str = "") -> str:
+    """Do one thing, then return the fresh table.
+    operation: CLICK | TYPE | SELECT | PRESS | HOVER | SCROLL_DOWN | SCROLL_UP | WAIT.
+      Returns once the page settles (max 2s). If it is still loading after that, WAIT (returns on change, max 3s).
+    target: index from the table ("3"; "3:2" picks a SELECT option), or a Playwright selector
+      ("input[type=password]", "text=Send", "role=button[name='OK']") for anything not in the table.
+    text: TYPE value, SELECT option label (instead of "3:2"), or PRESS key ("Enter")."""
+    op = operation.upper().replace("TYPE_TEXT", "TYPE")
+    page = await _page()
+
+    async def do():
+        if op in ("SCROLL_DOWN", "SCROLL_UP"):
+            await page.mouse.wheel(0, 600 if op == "SCROLL_DOWN" else -600)
+            return
+        if op == "WAIT":
+            await _wait_for_change(page)
+            return
+        if op == "PRESS" and not target:
+            await page.keyboard.press(text)
+            return
+        if not target:
+            raise ValueError(f"{op} needs a target.")
+        el, option = await _resolve(target)
+        if op == "CLICK":
+            await el.click(timeout=5000, no_wait_after=True)
+        elif op == "TYPE":
+            await el.fill(text, timeout=5000)
+        elif op == "SELECT" and option:
+            await el.select_option(value=option, timeout=5000)
+        elif op == "SELECT":
+            await el.select_option(label=text, timeout=5000)
+        elif op == "PRESS":
+            await el.press(text, timeout=5000, no_wait_after=True)
+        elif op == "HOVER":
+            await el.hover(timeout=5000)
+        else:
+            raise ValueError(f"Unknown operation {operation!r}.")
+
+    return await _run(do())
+
+
+@mcp.tool()
+@_one_at_a_time
+async def upload(target: str, paths: list[str]) -> str:
+    """Set files on a file input. target: selector (file inputs are not in the table), e.g. "input[type=file]"."""
+
+    async def do():
+        el, _ = await _resolve(target)
+        await el.set_input_files(paths, timeout=5000)
+
+    return await _run(do())
+
+
+@mcp.tool()
+@_one_at_a_time
+async def screenshot(full_page: bool = False) -> Image:
+    """JPEG of the current page."""
+    page = await _page()
+    return Image(data=await page.screenshot(type="jpeg", quality=70, full_page=full_page), format="jpeg")
+
+
+@mcp.tool()
+@_one_at_a_time
+async def evaluate(js: str, max_chars: int = 6000) -> str:
+    """Run JS in the page: an expression, or a function like "() => document.title".
+    Returns JSON, cut at max_chars (0: no limit)."""
+    page = await _page()
+    out = json.dumps(await page.evaluate(js), ensure_ascii=False, default=str)
+    if max_chars and len(out) > max_chars:
+        return f"{out[:max_chars]}\n(cut at {max_chars} of {len(out)} chars; max_chars=0 returns all of it)"
+    return out
+
+
+@mcp.tool()
+@_one_at_a_time
+async def console(clear: bool = True) -> str:
+    """Console messages and page errors since the last call."""
+    lines = S["console"][-100:]
+    if clear:
+        S["console"].clear()
+    return "\n".join(lines) or "(empty)"
+
+
+@mcp.tool()
+@_one_at_a_time
+async def close() -> str:
+    """Close the browser. The next call starts a fresh, empty session."""
+    if S["browser"]:
+        await S["browser"].close()
+        await S["pw"].stop()
+    S.update(pw=None, browser=None, ctx=None, page=None, index={}, console=[], fp=None, notes=[], inflight={})
+    return "closed"
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

pointclick/snapshot.js

@@ -0,0 +1,112 @@
+// Adapted from browser-use/jev-ultrafast (MIT, see LICENSE-jev). Changes:
+// `full` lifts the viewport filter; a control repeating its wrapper's label is dropped;
+// a <button> is named by its text, not its value.
+(full => {
+  if (!document.body) return null;
+  const cache = window.__jevFast ||= {ids:new WeakMap(), nodes:new Map(), next:1};
+  const identity = e => {
+    if (!cache.ids.has(e)) cache.ids.set(e,cache.next++);
+    const id=cache.ids.get(e); cache.nodes.set(id,e); return id;
+  };
+  for (const [id,e] of cache.nodes) if (!e.isConnected) cache.nodes.delete(id);
+  const safe = e => !['password','file','hidden'].includes(e.type);
+  const visible = e => !e.closest('[aria-hidden="true"],[inert]') &&
+    e.checkVisibility({checkOpacity:true,checkVisibilityCSS:true});
+  const name = (e,seen=new Set()) => {
+    if (!e || seen.has(e)) return '';
+    seen.add(e);
+    const referenced=(e.getAttribute('aria-labelledby')||'').split(/\s+/)
+      .map(id=>name(document.getElementById(id),seen)).filter(Boolean).join(' ');
+    return referenced || e.getAttribute('aria-label') ||
+      [...(e.labels||[])].map(l=>name(l,seen)).filter(Boolean).join(' ') ||
+      (e.tagName==='INPUT' && ['button','submit','reset'].includes(e.type) ? e.value : '') || e.getAttribute('alt') ||
+      (e.tagName==='INPUT' ? '' : [...e.childNodes].map(n=>n.nodeType===3 ? n.textContent :
+        n.nodeType===1 && n.getAttribute('aria-hidden')!=='true' ? name(n,seen) : '').join(' ').trim()) ||
+      e.getAttribute('title') || e.getAttribute('placeholder') || '';
+  };
+  const roles=['button','link','checkbox','radio','switch','tab','menuitem','menuitemradio',
+    'option','gridcell','combobox','textbox','searchbox','spinbutton'];
+  const selector='a[href],button,input,textarea,select,summary,[contenteditable="true"],'+
+    roles.map(role=>'[role="'+role+'"]').join(',');
+  const role = e => {
+    const explicit=e.getAttribute('role');
+    if (roles.includes(explicit)) return explicit;
+    if (e.tagName==='BUTTON' || e.tagName==='SUMMARY') return 'button';
+    if (e.tagName==='A') return 'link';
+    if (e.tagName==='SELECT') return 'combobox';
+    if (e.tagName==='TEXTAREA' || e.isContentEditable) return 'textbox';
+    if (e.tagName==='INPUT') {
+      if (['checkbox','radio'].includes(e.type)) return e.type;
+      if (['button','submit','reset','image'].includes(e.type)) return 'button';
+      if (e.type==='search') return 'searchbox';
+      if (e.type==='number') return 'spinbutton';
+      if (['text','email','url','tel'].includes(e.type)) return 'textbox';
+    }
+    return null;
+  };
+  cache.pageKey=()=>[performance.timeOrigin,location.href,scrollX,scrollY,innerWidth,innerHeight,
+    [...document.querySelectorAll('input,textarea,select')].filter(safe)
+      .map(e=>[identity(e),e.value,e.checked,e.selectedIndex,e.disabled,e.readOnly])];
+  cache.guard=e=>{
+    if (!e?.isConnected || !visible(e)) return null;
+    const scope=e.closest('form,dialog,[role="dialog"],article,li,tr,[role="row"]') || e.parentElement;
+    return [identity(e),role(e),name(e),e.value??null,e.checked??null,e.selectedIndex??null,
+      e.readOnly??null,e.matches(':disabled'),e.getAttribute('aria-disabled'),
+      e.getAttribute('aria-expanded'),e.getAttribute('aria-checked'),e.getAttribute('aria-selected'),
+      e.getAttribute('href'),scope?.innerText?.slice(0,6000)||''];
+  };
+  const actions=[];
+  for (const e of document.querySelectorAll(selector)) {
+    if (!safe(e) || !visible(e) || e.matches(':disabled') || e.closest('[aria-disabled="true"]')) continue;
+    const r=e.getBoundingClientRect(), x=r.x+r.width/2, y=r.y+r.height/2, rname=role(e);
+    if (!rname || r.width<=0 || r.height<=0 || (!full && (x<0 || y<0 || x>=innerWidth || y>=innerHeight))) continue;
+    if (rname==='gridcell' && e.querySelector('button,[role="button"]')) continue;
+    const outer=e.parentElement?.closest(selector);
+    if (outer && name(outer).replace(/\s+/g,' ').trim()===name(e).replace(/\s+/g,' ').trim()) continue;
+    const base={node:identity(e),role:rname,label:name(e)||rname,
+      rect:{x:r.x,y:r.y,w:r.width,h:r.height}};
+    for (const key of ['checked','selected','expanded']) {
+      const value=e.getAttribute('aria-'+key);
+      if (value!==null) base[key]=value;
+    }
+    if (['checkbox','radio'].includes(e.type)) base.checked=String(e.checked);
+    if (e.tagName==='SELECT') {
+      for (const o of e.options) if (!o.selected && !o.disabled && !o.closest('optgroup[disabled]'))
+        actions.push({...base,kind:'select',value:o.value,
+          current_value:[...e.selectedOptions].map(o=>o.label).join(', '),label:base.label+' → '+o.label});
+    } else {
+      const editable=!e.readOnly && e.getAttribute('aria-readonly')!=='true' &&
+        (['textbox','searchbox','spinbutton'].includes(rname) ||
+          (rname==='combobox' && ['INPUT','TEXTAREA'].includes(e.tagName)));
+      const value='value' in e ? String(e.value) :
+        e.isContentEditable || rname==='combobox' ? e.innerText.trim() : '';
+      actions.push({...base,kind:editable?'fill':'click',value});
+      if (editable) actions.push({...base,kind:'click',value,label:'Open '+base.label});
+    }
+  }
+  const words=[], walker=document.createTreeWalker(document.body,NodeFilter.SHOW_TEXT);
+  const range=document.createRange(); let node,length=0;
+  while ((node=walker.nextNode()) && length<6000) {
+    const value=node.textContent.trim(), parent=node.parentElement;
+    if (!value || !parent || parent.closest('script,style,noscript,template') || !visible(parent)) continue;
+    range.selectNodeContents(node); const r=range.getBoundingClientRect();
+    if (r.width>0 && r.height>0 && (full || (r.bottom>0 && r.top<innerHeight && r.right>0 && r.left<innerWidth))) {
+      words.push(value); length+=value.length;
+    }
+  }
+  const text=words.join('\n').slice(0,6000), height=document.documentElement.scrollHeight;
+  const page_key=cache.pageKey(), guards={};
+  for (const a of actions) if (!(a.node in guards)) guards[a.node]=cache.guard(cache.nodes.get(a.node));
+  // Compare meaning and identity. Geometry is always resolved and hit-tested just before input.
+  const semantics=actions.map(({rect,...action})=>action);
+  const marker=[performance.timeOrigin,location.href,scrollX,scrollY,innerWidth,innerHeight,
+    document.title,text,semantics,page_key[6]];
+  const omitted_actions=Math.max(0,actions.length-250);
+  actions.splice(250);
+  actions.forEach((a,i)=>a.id='e'+(i+1));
+  if (scrollY+innerHeight<height-2) actions.push({id:'scroll_down',kind:'scroll',label:'Scroll down',delta:560});
+  if (scrollY>0) actions.push({id:'scroll_up',kind:'scroll',label:'Scroll up',delta:-560});
+  actions.push({id:'wait',kind:'wait',label:'Wait for the page to update'});
+  return {url:location.href,title:document.title,w:innerWidth,h:innerHeight,text,
+    scroll:{y:scrollY,height},actions,marker,page_key,guards,omitted_actions};
+})

pointclick-0.1.0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.5
+Name: pointclick
+Version: 0.1.0
+Summary: A browser MCP server with a small footprint: a numbered list of what you can click, and eight tools.
+Project-URL: Homepage, https://github.com/dashgin/pointclick
+Project-URL: Issues, https://github.com/dashgin/pointclick/issues
+Author-email: Dashgin <dashgin@praxis.az>
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSE-jev
+Keywords: agent,automation,browser,mcp,playwright
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: mcp>=2
+Requires-Dist: playwright>=1.50
+Description-Content-Type: text/markdown
+
+# pointclick
+
+**A browser MCP server in under 1,000 tokens.** The page comes back as a numbered list of what
+you can click, type into or select. Your agent points at a number; pointclick clicks it.
+
+[![PyPI](https://img.shields.io/pypi/v/pointclick.svg)](https://pypi.org/project/pointclick/)
+[![CI](https://github.com/dashgin/pointclick/actions/workflows/ci.yml/badge.svg)](https://github.com/dashgin/pointclick/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+```
+url: https://en.wikipedia.org/wiki/Main_Page
+title: Wikipedia, the free encyclopedia
+[1] link 'Wikipedia The Free Encyclopedia' <CLICK>
+[2] searchbox 'Search Wikipedia' <TYPE,CLICK>
+[3] button 'Search' <CLICK>
+...
+(more below: 3156px; SCROLL_DOWN or observe(full=true))
+
+text:
+Welcome to
+Wikipedia
+...
+```
+
+```
+act("TYPE", "2", "Ada Lovelace")   → the new list, once the page has settled
+act("PRESS", "2", "Enter")
+```
+
+## Why
+
+Same task, same model (Claude Sonnet 5 in headless Claude Code), one browser MCP each —
+sign in, search, sort, open a record, read a number off it. 18 of 18 runs got it right.
+
+| | turns | tokens read | cost per run | time |
+|---|---|---|---|---|
+| **pointclick** | **7** | **104k** | **$0.056** | **15.8 s** |
+| Playwright MCP | 13 | 266k | $0.118 | 27.5 s |
+| agent-browser | 12 | 525k | $0.223 | 17.8 s |
+
+Medians. Cost is the API price Claude Code reports; time is noisy at this sample size.
+
+- **Eight tools, under 1k tokens of definitions.** Playwright MCP's are ~5k, Chrome DevTools MCP's
+  ~7k, agent-browser's ~18k. Clients that load every tool up front pay that on every turn.
+- **Only what you can act on.** No wrapper `div`s, no layout tree: controls, their state, and the
+  visible text.
+- **Every action returns the settled page.** No follow-up snapshot call, and no waiting for the
+  network to go quiet: long-polls and streams don't stall it.
+
+## Quick start
+
+Needs Python 3.12+ and [uv](https://docs.astral.sh/uv/). Uses your installed Chrome, or
+Playwright's Chromium if there is none (`uvx --from pointclick playwright install chromium`).
+
+**Claude Code**
+
+```bash
+claude mcp add pointclick -- uvx pointclick
+```
+
+**Cursor, Claude Desktop, Windsurf, and other clients** — add to the MCP config:
+
+```json
+{
+  "mcpServers": {
+    "pointclick": { "command": "uvx", "args": ["pointclick"] }
+  }
+}
+```
+
+**VS Code**
+
+```bash
+code --add-mcp '{"name":"pointclick","command":"uvx","args":["pointclick"]}'
+```
+
+**Codex**
+
+```bash
+codex mcp add pointclick -- uvx pointclick
+```
+
+### Your first prompt
+
+```
+Open news.ycombinator.com, go to the second page, and tell me the top story there.
+```
+
+## Tools
+
+| Tool | |
+|---|---|
+| `navigate(url)` | Open a page, return the list |
+| `observe(full=false)` | The list again. Viewport only unless `full` |
+| `act(operation, target, text)` | `CLICK` `TYPE` `SELECT` `PRESS` `HOVER` `SCROLL_DOWN` `SCROLL_UP` `WAIT` |
+| `upload(target, paths)` | Set files on a file input |
+| `screenshot(full_page=false)` | JPEG |
+| `evaluate(js, max_chars=6000)` | Run JS in the page, JSON back. A longer result is cut and says so; `0` for all of it |
+| `console()` | Console messages and page errors since the last call |
+| `close()` | End the session; the next call starts fresh |
+
+`target` is a number from the list (`"3"`, or `"3:2"` for the second option of a select), or any
+Playwright selector (`"input[type=password]"`, `"text=Send"`, `"role=button[name='OK']"`).
+Password and file inputs are never in the list; reach them by selector.
+
+| Env | |
+|---|---|
+| `HEADED=1` | Show the window |
+| `BROWSER_CHANNEL` | `chrome` (default), `msedge`, or `chromium` for Playwright's bundled build |
+
+## How it works
+
+- **The list** comes from one script that reads every visible control and the visible text in a
+  single pass — adapted from [jev-ultrafast](https://github.com/browser-use/jev-ultrafast)
+  (Browser Use × TypeSafe). It runs in every frame, cross-origin ones included, and a control that
+  only repeats its wrapper's label is listed once.
+- **Settling.** After an action, pointclick returns once the page has been still for 150 ms and
+  no request younger than 0.5 s is pending — at most 2 s. Older requests (long-polls, streams)
+  don't hold it up. If the page is still busy after that, `WAIT` returns the moment it changes.
+- **Numbers point at real elements**, not at a position. If a framework re-renders the element,
+  pointclick follows it when its label is unique on the page and says so; a duplicate label (two
+  "Start" buttons) is refused rather than guessed.
+- **A timeout on a page that changed anyway** is reported that way, so the agent checks before
+  retrying instead of clicking twice.
+- **Playwright underneath** handles selectors, uploads, popups (they become the current page),
+  screenshots and the console. Every session is a fresh, isolated browser context.
+
+`server.py` is ~350 lines and `snapshot.js` ~110. Small enough to read before you trust it.
+
+## Benchmarks
+
+`bench/` has a small SPA shaped like a real dashboard — demo login, a list with search and sort, a
+detail page, API calls over the network, and an optional long-poll like a realtime fallback.
+
+**With a real agent** — headless Claude Code, built-in tools off, the task given in plain words:
+
+```bash
+uv run python bench/agent_race.py --runs 3 --model sonnet
+```
+
+| | correct | turns | tokens read | tokens written | cost | time, no long-poll | time, long-poll open |
+|---|---|---|---|---|---|---|---|
+| **pointclick** | 6/6 | **7** | **104k** | **620–660** | **$0.056** | **13.7 s** | 16.7 s |
+| Playwright MCP 0.0.81 | 6/6 | 13 | 266–289k | 1.1k | $0.113–0.118 | 23.3 s | 28.5 s |
+| agent-browser 0.38.1 | 6/6 | 12 | 525k | 760–780 | $0.223 | 19.1 s | **14.8 s** |
+
+Medians of 3 runs per column. Turns and tokens barely move between runs; time moves by up to a
+third with model latency, so read it as a range. Playwright MCP's action replies link to a
+snapshot file instead of including the page, so the model asks for a snapshot after each step.
+agent-browser's actions return nothing, so every step is an action plus a snapshot too.
+
+**Tools alone** — the same flow driven by a script, so no model time is included:
+
+```bash
+uv run python bench/race.py --runs 8 --poll 0
+```
+
+| | calls | text to the model | tool time | with a long-poll open |
+|---|---|---|---|---|
+| **pointclick** | **6** | **6.6k chars (~1.9k tokens)** | 2.25 s | **2.31 s** |
+| Playwright MCP 0.0.81 | 6 | 17.0k chars (~4.9k tokens) | 3.32 s | 8.27 s |
+| agent-browser 0.38.1 | 18 | 12.3k chars (~3.5k tokens) | **1.13 s** | 1.12 s |
+
+agent-browser's tool time is lowest because its actions return nothing: it re-snapshots, and the
+script polls for free. In a real agent every one of those calls is a model turn.
+
+**Tool definitions**, sent with every request by clients that don't load tools lazily (all four
+estimated the same way, JSON characters ÷ 3.5):
+
+| | tools | definitions |
+|---|---|---|
+| **pointclick** | **8** | **~0.8k tokens** |
+| Playwright MCP | 26 | ~5.2k tokens |
+| Chrome DevTools MCP | 29 | ~6.9k tokens |
+| agent-browser (`core`) | 29 | ~18.4k tokens |
+
+Measured on an M-series Mac with Chrome 153. Raw results are in `bench/*.json`.
+
+## When to use something else
+
+- **Playwright MCP** — you need network interception, tracing, PDF export, or the full Playwright
+  surface.
+- **Chrome DevTools MCP** — performance traces, Lighthouse-style audits, deep DevTools debugging.
+- **agent-browser** — you'd rather drive the browser from a shell (CLI + skills), want saved auth
+  profiles, or need its long tail of commands.
+- **Stagehand** — you want natural-language `act`/`extract` backed by its own model, or hosted
+  browsers on Browserbase.
+
+pointclick does one job: get an agent through a web app with as little text and as few turns as
+it can — locally, with no account and no second model.
+
+## Security
+
+- Everything on a page — text, labels, titles — is **untrusted input** to your model. A page can
+  try to instruct your agent. Keep the agent's permissions narrow and confirm consequential steps.
+- Each session is an isolated browser context: no access to your Chrome profile, cookies or
+  passwords. Nothing persists after `close()`.
+- `evaluate` runs arbitrary JavaScript in the page; `upload` reads files you name from disk.
+
+## Limits
+
+- The list is viewport-only by default; long pages take `SCROLL_DOWN` or `observe(full=true)`.
+- Every action returns the whole list, not a diff.
+- Chromium only, one page at a time per server. Calls sent in parallel run one after another.
+- No network inspection, PDF export or dialog control; `evaluate` covers some of it.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest     # 45 tests; fixture pages served from two local origins
+uv run ruff check . && uv run ruff format --check .
+```
+
+To release, bump `version` in `pyproject.toml`, then push a matching tag (`v0.1.0`). `release.yml` publishes
+to PyPI through trusted publishing; there is no token to keep.
+
+## Credits
+
+The page snapshot is adapted from [jev-ultrafast](https://github.com/browser-use/jev-ultrafast),
+MIT © 2026 Browser Use — see `LICENSE-jev`.
+
+## License
+
+MIT

pointclick-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pointclick/__init__.py,sha256=hyKRHYhJ1P99GUL5bd4Efz7Pi6RsbIh4B0wJNO5eI9k,81
+pointclick/server.py,sha256=u5OxOto8RaLUrEg7IWJiEb3NFvQkootabMuoO-vkEZ4,14722
+pointclick/snapshot.js,sha256=UESumNjTyLgiZLZa_-zX_EuHFPOHKiLygoAxiHEqFFk,6909
+pointclick-0.1.0.dist-info/METADATA,sha256=jgcJG4EOEF3s12dLu4vfsvNRfdeLLnj_rGRVbZ5jxng,10032
+pointclick-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pointclick-0.1.0.dist-info/entry_points.txt,sha256=XrS2c2Q40Pon8wHbfpaf0T72SEm5-QD8F0JrUtqsFQo,54
+pointclick-0.1.0.dist-info/licenses/LICENSE,sha256=H2xzjbUsz8hg3tHkGMEuI78ezi6Bl0sjMV4XqR-ujJw,1064
+pointclick-0.1.0.dist-info/licenses/LICENSE-jev,sha256=Wvo9l78eb5mNWH-hAeP-DQxBaEC3_ne81q6XaQozRjE,1068
+pointclick-0.1.0.dist-info/RECORD,,

pointclick-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pointclick-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pointclick = pointclick.server:main

pointclick-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dashgin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pointclick-0.1.0.dist-info/licenses/LICENSE-jev

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browser Use
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.