nullprint-mcp 0.1.0__tar.gz

nullprint_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+uv.lock

nullprint_mcp-0.1.0/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.

nullprint_mcp-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,114 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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