nullprint-mcp 0.1.0__py3-none-any.whl

nullprint_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""Nullprint MCP server — an open-protocol tool layer over the local daemon.
+
+MCP is an open protocol, so any MCP client (Claude Code, OpenAI Codex, Kimi,
+...) drives Nullprint identities with the same server. This package is a thin
+HTTP client: the daemon owns all behavior, every tool maps onto daemon
+endpoints and passes daemon errors through as readable messages.
+
+Run it as `nullprint-mcp` (stdio transport).
+"""
+
+__all__ = ["daemon", "tools", "server"]

nullprint_mcp/__main__.py

@@ -0,0 +1,39 @@
+"""Entry point: `nullprint-mcp` (also `python -m nullprint_mcp`), stdio transport.
+
+Nothing may be printed to stdout — stdout IS the MCP channel.
+"""
+from __future__ import annotations
+
+import argparse
+
+from .daemon import DEFAULT_HOST
+from .server import build_server
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="nullprint-mcp",
+        description="Nullprint MCP server (stdio) — drive browser identities from any MCP client.",
+    )
+    p.add_argument(
+        "--daemon-url",
+        help="full daemon base URL, e.g. http://127.0.0.1:7801. "
+             "Default: read the running daemon's port from ~/.nullprint/daemon.json.",
+    )
+    p.add_argument("--port", type=int, help=f"shorthand for --daemon-url http://{DEFAULT_HOST}:<port>")
+    p.add_argument("--host", default=DEFAULT_HOST, help=f"host to use with --port (default {DEFAULT_HOST})")
+    args = p.parse_args(argv)
+    if args.daemon_url and args.port:
+        p.error("pass either --daemon-url or --port, not both")
+    if args.port is not None:
+        args.daemon_url = f"http://{args.host}:{args.port}"
+    return args
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parse_args(argv)
+    build_server(args.daemon_url).run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

nullprint_mcp/daemon.py

@@ -0,0 +1,160 @@
+"""HTTP plumbing for the daemon: where it lives, and how its errors read.
+
+The daemon binds a RANDOM free port by default and records it in
+`<runtime dir>/daemon.json` (`NULLPRINT_PORT` pins it instead). There is no
+fixed default port to hard-code, so the address is resolved per call — that
+also means a daemon restart on a new port is picked up without restarting this
+server.
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+
+import httpx
+
+DEFAULT_HOST = "127.0.0.1"
+TIMEOUT = 130            # a headed launch can take a while; same budget the CLI uses
+
+_daemon_url: str | None = None   # set by --daemon-url / --port at startup
+
+
+class DaemonError(RuntimeError):
+    """Anything that stops a tool from answering: daemon down, or daemon said no.
+
+    The message is written for whoever reads the tool result — a human or an
+    AI client — so it names the address, the status, and what to do next.
+    `status` is the HTTP status when the daemon answered, None when it did not,
+    so a tool can branch on it (profile_stop falls back on 404/409).
+    """
+
+    def __init__(self, message: str, status: int | None = None):
+        super().__init__(message)
+        self.status = status
+
+
+def set_daemon_url(url: str | None) -> None:
+    """Pin the daemon address (from --daemon-url / --port). None restores discovery."""
+    global _daemon_url
+    _daemon_url = url.rstrip("/") if url else None
+
+
+def runtime_dir() -> pathlib.Path:
+    """NULLPRINT_HOME if set, else ~/.nullprint (where the desktop app keeps daemon.json)."""
+    home = os.environ.get("NULLPRINT_HOME")
+    if home:
+        return pathlib.Path(home).expanduser()
+    return pathlib.Path.home() / ".nullprint"
+
+
+def base_url() -> str:
+    """Resolve the daemon's base URL, most explicit source first.
+
+    1. `--daemon-url` / `--port` (set_daemon_url)
+    2. `NULLPRINT_DAEMON_URL` (`SUPLOGIN_DAEMON_URL` still honoured for old setups)
+    3. `NULLPRINT_PORT` (the daemon's own port pin)
+    4. `<runtime dir>/daemon.json`, which the running daemon writes
+    """
+    if _daemon_url:
+        return _daemon_url
+    env_url = os.environ.get("NULLPRINT_DAEMON_URL") or os.environ.get("SUPLOGIN_DAEMON_URL")
+    if env_url:
+        return env_url.rstrip("/")
+    env_port = os.environ.get("NULLPRINT_PORT")
+    if env_port:
+        return f"http://{DEFAULT_HOST}:{env_port}"
+
+    path = runtime_dir() / "daemon.json"
+    try:
+        info = json.loads(path.read_text())
+    except OSError:
+        raise DaemonError(
+            f"the Nullprint daemon does not look like it is running: no {path}. "
+            "Start the daemon (the desktop app starts it for you), or point this "
+            "server at one with --daemon-url http://127.0.0.1:<port>."
+        ) from None
+    except ValueError:
+        raise DaemonError(
+            f"{path} is not valid JSON — the daemon may have been killed mid-write. "
+            "Restart the daemon, or pass --daemon-url."
+        ) from None
+    port = info.get("port")
+    if not port:
+        raise DaemonError(f"{path} has no 'port' field; restart the daemon or pass --daemon-url.")
+    return f"http://{DEFAULT_HOST}:{port}"
+
+
+def api_key() -> str | None:
+    """daemon.json 里的 api_key;NULLPRINT_API_KEY 可覆盖(配合 --daemon-url 指向别的 daemon)。"""
+    env = os.environ.get("NULLPRINT_API_KEY")
+    if env:
+        return env
+    try:
+        return json.loads((runtime_dir() / "daemon.json").read_text()).get("api_key")
+    except (OSError, ValueError):
+        return None
+
+
+_STATUS_HINT = {
+    401: "API key missing or wrong — the daemon.json api_key is read automatically; "
+         "set NULLPRINT_API_KEY when using --daemon-url",
+    403: "not authorized (license invalid or profile quota reached)",
+    404: "not found",
+    409: "conflict — it is already in that state, or busy",
+    422: "the daemon rejected the arguments",
+    429: "too many warm sessions; stop one first",
+    502: "the browser worker failed to answer",
+    503: "the daemon could not reach its backend",
+}
+
+
+def _license_text(d: dict) -> str:
+    """The license/quota 403 carries a {reason, limit, used} dict, not a sentence.
+    Say it in words — an AI client that reads 'quota_exceeded' should not have to
+    guess whether deleting something would help."""
+    used, limit = d.get("used"), d.get("limit")
+    counts = f" ({used} of {limit} identities used)" if None not in (used, limit) else ""
+    if d.get("reason") == "quota_exceeded":
+        return ("profile quota reached" + counts +
+                " — delete an identity you no longer need, or raise the plan's limit.")
+    return (f"this installation is not authorized (license state: {d.get('reason')})"
+            + counts + ". Authorize it from the desktop app, then retry.")
+
+
+def _detail(resp: httpx.Response) -> str:
+    """Pull the readable part out of a FastAPI error body."""
+    try:
+        body = resp.json()
+    except ValueError:
+        return (resp.text or "").strip()[:400] or "(empty response body)"
+    detail = body.get("detail", body) if isinstance(body, dict) else body
+    if isinstance(detail, dict) and detail.get("reason") in ("api_key_required", "invalid_api_key"):
+        return detail["reason"]           # 401 的说明已在 _STATUS_HINT 里,别当成授权问题
+    if isinstance(detail, dict) and "reason" in detail:
+        return _license_text(detail)
+    return detail if isinstance(detail, str) else json.dumps(detail, ensure_ascii=False)
+
+
+def request(method: str, path: str, **kw) -> httpx.Response:
+    """Call the daemon. Raises DaemonError with a readable message on any failure."""
+    url = base_url()
+    headers = dict(kw.pop("headers", {}) or {})
+    k = api_key()
+    if k:
+        headers["X-API-Key"] = k
+    try:
+        with httpx.Client(timeout=TIMEOUT) as client:
+            resp = client.request(method, f"{url}{path}", headers=headers, **kw)
+    except httpx.HTTPError as e:
+        raise DaemonError(
+            f"cannot reach the Nullprint daemon at {url} ({type(e).__name__}: {e}). "
+            "Check that it is running, or pass --daemon-url with the right address."
+        ) from None
+    if resp.is_success:
+        return resp
+    hint = _STATUS_HINT.get(resp.status_code, "the daemon refused the request")
+    raise DaemonError(
+        f"daemon {method} {path} -> {resp.status_code} ({hint}): {_detail(resp)}",
+        status=resp.status_code,
+    )

nullprint_mcp/server.py

@@ -0,0 +1,29 @@
+"""The MCP server object: name, instructions, and the tool registry."""
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from . import daemon
+from .tools import TOOLS
+
+SERVER_NAME = "nullprint"
+
+INSTRUCTIONS = """Nullprint runs browser identities: each one is a separate browser
+profile with its own frozen fingerprint, its own exit IP, and its own cookies, so
+sites see independent people rather than one machine.
+
+Typical flow: profiles_list to find the identity, profile_start to open its
+browser, do the work, profile_stop when finished. Never leave a session open
+after you are done — it holds a warm browser with live login state.
+
+Identity names are case-sensitive and come from profiles_list; do not invent them."""
+
+
+def build_server(daemon_url: str | None = None) -> FastMCP:
+    """Construct the server. daemon_url pins the daemon address; None discovers it."""
+    if daemon_url is not None:
+        daemon.set_daemon_url(daemon_url)
+    server = FastMCP(SERVER_NAME, instructions=INSTRUCTIONS)
+    for fn in TOOLS:
+        server.tool()(fn)
+    return server

nullprint_mcp/tools.py

@@ -0,0 +1,457 @@
+"""The tools themselves.
+
+Plain functions, undecorated: tests call them directly, `server.build_server()`
+registers them. Each one maps onto daemon endpoints and adds nothing but
+argument checking and a readable error.
+"""
+from __future__ import annotations
+
+from . import daemon
+from .daemon import DaemonError
+
+# Keys a daemon build may use for the live-debugging endpoint of a session.
+# Accepting several keeps this tool stable whichever name the engine settles on.
+_CDP_KEYS = ("cdp_endpoint", "ws_endpoint", "cdp_url", "webSocketDebuggerUrl")
+
+_NO_CDP_NOTE = (
+    "This identity's browser core does not publish a CDP endpoint — only the Chrome "
+    "core does. Drive it through the daemon's /sessions/{name}/* commands instead "
+    "(goto, snapshot, click, type, screenshot, ...)."
+)
+
+
+def _identity_name(name: str) -> str:
+    """Validate an identity name before it becomes a URL path segment."""
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("name is required: the identity's name, e.g. 'bing-us'")
+    clean = name.strip()
+    if "/" in clean or clean in (".", ".."):
+        raise ValueError(f"invalid identity name {name!r}: '/' and '.'/'..' are not allowed")
+    return clean
+
+
+def profiles_list() -> list[dict]:
+    """List every identity in this installation, with its live status.
+
+    Each entry carries: name, os, engine (which browser core backs it),
+    created, proxy (the exit server only — never credentials), status
+    ("running" when a browser is open for it, otherwise "idle"), and meta
+    (the local ledger: group, tags, note, last_launched).
+
+    Call this first to find the exact name to pass to profile_start /
+    profile_stop; names are case-sensitive.
+    """
+    return daemon.request("GET", "/profiles").json()
+
+
+def profile_start(name: str, headless: bool = False) -> dict:
+    """Open a browser session for an identity and return the endpoint to drive it.
+
+    The identity keeps its frozen fingerprint, its exit proxy, and its logged-in
+    cookies — starting it does not re-randomize anything. Starting an identity
+    that already has a session open is a no-op that returns the existing one.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+        headless: run without a visible window. Default False (headed), which
+            is what sites expect and what you want for anything login-shaped.
+
+    Returns the session record: name, opened_at, idle_seconds, url (the page it
+    is on), plus cdp_endpoint — a ws:// DevTools address you can attach your own
+    automation to. Only the Chrome browser core publishes one; on the Firefox
+    core it is None and cdp_note says what to use instead.
+
+    Prefer the daemon's own commands over attaching to cdp_endpoint. A session
+    driven from outside bypasses Nullprint's consistency guards, so an outside
+    tool can set a viewport, locale, timezone, or header that contradicts the
+    identity's frozen fingerprint and make it detectable. Attach at your own
+    risk, and change nothing the identity did not already claim.
+
+    Fails with a readable message if the identity does not exist (404), if too
+    many sessions are already warm (429), or if the daemon is not running.
+    """
+    clean = _identity_name(name)
+    session = daemon.request(
+        "POST", f"/sessions/{clean}", json={"headless": bool(headless)}
+    ).json()
+
+    out = dict(session)
+    out["cdp_endpoint"] = next((session[k] for k in _CDP_KEYS if session.get(k)), None)
+    if out["cdp_endpoint"] is None:
+        out["cdp_note"] = _NO_CDP_NOTE
+    return out
+
+
+def profile_stop(name: str) -> dict:
+    """Stop an identity's browser, however it was started.
+
+    Cookies and login state live in the identity's own storage and survive the
+    stop; whatever was typed into an open form does not. Stop identities you are
+    done with — a running identity holds a warm browser and keeps its login
+    state exposed.
+
+    Two things can be running for one identity and this closes either: the warm
+    session profile_start opens (the daemon drives it), and a window the desktop
+    app launched on its own. The session is closed first; if there is none, the
+    identity-level stop is used instead, which also terminates a launched window
+    and is a no-op on an identity that is already idle.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+
+    Returns {name, stopped, closed}: `stopped` is False when the identity was
+    already idle, and `closed` lists what was actually shut down.
+
+    Fails with a readable message if the identity does not exist, or if the
+    daemon is not running.
+    """
+    clean = _identity_name(name)
+    try:
+        daemon.request("DELETE", f"/sessions/{clean}")
+        return {"name": clean, "stopped": True, "closed": ["session"]}
+    except DaemonError as e:
+        # 409 "session not open" is the usual answer for an identity that was
+        # launched as a window rather than opened as a session; 404 is allowed
+        # for too in case a daemon build reports it that way. Anything else
+        # (daemon down, 422, ...) is a real failure and must not be swallowed.
+        if e.status not in (404, 409):
+            raise
+    result = daemon.request("POST", f"/profiles/{clean}/stop").json()
+    closed = result.get("stopped") or []
+    return {"name": clean, "stopped": bool(closed), "closed": closed,
+            "status": result.get("status")}
+
+
+def profile_create(name: str, engine: str | None = None, proxy: str | None = None,
+                   group: str | None = None, tags: list[str] | None = None,
+                   note: str | None = None, urls: list[str] | None = None) -> dict:
+    """Create a new identity. Its fingerprint is generated and frozen on the spot.
+
+    You do not choose the fingerprint — the point of the product is that every
+    identity gets one self-consistent, frozen set of traits that stays
+    byte-identical across restarts. Do not create identities speculatively: they
+    count against the installation's quota.
+
+    Args:
+        name: the new identity's name. Must be unique — creating a name that
+            already exists fails rather than overwriting it.
+        engine: which browser core backs the identity. Leave unset to use this
+            installation's default; an unknown value is rejected with the list
+            of accepted ones. The `engine` field in profiles_list shows what
+            existing identities use.
+        proxy: exit proxy URL, e.g. "http://user:pass@host:port" or
+            "socks5://host:port" — any vendor, bring your own. Omit it and the
+            identity runs on a direct connection. Test a URL with proxy_check
+            before binding it here.
+        group, tags, note: the local ledger — which account, email, or purpose
+            this identity is bound to. Free text, searchable in the app, and
+            returned under `meta` by profiles_list.
+        urls: startup tabs — pages opened automatically when the identity starts.
+
+    Returns {name, os, created}. Fails with a readable message if the name is
+    taken (409), if the quota is reached or the installation is unauthorized
+    (403), or if an argument is rejected (422).
+    """
+    clean = _identity_name(name)
+    body = {"name": clean, "engine": engine, "proxy": proxy,
+            "group": group, "tags": tags, "note": note, "urls": urls}
+    return daemon.request(
+        "POST", "/profiles", json={k: v for k, v in body.items() if v is not None}
+    ).json()
+
+
+def profile_checkup(name: str, live: bool = False) -> dict:
+    """Run the consistency checkup on an identity — is its fingerprint coherent?
+
+    This is the check competitors cannot make: every trait has one correct value
+    given the identity's OS, browser core, and exit IP, so each item gets a
+    verdict rather than just being displayed. Run it after changing an
+    identity's proxy, and before trusting an identity with anything that matters.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+        live: False (default) derives everything from the stored record — fast,
+            no side effects. True additionally STARTS THE BROWSER to measure the
+            real TLS/JA3 fingerprint and User-Agent against the browser core's
+            baseline. That takes tens of seconds and opens a window, so use it
+            when you actually need measured proof, not for a routine look.
+
+    Returns {name, engine, live, summary, checks}. `summary` is "pass", "warn",
+    or "fail" — the worst verdict among the checks. Each entry in `checks` has
+    an id, a label, a verdict ("pass"/"warn"/"fail"/"skip"), and a detail
+    string explaining it. "skip" means the check needs live=True, or does not
+    apply (a direct-connection identity has no exit geography to align).
+    """
+    clean = _identity_name(name)
+    return daemon.request(
+        "GET", f"/profiles/{clean}/checkup", params={"live": bool(live)}
+    ).json()
+
+
+def proxy_check(url: str) -> dict:
+    """Test a proxy URL and report where it actually comes out. No identity needed.
+
+    Use it before binding a proxy to an identity with profile_create: a dead or
+    slow exit found here costs nothing, the same exit found halfway through a
+    signup costs the account.
+
+    Args:
+        url: the proxy URL to test, e.g. "http://user:pass@host:port" or
+            "socks5://host:port".
+
+    Returns {ok: true, exit_ip, country, latency_ms} when the proxy works, or
+    {ok: false, error} when it does not. A dead proxy is an ANSWER, not a
+    failure — check the `ok` field rather than assuming success. Note that
+    `country` can be null even on a working proxy if the exit IP cannot be
+    geolocated.
+
+    This tests a bare URL. To test the proxy an identity is already bound to,
+    the daemon's per-identity check is a separate endpoint not yet exposed here.
+    """
+    if not isinstance(url, str) or not url.strip():
+        raise ValueError("url is required: the proxy to test, e.g. 'socks5://host:port'")
+    return daemon.request("POST", "/proxy-check", json={"url": url.strip()}).json()
+
+
+def profile_delete(name: str) -> dict:
+    """Move an identity to the recycle bin. Recoverable — this is not erasure.
+
+    The identity's browser storage, cookies and logged-in sessions go to the
+    recycle bin intact and profile_restore brings them back unchanged. It stops
+    counting against the installation's quota while it sits there, and it no
+    longer appears in profiles_list.
+
+    A running identity is refused (409) rather than killed under itself — stop
+    it with profile_stop first, then delete. Deleting a name that is already in
+    the recycle bin replaces the older copy, so the older one is lost.
+
+    There is deliberately NO tool here for permanent deletion. Emptying the
+    recycle bin destroys logged-in accounts with no way back, so it is a manual
+    action in the desktop app only — a person does it, looking at what they are
+    about to lose. Do not look for a way around this; tell the human instead.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+
+    Fails with a readable message if the identity does not exist (404), or if it
+    is still running (409).
+    """
+    clean = _identity_name(name)
+    daemon.request("DELETE", f"/profiles/{clean}")
+    return {"name": clean, "deleted": True, "recoverable": True,
+            "note": "in the recycle bin; profile_restore brings it back"}
+
+
+def trash_list() -> list[dict]:
+    """List the identities in the recycle bin — what is still recoverable.
+
+    Read-only. This is how you find out what can be restored: deleted
+    identities do not appear in profiles_list, so without this you could only
+    restore a name you already knew. Pair it with profile_restore.
+
+    Each entry carries name, engine, os, created, and deleted_at. Newest
+    deletion first. An empty list means the recycle bin is empty.
+
+    Nothing here is gone yet — everything listed still has its cookies and
+    login state and comes back intact via profile_restore.
+    """
+    return daemon.request("GET", "/trash").json()
+
+
+def profile_restore(name: str) -> dict:
+    """Bring an identity back from the recycle bin, exactly as it was.
+
+    Its frozen fingerprint, proxy binding, cookies and login state all come
+    back — restoring is not re-creating, so nothing is regenerated and no
+    logged-in account is lost.
+
+    Args:
+        name: the trashed identity's name.
+
+    Returns {name, engine, created}. Fails with a readable message if nothing by
+    that name is in the recycle bin (404), or if a live identity has taken the
+    name since (409) — rename or delete that one first, then restore.
+    """
+    clean = _identity_name(name)
+    return daemon.request("POST", f"/trash/{clean}/restore").json()
+
+
+def session_goto(name: str, url: str) -> dict:
+    """Navigate a session's current page to a URL.
+
+    Open the identity's session with profile_start first — this drives an
+    already-open session, it does not open one itself.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+        url: the URL to navigate to, e.g. "https://example.com/login".
+
+    Returns {url}: the page's URL after navigation. Fails with a readable
+    message if the session is not open (409 — call profile_start first) or
+    the identity does not exist (404).
+    """
+    clean = _identity_name(name)
+    if not isinstance(url, str) or not url.strip():
+        raise ValueError("url is required: the page to navigate to, e.g. 'https://example.com'")
+    return daemon.request(
+        "POST", f"/sessions/{clean}/goto", json={"url": url.strip()}
+    ).json()
+
+
+def session_snapshot(name: str) -> dict:
+    """Take an accessibility-tree snapshot of the session's current page.
+
+    This is the primary way to see what is on a page before acting on it —
+    read it to find the roles/names/selectors to pass to session_click_selector
+    or session_fill_selector. Requires a session opened with profile_start first.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+
+    Returns {snapshot}: the page's accessibility tree as text. Fails with a
+    readable message if the session is not open (409 — call profile_start
+    first) or the identity does not exist (404).
+    """
+    clean = _identity_name(name)
+    return daemon.request("GET", f"/sessions/{clean}/snapshot").json()
+
+
+def session_click_selector(name: str, selector: str) -> dict:
+    """Click an element on the session's current page, located by a CSS selector.
+
+    Requires a session opened with profile_start first. `selector` is a CSS
+    selector (e.g. "button#submit", "a.nav-link") — not an XPath, not a role/name
+    pair (use session_snapshot to find one).
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+        selector: CSS selector for the element to click.
+
+    Returns {ok: true}. Fails with a readable message if the session is not
+    open (409 — call profile_start first), the identity does not exist (404),
+    or the selector never matches / the click times out (502).
+    """
+    clean = _identity_name(name)
+    if not isinstance(selector, str) or not selector.strip():
+        raise ValueError("selector is required: a CSS selector, e.g. 'button#submit'")
+    return daemon.request(
+        "POST", f"/sessions/{clean}/click_selector", json={"selector": selector.strip()}
+    ).json()
+
+
+def session_fill_selector(name: str, selector: str, text: str) -> dict:
+    """Fill a text field on the session's current page, located by a CSS selector.
+
+    Uses Playwright's fill(), which drives React/Vue-controlled inputs correctly
+    (setting the DOM value directly does not). Requires a session opened with
+    profile_start first. `selector` is a CSS selector, not an XPath.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+        selector: CSS selector for the input to fill.
+        text: the text to put in the field, replacing whatever was there.
+
+    Returns {ok: true}. Fails with a readable message if the session is not
+    open (409 — call profile_start first), the identity does not exist (404),
+    or the selector never matches / the fill times out (502).
+    """
+    clean = _identity_name(name)
+    if not isinstance(selector, str) or not selector.strip():
+        raise ValueError("selector is required: a CSS selector, e.g. 'input[name=email]'")
+    return daemon.request(
+        "POST", f"/sessions/{clean}/fill_selector",
+        json={"selector": selector.strip(), "value": text},
+    ).json()
+
+
+def session_press(name: str, key: str) -> dict:
+    """Press a keyboard key on the session's current page (whatever is focused).
+
+    Requires a session opened with profile_start first. Use Playwright key
+    names, e.g. "Enter", "Tab", "Escape", "Control+A".
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+        key: the key (or chord) to press.
+
+    Returns {ok: true}. Fails with a readable message if the session is not
+    open (409 — call profile_start first) or the identity does not exist (404).
+    """
+    clean = _identity_name(name)
+    return daemon.request(
+        "POST", f"/sessions/{clean}/press", json={"key": key}
+    ).json()
+
+
+def session_eval(name: str, expr: str) -> dict:
+    """Evaluate a JavaScript expression on the session's current page.
+
+    Requires a session opened with profile_start first. A page-JS error is
+    data to read, not a tool failure: the daemon returns {"ok": false,
+    "error", "error_type"} instead of raising when the expression throws.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+        expr: the JavaScript expression to evaluate in the page, e.g.
+            "document.title" or "document.querySelectorAll('a').length".
+
+    Returns the {ok, result} envelope: {"ok": true, "result": <value>} on
+    success. `result` is whatever the expression evaluates to as JSON —
+    string, number, boolean, object, array, or null — not necessarily a
+    string; do not assume its type. Fails with a readable message (raises,
+    rather than the {ok: false} envelope above) if the session is not open
+    (409 — call profile_start first) or the identity does not exist (404).
+    """
+    clean = _identity_name(name)
+    if not isinstance(expr, str) or not expr.strip():
+        raise ValueError("expr is required: the JavaScript expression to evaluate")
+    return daemon.request(
+        "POST", f"/sessions/{clean}/eval", json={"expr": expr}
+    ).json()
+
+
+def session_tabs(name: str) -> dict:
+    """List the session's open tabs, with the currently active one marked.
+
+    Requires a session opened with profile_start first. Use this to find the
+    index to pass to session_switch_tab.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+
+    Returns {tabs, active}: `tabs` is a list of {index, url}, `active` is the
+    index of the tab currently in front. Fails with a readable message if the
+    session is not open (409 — call profile_start first) or the identity does
+    not exist (404).
+    """
+    clean = _identity_name(name)
+    return daemon.request("GET", f"/sessions/{clean}/tabs").json()
+
+
+def session_switch_tab(name: str, index: int) -> dict:
+    """Bring one of the session's open tabs to the front and make it the active one.
+
+    Requires a session opened with profile_start first. Get `index` from
+    session_tabs — indices are only valid as of that snapshot, a tab opened or
+    closed since shifts them.
+
+    Args:
+        name: identity name, exactly as profiles_list reports it.
+        index: the tab's index, from session_tabs.
+
+    Returns {index, url} for the now-active tab. Fails with a readable message
+    if the session is not open (409 — call profile_start first), the identity
+    does not exist (404), or the index is out of range (422).
+    """
+    clean = _identity_name(name)
+    return daemon.request(
+        "POST", f"/sessions/{clean}/switch_tab", json={"index": index}
+    ).json()
+
+
+TOOLS = (profiles_list, profile_start, profile_stop,
+         profile_create, profile_checkup, proxy_check,
+         profile_delete, trash_list, profile_restore,
+         session_goto, session_snapshot, session_click_selector,
+         session_fill_selector, session_press, session_eval,
+         session_tabs, session_switch_tab)

nullprint_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: nullprint-mcp
+Version: 0.1.0
+Summary: MCP server for Nullprint, the multi-profile browser: create, launch, check and drive browser profiles from any MCP-capable AI agent.
+Project-URL: Homepage, https://nullprint.ai
+Project-URL: Documentation, https://nullprint.ai/docs/mcp/
+Project-URL: Source, https://github.com/nullprintai/nullprint-mcp
+Author-email: Nullprint <support@nullprint.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,browser,fingerprint,mcp,model-context-protocol,nullprint
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.11
+Requires-Dist: httpx
+Requires-Dist: mcp<2,>=1.27
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nullprint-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [Nullprint](https://nullprint.ai), the multi-profile browser. It lets any MCP-capable AI agent (Claude Code, Claude Desktop, OpenAI Codex, Kimi, …) create browser profiles, launch them, run consistency check-ups and drive the pages inside a running profile.
+
+The server is a thin layer over the local Nullprint daemon's HTTP API: every tool maps to one daemon endpoint. The daemon, the browser kernels and the fingerprint engine ship with the Nullprint desktop app and are not part of this package.
+
+## Requirements
+
+- Nullprint desktop app installed and running (Windows or macOS), signed in. Download: https://nullprint.ai
+- Python 3.11+ on the same machine. The easiest way to run the server is [uv](https://docs.astral.sh/uv/), which installs the package on first use.
+
+## Install
+
+```bash
+# Claude Code
+claude mcp add nullprint -- uvx nullprint-mcp
+
+# OpenAI Codex
+codex mcp add nullprint -- uvx nullprint-mcp
+```
+
+Claude Desktop, Kimi and other clients that use an `mcpServers` config file:
+
+```json
+{
+  "mcpServers": {
+    "nullprint": {
+      "command": "uvx",
+      "args": ["nullprint-mcp"]
+    }
+  }
+}
+```
+
+Without uv: `pip install nullprint-mcp`, then use `nullprint-mcp` as the command (no args).
+
+No port or key to configure: the server reads the running daemon's port and API key from `~/.nullprint/daemon.json`, which the desktop app writes on start-up. To point at a daemon elsewhere, pass `--daemon-url http://host:port` (or `--port 7801` for localhost) and set `NULLPRINT_API_KEY`. Resolution order, most explicit first:
+
+1. `--daemon-url` / `--port`
+2. `NULLPRINT_DAEMON_URL`
+3. `NULLPRINT_PORT`
+4. `~/.nullprint/daemon.json` (`NULLPRINT_HOME` changes the directory)
+
+If the daemon is not running the tools say so plainly instead of throwing a connection trace.
+
+## Tools
+
+| Tool | What it does | Daemon endpoint |
+|---|---|---|
+| `profiles_list` | List every profile with status (running / idle), exit and ledger metadata | `GET /profiles` |
+| `profile_start` | Open a browser session for a profile; returns the driving endpoints | `POST /sessions/{name}` |
+| `profile_stop` | Stop that profile's browser (session or app-launched window) | `DELETE /sessions/{name}` → falls back to `POST /profiles/{name}/stop` |
+| `profile_create` | Create a profile (fingerprint generated and frozen), optionally with proxy, ledger and start pages | `POST /profiles` |
+| `profile_checkup` | Consistency check-up, returns `{summary, checks}` | `GET /profiles/{name}/checkup?live=` |
+| `proxy_check` | Stateless proxy test: exit IP, country, latency | `POST /proxy-check` |
+| `profile_delete` | Soft delete to the recycle bin (recoverable); refused while running | `DELETE /profiles/{name}` |
+| `trash_list` | Read-only list of recoverable profiles in the recycle bin | `GET /trash` |
+| `profile_restore` | Restore from the recycle bin with fingerprint, proxy and logins intact | `POST /trash/{name}/restore` |
+| `session_goto` | Navigate the session's current page | `POST /sessions/{name}/goto` |
+| `session_snapshot` | Accessibility tree of the current page (find selectors, read state) | `GET /sessions/{name}/snapshot` |
+| `session_click_selector` | Click an element by CSS selector | `POST /sessions/{name}/click_selector` |
+| `session_fill_selector` | Fill an input by CSS selector | `POST /sessions/{name}/fill_selector` |
+| `session_press` | Send a key (e.g. `Enter`) | `POST /sessions/{name}/press` |
+| `session_eval` | Run JavaScript on the page, returns `{ok, result}` | `POST /sessions/{name}/eval` |
+| `session_tabs` | List the session's tabs and the active one | `GET /sessions/{name}/tabs` |
+| `session_switch_tab` | Bring a tab to the front | `POST /sessions/{name}/switch_tab` |
+
+Notes that matter when writing prompts:
+
+- **`session_*` tools need an open session.** They drive the warm session opened by `profile_start`; calling them on a profile without one returns 409. Selectors are CSS, not XPath or role/name; call `session_snapshot` first when you do not know a selector.
+- **`session_eval` returns an envelope.** A page-side JavaScript error comes back as data (`{ok: false, error, error_type}`), not as a tool failure; `result` follows the expression's type.
+- **`profile_stop` has two levels.** A profile can be "running" as a warm session or as a window launched from the app. The tool tries the session first and falls back to the app-level stop, which is idempotent for idle profiles. It returns `{name, stopped, closed}`.
+- **`profile_create` does not hard-code a kernel.** Leave `engine` empty to use the app's default; unknown values come back as a 422 listing the options.
+- **`proxy_check` failures are data.** An unreachable proxy returns `{ok: false, error}`; only an unreachable daemon raises.
+- **`profile_start` returns `cdp_endpoint`** (a `ws://` DevTools address) for Chrome kernels, so external tools can attach. A session driven from outside bypasses Nullprint's consistency guards: an outside tool can set a viewport, language or time zone that contradicts the profile's frozen fingerprint and make it detectable. Prefer the `session_*` tools; if you must attach, do not change anything the profile has not declared.
+
+## What is deliberately not exposed
+
+Permanently deleting a profile (`DELETE /trash/{name}`) destroys its logins and cannot be undone. It is not a tool on purpose: emptying the recycle bin is a human action in the desktop app. `profile_delete`'s description tells the agent to say so instead of working around it, and a test scans every tool's source to keep the purge endpoint out. Screenshot-to-disk and file-writing tools are left out for the same reason (local path safety).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests
+nullprint-mcp --help
+```
+
+Tools live in `nullprint_mcp/tools.py` (the `TOOLS` tuple); `server.py` and `__main__.py` do not change when a tool is added. Nothing may be printed to stdout: stdout is the MCP channel.
+
+## License
+
+MIT. Copyright (c) 2026 HENGCHENG LLC.
+
+---
+
+## 中文说明
+
+这是 [Nullprint](https://nullprint.ai)（多身份指纹浏览器）的 MCP 服务：Claude Code、Claude Desktop、OpenAI Codex、Kimi 等任何支持 MCP 的 AI 都可以用它建身份、启动浏览器、做一致性体检、驱动身份里的网页。它只是本地 daemon HTTP 接口上的薄薄一层，每个工具对应 daemon 的一个端点；daemon、浏览器内核和指纹引擎随 Nullprint 桌面应用发布，不在本包内。
+
+**前提**：本机装好并登录 Nullprint 桌面应用；本机有 Python 3.11+，推荐用 [uv](https://docs.astral.sh/uv/)（首次运行自动装包）。
+
+**接入**：
+
+```bash
+claude mcp add nullprint -- uvx nullprint-mcp      # Claude Code
+codex mcp add nullprint -- uvx nullprint-mcp       # OpenAI Codex
+```
+
+Claude Desktop、Kimi 等走配置文件的客户端，在 `mcpServers` 里加 `{"command": "uvx", "args": ["nullprint-mcp"]}`。没有 uv 就 `pip install nullprint-mcp`，命令改为 `nullprint-mcp`。
+
+不用配端口和密钥：服务自动读桌面应用写在 `~/.nullprint/daemon.json` 里的端口和 API Key。要连别的机器上的 daemon，传 `--daemon-url` 并设 `NULLPRINT_API_KEY`。
+
+**17 个工具**：`profiles_list`、`profile_start`、`profile_stop`、`profile_create`、`profile_checkup`、`proxy_check`、`profile_delete`、`trash_list`、`profile_restore`，以及 8 个会话工具 `session_goto / snapshot / click_selector / fill_selector / press / eval / tabs / switch_tab`（先 `profile_start` 再用）。彻底删除身份故意不做成工具：清空回收站只能在桌面应用里由人操作。

nullprint_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+nullprint_mcp/__init__.py,sha256=Fvhusg9kWpfG_A1FylE9q27R_yr1lT4fNdTNede2jdE,462
+nullprint_mcp/__main__.py,sha256=6QxRVy0ioVQf8E6SFeB5EG4DkWUefnWwKAb40U0CtN0,1345
+nullprint_mcp/daemon.py,sha256=XWVshPQ-aoeRj9FQpzbQHFrxEDLEliFPjUx-XLUKjxg,6437
+nullprint_mcp/server.py,sha256=dtADSG_qMSlDt-hIghkMQ9MEqTsrz9h9AZS7uJfvUbQ,1101
+nullprint_mcp/tools.py,sha256=maYvONouzIMXQqkaJd_AKMjc9zqEYkH49lIJ_bG-qI0,20491
+nullprint_mcp-0.1.0.dist-info/METADATA,sha256=dExg9VQBta-qaayZruncREodFCLXS_e0bBjXSVQ9bcA,8538
+nullprint_mcp-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+nullprint_mcp-0.1.0.dist-info/entry_points.txt,sha256=sZ3_9w3e0Xr5A_hGIJvknIeTFBR0nAqH_kQlMQNczNI,62
+nullprint_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=QOckAHb4qakTd_YPlFQxVOfEbBOBam8U7b6yHU2Smc0,1070
+nullprint_mcp-0.1.0.dist-info/RECORD,,

nullprint_mcp-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

nullprint_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nullprint-mcp = nullprint_mcp.__main__:main

nullprint_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HENGCHENG LLC
+
+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.