@webeyez/mcp-server 1.0.5 → 1.0.7

package/README.md

@@ -1,35 +1,54 @@
 # Webeyez Model Context Protocol (MCP) Server
 
-Access Webeyez session replays, JavaScript errors, conversion funnels, and performance diagnostics directly from any MCP-compatible AI client.
+[![NPM Version](https://img.shields.io/npm/v/@webeyez/mcp-server.svg)](https://www.npmjs.com/package/@webeyez/mcp-server)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Model Context Protocol Compliant](https://img.shields.io/badge/MCP-Compliant-green.svg)](https://modelcontextprotocol.io)
+
+Expose Webeyez session replays, JavaScript errors, conversion funnels, rage clicks, and performance diagnostics directly to your AI agents and assistants (Claude, Cursor, Windsurf, ChatGPT, etc.) using the Model Context Protocol (MCP).
+
+---
 
 ## What is Webeyez?
-Webeyez is a comprehensive real-time user experience monitoring and diagnostic platform that helps online businesses detect, investigate, and resolve issues impacting their users. By tracking user friction, client-side errors, and drop-offs, Webeyez pinpoints exact conversion and revenue leaks. 
 
-**All data, insights, and opportunities collected by Webeyez are available through the Model Context Protocol (MCP).** This allows your AI agents and assistants to query live performance data, search session recordings, inspect JavaScript logs, and analyze conversion drop-offs directly within your chat environment.
+**Webeyez** is a real-time user experience monitoring, conversion optimization, and error diagnostics platform. It helps online businesses identify and resolve conversion leaks, user friction, client-side bugs, and performance anomalies. 
+
+The **Webeyez MCP Server** bridges your local AI tools directly to the Webeyez diagnostics engine. It is implemented as a **secure proxy client**, meaning the server runs safely on Webeyez infrastructure to protect your data and proprietary logic, while the local NPM package serves as a lightweight, secure gateway.
+
+---
+
+## When to Use the Webeyez MCP Server
+
+Use this MCP server when you want your AI developer agent or assistant to:
+* **Debug Client-Side Bugs:** Retrieve JS console logs, stack traces, and uncaught exceptions for a user session or globally.
+* **Diagnose Network Failures:** Analyze failed HTTP/AJAX requests (4xx/5xx errors) on your web applications.
+* **Identify Friction & Rage Clicks:** Search user sessions containing Dead Clicks, Rage Clicks, or other frustration signals.
+* **Analyze Funnel Drops:** Diagnose why conversion rates dropped during checkout or specific funnels.
+* **Quantify Revenue Loss:** Retrieve estimates of business impact caused by bugs and performance drop-offs.
+* **Inspect Session Replays:** Retrieve links to actual user session replays matching specific error criteria to witness user frustration firsthand.
 
-This server implements the Model Context Protocol (MCP) to seamlessly expose Webeyez's core analytics tools into AI clients such as **Claude (Web App)**, **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, and any other MCP-compliant interface.
+---
 
 ## Installation
 
+You do not need to install the server globally. The package can be run directly using `npx`:
+
 ```bash
-npm install -g @webeyez/mcp-server
+npx -y @webeyez/mcp-server
 ```
 
+---
+
 ## Connection Setup
 
-The Webeyez MCP server supports both SSE (Server-Sent Events) for web applications and stdio/SSE bridging for local desktop editors.
+The Webeyez MCP server supports both standard local `stdio` connection (using our NPM package as a secure proxy) and direct web-based SSE connections.
+
+### Option 1: Claude Desktop Configuration (Local stdio Proxy)
 
-### Option 1: SSE Configuration (e.g., Claude Web App)
-Register the server as a custom connector in web-based clients:
-1. Go to **Settings > Connectors > Add custom connector** (or equivalent in your AI client).
-2. Enter the connector URL: `https://api.app.webeyez.com/mcp`
-3. Log in with your Webeyez credentials when prompted.
+Add the server to your `claude_desktop_config.json` configuration file:
 
-### Option 2: Stdio Bridge Configuration (e.g., Claude Desktop, Cursor, Windsurf)
-Since local editor applications expect local processes, connect them to the remote server using the official `mcp-remote` bridge tool.
+* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
-#### For Claude Desktop:
-Configure your `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
@@ -37,48 +56,72 @@ Configure your `claude_desktop_config.json`:
       "command": "npx",
       "args": [
         "-y",
-        "mcp-remote@latest",
-        "https://api.app.webeyez.com/mcp"
-      ]
+        "@webeyez/mcp-server"
+      ],
+      "env": {
+        "WEBEYEZ_API_KEY": "your_webeyez_api_token_here"
+      }
     }
   }
 }
 ```
 
-#### For Cursor:
-1. Go to **Settings > Features > MCP**.
-2. Click **+ Add New MCP Server**.
-3. Set **Name** to `webeyez`.
-4. Set **Type** to `command`.
-5. Set **Command** to:
+### Option 2: IDE / Editor Configuration (Cursor, Windsurf, Cline)
+
+Configure your editor to run the MCP proxy as a shell command:
+
+1. Open your editor's **Settings > Features > MCP** (or equivalent).
+2. Add a new MCP server with type `command`.
+3. Set the command to:
    ```bash
-   npx -y mcp-remote@latest https://api.app.webeyez.com/mcp
+   npx -y @webeyez/mcp-server
    ```
+4. Define the environment variable:
+   * **Key:** `WEBEYEZ_API_KEY`
+   * **Value:** *[Your personal access token/API key]*
+
+### Option 3: Remote Server-Sent Events (SSE)
+Web-based clients and custom applications can connect directly to the Webeyez SSE endpoint without any local installation:
+* **SSE Endpoint:** `https://api.app.webeyez.com/mcp`
+* **Authentication:** Pass your token in the `x-api-key` header or as a `token` URL query parameter.
+
+---
 
 ## Available Tools
 
-All tools require standard authentication (which is handled automatically via OAuth on connection setup):
-
-### Core AI Query Tools (Query live data using natural language)
-* `start_webeyez_query`: Kicks off a long-running natural language query to the Webeyez AI agent regarding any data collected by Webeyez (including session replays, conversion funnels, JS errors, failed API calls, and revenue impact).
-* `check_webeyez_status`: Polls and retrieves the status and the final response of a running background query.
-* `get_organizations_list`: Lists all organizations the authenticated user has access to.
-* `get_organization_domains`: Lists all registered domains under a specific organization.
-* `logout_webeyez`: Safely logs out and resets saved connection context.
-
-### Direct Resource Tools (Direct query and management stubs)
-* `list_accounts`: Lists accessible Webeyez accounts.
-* `list_sites`: Lists configured sites.
-* `get_site_status`: Returns tracking and integration status.
-* `get_revenue_loss_estimate`: Returns estimated conversion and revenue losses.
-* `get_funnel_summary`: Retrieves conversion funnel analysis.
-* `get_checkout_dropoffs`: Returns checkout friction details.
-* `get_js_errors`: Returns client-side JavaScript console errors.
-* `get_failed_api_calls`: Lists failed HTTP network requests.
-* `get_session_examples`: Retrieve recorded session replay links and examples.
-* `create_issue_export`: Export detected issues and anomalies.
-* `connect_shopify_store` / `connect_magento_store`: Platform integration shortcuts.
-* `manage_tracker_settings`: Configures client tracker preferences.
+The following tools are exposed by the server for AI agents to query:
+
+### 1. Core AI Query Tools
+* **`start_webeyez_query`**: Starts a long-running natural language query against the Webeyez diagnostics engine. Use this to ask questions about your session data, checkout friction, JS errors, or conversion drop-offs.
+* **`check_webeyez_status`**: Polls the status and retrieves the final text answer/response of a query started with `start_webeyez_query`.
+* **`get_organizations_list`**: Lists all Webeyez organizations you have access to (along with their `organizationId`s).
+* **`get_organization_domains`**: Lists all registered domains for a specific organization.
+* **`logout_webeyez`**: Safely clears connection state and credentials.
+
+### 2. Direct Resource Diagnostics
+* **`get_js_errors`**: Returns client-side JavaScript console errors, occurrences, and stack traces.
+* **`get_failed_api_calls`**: Lists failed HTTP/network requests (AJAX/Fetch returning 4xx or 5xx).
+* **`get_session_examples`**: Retrieves recorded user session replay links matching specific filters.
+* **`get_funnel_summary`**: Retrieves conversion rates and drop-off summaries for configured funnels.
+* **`get_checkout_dropoffs`**: Returns checkout funnel friction details.
+* **`get_revenue_loss_estimate`**: Returns estimated revenue impact caused by conversion drop-offs or errors.
+* **`list_accounts` / `list_sites`**: Helper tools to retrieve accessible accounts and sites.
+
+---
+
+## Environment Variables
+
+* **`WEBEYEZ_API_KEY`** (Required): Your personal API Key or Personal Access Token (PAT).
+* **`WEBEYEZ_MCP_URL`** (Optional): Overrides the default hosted Webeyez MCP gateway endpoint (default: `https://api.app.webeyez.com/mcp`).
+
+---
+
+## Security & Architecture
+
+The Webeyez MCP server uses a **secure hybrid model**:
+1. **Lightweight Gateway:** The NPM package published is a transparent proxy. It doesn't contain any local business logic or database drivers, preventing intellectual property exposure.
+2. **Standard stdin/stdout:** The proxy listens to standard streams, ensuring 100% compatibility with all standard MCP hosts (e.g. Claude Desktop, Cursor).
+3. **Encrypted HTTPS/SSE Tunnel:** Messages are securely routed from the proxy over TLS to the hosted Webeyez endpoints where authentication and query processing take place.
 
 ## License
-ISC License
+ISC License.

package/dist/client.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const eventsource_1 = require("eventsource");
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const readline_1 = __importDefault(require("readline"));
+const mcpUrl = process.env.WEBEYEZ_MCP_URL || 'https://api.app.webeyez.com/mcp';
+const apiKey = process.env.WEBEYEZ_API_KEY || process.env.WEBEYEZ_TOKEN || process.env.WEBEYEZ_PAT;
+if (!apiKey) {
+    console.error('Error: WEBEYEZ_API_KEY environment variable is not set.');
+    console.error('\nTo use the Webeyez MCP Server locally, you must provide your API Key.');
+    console.error('Please configure your client config file (e.g., claude_desktop_config.json) as follows:');
+    console.error(JSON.stringify({
+        mcpServers: {
+            webeyez: {
+                command: "npx",
+                args: ["-y", "@webeyez/mcp-server"],
+                env: {
+                    WEBEYEZ_API_KEY: "YOUR_WEBEYEZ_API_KEY_HERE"
+                }
+            }
+        }
+    }, null, 2));
+    process.exit(1);
+}
+// Prepare URL with credentials query parameter as fallback for some HTTP proxies
+const url = new URL(mcpUrl);
+url.searchParams.set('token', apiKey);
+const es = new eventsource_1.EventSource(url.toString(), {
+    headers: {
+        'x-api-key': apiKey,
+        'Authorization': `Bearer ${apiKey}`
+    }
+});
+let postUrl = null;
+const pendingMessages = [];
+es.addEventListener('endpoint', (event) => {
+    const endpointUri = event.data;
+    if (endpointUri.startsWith('http://') || endpointUri.startsWith('https://')) {
+        postUrl = endpointUri;
+    }
+    else {
+        const base = new URL(mcpUrl);
+        postUrl = new URL(endpointUri, base).toString();
+    }
+    // Flush any messages received from stdin before the SSE stream was fully established
+    while (pendingMessages.length > 0) {
+        const msg = pendingMessages.shift();
+        if (msg) {
+            sendPost(msg);
+        }
+    }
+});
+es.addEventListener('message', (event) => {
+    // Write message data directly to stdout for the local LLM client
+    console.log(event.data);
+});
+es.onerror = (err) => {
+    console.error('Webeyez MCP connection error:', err);
+};
+const rl = readline_1.default.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false
+});
+rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    if (postUrl) {
+        sendPost(trimmed);
+    }
+    else {
+        pendingMessages.push(trimmed);
+    }
+});
+async function sendPost(messageStr) {
+    if (!postUrl)
+        return;
+    try {
+        const response = await (0, node_fetch_1.default)(postUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey,
+                'Authorization': `Bearer ${apiKey}`
+            },
+            body: messageStr
+        });
+        if (!response.ok) {
+            const errText = await response.text();
+            console.error(`HTTP error posting message: ${response.status} ${response.statusText} - ${errText}`);
+        }
+    }
+    catch (error) {
+        console.error('Network error posting message:', error);
+    }
+}
+// Graceful cleanup
+const cleanup = () => {
+    es.close();
+    process.exit(0);
+};
+process.on('SIGINT', cleanup);
+process.on('SIGTERM', cleanup);

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@webeyez/mcp-server",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "mcpName": "io.github.ShaharAlbag/webeyez-mcp-server",
-  "main": "dist/index.js",
+  "main": "dist/client.js",
+  "bin": {
+    "webeyez-mcp-server": "./dist/client.js"
+  },
   "files": [
-    "dist"
+    "dist/client.js"
   ],
   "scripts": {
     "build": "tsc && cp src/tools/*.proto dist/tools/",