plurity-mcp 0.1.0__tar.gz

plurity_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

plurity_mcp-0.1.0/LICENSE

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

plurity_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: plurity-mcp
+Version: 0.1.0
+Summary: Unified MCP server for all Plurity services (Audit, Toll, Intelligence)
+Project-URL: Homepage, https://plurity.ai
+Project-URL: Repository, https://github.com/plurity-ai/plurity-mcp
+Project-URL: Bug Tracker, https://github.com/plurity-ai/plurity-mcp/issues
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.6.0
+Description-Content-Type: text/markdown
+
+# plurity-mcp
+
+Unified [MCP](https://modelcontextprotocol.io) server for all Plurity services — **Audit**, **Toll**, and **Intelligence** — using a single API key.
+
+## Installation
+
+```bash
+uvx plurity-mcp
+```
+
+Or install permanently:
+
+```bash
+uv tool install plurity-mcp
+```
+
+## Quick start
+
+**1. Get an API key**
+
+Log in to [account.plurity.ai](https://account.plurity.ai) → Settings → API Keys → Create key.
+Grant the scopes for each service you want to use (`audit`, `toll`, `intelligence`).
+
+**2. Run the setup wizard**
+
+```bash
+plurity-mcp-setup
+```
+
+The wizard validates your key and saves it to `~/.config/plurity/config.toml`.
+
+**3. Add to your MCP client**
+
+Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "plurity": {
+      "command": "uvx",
+      "args": ["plurity-mcp"],
+      "env": {
+        "PLURITY_API_KEY": "plt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PLURITY_API_KEY` | — | Your `plt_*` API key (**required**) |
+| `PLURITY_ACCOUNTS_URL` | `https://account.plurity.ai` | Override accounts API URL |
+| `PLURITY_AUDIT_URL` | `https://audit.plurity.ai` | Override Audit API URL |
+| `PLURITY_TOLL_URL` | `https://toll.plurity.ai` | Override Toll API URL |
+| `PLURITY_INTELLIGENCE_URL` | `https://intelligence.plurity.ai` | Override Intelligence API URL |
+| `PLURITY_AUDIT_ENABLED` | `true` | Set to `false` to disable Audit tools |
+| `PLURITY_TOLL_ENABLED` | `true` | Set to `false` to disable Toll tools |
+| `PLURITY_INTELLIGENCE_ENABLED` | `true` | Set to `false` to disable Intelligence tools |
+
+### Config file (`~/.config/plurity/config.toml`)
+
+```toml
+[mcp]
+api_key = "plt_..."
+accounts_url = "https://account.plurity.ai"
+audit_base_url = "https://audit.plurity.ai"
+toll_base_url = "https://toll.plurity.ai"
+intelligence_base_url = "https://intelligence.plurity.ai"
+audit_enabled = true
+toll_enabled = true
+intelligence_enabled = true
+```
+
+Environment variables take precedence over the config file.
+
+### Service activation
+
+On startup the server:
+
+1. Validates your API key against plurity-accounts
+2. Reads the key's scopes (e.g. `["audit", "toll"]`)
+3. Registers only the tools for services the key is scoped for
+4. Applies your `*_ENABLED` overrides — you can disable services the key has access to, but you cannot enable services the key lacks a scope for
+
+If the key is invalid the server exits immediately with a clear error message visible in your MCP client.
+
+## Tools
+
+### Audit (GEO readiness)
+
+| Tool | Description |
+|---|---|
+| `submit_audit_scan` | Queue a URL for AI-readiness analysis |
+| `get_audit_scan` | Get scan status and results by ID |
+| `get_audit_scan_by_url` | Look up the latest scan for a URL |
+| `run_audit` | Submit and wait until complete (blocking) |
+
+### Toll (agent traffic + llms.txt)
+
+| Tool | Description |
+|---|---|
+| `list_toll_sites` | List your sites/pages |
+| `create_toll_site` | Create a new site |
+| `get_toll_site` | Get site details including site key |
+| `update_toll_site` | Update name, domain, cache TTL, llms.txt mode |
+| `get_toll_installation_instructions` | Get integration code snippets for HTML/Next.js/React/GTM |
+| `list_toll_qa_pairs` | List Q&A pairs in a site's llms.txt |
+| `create_toll_qa_pair` | Add a Q&A entry to llms.txt |
+| `update_toll_qa_pair` | Edit a Q&A entry (or publish/unpublish it) |
+| `delete_toll_qa_pair` | Remove a Q&A entry |
+| `get_toll_traffic` | Agent traffic chart data (today/week/month/year) |
+
+### Intelligence (question & topic monitoring)
+
+| Tool | Description |
+|---|---|
+| `list_intelligence_sources` | Browse the global source catalogue |
+| `list_subscribed_intelligence_sources` | List sources your org follows |
+| `subscribe_intelligence_source` | Subscribe to a source |
+| `unsubscribe_intelligence_source` | Unsubscribe from a source |
+| `request_intelligence_source` | Add a new source by URL (auto-subscribes) |
+| `list_intelligence_source_content` | List raw scraped documents |
+| `list_intelligence_qa_pairs` | Browse the Q&A feed with filters |
+| `approve_intelligence_qa_pair` | Move a Q&A pair into your knowledge base |
+| `skip_intelligence_qa_pair` | Dismiss a Q&A pair from the feed |
+
+## Development
+
+```bash
+git clone https://github.com/plurity-oss/plurity-mcp
+cd plurity-mcp
+uv sync
+uv run plurity-mcp-setup    # set up key
+uv run plurity-mcp          # run locally
+```
+
+## License
+
+MIT

plurity_mcp-0.1.0/README.md

@@ -0,0 +1,144 @@
+# plurity-mcp
+
+Unified [MCP](https://modelcontextprotocol.io) server for all Plurity services — **Audit**, **Toll**, and **Intelligence** — using a single API key.
+
+## Installation
+
+```bash
+uvx plurity-mcp
+```
+
+Or install permanently:
+
+```bash
+uv tool install plurity-mcp
+```
+
+## Quick start
+
+**1. Get an API key**
+
+Log in to [account.plurity.ai](https://account.plurity.ai) → Settings → API Keys → Create key.
+Grant the scopes for each service you want to use (`audit`, `toll`, `intelligence`).
+
+**2. Run the setup wizard**
+
+```bash
+plurity-mcp-setup
+```
+
+The wizard validates your key and saves it to `~/.config/plurity/config.toml`.
+
+**3. Add to your MCP client**
+
+Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "plurity": {
+      "command": "uvx",
+      "args": ["plurity-mcp"],
+      "env": {
+        "PLURITY_API_KEY": "plt_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PLURITY_API_KEY` | — | Your `plt_*` API key (**required**) |
+| `PLURITY_ACCOUNTS_URL` | `https://account.plurity.ai` | Override accounts API URL |
+| `PLURITY_AUDIT_URL` | `https://audit.plurity.ai` | Override Audit API URL |
+| `PLURITY_TOLL_URL` | `https://toll.plurity.ai` | Override Toll API URL |
+| `PLURITY_INTELLIGENCE_URL` | `https://intelligence.plurity.ai` | Override Intelligence API URL |
+| `PLURITY_AUDIT_ENABLED` | `true` | Set to `false` to disable Audit tools |
+| `PLURITY_TOLL_ENABLED` | `true` | Set to `false` to disable Toll tools |
+| `PLURITY_INTELLIGENCE_ENABLED` | `true` | Set to `false` to disable Intelligence tools |
+
+### Config file (`~/.config/plurity/config.toml`)
+
+```toml
+[mcp]
+api_key = "plt_..."
+accounts_url = "https://account.plurity.ai"
+audit_base_url = "https://audit.plurity.ai"
+toll_base_url = "https://toll.plurity.ai"
+intelligence_base_url = "https://intelligence.plurity.ai"
+audit_enabled = true
+toll_enabled = true
+intelligence_enabled = true
+```
+
+Environment variables take precedence over the config file.
+
+### Service activation
+
+On startup the server:
+
+1. Validates your API key against plurity-accounts
+2. Reads the key's scopes (e.g. `["audit", "toll"]`)
+3. Registers only the tools for services the key is scoped for
+4. Applies your `*_ENABLED` overrides — you can disable services the key has access to, but you cannot enable services the key lacks a scope for
+
+If the key is invalid the server exits immediately with a clear error message visible in your MCP client.
+
+## Tools
+
+### Audit (GEO readiness)
+
+| Tool | Description |
+|---|---|
+| `submit_audit_scan` | Queue a URL for AI-readiness analysis |
+| `get_audit_scan` | Get scan status and results by ID |
+| `get_audit_scan_by_url` | Look up the latest scan for a URL |
+| `run_audit` | Submit and wait until complete (blocking) |
+
+### Toll (agent traffic + llms.txt)
+
+| Tool | Description |
+|---|---|
+| `list_toll_sites` | List your sites/pages |
+| `create_toll_site` | Create a new site |
+| `get_toll_site` | Get site details including site key |
+| `update_toll_site` | Update name, domain, cache TTL, llms.txt mode |
+| `get_toll_installation_instructions` | Get integration code snippets for HTML/Next.js/React/GTM |
+| `list_toll_qa_pairs` | List Q&A pairs in a site's llms.txt |
+| `create_toll_qa_pair` | Add a Q&A entry to llms.txt |
+| `update_toll_qa_pair` | Edit a Q&A entry (or publish/unpublish it) |
+| `delete_toll_qa_pair` | Remove a Q&A entry |
+| `get_toll_traffic` | Agent traffic chart data (today/week/month/year) |
+
+### Intelligence (question & topic monitoring)
+
+| Tool | Description |
+|---|---|
+| `list_intelligence_sources` | Browse the global source catalogue |
+| `list_subscribed_intelligence_sources` | List sources your org follows |
+| `subscribe_intelligence_source` | Subscribe to a source |
+| `unsubscribe_intelligence_source` | Unsubscribe from a source |
+| `request_intelligence_source` | Add a new source by URL (auto-subscribes) |
+| `list_intelligence_source_content` | List raw scraped documents |
+| `list_intelligence_qa_pairs` | Browse the Q&A feed with filters |
+| `approve_intelligence_qa_pair` | Move a Q&A pair into your knowledge base |
+| `skip_intelligence_qa_pair` | Dismiss a Q&A pair from the feed |
+
+## Development
+
+```bash
+git clone https://github.com/plurity-oss/plurity-mcp
+cd plurity-mcp
+uv sync
+uv run plurity-mcp-setup    # set up key
+uv run plurity-mcp          # run locally
+```
+
+## License
+
+MIT

plurity_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "plurity-mcp"
+version = "0.1.0"
+description = "Unified MCP server for all Plurity services (Audit, Toll, Intelligence)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.6.0",
+    "httpx>=0.27.0",
+]
+
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://plurity.ai"
+Repository = "https://github.com/plurity-ai/plurity-mcp"
+"Bug Tracker" = "https://github.com/plurity-ai/plurity-mcp/issues"
+
+[project.scripts]
+plurity-mcp = "plurity_mcp.server:main"
+plurity-mcp-setup = "plurity_mcp.setup:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/plurity_mcp"]

plurity_mcp-0.1.0/src/plurity_mcp/__init__.py

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

plurity_mcp-0.1.0/src/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", {})