bing-webmaster-ai-cli-mcp 0.1.2__py3-none-any.whl

bing_webmaster_ai_cli_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server and CLI over the Bing Webmaster Tools API."""
+
+__version__ = "0.1.2"

bing_webmaster_ai_cli_mcp/_serialize.py

@@ -0,0 +1,64 @@
+"""Serialization for Bing's JSON endpoint and its ASP.NET date representation."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta, timezone
+from typing import Any
+
+from .errors import MalformedResponse
+
+_TICKS = re.compile(r"^\\?/Date\((?P<ms>-?\d+)(?:(?P<sign>[+-])(?P<hh>\d{2})(?P<mm>\d{2}))?\)\\?/$")
+
+
+def unwrap(payload: Any) -> Any:
+    if not isinstance(payload, dict) or "d" not in payload:
+        raise MalformedResponse(
+            "response body has no 'd' envelope",
+            suggestion="inspect the status and upstream response contract",
+            details={"keys": sorted(payload) if isinstance(payload, dict) else None},
+        )
+    return payload["d"]
+
+
+def parse_bing_datetime(value: str) -> datetime:
+    match = _TICKS.fullmatch(value)
+    if match is None:
+        raise MalformedResponse(
+            f"not an ASP.NET tick date: {value!r}",
+            suggestion="Bing JSON dates must use /Date(milliseconds±hhmm)/",
+        )
+    try:
+        moment = datetime.fromtimestamp(int(match["ms"]) / 1000, tz=UTC)
+        if match["sign"] is None:
+            return moment
+        if int(match["mm"]) >= 60:
+            raise ValueError("timezone minutes must be below 60")
+        offset = timedelta(hours=int(match["hh"]), minutes=int(match["mm"]))
+        if match["sign"] == "-":
+            offset = -offset
+        return moment.astimezone(timezone(offset))
+    except (OSError, OverflowError, ValueError) as exc:
+        # A tick count or an offset outside what datetime can represent.
+        raise MalformedResponse(f"tick date is out of range: {value!r}") from exc
+
+
+def encode_bing_datetime(value: datetime) -> str:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError("Bing datetimes must be timezone-aware")
+    milliseconds = int(value.timestamp() * 1000)
+    offset = value.utcoffset() or timedelta(0)
+    sign = "+" if offset >= timedelta(0) else "-"
+    total_minutes = abs(int(offset.total_seconds() // 60))
+    hours, minutes = divmod(total_minutes, 60)
+    return f"/Date({milliseconds}{sign}{hours:02d}{minutes:02d})/"
+
+
+def decode(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {key: decode(item) for key, item in value.items() if key != "__type"}
+    if isinstance(value, list):
+        return [decode(item) for item in value]
+    if isinstance(value, str) and _TICKS.fullmatch(value):
+        return parse_bing_datetime(value)
+    return value

bing_webmaster_ai_cli_mcp/apply.py

@@ -0,0 +1,197 @@
+"""The only module that executes a mutating Bing API request."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .audit import AuditLog
+from .client import BingClient
+from .config import Settings
+from .errors import BingWebmasterError, PlanUnknownOutcome
+from .limits import RateLimiter
+from .ops import indexnow
+from .plans import PlanStore, create_write_plan
+from .render import redact, secret_values
+from .writes import prepare_write
+
+
+async def apply_plan(
+    plan_id: str,
+    *,
+    settings: Settings,
+    store: PlanStore,
+    client: BingClient | None,
+    audit: AuditLog,
+    limiter: RateLimiter,
+    indexnow_transport: httpx.AsyncBaseTransport | None = None,
+) -> dict[str, Any]:
+    with store.applying(plan_id) as lease:
+        plan = lease.plan
+        prepared = prepare_write(plan.operation, plan.args)
+        if prepared.method != "IndexNow" and client is None:
+            raise RuntimeError("a Bing client is required to apply this plan")
+        # Re-checked here, not just at plan creation: the denylist may have grown since,
+        # and a plan can sit pending for a whole BING_WM_PLAN_TTL_SECONDS.
+        try:
+            settings.check_site_allowed(plan.site_url)
+        except BingWebmasterError as exc:
+            audit.record("plan_apply_denied", plan_id=plan_id, error=exc.to_dict())
+            raise
+
+        # Reserved before the request, not counted after it: a ceiling that refuses once
+        # the write has already been sent would leave the plan pending and invite a retry.
+        reserved_day = limiter.consume(plan.site_url, prepared.cost)
+        try:
+            if prepared.method == "IndexNow":
+                # Fetching the key file sends no submission, so a failure or an interrupt
+                # here is an ordinary failure and stays outside the unknown-outcome zone.
+                async with httpx.AsyncClient(
+                    transport=indexnow_transport, timeout=30.0
+                ) as preflight:
+                    await indexnow.verify_key_file(
+                        preflight,
+                        prepared.body["host"],
+                        prepared.body["key"],
+                        prepared.body["keyLocation"],
+                    )
+            audit.record(
+                "plan_apply_attempted",
+                plan_id=plan_id,
+                operation=plan.operation,
+                site=plan.site_url,
+            )
+        except BingWebmasterError as exc:
+            limiter.release(plan.site_url, prepared.cost, day=reserved_day)
+            audit.record("plan_apply_failed", plan_id=plan_id, error=exc.to_dict())
+            raise
+        except BaseException:
+            limiter.release(plan.site_url, prepared.cost, day=reserved_day)
+            raise
+
+        try:
+            if prepared.method == "IndexNow":
+                async with httpx.AsyncClient(
+                    transport=indexnow_transport, timeout=30.0
+                ) as indexnow_http:
+                    result = await indexnow.submit(
+                        indexnow_http,
+                        prepared.body["host"],
+                        prepared.body["key"],
+                        prepared.body["urlList"],
+                        prepared.body["keyLocation"],
+                    )
+            else:
+                result = await client.call(
+                    prepared.method,
+                    body=prepared.body,
+                    mutating=True,
+                )
+        except PlanUnknownOutcome as exc:
+            try:
+                store.mark_unknown(plan_id)
+            except BaseException:
+                lease.preserve_lock()
+                raise
+            audit.record("plan_apply_unknown", plan_id=plan_id, error=exc.to_dict())
+            raise
+        except BingWebmasterError as exc:
+            # Everything reaching here failed before or during dispatch: a lost or
+            # ambiguous response is a PlanUnknownOutcome and was handled above.
+            limiter.release(plan.site_url, prepared.cost, day=reserved_day)
+            audit.record("plan_apply_failed", plan_id=plan_id, error=exc.to_dict())
+            raise
+        except BaseException as exc:
+            # Ctrl-C or any other interruption once dispatch has begun: the lock is
+            # released by the context manager, so a plan left pending would invite a
+            # retry of a write that may already have been sent.
+            try:
+                store.mark_unknown(plan_id)
+            except BaseException:
+                lease.preserve_lock()
+                raise
+            audit.record(
+                "plan_apply_unknown",
+                plan_id=plan_id,
+                error={"code": "INTERRUPTED", "type": type(exc).__name__},
+            )
+            raise
+
+        try:
+            store.mark_applied(plan_id)
+        except BaseException:
+            lease.preserve_lock()
+            raise
+        audit.record("plan_apply_succeeded", plan_id=plan_id)
+        return {
+            "applied": True,
+            "plan_id": plan_id,
+            "operation": plan.operation,
+            # A write leaves by this door, and reads leave by ``ops._common.fetch``.
+            # Both are redacted, so neither is the way a code Bing echoed back reaches a
+            # transcript. The literals we sent are hidden too, not only the named fields.
+            "result": redact(result, secret_values(prepared.body)),
+        }
+
+
+async def execute_write(
+    operation: str,
+    args: dict[str, Any],
+    *,
+    settings: Settings,
+    client: BingClient | None,
+    audit: AuditLog,
+    limiter: RateLimiter,
+    indexnow_transport: httpx.AsyncBaseTransport | None = None,
+) -> dict[str, Any]:
+    """Record a plan and apply it in the same call.
+
+    The one-step path is not a second write implementation: it still creates the durable
+    plan record and then goes through ``apply_plan``, so the denylist, Bing's own
+    submission quota, the local daily ceiling, one-shot application and the audit trail
+    are exactly the ones the reviewed path uses. What it drops is the human between the
+    two steps, which is what ``BING_WM_ALLOW_WRITES`` decides.
+    """
+    settings.check_writes_allowed()
+    store = PlanStore(settings.state_dir, settings.plan_ttl_seconds)
+    plan = await create_write_plan(operation, args, settings=settings, client=client)
+    try:
+        return await apply_plan(
+            plan.plan_id,
+            settings=settings,
+            store=store,
+            client=client,
+            audit=audit,
+            limiter=limiter,
+            indexnow_transport=indexnow_transport,
+        )
+    except BingWebmasterError as exc:
+        _close_out(store, plan.plan_id, audit)
+        # Whatever went wrong, the caller has to be able to find the record: for an
+        # unknown outcome the plan id is the only way to tell which write to check
+        # against Bing.
+        exc.details = {**(exc.details or {}), "plan_id": plan.plan_id}
+        raise
+    except BaseException:
+        _close_out(store, plan.plan_id, audit)
+        raise
+
+
+def _close_out(store: PlanStore, plan_id: str, audit: AuditLog) -> None:
+    """Refuse a one-step plan whose write never happened.
+
+    Nobody is coming back to it. Left pending it would stay applicable by hand for a
+    whole TTL, which would send a change no human ever reviewed. A plan the apply
+    boundary already made terminal - applied, or an unknown outcome - keeps exactly the
+    state it recorded, and a failure to clean up never masks the original error.
+    """
+    try:
+        if store.get(plan_id).state != "pending":
+            return
+        store.reject(plan_id)
+        audit.record("plan_discarded", plan_id=plan_id, reason="one_step_write_failed")
+    except BingWebmasterError:
+        return
+    except OSError:
+        return

bing_webmaster_ai_cli_mcp/audit.py

@@ -0,0 +1,45 @@
+"""Append-only record of attempted and completed writes."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+try:  # pragma: no cover - Windows has no fcntl; O_APPEND still protects each write offset.
+    import fcntl
+except ImportError:  # pragma: no cover
+    fcntl = None  # type: ignore[assignment]
+
+
+class AuditLog:
+    def __init__(self, state_dir: Path) -> None:
+        directory = Path(state_dir)
+        directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self._path = directory / "audit.jsonl"
+
+    def record(self, event: str, **fields: Any) -> None:
+        entry = {"ts": datetime.now(UTC).isoformat(), "event": event, **fields}
+        line = (json.dumps(entry, ensure_ascii=False, default=str) + "\n").encode()
+        descriptor = os.open(self._path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        try:
+            if fcntl is not None:
+                fcntl.flock(descriptor, fcntl.LOCK_EX)
+            remaining = memoryview(line)
+            while remaining:
+                written = os.write(descriptor, remaining)
+                if written == 0:
+                    raise OSError("audit write returned zero bytes")
+                remaining = remaining[written:]
+            os.fsync(descriptor)
+        finally:
+            if fcntl is not None:
+                fcntl.flock(descriptor, fcntl.LOCK_UN)
+            os.close(descriptor)
+
+    def entries(self) -> list[dict[str, Any]]:
+        if not self._path.exists():
+            return []
+        return [json.loads(line) for line in self._path.read_text().splitlines() if line]

bing_webmaster_ai_cli_mcp/auth.py

@@ -0,0 +1,42 @@
+"""Credential application with an interface that can later host OAuth2."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from .config import Settings
+
+
+class AuthProvider(Protocol):
+    def apply(self, params: dict[str, Any], headers: dict[str, str]) -> None: ...
+
+    def secrets(self) -> frozenset[str]: ...
+
+
+class ApiKeyAuth:
+    def __init__(self, api_key: str) -> None:
+        self._api_key = api_key
+
+    def apply(self, params: dict[str, Any], headers: dict[str, str]) -> None:
+        # Microsoft documents the API key only as a query-string parameter; the header
+        # form it documents (``Authorization: Bearer``) belongs to the separate OAuth2
+        # flow, not to a key. So the credential is part of every URL this client builds,
+        # and ``secrets`` exists to cover what that implies.
+        params["apikey"] = self._api_key
+
+    def secrets(self) -> frozenset[str]:
+        """The literals this provider puts into a request, for the redaction boundary.
+
+        Whoever applies a credential is the only one that knows what it is. Asking the
+        provider instead of reaching into the settings keeps the two in step: a provider
+        added later hides its own token by implementing this, and nothing else changes.
+        """
+        return frozenset({self._api_key})
+
+
+def build_auth(settings: Settings) -> AuthProvider:
+    if settings.api_key is None:
+        from .errors import AuthFailed
+
+        raise AuthFailed("BING_WM_API_KEY is required for Bing Webmaster API calls")
+    return ApiKeyAuth(settings.api_key.get_secret_value())