krystalview-mcp 0.1.0__tar.gz

krystalview_mcp-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/

krystalview_mcp-0.1.0/LICENSE

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

krystalview_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: krystalview-mcp
+Version: 0.1.0
+Summary: KrystalView MCP Server — AI agent access to website analytics, session replay, friction scoring, and anomaly detection.
+Project-URL: Homepage, https://krystalview.com
+Project-URL: Documentation, https://docs.krystalview.com/integrations/mcp
+Project-URL: Repository, https://github.com/McSlaine/krystalview-mcp
+Author-email: KrystalView <support@krystalview.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,analytics,krystalview,mcp,session-replay
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# KrystalView MCP Server
+
+Give your AI agents direct access to website analytics. Query visitor sessions, investigate UX friction, analyze conversion funnels, and get anomaly alerts — all from Claude, Cursor, or any MCP-compatible client.
+
+## Quick Start
+
+### Install
+
+```bash
+pip install krystalview-mcp
+```
+
+### Configure
+
+Generate an API key in your [KrystalView console](https://app.krystalview.com) under **Settings > API Keys**.
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "krystalview": {
+      "command": "krystalview-mcp",
+      "env": {
+        "KRYSTALVIEW_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+```bash
+claude mcp add krystalview -- krystalview-mcp
+# Then set your API key:
+export KRYSTALVIEW_API_KEY="your-api-key-here"
+```
+
+#### Cursor
+
+Add to your MCP settings:
+
+```json
+{
+  "krystalview": {
+    "command": "krystalview-mcp",
+    "env": {
+      "KRYSTALVIEW_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_sessions` | List/search visitor sessions with filters (device, location, friction, rage clicks) |
+| `get_session_detail` | Deep dive into a specific session — full timeline, events, navigation path |
+| `get_site_stats` | Aggregate performance metrics — sessions, friction, devices, top pages |
+| `get_anomalies` | AI-detected anomalies with explanations (traffic spikes/drops, friction surges) |
+| `get_funnels` | List defined conversion funnels |
+| `get_funnel_analysis` | Step-by-step funnel conversion rates and drop-off analysis |
+
+## Example Prompts
+
+Once connected, try asking your AI assistant:
+
+- *"How's my site performing this week?"*
+- *"Show me frustrated mobile users from the last 24 hours"*
+- *"Why did our traffic drop yesterday?"*
+- *"Where are users dropping off in the checkout funnel?"*
+- *"Find sessions with rage clicks on the pricing page"*
+- *"Are there any anomalies I should know about?"*
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `KRYSTALVIEW_API_KEY` | Yes | — | Your KrystalView API key |
+| `KRYSTALVIEW_BASE_URL` | No | `https://app.krystalview.com/api` | API base URL |
+| `KRYSTALVIEW_TIMEOUT` | No | `15` | Request timeout in seconds |
+
+## Rate Limits
+
+API keys have configurable rate limits (default: 60 requests per minute). Rate limit headers are included in every response. If you hit the limit, the server returns a clear error with retry timing.
+
+## Security
+
+- API keys are scoped to a single site — agents can only access data for the site the key was created for
+- All requests use HTTPS
+- Keys can be rotated or revoked in the KrystalView console
+- No data is stored by the MCP server — it proxies directly to the KrystalView API
+
+## License
+
+MIT

krystalview_mcp-0.1.0/README.md

@@ -0,0 +1,100 @@
+# KrystalView MCP Server
+
+Give your AI agents direct access to website analytics. Query visitor sessions, investigate UX friction, analyze conversion funnels, and get anomaly alerts — all from Claude, Cursor, or any MCP-compatible client.
+
+## Quick Start
+
+### Install
+
+```bash
+pip install krystalview-mcp
+```
+
+### Configure
+
+Generate an API key in your [KrystalView console](https://app.krystalview.com) under **Settings > API Keys**.
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "krystalview": {
+      "command": "krystalview-mcp",
+      "env": {
+        "KRYSTALVIEW_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+```bash
+claude mcp add krystalview -- krystalview-mcp
+# Then set your API key:
+export KRYSTALVIEW_API_KEY="your-api-key-here"
+```
+
+#### Cursor
+
+Add to your MCP settings:
+
+```json
+{
+  "krystalview": {
+    "command": "krystalview-mcp",
+    "env": {
+      "KRYSTALVIEW_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_sessions` | List/search visitor sessions with filters (device, location, friction, rage clicks) |
+| `get_session_detail` | Deep dive into a specific session — full timeline, events, navigation path |
+| `get_site_stats` | Aggregate performance metrics — sessions, friction, devices, top pages |
+| `get_anomalies` | AI-detected anomalies with explanations (traffic spikes/drops, friction surges) |
+| `get_funnels` | List defined conversion funnels |
+| `get_funnel_analysis` | Step-by-step funnel conversion rates and drop-off analysis |
+
+## Example Prompts
+
+Once connected, try asking your AI assistant:
+
+- *"How's my site performing this week?"*
+- *"Show me frustrated mobile users from the last 24 hours"*
+- *"Why did our traffic drop yesterday?"*
+- *"Where are users dropping off in the checkout funnel?"*
+- *"Find sessions with rage clicks on the pricing page"*
+- *"Are there any anomalies I should know about?"*
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `KRYSTALVIEW_API_KEY` | Yes | — | Your KrystalView API key |
+| `KRYSTALVIEW_BASE_URL` | No | `https://app.krystalview.com/api` | API base URL |
+| `KRYSTALVIEW_TIMEOUT` | No | `15` | Request timeout in seconds |
+
+## Rate Limits
+
+API keys have configurable rate limits (default: 60 requests per minute). Rate limit headers are included in every response. If you hit the limit, the server returns a clear error with retry timing.
+
+## Security
+
+- API keys are scoped to a single site — agents can only access data for the site the key was created for
+- All requests use HTTPS
+- Keys can be rotated or revoked in the KrystalView console
+- No data is stored by the MCP server — it proxies directly to the KrystalView API
+
+## License
+
+MIT

krystalview_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "krystalview-mcp"
+version = "0.1.0"
+description = "KrystalView MCP Server — AI agent access to website analytics, session replay, friction scoring, and anomaly detection."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "KrystalView", email = "support@krystalview.com" }]
+keywords = ["mcp", "analytics", "krystalview", "ai", "session-replay"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+krystalview-mcp = "krystalview_mcp.server:main"
+
+[project.urls]
+Homepage = "https://krystalview.com"
+Documentation = "https://docs.krystalview.com/integrations/mcp"
+Repository = "https://github.com/McSlaine/krystalview-mcp"

krystalview_mcp-0.1.0/src/krystalview_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""KrystalView MCP Server — AI agent access to website analytics."""
+
+__version__ = "0.1.0"

krystalview_mcp-0.1.0/src/krystalview_mcp/server.py

@@ -0,0 +1,258 @@
+"""KrystalView MCP Server.
+
+Gives AI agents direct access to website analytics — sessions, visitor
+behavior, friction scores, anomalies, and funnel analysis.
+
+Authenticates against the KrystalView API using the same API keys
+generated in the KrystalView console.
+"""
+
+import json
+import os
+from typing import Any, Optional
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+API_KEY = os.environ.get("KRYSTALVIEW_API_KEY", "")
+BASE_URL = os.environ.get(
+    "KRYSTALVIEW_BASE_URL", "https://app.krystalview.com/api"
+).rstrip("/")
+TIMEOUT = int(os.environ.get("KRYSTALVIEW_TIMEOUT", "15"))
+
+mcp = FastMCP(
+    "KrystalView",
+    instructions=(
+        "KrystalView provides real-time website analytics with session replay, "
+        "friction scoring, anomaly detection, and funnel analysis. "
+        "Use these tools to investigate visitor behavior, diagnose UX issues, "
+        "and answer questions about site performance."
+    ),
+)
+
+# ---------------------------------------------------------------------------
+# HTTP helpers
+# ---------------------------------------------------------------------------
+
+
+def _headers() -> dict[str, str]:
+    return {"X-API-Key": API_KEY, "Accept": "application/json"}
+
+
+async def _get(path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Make an authenticated GET request to the KrystalView API."""
+    url = f"{BASE_URL}{path}"
+    # Strip None values from params
+    if params:
+        params = {k: v for k, v in params.items() if v is not None}
+    async with httpx.AsyncClient(timeout=TIMEOUT) as client:
+        resp = await client.get(url, headers=_headers(), params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _format_error(exc: Exception) -> str:
+    if isinstance(exc, httpx.HTTPStatusError):
+        status = exc.response.status_code
+        if status == 401:
+            return "Authentication failed. Check your KRYSTALVIEW_API_KEY."
+        if status == 403:
+            return "API key does not have the required 'read' scope."
+        if status == 429:
+            retry = exc.response.headers.get("Retry-After", "?")
+            return f"Rate limited. Retry after {retry} seconds."
+        try:
+            detail = exc.response.json().get("detail", exc.response.text)
+        except Exception:
+            detail = exc.response.text
+        return f"API error {status}: {detail}"
+    return f"Request failed: {exc}"
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+async def get_sessions(
+    query: Optional[str] = None,
+    limit: int = 20,
+    offset: int = 0,
+    country: Optional[str] = None,
+    device_type: Optional[str] = None,
+    min_friction: Optional[int] = None,
+    min_duration: Optional[int] = None,
+    has_rage_clicks: Optional[bool] = None,
+) -> str:
+    """List recent visitor sessions with filtering.
+
+    Each session includes: duration, page count, entry/exit URLs, device info,
+    screen size, IP address, location (country/city), friction score, and
+    rage click count.
+
+    Use this to find sessions matching specific criteria — e.g. frustrated
+    mobile users, visitors from a specific country, or high-friction sessions.
+
+    Args:
+        query: Search entry/exit URLs (e.g. "/pricing", "/checkout")
+        limit: Max results (1-100, default 20)
+        offset: Pagination offset
+        country: Filter by country name
+        device_type: "mobile" or "desktop"
+        min_friction: Minimum friction score (0-10)
+        min_duration: Minimum session duration in seconds
+        has_rage_clicks: Only sessions with rage clicks
+    """
+    try:
+        data = await _get("/v1/api/sessions", {
+            "q": query,
+            "limit": min(limit, 100),
+            "offset": max(offset, 0),
+            "country": country,
+            "device_type": device_type,
+            "min_friction": min_friction,
+            "min_duration": min_duration,
+            "has_rage_clicks": has_rage_clicks,
+        })
+        return json.dumps(data["data"], indent=2, default=str)
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def get_session_detail(session_id: str) -> str:
+    """Get full details for a specific session.
+
+    Returns the complete session record including: all page visits with
+    timestamps, event timeline, device/browser info, IP address, geographic
+    location, friction breakdown, rage clicks, errors encountered, and
+    navigation path.
+
+    Use this to deep-dive into a specific session after finding it via
+    get_sessions.
+
+    Args:
+        session_id: The session primary key (UUID) from get_sessions results
+    """
+    try:
+        data = await _get(f"/v1/api/sessions/{session_id}")
+        return json.dumps(data["data"], indent=2, default=str)
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def get_site_stats(days: int = 7) -> str:
+    """Get aggregate site statistics and performance metrics.
+
+    Returns: total sessions, average duration, average friction score,
+    bounce rate, rage click sessions, device breakdown (desktop/mobile),
+    browser breakdown, top entry pages, top exit pages, daily session
+    counts, and friction score distribution.
+
+    Use this for an overview of site health and trends.
+
+    Args:
+        days: Lookback period in days (7-90, default 7)
+    """
+    try:
+        data = await _get("/v1/api/stats", {"days": min(max(days, 7), 90)})
+        return json.dumps(data["data"], indent=2, default=str)
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def get_anomalies(
+    limit: int = 20,
+    unacknowledged_only: bool = False,
+) -> str:
+    """Get detected anomalies for the site.
+
+    Anomalies are automatically detected when metrics deviate significantly
+    from their 7-day rolling average (>2 standard deviations). Types include:
+    traffic_spike, traffic_drop, friction_surge, and bounce_spike.
+
+    Each anomaly includes: type, severity (warning/critical), metric name,
+    expected vs actual values, deviation percentage, and an AI-generated
+    explanation of what likely caused it.
+
+    Args:
+        limit: Max results (1-200, default 20)
+        unacknowledged_only: Only show unacknowledged anomalies
+    """
+    try:
+        data = await _get("/v1/api/anomalies", {
+            "limit": min(limit, 200),
+            "unacknowledged": unacknowledged_only,
+        })
+        return json.dumps(data["data"], indent=2, default=str)
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def get_funnels() -> str:
+    """List all conversion funnels defined for this site.
+
+    Returns funnel definitions with their name, steps (URLs/patterns),
+    and creation date. Use the funnel ID with get_funnel_analysis to see
+    conversion rates and drop-off points.
+    """
+    try:
+        data = await _get("/v1/api/funnels")
+        return json.dumps(data["data"], indent=2, default=str)
+    except Exception as exc:
+        return _format_error(exc)
+
+
+@mcp.tool()
+async def get_funnel_analysis(funnel_id: int, days: int = 30) -> str:
+    """Analyze a conversion funnel — see where users drop off.
+
+    Returns step-by-step conversion rates showing how many sessions
+    reached each step, the conversion rate between steps, and the
+    overall funnel completion rate.
+
+    Use this to identify which step in a user flow (e.g. landing ->
+    signup -> checkout -> payment) loses the most visitors.
+
+    Args:
+        funnel_id: Funnel ID from get_funnels results
+        days: Lookback period in days (7-90, default 30)
+    """
+    try:
+        data = await _get(f"/v1/api/funnels/{funnel_id}/analysis", {
+            "days": min(max(days, 7), 90),
+        })
+        return json.dumps(data["data"], indent=2, default=str)
+    except Exception as exc:
+        return _format_error(exc)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main():
+    """Run the KrystalView MCP server (stdio transport)."""
+    if not API_KEY:
+        import sys
+        print(
+            "Error: KRYSTALVIEW_API_KEY environment variable is required.\n"
+            "Generate an API key in your KrystalView console under "
+            "Settings > API Keys.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()