cairn-browser-mcp 0.1.0__tar.gz

cairn_browser_mcp-0.1.0/.gitignore

@@ -0,0 +1,75 @@
+# --- Python (package/, mcp/, backend/) ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+env/
+.python-version
+
+# test + type + lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# --- Node / Next.js (frontend/) ---
+node_modules/
+.next/
+out/
+.vercel/
+*.tsbuildinfo
+next-env.d.ts
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# --- Secrets ---
+# Cairn needs NO API key to run. If one ever appears (OpenRouter, x402), it stays out of git.
+.env
+.env.*
+!.env.example
+*.pem
+
+# --- Cairn runtime state ---
+# Memory lives in ~/.sibyl-memory by default. If it is ever written next to the
+# code, it must never be committed: the deletion-gate test needs a real wipe.
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+.cairn/
+runs/
+
+# --- Browser automation output ---
+.playwright-mcp/
+playwright-report/
+test-results/
+blob-report/
+.cache/ms-playwright/
+
+# --- Agent tooling ---
+# Third-party skills are cloned in, not authored here. Reinstall with:
+#   git clone --depth 1 https://github.com/greensock/gsap-skills
+#   cp -r gsap-skills/skills/* .claude/skills/
+.claude/skills/
+.claude/settings.local.json
+
+# --- Scratch ---
+*.b64.txt
+scratch/
+tmp/
+
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+desktop.ini
+.idea/
+*.swp

cairn_browser_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md — mcp/ (THE PRODUCT)
+
+**This folder is the main deliverable.** Cairn as an MCP server, so Claude Code, Codex or
+Cursor becomes the brain and gets a browser that remembers websites.
+
+Phase 2. Read `PLAN.md` for what to build, `PROGRESS.md` for where we are. Root rules in
+`../CLAUDE.md` apply. Depends on `package/` (Phase 1) only.
+
+## Why this shape (do not drift back)
+
+The host AI does the thinking. Cairn supplies the browser and the memory. That means: no API
+key for us or the user, one-command install, and a judge can try it inside their own Claude
+Code. Warm replay is deterministic — zero model calls.
+
+## Stack (versions verified 2026-08-31)
+
+Python 3.11+ · official `mcp` SDK 2.1.1 **or** `fastmcp` 3.4.7 (decide at build time after
+opening both docs — RESEARCH rule) · the cairn package installed editable.
+
+## The one architecture rule
+
+Thin wrapper. Imports `package/` ONLY — never backend/ or frontend/. No browser logic, no
+Sibyl calls, no model calls here. Each tool is a few lines calling into `cairn`. If a tool
+needs real logic, that logic belongs in the package.
+
+## Tools to expose
+
+**Cold path (the host AI drives these to learn a new site):**
+
+| tool | does |
+|---|---|
+| `cairn_act(intent, action, ref?, value?, to?)` | ONE tool for all 31 actions, chosen by the `action` argument |
+| `cairn_read(kind, ref?, attribute?)` | `kind="page"` lists the controls; the other 12 kinds read one element |
+| `cairn_save(task)` | distil this session's trace into a playbook, store it |
+
+**One tool per verb, never one tool per action (locked 2026-09-01).** Tool choice is the
+most fragile part of this system — on the first live test a host AI ignored Cairn and used
+`curl`. Thirty-one tool names to choose between makes that worse, not better. Both tool
+descriptions are GENERATED from `actions.ACTIONS` and `reads.READS`, so an action can never
+exist without being discoverable.
+
+**Warm path (one call, no thinking):**
+
+| tool | does |
+|---|---|
+| `cairn_run(task, site)` | replay the playbook deterministically; repairs a broken step by asking the host AI only for that step |
+| `cairn_sites()` | learned sites + playbook health |
+| `cairn_show(domain)` | the playbook, human-readable |
+| `cairn_forget(domain)` | wipe a site's memory — the gate test, from inside any MCP client |
+
+Tool descriptions ARE the UX — the host AI decides what to call from them alone. One dedicated
+revision pass on the wording is mandatory before this phase is done.
+
+## Clean code rules
+
+- One file if it fits (`server.py`), two at most. Type hints, ruff clean.
+- Long operations must report progress, never hang the client silently.
+- Errors return readable messages, never stack traces.
+- Never print to stdout — it corrupts stdio MCP transport. Log to stderr only.
+
+## Definition of done
+
+Works from a CLEAN Claude Code session in a DIFFERENT folder + install instructions tested by
+following them literally + PROGRESS.md updated.

cairn_browser_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: cairn-browser-mcp
+Version: 0.1.0
+Summary: Cairn as MCP tools: a browser with a memory, for Claude Code, Cursor and Codex.
+Project-URL: Homepage, https://github.com/rohit-jsfreaky/cairn
+Project-URL: Repository, https://github.com/rohit-jsfreaky/cairn
+Project-URL: Issues, https://github.com/rohit-jsfreaky/cairn/issues
+Author: Rohit Kashyap
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing :: Acceptance
+Requires-Python: >=3.11
+Requires-Dist: cairn-browser
+Requires-Dist: mcp<2,>=1.29.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: market
+Requires-Dist: cairn-browser[market]; extra == 'market'
+Description-Content-Type: text/markdown
+
+# Cairn as MCP tools
+
+**Your AI can use websites. But it forgets how, every single time. Cairn makes it remember.**
+
+This gives Claude Code, Cursor, Codex or any MCP client a browser that remembers. Your AI
+walks a site once and Cairn writes down the route; every run after that is **one tool call,
+no page reading, and zero model calls**. When the site changes, Cairn hands back the single
+step that moved rather than the whole task.
+
+```bash
+pip install cairn-browser-mcp
+playwright install chromium        # the browser is a separate download
+
+claude mcp add cairn -- cairn-mcp
+```
+
+Then just ask, in your own words: *"go to github.com/microsoft/playwright and tell me how
+many open issues it has."* The first time it explores. After that it is one call.
+
+**No API key.** There is no model call anywhere in this package or anything it imports —
+your AI does the thinking and Cairn supplies the browser and the memory.
+
+Optional extra, so one agent can buy a trail from another over x402 on Base:
+
+```bash
+pip install "cairn-browser-mcp[market]"
+```
+
+The engine on its own is [`cairn-browser`](https://pypi.org/project/cairn-browser/).
+
+Full documentation, the tool list, and the deletion test that proves the memory is
+load-bearing: **https://github.com/rohit-jsfreaky/cairn**
+
+MIT licensed.

cairn_browser_mcp-0.1.0/PLAN.md

@@ -0,0 +1,46 @@
+# PLAN — mcp/ (Phase 2, Sep 4–5)
+
+Finish line in `../MASTER-PLAN.md`. Start after Phase 1 passes. This is the main deliverable —
+it is NOT cuttable.
+
+### 2a. Research (timebox 30 min)
+- Open the `mcp` (2.1.1) and `fastmcp` (3.4.7) docs with Playwright. Pick one, note the choice
+  and reason in `../RESEARCH.md`.
+- Look at how `sibyl-memory-mcp` structures its server — same sponsor, good reference.
+
+### 2b. Cold-path tools
+- `cairn_look`, `cairn_act`, `cairn_save` wired to `cairn.operations` + `cairn.distill`.
+- Session handling: one browser session per MCP connection, cleaned up properly on exit.
+- ✅ in Claude Code, asking it to do the demo task works: it looks, acts, and saves a playbook.
+
+### 2c. Warm-path tools
+- `cairn_run`, `cairn_sites`, `cairn_show`, `cairn_forget`.
+- Repair inside `cairn_run`: when a step breaks, return a precise repair request so the host AI
+  fixes only that step, then persist it.
+- ✅ the whole four-beat flow works from Claude Code with no terminal.
+
+### 2d. Tool description pass
+- Rewrite every description so the host AI reliably picks `cairn_run` (warm) over the cold
+  tools when a playbook already exists. Test by asking vaguely: "get my invoice from that
+  portal" — it should go straight to `cairn_run`.
+- ✅ three vague prompts in a row route correctly.
+
+### 2e. Install path + adoption
+- `claude mcp add` line, plus config snippets for Codex and Cursor.
+- **OpenClaw (388k★) — confirmed: docs.openclaw.ai lists "Connect MCP servers", so our server
+  plugs in with install docs only, no extra code.** Note their users ALREADY have browser
+  tools (Browser control API, Chrome Extension, etc.), so the message there is not "here is a
+  browser" but "your browser stops re-learning the same site". They also run ClawHub + a
+  5,400-skill registry — a good place to be seen. See ../RESEARCH.md.
+- **Hermes Agent (Nous Research) — check this before writing the install docs.** Sibyl
+  officially supports Hermes, so it is inside the sponsor's own world. First find out whether
+  Hermes loads MCP servers directly: if yes, we get it free and only need install docs; if no,
+  a thin plugin adapter (mirror how `sibyl-memory-hermes` installs into
+  `$HERMES_HOME/plugins/`). Hermes is the strongest home for Cairn because it runs
+  **unattended on a cron schedule** — exactly where deterministic replay beats an improvising
+  AI. See ../RESEARCH.md.
+- README install section, tested by following it literally in a clean folder.
+- Share in the hackathon Discord — one non-Rohit person installs and runs it. That is real,
+  verifiable PMF evidence (and the rules require evidence a judge can check in 5 minutes).
+- ✅ Phase 2 finish line: clean Claude Code session learns a site, quit, fresh session replays
+  it in seconds, `cairn_forget` makes it slow again.

cairn_browser_mcp-0.1.0/PROGRESS.md

@@ -0,0 +1,201 @@
+# PROGRESS — mcp/ (THE PRODUCT)
+
+> Working memory for this folder. Read first, update before ending every session.
+
+## Current state — 2026-09-01
+
+**PHASE 2 IS DONE. The finish line passed on a live Claude Code session, 2026-09-01.**
+
+24 tests pass, ruff clean, real stdio transport verified, and all four beats ran in a
+CLEAN Claude Code session in a DIFFERENT folder (`D:\my_projects\project_research`).
+
+```
+pytest mcp        22 passed
+ruff check mcp    All checks passed
+stdio handshake   server: cairn, 9 tools listed, structured results returned
+```
+
+## What exists
+
+```
+mcp/
+  pyproject.toml            distribution `cairn-mcp`, console script `cairn-mcp`
+  README.md                 install for Claude Code / Cursor / Codex + the 4-beat demo
+  src/cairn_mcp/
+    server.py               all 9 tools, thin wrappers over the engine
+    __main__.py             `python -m cairn_mcp`
+  tests/
+    conftest.py             demo site + a server with its own memory db
+    helpers.py              call() a tool the way a host AI would
+    test_server.py          22 tests
+```
+
+Plus `../.mcp.json` at the repo root, so Claude Code opened in this repo offers the server
+with a **relative** command — clone, make the venv, approve, done. Verified with
+`claude mcp list`: `cairn: .venv/Scripts/python.exe -m cairn_mcp - Pending approval`.
+
+## The 9 tools
+
+| tool | path | note |
+|---|---|---|
+| `cairn_run` | warm | the product. One call, 0 model calls, 0 pages read. |
+| `cairn_repair` | warm | applies the host AI's fix to ONE step |
+| `cairn_sites` `cairn_show` `cairn_forget` | warm | inspect and wipe |
+| `cairn_open` `cairn_look` `cairn_act` `cairn_save` | cold | only for a site never seen |
+
+Two departures from the table in CLAUDE.md, both deliberate:
+
+- **`cairn_open` added.** The plan routed navigation through `cairn_act(action="goto")`.
+  That is awkward to describe and easy for a host AI to get wrong, and tool descriptions
+  are the entire UX here. A named tool for "start here" is clearer.
+- **`cairn_repair` added.** `cairn_run` can detect a break and describe it, but applying
+  the fix needs a second call, because the host AI is the thing that decides what the new
+  control is. Without this tool the repair loop cannot close.
+
+## Decisions
+
+- **Official `mcp` SDK, not the `fastmcp` package.** Reasons in `../RESEARCH.md`; the short
+  version is that FastMCP ships inside the official SDK, `mcp` was already installed, and
+  Sibyl's own MCP server uses exactly this shape.
+- **The browser runs on its own thread** (`cairn/worker.py` in the engine). Playwright's
+  sync API binds objects to their creating thread and refuses to run inside an asyncio
+  loop; an MCP server breaks both rules. Marshalling every call onto one thread is the
+  proper fix, not a workaround.
+- **Every tool returns a `next` string** when the AI has more to do. The result is the only
+  thing it sees, so telling it what to do next is not decoration, it is the control flow.
+- **Tool descriptions are tested.** `TestToolDescriptions` asserts `cairn_run` says
+  "TRY THIS FIRST" and appears before `cairn_open` in the server instructions. A host AI
+  that reaches for the cold tools on a known site would quietly destroy the whole point of
+  the project, so the wording that prevents it cannot be allowed to rot silently.
+
+## The finish line — PASSED 2026-09-01, observed live
+
+Clean Claude Code (v2.1.252, Opus 5), folder `D:\my_projects\project_research`, which has
+never contained any Cairn code.
+
+| beat | asked | what happened |
+|---|---|---|
+| recall | "Download this month's invoice from http://127.0.0.1:8787" | **one** cairn call. 4 steps replayed, ~2s, no page reading. Reported the saved path. |
+| repair | "same thing but the site is now at ...?variant=b" | 2 cairn calls. 3 steps replayed, step 4 broke, it chose `#get-pdf` ("Get PDF"), repaired, re-ran. Said the fix is saved so the next run needs no repair. |
+| gate | "Forget 127.0.0.1:8787" | forgotten, and it explained the consequence unprompted: the next download "will need full exploring again". |
+
+**Discovery worked with no prompting.** It went straight to `cairn_run` without being told
+to use Cairn — the description rewrite (below) is what fixed that.
+
+### The two failures that got us here, both real
+
+1. **It used `curl` and ignored Cairn entirely.** Cause: `cairn_run`'s summary line read
+   "a website **that Cairn already knows**" — a condition the AI cannot evaluate while
+   scanning the tool list, so it skipped the tool. And "TRY THIS FIRST, before any other
+   **Cairn** tool" only ranked our own tools against each other; it never mentioned the
+   shell, which is what it actually chose. Fixed by opening unconditionally with "USE THIS
+   FOR ANY WEBSITE TASK" and naming curl/wget/fetch/shell explicitly. Pinned by tests.
+
+2. **Downloads never reached disk.** Found by the host AI itself, not by our tests.
+   `Browser` accepted a `downloads` path that nobody passed, so Playwright deleted the file
+   when the context closed. Our test only asserted the download *event* fired — it was
+   green while proving the wrong thing. Fixed with a default `~/.cairn/downloads`, deferred
+   saving (saving inside Playwright's event callback fails with "Download.save_as:
+   canceled"), and `saved_files` reported through run/CLI/MCP. Tests now assert a real
+   non-empty file.
+
+**Lesson worth keeping:** a real host AI on a real task found a bug that 94 passing tests
+did not. Assert the user-visible outcome, not the internal event.
+
+**Phase 1g is DONE (2026-09-02).** Proven through these tools on 8 real websites, two of
+them signed in. Nothing here is demo-site-only any more.
+
+## Session log
+
+- **2026-08-31** — folder created, plan written. No code.
+- **2026-09-01** — Phase 2 built in one pass. SDK decision closed by reading Sibyl's own
+  installed server rather than docs. Found and fixed the Playwright-threading problem with a
+  dedicated browser thread in the engine. `call_tool` turned out to return a
+  `(blocks, structured)` tuple, which cost one debugging round. Install docs written and the
+  project-scoped `.mcp.json` verified with `claude mcp list`.
+- **2026-09-02/03** — surface collapsed to `cairn_act` + `cairn_read`, both descriptions
+  GENERATED from the engine registries so a capability cannot exist without being
+  discoverable. Three commons tools added (`cairn_share`, `cairn_borrow`, `cairn_commons`)
+  and the `cairn_run` miss branch rewritten so `next` is REPLACED, not appended — left as it
+  was it said "explore this site" and "do NOT explore this site" in the same message.
+  `run_stdio()` now reads `CAIRN_AGENT`, `CAIRN_PROFILE` and `CAIRN_DB`, so a second agent
+  can be configured from `.mcp.json` at all — before this there was no way to.
+  `cairn_forget` now reports what it withdrew from the commons and what it cannot reach.
+  **80 tests, ruff clean.**
+
+- **2026-09-03 (Phase 5b — Base x402 — BUILT)** — a trail you can sell. The original plan
+  assumed payment could be bolted onto the local commons; it could not, because x402 is
+  defined by an HTTP 402 exchange and the commons is two Sibyl tenants in one local file with
+  no network anywhere. So the phase grew an HTTP boundary: `cairn sell` serves this agent's
+  shared trails, `cairn buy` (and the `cairn_buy` MCP tool) pays for one. That also closes a
+  real gap — two agents could previously only share memory by sharing a database file.
+  Design rules held to: browsing the catalogue is FREE and carries no steps or locators (it
+  reuses `describe_offer`, a shape with none in it to leak); the trail is genuinely
+  unreachable without a settled payment; **the trail never goes on chain**, only the payment
+  does; and the local commons stays free, because charging your own second agent on your own
+  laptop is theatre. All x402 lives in ONE file, `payments.py`, mirroring the `store.py` rule
+  — `shop.py` goes through `payments.gate()` rather than importing the SDK, and a test walks
+  the source to keep it that way.
+  Borrowing and buying now share `_import_offer`, so a bought trail gets the same provenance,
+  the same protection over a repaired trail and the same note merging. Two import paths would
+  have drifted, and the paid one is the one nobody exercises by accident.
+  **518 engine + 98 MCP tests, ruff clean.** Four new deletion-gate tests are the ones that
+  matter: a bought trail can still be forgotten, the transaction cannot bring it back, the
+  seller's shelf empties when the seller forgets, and the buyer keeps what it paid for when
+  the seller forgets.
+  Facts were read off the INSTALLED SDK, not its docs, which were wrong twice: `ResourceConfig`
+  takes `payTo` (camelCase) while `PaymentOption` takes `pay_to`, and the ASGI middleware needs
+  the async resource server. Also found: the middleware skips settlement on any 4xx, so a
+  buyer who pays for a trail the shop does not have gets a 404 and an untouched wallet.
+  No new `events.py` types: share and borrow do not emit any either, the cold journal is the
+  record, and three event classes nothing subscribes to would be dead code.
+  **Still needed from Rohit: a funded wallet.** Everything up to the signature is verified —
+  a live shop answering a real `HTTP/1.1 402 Payment Required`, the challenge naming Base
+  Sepolia and the real USDC contract `0x036CbD…F7e`, and a purchase attempt that reached the
+  facilitator and failed only on funds.
+
+- **2026-09-04 (Phase 6 — hardening, part one)** — an audit before touching anything, then
+  the fixes. Five real bugs, not tidying:
+  1. **`steps_repaired` had never once been true.** `executor.py` hardcoded it to 0 and
+     nothing incremented it, because a run cannot repair anything — it stops at the broken
+     step and the fix arrives as a separate call. The CLI printed "0 repaired" after every
+     run regardless, including runs of a trail that HAD been repaired, and `benchmark.py`
+     faked its own repair count by hand to make the README table read right. Replaced with
+     `trail_repairs`, which is the trail's real repair history, mentioned only when it is
+     non-zero. Two tests now hold it in place.
+  2. **Three blind `except Exception`** — including `except (PWTimeout, Exception)` in
+     `resolve()`, where the second clause swallowed the first along with any real bug in
+     `_to_playwright` and reported it as ordinary site drift. All narrowed to
+     `PlaywrightError`, so only the browser's own failures count as drift and a fault of
+     ours surfaces as itself. **`BLE` added to ruff's `select`** in both packages so this
+     cannot come back — it had already caused two incidents here.
+  3. **A machine with no browser was told its profile was broken** and invited to delete it.
+     `_is_missing_browser` existed but was only consulted on the clean-mode path, and
+     profile mode is the default. It now says `playwright install chromium` and explicitly
+     that nothing is wrong with the profile.
+  4. **The front door was Windows-only.** `.mcp.json` named `.venv/Scripts/cairn-mcp.exe`,
+     and Claude Code reads that file the moment anyone opens the repo — so a judge on a Mac
+     got a broken server before reading a word. Now it runs `mcp-server.py`, a launcher that
+     finds the venv on either layout. The README shows both `claude mcp add` commands, and
+     the demo site's busy-port help no longer prints `netstat`/`taskkill` to Linux users.
+  5. **`mcp>=1.29.1` let a fresh install pick up mcp 2.x, where `FastMCP` was renamed to
+     `MCPServer`.** The server raised ModuleNotFoundError on import and never started. This
+     venv held 1.29.1 from an earlier install, so all 616 tests passed while a stranger's
+     `pip install` was completely broken. **This is the one that would have hit every
+     judge.** Found by building the wheels and installing them into a clean Python 3.11
+     virtualenv. Pinned to `<2`; migrating to 2.x is post-deadline work.
+
+  Also: the 47 payment tests are `importorskip`-gated, so the README's Development block now
+  installs `[market]` first — otherwise "all tests passed" can be true while none of the
+  Base code ran. CI does the same.
+
+  **Packaging.** `cairn` and `cairn-mcp` are both taken on PyPI by unrelated projects, so
+  the distributions are now **`cairn-browser`** and **`cairn-browser-mcp`**. Only the
+  distribution names changed: the import package is still `cairn` and the commands are still
+  `cairn` and `cairn-mcp`. Added readmes, classifiers and project URLs so the PyPI pages are
+  not blank. All four artefacts pass `twine check`, and both wheels install and run from a
+  clean Python 3.11 venv.
+
+  **CI.** `.github/workflows/test.yml` installs from scratch on Ubuntu against Python 3.11
+  and 3.13, runs both suites with `[market]`, and checks ruff. It cannot run until Rohit
+  pushes. The lint commands were verified locally from the repo root first.

cairn_browser_mcp-0.1.0/README.md

@@ -0,0 +1,34 @@
+# Cairn as MCP tools
+
+**Your AI can use websites. But it forgets how, every single time. Cairn makes it remember.**
+
+This gives Claude Code, Cursor, Codex or any MCP client a browser that remembers. Your AI
+walks a site once and Cairn writes down the route; every run after that is **one tool call,
+no page reading, and zero model calls**. When the site changes, Cairn hands back the single
+step that moved rather than the whole task.
+
+```bash
+pip install cairn-browser-mcp
+playwright install chromium        # the browser is a separate download
+
+claude mcp add cairn -- cairn-mcp
+```
+
+Then just ask, in your own words: *"go to github.com/microsoft/playwright and tell me how
+many open issues it has."* The first time it explores. After that it is one call.
+
+**No API key.** There is no model call anywhere in this package or anything it imports —
+your AI does the thinking and Cairn supplies the browser and the memory.
+
+Optional extra, so one agent can buy a trail from another over x402 on Base:
+
+```bash
+pip install "cairn-browser-mcp[market]"
+```
+
+The engine on its own is [`cairn-browser`](https://pypi.org/project/cairn-browser/).
+
+Full documentation, the tool list, and the deletion test that proves the memory is
+load-bearing: **https://github.com/rohit-jsfreaky/cairn**
+
+MIT licensed.

cairn_browser_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cairn-browser-mcp"
+version = "0.1.0"
+description = "Cairn as MCP tools: a browser with a memory, for Claude Code, Cursor and Codex."
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing :: Acceptance",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+]
+authors = [{ name = "Rohit Kashyap" }]
+dependencies = [
+    "cairn-browser",
+    # Capped at <2 deliberately, and it is not cosmetic. In mcp 2.x `FastMCP` was renamed
+    # to `MCPServer` and other APIs changed with it, so `from mcp.server.fastmcp import
+    # FastMCP` raises ModuleNotFoundError on import and the server never starts.
+    # This venv happened to hold 1.29.1 from an earlier install, so every test passed while
+    # a fresh `pip install` was completely broken — found by installing the built wheels
+    # into a clean virtualenv, 2026-09-04. Migrating to 2.x is post-deadline work.
+    "mcp>=1.29.1,<2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+# `cairn_buy` needs the payment code, which lives in the engine's optional extra.
+# Declaring it here means one install is enough, instead of relying on somebody having
+# put the engine's extra into the same virtualenv by hand.
+market = ["cairn-browser[market]"]
+
+[project.urls]
+Homepage = "https://github.com/rohit-jsfreaky/cairn"
+Repository = "https://github.com/rohit-jsfreaky/cairn"
+Issues = "https://github.com/rohit-jsfreaky/cairn/issues"
+
+[project.scripts]
+cairn-mcp = "cairn_mcp.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cairn_mcp"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# BLE catches `except Exception`. It is here because that exact shape has already
+# caused two incidents in this project: a silent sign-out, and an error that blamed
+# the browser profile for every possible failure. Where a blind catch is genuinely
+# right, mark it `# noqa: BLE001` with the reason.
+select = ["E", "F", "I", "UP", "B", "SIM", "BLE"]

cairn_browser_mcp-0.1.0/src/cairn_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Cairn as MCP tools: a browser with a memory, for the AI you already use."""
+
+from .server import build_server, run_stdio
+
+__version__ = "0.1.0"
+__all__ = ["build_server", "run_stdio", "__version__"]

cairn_browser_mcp-0.1.0/src/cairn_mcp/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point: `cairn-mcp` console script and `python -m cairn_mcp`."""
+
+from .server import run_stdio
+
+
+def main() -> None:
+    run_stdio()
+
+
+if __name__ == "__main__":
+    main()