bookmark-research 0.5.0-beta.1

package/src/readiness.py

@@ -0,0 +1,283 @@
+"""Bounded capability checks, honest auth status, and private expiring cache."""
+
+import concurrent.futures
+import copy
+import hashlib
+import hmac
+import json
+import os
+from pathlib import Path
+import tempfile
+import time
+
+from credentials import Credentials
+from remote_mcp import McpError, McpHttpClient
+from service_http import ResearchHttp, ServiceError
+from settings import Settings
+from web_search import SearchProviders
+
+
+class Readiness:
+    VERSION = 1
+
+    def __init__(self, settings=None, web=None, transport=None, cache_path=None):
+        self.settings = settings if settings is not None else Settings()
+        self.credentials = Credentials(self.settings)
+        timeout = self.settings.load()["readiness"]["timeout_seconds"]
+        self.web = web if web is not None else SearchProviders(settings=self.settings, timeout=timeout)
+        self.transport = transport if transport is not None else ResearchHttp(timeout, self.credentials)
+        identity = hashlib.sha256(str(self.settings.path).encode()).hexdigest()[:16]
+        self.cache_path = Path(cache_path or Settings.data_directory() / "readiness" / (identity + ".json"))
+
+    def _cache(self):
+        if self.cache_path.is_symlink():
+            raise ValueError("Readiness cache must not be a symlink")
+        try:
+            if self.cache_path.stat().st_size > 256000:
+                raise ValueError("Readiness cache exceeds size limit")
+            cache = json.loads(self.cache_path.read_text(encoding="utf-8"))
+            if (isinstance(cache, dict) and cache.get("version") == self.VERSION
+                    and isinstance(cache.get("salt"), str) and isinstance(cache.get("checks"), dict)):
+                return cache
+        except (FileNotFoundError, ValueError, UnicodeError):
+            pass
+        return {"version": self.VERSION, "salt": os.urandom(32).hex(), "checks": {}}
+
+    def _save(self, cache):
+        if self.cache_path.is_symlink():
+            raise ValueError("Readiness cache must not be a symlink")
+        path = Settings.external_path(str(self.cache_path), "Readiness cache")
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        temporary = None
+        try:
+            with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", newline="", dir=path.parent,
+                                             prefix=".readiness-", delete=False) as stream:
+                temporary = Path(stream.name)
+                json.dump(cache, stream, ensure_ascii=False)
+                stream.flush()
+                os.fsync(stream.fileno())
+            temporary.replace(path)
+        finally:
+            if temporary is not None:
+                temporary.unlink(missing_ok=True)
+
+    def _signature(self, row, salt):
+        # Only a salted signature is persisted; no keys, headers, or signatures
+        # are included in CLI/MCP results. Rotation invalidates cached checks.
+        content = {"row": row, "settings": self.settings.load(),
+                   "credential": self.credentials.get(row["credential_env"]),
+                   "registry": self.web.registry, "version": self.VERSION}
+        return hmac.new(salt.encode(), json.dumps(content, sort_keys=True).encode(), hashlib.sha256).hexdigest()
+
+    @staticmethod
+    def _error(error):
+        if isinstance(error, (ServiceError, McpError)):
+            detail = error.details()
+            # Only typed error metadata is needed for remediation. Never retain
+            # response bodies or arbitrary exception text in the cache.
+            return {key: detail[key] for key in ("error_kind", "http_status", "retry_after_seconds") if key in detail}
+        return {"error_kind": "check_failed"}
+
+    def _retrieval_rows(self, providers):
+        preferences = self.settings.load()
+        names = providers if providers is not None else list(dict.fromkeys(
+            preferences["search"]["providers"] + preferences["search"]["fallback_providers"] +
+            Settings.fetch_providers(preferences)))
+        described = self.web.describe(names)["providers"]
+        return [{"id": "retrieval:" + row["provider"], "kind": "retrieval", "provider": row["provider"],
+                 "credential_env": row["provider"].upper() + "_API_KEY",
+                 "credential_configured": row["authentication_state"]["credential_configured"],
+                 "authentication_mode": row["authentication_state"]["mode"],
+                 "authentication_verified": False, "execution_verified": False,
+                 "status": "unchecked", "docs": row["docs"], "operations": row["operations"],
+                 "installation": "included_adapter", "network_checked": False,
+                 "next_step": "Run readiness --refresh for connection checks; --test-retrieval also uses retrieval quota."}
+                for row in described]
+
+    def _service_rows(self, service):
+        config = self.settings.load()["professional_research"]
+        rows = []
+        for name in ([service] if service else ["openai", "parallel"]):
+            key = ResearchHttp.PROVIDERS[name]["key_env"]
+            enabled = config["enabled"] and (config["provider"] in (None, name) or service == name)
+            configured = bool(self.credentials.get(key))
+            rows.append({"id": "service:" + name, "kind": "professional_research", "provider": name,
+                         "credential_env": key, "credential_configured": configured,
+                         "authentication_verified": False, "execution_verified": False,
+                         "network_checked": False, "enabled": enabled,
+                         "status": "unchecked" if configured and enabled else "disabled" if not enabled else "missing_credentials",
+                         "next_step": "Run setup to enable this optional service and configure " + key + ".",
+                         "docs": "https://developers.openai.com/api/docs/guides/deep-research" if name == "openai"
+                         else "https://docs.parallel.ai/task-api/guides/execute-task-run"})
+        return rows
+
+    def _probe_retrieval(self, row, test_retrieval):
+        name = row["provider"]
+        if test_retrieval:
+            operations = copy.deepcopy(row["operations"])
+            for purpose in ("search", "fetch"):
+                if operations[purpose]["missing"]:
+                    operations[purpose]["status"] = "missing_credentials"
+                    continue
+                if purpose == "search":
+                    result = self.web.search([{"target": "readiness", "query": "example.com Example Domain"}],
+                                             providers=[name], limit_per_target=1)["batches"][0]
+                    verified = result["status"] == "ok" and bool(result.get("results"))
+                else:
+                    result = self.web.fetch(["https://example.com/"], provider=name, archive=False, max_characters=1000)
+                    verified = result["status"] == "ok" and result.get("successful_url_count", 0) > 0
+                operations[purpose].update(status="verified" if verified else "failed",
+                                           error_kind=result.get("error_kind"))
+            verified = any(operation.get("status") == "verified" for operation in operations.values())
+            return {"status": "retrieval_verified" if verified else "failed", "operations": operations,
+                    "network_checked": True, "execution_verified": verified,
+                    "authentication_verified": verified and row["credential_configured"],
+                    "verification_scope": "Only the successful search/fetch operations in this check.",
+                    "next_step": "Use verified operations; configure missing credentials or address failed operations before relying on them."}
+        probe = self.web.probe([name])["providers"][0]
+        if probe["status"] == "ok":
+            return {"status": "catalog_reachable", "network_checked": True,
+                    "capabilities": probe["capabilities"],
+                    "next_step": "Search/fetch can be attempted. Catalog discovery does not verify retrieval authorization or quota."}
+        if probe["status"] == "not_probed":
+            return {"status": "http_unchecked", "network_checked": False,
+                    "next_step": "Reader can be attempted anonymously; Search needs JINA_API_KEY. Use --test-retrieval for an actual check."}
+        return {"status": "failed", "network_checked": True,
+                "error_kind": probe.get("error_kind", "check_failed"),
+                "next_step": "Check credentials and connectivity, then refresh; another configured provider may remain available."}
+
+    def _probe_service(self, row):
+        name = row["provider"]
+        if name == "openai":
+            model = self.settings.load()["professional_research"]["openai"]["model"]
+            result = self.transport.request("openai", "GET", "/v1/models/" + model)
+            if result.get("id") != model or result.get("object") != "model":
+                raise ValueError("Unexpected model metadata")
+            return {"status": "model_access_verified", "authentication_verified": True,
+                    "network_checked": True, "verification_scope": "GET /v1/models/" + model,
+                    "next_step": "Model metadata is accessible. Research execution and billing quota remain untested; prepare the intended run before starting."}
+        endpoint = self.web.registry["providers"]["parallel"]["native_research"]["url"]
+        client = McpHttpClient(endpoint, headers={"Authorization": "Bearer " + self.credentials.get("PARALLEL_API_KEY")},
+                               timeout=self.settings.load()["readiness"]["timeout_seconds"])
+        tools = client.list_tools()
+        required = self.web.registry["providers"]["parallel"]["native_research"]["required_tools"]
+        if not isinstance(tools, list) or not set(required) <= {tool.get("name") for tool in tools if isinstance(tool, dict)}:
+            raise ValueError("Task MCP catalog is incomplete")
+        return {"status": "task_mcp_access_verified", "network_checked": True,
+                "task_mcp_authentication_verified": True, "authentication_verified": False,
+                "verification_scope": "Authenticated Task MCP initialize/tools/list; Task API execution was not tested.",
+                "next_step": "Task MCP accepted this API key. Task API permission and billing quota still need verification on the intended run."}
+
+    def _probe(self, row, test_retrieval):
+        try:
+            update = self._probe_retrieval(row, test_retrieval) if row["kind"] == "retrieval" else self._probe_service(row)
+            return {**row, **update}
+        except (RuntimeError, ValueError, OSError) as error:
+            return {**row, "status": "failed", "network_checked": True, **self._error(error),
+                    "next_step": "Check the selected provider's credential, permissions and connectivity; refresh after fixing it."}
+
+    def _host_integrations(self, host, observed_tools):
+        from routing import ResearchRouting
+        if host not in ResearchRouting.HOSTS:
+            raise ValueError("Unsupported host")
+        tools = ResearchRouting._names(observed_tools, "observed_tools")
+        rows = []
+        for name, info in self.web.registry["providers"].items():
+            native = info.get("native_research")
+            if not native:
+                continue
+            required = native.get("required_tools", [])
+            present = (all(ResearchRouting._has(tools, tool) for tool in required) if required else
+                       any(ResearchRouting._has(tools, tool) for tool in native["tools"]))
+            alias = "bookmark-" + name + "-research"
+            if host == "codex":
+                setup = {"inspect_command": ["codex", "mcp", "list", "--json"],
+                         "add_command": ["codex", "mcp", "add", alias, "--url", native["url"]],
+                         "login_command": ["codex", "mcp", "login", alias],
+                         "login_instruction": "Use the host's OAuth flow if this endpoint supports it, then inspect /mcp in a new session.",
+                         "reference": "https://developers.openai.com/codex/mcp"}
+            elif host == "claude_code":
+                setup = {"inspect_command": ["claude", "mcp", "list"],
+                         "add_command": ["claude", "mcp", "add", "--scope", "user", "--transport", "http", alias, native["url"]],
+                         "login_instruction": "Open /mcp in Claude Code and authenticate this server if OAuth is supported. Choose the intended scope when adding it.",
+                         "reference": "https://code.claude.com/docs/en/mcp"}
+            elif host == "dsh":
+                setup = {"mcp_config": {"serverName": alias, "transport": "streamable-http", "url": native["url"]},
+                         "credential_env": name.upper() + "_API_KEY",
+                         "credential_header": "x-api-key" if name == "exa" else "Authorization: Bearer",
+                         "login_instruction": "Add this optional server to the selected DSH profile with an environment-backed authentication header. The documented DSH bridge supports headers; OAuth support is not established.",
+                         "reference": "https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md"}
+            else:
+                setup = {"login_instruction": "Pi uses the bundled CLI for ordinary research. Native research MCPs need a separately chosen MCP extension and its authentication flow. The plugin does not assume one is installed."
+                         if host == "pi" else "Select --host when running setup, or inspect the MCP settings in your actual host.",
+                         "reference": "skills/bookmark-research/references/host-workflows.md"}
+            rows.append({"provider": name, "optional": True, "endpoint": native["url"],
+                         "status": "needs_host_session" if observed_tools is None else "observed" if present else "not_observed",
+                         "authentication_verified": False, "docs": native.get("docs", info["docs"]),
+                         "setup": setup,
+                         "next_step": "Inspect the current host's MCP tools; add this optional endpoint and complete its host-managed login if needed. Tool presence alone does not verify authorization."})
+        collaboration_tools = {"codex": ("spawn_agent",), "claude_code": ("Agent", "Task", "Workflow"),
+                               "pi": ("subagent", "pi_subagent_workflow"), "dsh": ("subagent", "workflow"), "unknown": ()}
+        collaboration = {"optional": True,
+            "status": "needs_host_session" if observed_tools is None or host == "unknown" else
+                      "observed" if ResearchRouting._has(tools, *collaboration_tools[host]) else "not_observed",
+            "next_step": "Use the host's own search/read loop when collaboration is unavailable. Enable the host's supported subagent/workflow capability only when needed.",
+            "reference": "skills/bookmark-research/references/host-workflows.md"}
+        return {"host": host, "session_observed": observed_tools is not None,
+                "collaboration": collaboration, "native_research_mcps": rows}
+
+    def check(self, providers=None, service=None, refresh=False, offline=False, test_retrieval=False,
+              host="unknown", observed_tools=None):
+        if service not in (None, "openai", "parallel"):
+            raise ValueError("Select openai or parallel")
+        if any(type(value) is not bool for value in (refresh, offline, test_retrieval)):
+            raise ValueError("Readiness flags must be boolean")
+        if offline and (refresh or test_retrieval):
+            raise ValueError("Offline checks cannot refresh or test retrieval")
+        integrations = self._host_integrations(host, observed_tools)
+        policy = self.settings.load()["readiness"]
+        rows = self._retrieval_rows(providers) + self._service_rows(service)
+        cache_error = None
+        try:
+            cache = self._cache()
+        except (OSError, ValueError):
+            cache = {"version": self.VERSION, "salt": os.urandom(32).hex(), "checks": {}}
+            cache_error = "Readiness cache could not be read; current checks remain usable."
+        now, pending, output = time.time(), [], []
+        for row in rows:
+            if row["status"] in ("disabled", "missing_credentials"):
+                output.append(row)
+                continue
+            signature = self._signature(row, cache["salt"])
+            previous = cache["checks"].get(row["id"], {})
+            fresh = (isinstance(previous, dict) and previous.get("signature") == signature
+                     and type(previous.get("expires_at")) in (int, float) and previous["expires_at"] > now
+                     and isinstance(previous.get("result"), dict))
+            if fresh and not refresh and not test_retrieval and (offline or policy["mode"] != "always"):
+                output.append({**previous["result"], "cached": True, "network_checked_this_call": False})
+            elif offline or (policy["mode"] == "manual" and not refresh and not test_retrieval):
+                output.append({**row, "cached": False, "network_checked_this_call": False,
+                               "next_step": "Run readiness --refresh when a network check is wanted."})
+            else:
+                pending.append((row, signature))
+        if pending:
+            with concurrent.futures.ThreadPoolExecutor(max_workers=len(pending)) as pool:
+                results = list(pool.map(lambda work: self._probe(work[0], test_retrieval), pending))
+            for (row, signature), result in zip(pending, results):
+                ttl = min(policy["ttl_seconds"], 60) if result["status"] == "failed" else policy["ttl_seconds"]
+                result.update(checked_at=now, expires_at=now + ttl, cached=False,
+                              network_checked_this_call=result["network_checked"])
+                cache["checks"][row["id"]] = {"signature": signature, "expires_at": now + ttl, "result": result}
+                output.append(result)
+            if not cache_error:
+                try:
+                    self._save(cache)
+                except (OSError, ValueError):
+                    cache_error = "Readiness checks completed but their cache could not be saved."
+        order = {row["id"]: index for index, row in enumerate(rows)}
+        output.sort(key=lambda row: order[row["id"]])
+        return {"policy": policy, "research_preferences": self.settings.load()["research"],
+                "checks": output, "host_integrations": integrations,
+                "offline_ready": True, "network_checked": any(row.get("network_checked_this_call") for row in output),
+                "research_jobs_started": 0, "cache_error": cache_error,
+                "note": "Optional service failures do not block local queries or other providers. Cached status is evidence from its timestamp, not a guarantee. Host OAuth stays in the host; no login tokens are imported. MCP setup commands are guidance: inspect existing registrations and reuse their names before adding a server."}

package/src/remote_mcp.py

@@ -0,0 +1,295 @@
+"""Small Streamable HTTP client for the selected public search MCPs.
+
+This client declares no sampling/roots capabilities and does not implement OAuth.
+Hosts remain responsible for interactive OAuth and general-purpose MCP sessions.
+"""
+
+import json
+import math
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from urllib.parse import urlsplit
+
+
+class McpError(RuntimeError):
+    """A safe, classified failure; upstream bodies and credentials are omitted."""
+
+    def __init__(self, message, kind="protocol_error", retryable=False,
+                 http_status=None, rpc_code=None, retry_after=None):
+        super().__init__(message)
+        self.kind, self.retryable = kind, retryable
+        self.http_status, self.rpc_code = http_status, rpc_code
+        self.retry_after = retry_after
+
+    def details(self):
+        result = {"error": str(self), "error_kind": self.kind, "retryable": self.retryable}
+        for key, value in (("http_status", self.http_status), ("rpc_code", self.rpc_code),
+                           ("retry_after_seconds", self.retry_after)):
+            if value is not None:
+                result[key] = value
+        return result
+
+
+class McpHttpClient:
+    """A bounded initialize/list/call client accepting JSON or SSE responses."""
+
+    MAX_BYTES = 2_000_000
+    MAX_TOOL_PAGES = 8
+    MAX_TOOLS = 256
+    PROTOCOLS = {"2025-03-26", "2025-06-18", "2025-11-25"}
+
+    def __init__(self, url, headers=None, timeout=30):
+        if not isinstance(url, str) or any(c.isspace() or ord(c) < 32 for c in url):
+            raise ValueError("MCP endpoint must use HTTPS")
+        parsed = urlsplit(url)
+        if parsed.scheme != "https" or not parsed.hostname or parsed.username is not None or parsed.password is not None:
+            raise ValueError("MCP endpoint must use HTTPS without embedded credentials")
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 1 <= timeout <= 60:
+            raise ValueError("timeout must be between 1 and 60 seconds")
+        self.url = url
+        self.headers = dict(headers or {})
+        self.timeout = timeout
+        self.session_id = None
+        self.protocol = "2025-03-26"
+        self.counter = 0
+        self.initialized = False
+        self.catalog_version = 0
+        self._lock = threading.RLock()
+        self._usage = {"http_requests": 0, "initialize_requests": 0,
+                       "list_requests": 0, "tool_calls": 0, "session_recoveries": 0}
+
+    def snapshot_usage(self):
+        with self._lock:
+            return dict(self._usage)
+
+    def reset_session(self):
+        with self._lock:
+            self.initialized, self.session_id = False, None
+            self.catalog_version += 1
+
+    @staticmethod
+    def _retry_after(value):
+        if not isinstance(value, str) or len(value) > 100:
+            return None
+        try:
+            seconds = float(value)
+        except ValueError:
+            try:
+                stamp = parsedate_to_datetime(value)
+                if stamp.tzinfo is None:
+                    stamp = stamp.replace(tzinfo=timezone.utc)
+                seconds = (stamp - datetime.now(timezone.utc)).total_seconds()
+            except (ValueError, TypeError, OverflowError):
+                return None
+        return min(86400, max(0, math.ceil(seconds))) if math.isfinite(seconds) else None
+
+    def _http_error(self, status, retry_after=None):
+        kind, retryable = "http_error", False
+        if status in (401, 403):
+            kind = "authentication_required"
+        elif status == 402:
+            kind = "quota_exhausted"
+        elif status == 404 and self.initialized and self.session_id:
+            kind, retryable = "session_expired", True
+            self.reset_session()
+        elif status == 429:
+            kind, retryable = "rate_limited", True
+        elif status in (408, 500, 502, 503, 504):
+            kind, retryable = "transient_http", True
+        return McpError("MCP HTTP %s" % status, kind, retryable,
+                        http_status=status, retry_after=retry_after)
+
+    def _message(self, body):
+        headers = {"Content-Type": "application/json",
+                   "Accept": "application/json, text/event-stream",
+                   "User-Agent": "bookmark-research/0.5.0-beta.1"}
+        if self.initialized:
+            headers["MCP-Protocol-Version"] = self.protocol
+        request = urllib.request.Request(
+            self.url, json.dumps(body, ensure_ascii=False, allow_nan=False).encode("utf-8"),
+            headers=headers, method="POST")
+        # urllib follows redirects; credentials must stay on the configured endpoint.
+        for header, value in self.headers.items():
+            request.add_unredirected_header(header, value)
+        if self.session_id:
+            request.add_unredirected_header("Mcp-Session-Id", self.session_id)
+        self._usage["http_requests"] += 1
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                session = response.headers.get("Mcp-Session-Id")
+                if session:
+                    if len(session) > 4096 or any(not 0x21 <= ord(c) <= 0x7E for c in session):
+                        raise McpError("MCP server returned an invalid session identifier")
+                    self.session_id = session
+                if "id" not in body or "method" not in body:
+                    if response.status not in (200, 202, 204):
+                        raise McpError("MCP notification or response was not accepted")
+                    return None
+                if "text/event-stream" in response.headers.get("Content-Type", ""):
+                    return self._read_sse(response, body["id"])
+                data = response.read(self.MAX_BYTES + 1)
+                if len(data) > self.MAX_BYTES:
+                    raise McpError("MCP response exceeds size limit", "response_too_large")
+                return self._result(json.loads(data), body["id"])
+        except urllib.error.HTTPError as error:
+            # Never echo response bodies/URLs: a service may reflect credentials.
+            failure = self._http_error(error.code, self._retry_after((error.headers or {}).get("Retry-After")))
+            if error.fp is not None:
+                error.close()
+            raise failure from None
+        except urllib.error.URLError as error:
+            kind = "timeout" if isinstance(error.reason, (TimeoutError, socket.timeout)) else "connection_error"
+            raise McpError("MCP connection failed (%s)" % type(error.reason).__name__, kind, True) from None
+        except (TimeoutError, OSError) as error:
+            kind = "timeout" if isinstance(error, (TimeoutError, socket.timeout)) else "connection_error"
+            raise McpError("MCP transport failed (%s)" % type(error).__name__, kind, True) from None
+        except (ValueError, UnicodeError, RecursionError):
+            raise McpError("MCP returned invalid JSON or text") from None
+
+    @staticmethod
+    def _result(message, request_id):
+        messages = message if isinstance(message, list) else [message]
+        for item in messages:
+            if not isinstance(item, dict):
+                continue
+            if isinstance(item.get("id"), bool) or item.get("id") != request_id:
+                continue
+            if item.get("jsonrpc") != "2.0" or ("result" in item and "error" in item):
+                raise McpError("MCP returned an invalid JSON-RPC response")
+            if "error" in item:
+                code = item["error"].get("code") if isinstance(item["error"], dict) else None
+                if type(code) is not int:
+                    raise McpError("MCP returned an invalid JSON-RPC error")
+                kind = {-32602: "schema_mismatch", -32601: "tool_unavailable"}.get(code, "rpc_error")
+                raise McpError("MCP RPC error (%s)" % code, kind, rpc_code=code)
+            if "result" in item:
+                return item["result"]
+        raise McpError("MCP response did not match request ID")
+
+    def _read_sse(self, response, request_id):
+        deadline = time.monotonic() + self.timeout
+        event = []
+        consumed = 0
+        while time.monotonic() < deadline:
+            line = response.readline(self.MAX_BYTES + 1)
+            consumed += len(line)
+            if consumed > self.MAX_BYTES:
+                raise McpError("MCP response exceeds size limit", "response_too_large")
+            if not line and not event:
+                break
+            text = line.decode("utf-8").rstrip("\r\n")
+            if text.startswith("data:"):
+                event.append(text[5:].lstrip(" "))
+            if (not text or not line) and event:
+                data = "\n".join(event)
+                event = []
+                # 2025-11-25 servers may prime a resumable stream with empty data.
+                if not data:
+                    continue
+                message = json.loads(data)
+                messages = message if isinstance(message, list) else [message]
+                for incoming in messages:
+                    if (isinstance(incoming, dict) and incoming.get("jsonrpc") == "2.0"
+                            and incoming.get("method") == "notifications/tools/list_changed"
+                            and "id" not in incoming):
+                        self.catalog_version += 1
+                    if not isinstance(incoming, dict) or "method" not in incoming or "id" not in incoming:
+                        continue
+                    if (incoming.get("jsonrpc") != "2.0" or
+                            type(incoming["id"]) not in (int, str)):
+                        raise McpError("MCP returned an invalid JSON-RPC request")
+                    # Ping does not depend on sampling, roots or other capabilities.
+                    if incoming["method"] != "ping":
+                        raise McpError("MCP server requested an unsupported client capability", "unsupported_capability")
+                    self._message({"jsonrpc": "2.0", "id": incoming["id"], "result": {}})
+                if any(isinstance(m, dict) and m.get("id") == request_id
+                       and ("result" in m or "error" in m) for m in messages):
+                    return self._result(message, request_id)
+            if not line:
+                break
+        raise McpError("MCP SSE ended or timed out without a matching response", "incomplete_response", True)
+
+    def request(self, method, params=None):
+        with self._lock:
+            self.counter += 1
+            metric = {"initialize": "initialize_requests", "tools/list": "list_requests",
+                      "tools/call": "tool_calls"}.get(method)
+            if metric:
+                self._usage[metric] += 1
+            body = {"jsonrpc": "2.0", "id": self.counter, "method": method}
+            if params is not None:
+                body["params"] = params
+            return self._message(body)
+
+    def initialize(self):
+        with self._lock:
+            self.reset_session()
+            try:
+                result = self.request("initialize", {
+                    "protocolVersion": self.protocol, "capabilities": {},
+                    "clientInfo": {"name": "bookmark-research", "version": "0.5.0-beta.1"}})
+                if (not isinstance(result, dict) or not isinstance(result.get("protocolVersion"), str)
+                        or result["protocolVersion"] not in self.PROTOCOLS):
+                    raise McpError("MCP server selected an unsupported protocol version")
+                self.protocol = result["protocolVersion"]
+                self.initialized = True
+                self._message({"jsonrpc": "2.0", "method": "notifications/initialized"})
+            except Exception:
+                self.reset_session()
+                raise
+            return result
+
+    def list_tools(self):
+        with self._lock:
+            # An expired session definitively rejects metadata requests. Recover
+            # once, discarding earlier pages; never splice two catalogs together.
+            for recovery in range(2):
+                try:
+                    return self._tool_pages()
+                except McpError as error:
+                    if error.kind != "session_expired" or recovery:
+                        raise
+                    self._usage["session_recoveries"] += 1
+
+    def _tool_pages(self):
+        if not self.initialized:
+            self.initialize()
+        tools, names, cursors, cursor, size = [], set(), set(), None, 0
+        for _ in range(self.MAX_TOOL_PAGES):
+            result = self.request("tools/list", {"cursor": cursor} if cursor else {})
+            if not isinstance(result, dict) or not isinstance(result.get("tools"), list):
+                raise McpError("MCP tools/list returned an invalid tool list")
+            size += len(json.dumps(result, ensure_ascii=False).encode("utf-8"))
+            if size > self.MAX_BYTES or len(tools) + len(result["tools"]) > self.MAX_TOOLS:
+                raise McpError("MCP tool catalog exceeds size limit", "response_too_large")
+            for tool in result["tools"]:
+                if (not isinstance(tool, dict) or not isinstance(tool.get("name"), str)
+                        or not tool["name"] or len(tool["name"]) > 256 or tool["name"] in names):
+                    raise McpError("MCP tools/list returned invalid or duplicate tool names")
+                names.add(tool["name"])
+                tools.append(tool)
+            cursor = result.get("nextCursor")
+            if cursor is None or cursor == "":
+                return tools
+            if not isinstance(cursor, str) or len(cursor) > 4096 or cursor in cursors:
+                raise McpError("MCP tools/list returned an invalid or repeated pagination cursor")
+            cursors.add(cursor)
+        raise McpError("MCP tool catalog exceeds pagination limit", "response_too_large")
+
+    def call_tool(self, name, arguments):
+        with self._lock:
+            if not self.initialized:
+                self.initialize()
+            # One semantic attempt, including 404/429/timeouts. A response loss
+            # does not prove a billable tool was not executed.
+            result = self.request("tools/call", {"name": name, "arguments": arguments})
+            if not isinstance(result, dict):
+                raise McpError("MCP tool returned an invalid result")
+            if result.get("isError"):
+                raise McpError("MCP tool returned an error", "tool_error")
+            return result