plurity-mcp 0.1.0__py3-none-any.whl

plurity_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Plurity unified MCP server."""
+
+__version__ = "0.1.0"

plurity_mcp/client.py

@@ -0,0 +1,286 @@
+"""Synchronous HTTP clients for each Plurity service.
+
+All clients share the same auth header (Bearer plt_*) and error model
+(:class:`PlurityAPIError`). Service-specific methods live on each subclass.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import httpx
+
+_DEFAULT_TIMEOUT = 30.0
+
+
+class PlurityAPIError(Exception):
+    """Raised when a Plurity service returns an error response."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class _BaseClient:
+    """Shared httpx wrapper used by all service clients."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float = _DEFAULT_TIMEOUT) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            body = response.json()
+            detail = body.get("error") or body.get("message") or body.get("detail", "")
+        except Exception:
+            detail = response.text or "(no body)"
+        raise PlurityAPIError(
+            f"API error {response.status_code}: {detail}",
+            status_code=response.status_code,
+        )
+
+    def _get(self, path: str, **params: Any) -> dict[str, Any]:
+        response = self._client.get(
+            path, params={k: v for k, v in params.items() if v is not None}
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        response = self._client.post(path, json=body)
+        self._raise_for_status(response)
+        return response.json()
+
+    def _patch(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        response = self._client.patch(path, json=body)
+        self._raise_for_status(response)
+        return response.json()
+
+    def _delete(self, path: str, **params: Any) -> dict[str, Any]:
+        response = self._client.delete(
+            path, params={k: v for k, v in params.items() if v is not None}
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "_BaseClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Audit client
+# ---------------------------------------------------------------------------
+
+
+class AuditClient(_BaseClient):
+    """Client for the Plurity GEO Audit API."""
+
+    def submit_scan(self, url: str, webhook_url: str = "") -> dict[str, Any]:
+        body: dict[str, Any] = {"url": url}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        return self._post("/api/v1/scans", body)
+
+    def get_scan(self, scan_id: str) -> dict[str, Any]:
+        return self._get(f"/api/v1/scans/{scan_id}")
+
+    def get_scan_by_url(self, url: str) -> dict[str, Any]:
+        return self._get("/api/v1/scans", url=url)
+
+    def wait_for_scan(
+        self,
+        scan_id: str,
+        timeout_seconds: int = 300,
+        poll_interval: float = 5.0,
+    ) -> dict[str, Any]:
+        _TERMINAL = {"complete", "failed"}
+        deadline = time.monotonic() + timeout_seconds
+        last: dict[str, Any] = {}
+        while time.monotonic() < deadline:
+            last = self.get_scan(scan_id)
+            if last.get("status") in _TERMINAL:
+                return last
+            remaining = deadline - time.monotonic()
+            time.sleep(min(poll_interval, max(remaining, 0)))
+        return last
+
+
+# ---------------------------------------------------------------------------
+# Toll client
+# ---------------------------------------------------------------------------
+
+
+class TollClient(_BaseClient):
+    """Client for the Plurity Toll API (agent traffic + llms.txt management)."""
+
+    # Sites
+    def list_sites(self) -> dict[str, Any]:
+        return self._get("/api/v1/sites")
+
+    def create_site(self, name: str, domain: str) -> dict[str, Any]:
+        return self._post("/api/v1/sites", {"name": name, "domain": domain})
+
+    def get_site(self, site_id: str) -> dict[str, Any]:
+        return self._get(f"/api/v1/sites/{site_id}")
+
+    def update_site(
+        self,
+        site_id: str,
+        name: Optional[str] = None,
+        domain: Optional[str] = None,
+        cache_ttl_secs: Optional[int] = None,
+        llms_txt_mode: Optional[str] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if domain is not None:
+            body["domain"] = domain
+        if cache_ttl_secs is not None:
+            body["cache_ttl_secs"] = cache_ttl_secs
+        if llms_txt_mode is not None:
+            body["llms_txt_mode"] = llms_txt_mode
+        return self._patch(f"/api/v1/sites/{site_id}", body)
+
+    # Q&A pairs
+    def list_qa_pairs(self, site_id: str) -> dict[str, Any]:
+        return self._get(f"/api/v1/sites/{site_id}/qa-pairs")
+
+    def create_qa_pair(
+        self,
+        site_id: str,
+        question: str,
+        answer_url: str,
+        answer_summary: Optional[str] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"question": question, "answer_url": answer_url}
+        if answer_summary is not None:
+            body["answer_summary"] = answer_summary
+        return self._post(f"/api/v1/sites/{site_id}/qa-pairs", body)
+
+    def update_qa_pair(
+        self,
+        site_id: str,
+        pair_id: str,
+        question: Optional[str] = None,
+        answer_url: Optional[str] = None,
+        answer_summary: Optional[str] = None,
+        is_published: Optional[bool] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if question is not None:
+            body["question"] = question
+        if answer_url is not None:
+            body["answer_url"] = answer_url
+        if answer_summary is not None:
+            body["answer_summary"] = answer_summary
+        if is_published is not None:
+            body["is_published"] = is_published
+        return self._patch(f"/api/v1/sites/{site_id}/qa-pairs/{pair_id}", body)
+
+    def delete_qa_pair(self, site_id: str, pair_id: str) -> dict[str, Any]:
+        return self._delete(f"/api/v1/sites/{site_id}/qa-pairs/{pair_id}")
+
+    # Traffic
+    def get_traffic(
+        self,
+        site_id: str,
+        period: str = "week",
+        agents: Optional[str] = None,
+    ) -> dict[str, Any]:
+        return self._get(
+            f"/api/v1/sites/{site_id}/events/chart",
+            period=period,
+            agents=agents,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Intelligence client
+# ---------------------------------------------------------------------------
+
+
+class IntelligenceClient(_BaseClient):
+    """Client for the Plurity Intelligence API (question + topic monitoring)."""
+
+    # Sources
+    def list_sources(
+        self,
+        type: Optional[str] = None,
+        q: Optional[str] = None,
+    ) -> dict[str, Any]:
+        return self._get("/api/v1/sources", type=type, q=q)
+
+    def list_subscriptions(self) -> dict[str, Any]:
+        return self._get("/api/v1/subscriptions")
+
+    def subscribe_source(
+        self,
+        source_id: str,
+        start_date: Optional[str] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if start_date is not None:
+            body["start_date"] = start_date
+        return self._post(f"/api/v1/sources/{source_id}/subscribe", body)
+
+    def unsubscribe_source(self, source_id: str) -> dict[str, Any]:
+        return self._delete(f"/api/v1/sources/{source_id}/subscribe")
+
+    def request_source(self, url: str) -> dict[str, Any]:
+        return self._post("/api/v1/sources/request", {"url": url})
+
+    # Source content (documents)
+    def list_source_content(
+        self,
+        source_id: Optional[str] = None,
+        date_from: Optional[str] = None,
+        date_to: Optional[str] = None,
+        content_type: Optional[str] = None,
+    ) -> dict[str, Any]:
+        return self._get(
+            "/api/v1/source-content",
+            source_id=source_id,
+            date_from=date_from,
+            date_to=date_to,
+            content_type=content_type,
+        )
+
+    # Q&A feed
+    def list_qa_pairs(
+        self,
+        source_id: Optional[str] = None,
+        date_from: Optional[str] = None,
+        date_to: Optional[str] = None,
+        status: Optional[str] = None,
+    ) -> dict[str, Any]:
+        return self._get(
+            "/api/v1/feed",
+            source_id=source_id,
+            date_from=date_from,
+            date_to=date_to,
+            status=status,
+        )
+
+    def approve_qa_pair(self, qa_pair_id: str) -> dict[str, Any]:
+        return self._post(f"/api/v1/feed/{qa_pair_id}/approve", {})
+
+    def skip_qa_pair(self, qa_pair_id: str) -> dict[str, Any]:
+        return self._post(f"/api/v1/feed/{qa_pair_id}/skip", {})

plurity_mcp/config.py

@@ -0,0 +1,278 @@
+"""Configuration loading and API key validation for plurity-mcp.
+
+Resolution order (highest to lowest priority):
+1. Environment variables
+2. ~/.config/plurity/config.toml [mcp] section
+3. Built-in defaults
+
+After loading, the key is validated against the accounts API and the
+enabled service set is intersected with the key's scopes.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+_CONFIG_PATH = Path.home() / ".config" / "plurity" / "config.toml"
+
+_DEFAULT_ACCOUNTS_URL = "https://account.plurity.ai"
+_DEFAULT_AUDIT_URL = "https://audit.plurity.ai"
+_DEFAULT_TOLL_URL = "https://toll.plurity.ai"
+_DEFAULT_INTELLIGENCE_URL = "https://intelligence.plurity.ai"
+
+
+# ---------------------------------------------------------------------------
+# Scope helpers (mirrors the TypeScript hasScope in @plurity/auth)
+# ---------------------------------------------------------------------------
+
+
+def has_scope(key_scopes: list[str], required: str) -> bool:
+    """Return True if *key_scopes* grants *required*.
+
+    Supports wildcards:
+      ["*"]          -> full access
+      ["audit:*"]    -> all audit scopes
+      ["audit:read"] -> exact match only
+      ["audit"]      -> exact namespace match (convention: bare name = full access to service)
+    """
+    for scope in key_scopes:
+        if scope == "*":
+            return True
+        if scope.endswith(":*"):
+            ns = scope[:-2]
+            if required == ns or required.startswith(ns + ":"):
+                return True
+        if scope == required:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceConfig:
+    """Resolved configuration for one Plurity service."""
+
+    enabled: bool
+    """Whether this service's tools are registered."""
+
+    base_url: str
+    """Base URL for the service REST API."""
+
+
+@dataclass(frozen=True, slots=True)
+class PlurityMCPConfig:
+    """Fully resolved configuration for plurity-mcp."""
+
+    api_key: str
+    accounts_url: str
+    org_id: str
+    scopes: list[str]
+    audit: ServiceConfig
+    toll: ServiceConfig
+    intelligence: ServiceConfig
+
+
+# ---------------------------------------------------------------------------
+# TOML helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_toml() -> dict:
+    if not _CONFIG_PATH.exists():
+        return {}
+    with _CONFIG_PATH.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def _bool_env(name: str, default: bool) -> bool:
+    val = os.environ.get(name, "").strip().lower()
+    if val in ("0", "false", "no", "off"):
+        return False
+    if val in ("1", "true", "yes", "on"):
+        return True
+    return default
+
+
+# ---------------------------------------------------------------------------
+# Key validation
+# ---------------------------------------------------------------------------
+
+
+def _validate_key(api_key: str, accounts_url: str) -> tuple[str, str, list[str]]:
+    """Validate *api_key* against the accounts API.
+
+    Returns:
+        (org_id, key_id, scopes) on success.
+
+    Raises:
+        RuntimeError with a descriptive message on failure.
+    """
+    url = f"{accounts_url.rstrip('/')}/api/v1/validate-key"
+    try:
+        response = httpx.post(
+            url,
+            json={"key": api_key},
+            timeout=10.0,
+            headers={"Content-Type": "application/json"},
+        )
+    except httpx.ConnectError:
+        raise RuntimeError(
+            f"Could not connect to the Plurity accounts API at {accounts_url}. "
+            "Check your network connection or PLURITY_ACCOUNTS_URL."
+        )
+    except httpx.TimeoutException:
+        raise RuntimeError(
+            f"Timed out connecting to the Plurity accounts API at {accounts_url}."
+        )
+
+    if response.status_code == 401:
+        raise RuntimeError(
+            "Invalid API key. Check your PLURITY_API_KEY or run 'plurity-mcp-setup' "
+            "to save a new key."
+        )
+    if response.status_code == 403:
+        body = response.json()
+        raise RuntimeError(f"API key rejected: {body.get('error', 'Forbidden')}")
+    if not response.is_success:
+        raise RuntimeError(
+            f"Accounts API returned HTTP {response.status_code} when validating key."
+        )
+
+    body = response.json()
+    return body["org_id"], body["key_id"], body.get("scopes", [])
+
+
+# ---------------------------------------------------------------------------
+# Main resolver
+# ---------------------------------------------------------------------------
+
+
+def get_config() -> PlurityMCPConfig:
+    """Load, validate, and return the resolved :class:`PlurityMCPConfig`.
+
+    Validates the API key against the accounts service and intersects the
+    key's scopes with any user-level enable/disable overrides.
+
+    Raises:
+        RuntimeError if no API key is found or the key is invalid.
+    """
+    toml = _load_toml()
+    mcp_section: dict = toml.get("mcp", {})
+
+    # --- API key ---
+    api_key = (
+        os.environ.get("PLURITY_API_KEY", "").strip()
+        or mcp_section.get("api_key", "").strip()
+    )
+    if not api_key:
+        raise RuntimeError(
+            "No Plurity API key found. "
+            "Set the PLURITY_API_KEY environment variable or run 'plurity-mcp-setup'."
+        )
+
+    # --- Accounts URL ---
+    accounts_url = (
+        os.environ.get("PLURITY_ACCOUNTS_URL", "").strip()
+        or mcp_section.get("accounts_url", "").strip()
+        or _DEFAULT_ACCOUNTS_URL
+    ).rstrip("/")
+
+    # --- Validate key ---
+    org_id, key_id, scopes = _validate_key(api_key, accounts_url)
+
+    # --- Service base URLs ---
+    audit_url = (
+        os.environ.get("PLURITY_AUDIT_URL", "").strip()
+        or mcp_section.get("audit_base_url", "").strip()
+        or _DEFAULT_AUDIT_URL
+    ).rstrip("/")
+
+    toll_url = (
+        os.environ.get("PLURITY_TOLL_URL", "").strip()
+        or mcp_section.get("toll_base_url", "").strip()
+        or _DEFAULT_TOLL_URL
+    ).rstrip("/")
+
+    intelligence_url = (
+        os.environ.get("PLURITY_INTELLIGENCE_URL", "").strip()
+        or mcp_section.get("intelligence_base_url", "").strip()
+        or _DEFAULT_INTELLIGENCE_URL
+    ).rstrip("/")
+
+    # --- Service enablement ---
+    # Scope check: does the key have access to each service?
+    audit_scope_ok = has_scope(scopes, "audit")
+    toll_scope_ok = has_scope(scopes, "toll")
+    intelligence_scope_ok = has_scope(scopes, "intelligence")
+
+    # User overrides (env vars or TOML); can only disable, not grant beyond scope
+    audit_user_enabled = _bool_env("PLURITY_AUDIT_ENABLED", mcp_section.get("audit_enabled", True))
+    toll_user_enabled = _bool_env("PLURITY_TOLL_ENABLED", mcp_section.get("toll_enabled", True))
+    intelligence_user_enabled = _bool_env(
+        "PLURITY_INTELLIGENCE_ENABLED", mcp_section.get("intelligence_enabled", True)
+    )
+
+    return PlurityMCPConfig(
+        api_key=api_key,
+        accounts_url=accounts_url,
+        org_id=org_id,
+        scopes=scopes,
+        audit=ServiceConfig(
+            enabled=audit_scope_ok and audit_user_enabled,
+            base_url=audit_url,
+        ),
+        toll=ServiceConfig(
+            enabled=toll_scope_ok and toll_user_enabled,
+            base_url=toll_url,
+        ),
+        intelligence=ServiceConfig(
+            enabled=intelligence_scope_ok and intelligence_user_enabled,
+            base_url=intelligence_url,
+        ),
+    )
+
+
+def save_config(
+    api_key: str,
+    accounts_url: str = _DEFAULT_ACCOUNTS_URL,
+    audit_base_url: str = _DEFAULT_AUDIT_URL,
+    toll_base_url: str = _DEFAULT_TOLL_URL,
+    intelligence_base_url: str = _DEFAULT_INTELLIGENCE_URL,
+) -> None:
+    """Persist config to ``~/.config/plurity/config.toml`` under the ``[mcp]`` section."""
+    _CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    existing: dict = {}
+    if _CONFIG_PATH.exists():
+        with _CONFIG_PATH.open("rb") as fh:
+            existing = tomllib.load(fh)
+
+    existing.setdefault("mcp", {})
+    existing["mcp"]["api_key"] = api_key
+    existing["mcp"]["accounts_url"] = accounts_url
+    existing["mcp"]["audit_base_url"] = audit_base_url
+    existing["mcp"]["toll_base_url"] = toll_base_url
+    existing["mcp"]["intelligence_base_url"] = intelligence_base_url
+
+    lines: list[str] = []
+    for section, values in existing.items():
+        lines.append(f"[{section}]")
+        for k, v in values.items():
+            if isinstance(v, bool):
+                lines.append(f"{k} = {'true' if v else 'false'}")
+            else:
+                lines.append(f'{k} = "{v}"')
+        lines.append("")
+
+    _CONFIG_PATH.write_text("\n".join(lines), encoding="utf-8")

plurity_mcp/server.py

@@ -0,0 +1,69 @@
+"""Unified Plurity MCP server.
+
+Validates the API key against plurity-accounts on startup, then registers
+only the tools for services the key has access to (and that are not
+explicitly disabled in config).
+"""
+
+from __future__ import annotations
+
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("Plurity")
+
+
+def main() -> None:
+    """Validate config and start the MCP server."""
+    from .config import get_config
+
+    try:
+        config = get_config()
+    except RuntimeError as exc:
+        # Print a clear message to stderr so the MCP client (e.g. Claude
+        # Desktop) can surface it to the user.
+        print(f"[plurity-mcp] Configuration error: {exc}", file=sys.stderr, flush=True)
+        sys.exit(1)
+
+    enabled: list[str] = []
+    disabled_by_scope: list[str] = []
+
+    if config.audit.enabled:
+        from .tools.audit import register_audit_tools
+        register_audit_tools(mcp, config)
+        enabled.append("audit")
+    else:
+        disabled_by_scope.append("audit")
+
+    if config.toll.enabled:
+        from .tools.toll import register_toll_tools
+        register_toll_tools(mcp, config)
+        enabled.append("toll")
+    else:
+        disabled_by_scope.append("toll")
+
+    if config.intelligence.enabled:
+        from .tools.intelligence import register_intelligence_tools
+        register_intelligence_tools(mcp, config)
+        enabled.append("intelligence")
+    else:
+        disabled_by_scope.append("intelligence")
+
+    if not enabled:
+        print(
+            "[plurity-mcp] No services are enabled. "
+            "Your key's scopes may not grant access to any service, "
+            "or all services were manually disabled.\n"
+            f"Key scopes: {config.scopes}",
+            file=sys.stderr,
+            flush=True,
+        )
+        sys.exit(1)
+
+    summary = f"[plurity-mcp] Starting — services: {', '.join(enabled)}"
+    if disabled_by_scope:
+        summary += f" | disabled: {', '.join(disabled_by_scope)}"
+    print(summary, file=sys.stderr, flush=True)
+
+    mcp.run()