@convertcom/mcp-server 0.0.1-beta.3 → 0.0.1-beta.4

package/.assets/logo-dark.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 153 33">
+    <g fill="#FFFFFF">
+        <path
+            d="M17.94 24.823h4.699c-.69 2.634-2.007 4.64-3.947 6.018C16.748 32.283 14.308 33 11.365 33c-3.57 0-6.355-1.157-8.36-3.475C1 27.27 0 24.04 0 19.837c0-4.009.968-7.142 2.912-9.397 2-2.319 4.79-3.482 8.36-3.482 3.76 0 6.668 1.13 8.736 3.385 1.127 1.38 1.94 2.978 2.444 4.794h-6.578c-.314-.624-.626-1.092-.936-1.409-.82-.878-1.976-1.317-3.476-1.317-1.382 0-2.508.44-3.383 1.317-1.127 1.254-1.691 3.327-1.691 6.21 0 2.88.564 4.915 1.69 6.107.81 1.002 2.03 1.503 3.664 1.503 1.065 0 1.968-.217 2.724-.657.188-.061.358-.173.514-.329.158-.16.329-.33.52-.517.122-.19.374-.438.748-.752.381-.31.942-.47 1.692-.47"></path>
+        <path fill-rule="evenodd" clip-rule="evenodd"
+            d="M24.314 25.72c.561 1.912 1.505 3.43 2.818 4.557 1.252 1.127 2.931 1.928 5.029 2.394 2.095.474 4.18.43 6.246-.138 2.314-.502 4.225-1.788 5.735-3.855.681-1.002 1.25-2.222 1.688-3.663.436-1.442.655-3.166.655-5.178 0-2.756-.535-5.165-1.6-7.236-1.124-2.316-2.876-3.95-5.255-4.888-2.066-.756-4.384-.955-6.953-.613-2.569.346-4.667 1.46-6.294 3.34-1.007 1.124-1.74 2.539-2.214 4.232a19.12 19.12 0 00-.7 5.078c0 2.06.28 4.056.845 5.97zm5.549-5.55c-.129-2.853.464-4.998 1.779-6.442.438-.436 1.13-.798 2.068-1.081a4.58 4.58 0 012.815.048c.942.316 1.775 1.033 2.491 2.164.724 1.127 1.081 2.82 1.081 5.078-.06 2.503-.467 4.321-1.22 5.449-.751 1.127-1.617 1.832-2.585 2.117a4.47 4.47 0 01-2.867-.097c-.935-.342-1.594-.763-1.968-1.267-.942-1.124-1.475-3.113-1.594-5.97z"></path>
+        <path
+            d="M69.311 32.534h-3.285c-.94 0-1.708-.3-2.302-.895-.597-.598-.89-1.362-.89-2.302V16.552c0-1.505-.458-2.604-1.366-3.295a4.928 4.928 0 00-3.054-1.034 4.73 4.73 0 00-3.004 1.034c-.878.69-1.317 1.79-1.317 3.295v15.982h-6.572V17.867c0-4.26 1.107-7.113 3.334-8.558 2.221-1.44 4.677-2.222 7.373-2.351 2.756 0 5.29.723 7.61 2.164 2.318 1.44 3.473 4.358 3.473 8.745v14.667z"></path>
+        <path fill-rule="evenodd" clip-rule="evenodd"
+            d="M118.667 24.823h-4.698c-.747 0-1.333.159-1.735.47-.408.314-.647.562-.704.752l-.148.147-.372.37a1.33 1.33 0 01-.517.33c-.751.44-1.659.656-2.722.656-1.629 0-2.855-.501-3.666-1.503-.877-.94-1.346-2.383-1.406-4.326h16.249c.064-.123.095-.341.095-.658v-1.034c0-4.134-.999-7.362-3.003-9.684-2.071-2.255-4.982-3.385-8.742-3.385-3.563 0-6.355 1.163-8.357 3.482-1.942 2.255-2.917 5.388-2.917 9.397 0 4.203 1.003 7.433 3.008 9.688 2.004 2.318 4.794 3.475 8.362 3.475 2.945 0 5.388-.718 7.331-2.16 1.936-1.378 3.254-3.384 3.942-6.017zm-6.389-7.335h-9.579c.06-1.628.529-2.88 1.407-3.76.878-.878 2.003-1.317 3.38-1.317 1.504 0 2.662.44 3.48 1.317.751.814 1.186 2.067 1.312 3.76z"></path>
+        <path
+            d="M120.077 32.533V20.402c0-2.442.362-4.494 1.08-6.157.721-1.66 1.705-2.991 2.96-3.992 1.19-.944 2.583-1.632 4.182-2.07a18.552 18.552 0 014.928-.66H134.168V14.2h-2.158c-1.818 0-3.168.44-4.04 1.311-.879.882-1.318 2.262-1.318 4.142v12.88h-6.575zM145.907 32.533c-2.062.121-4.304.093-6.713-.095-2.414-.188-3.614-1.723-3.614-4.606V.187h3.381c.81 0 1.533.317 2.158.943.627.627.941 1.38.941 2.258v4.229h3.846v1.317c0 .937-.31 1.706-.933 2.304a3.163 3.163 0 01-2.257.894h-.655v13.913c0 1.063.621 1.598 1.878 1.598h1.967v4.89h.001z"></path>
+        <path opacity=".5" d="M71.839 8.985l-1.47 3.61 3.073 6.95 3.341-8.689-4.944-1.871z"
+            fill="inherit"></path>
+        <path opacity=".75" d="M80.39 8.316l-5.478 14.438 3.073 7.085 7.617-19.517-5.211-2.006z"
+            fill="inherit"></path>
+        <path
+            d="M96.025 10.322L94.42 1.098l-7.35 5.614 2.005.802-9.754 25.266h5.612L94.02 9.52l2.005.802zM149.906 3.124c-1.492 0-2.7 1.226-2.7 2.715 0 1.5 1.208 2.714 2.7 2.714a2.715 2.715 0 000-5.43zm0 4.904a2.176 2.176 0 01-2.178-2.19c0-1.204.969-2.189 2.178-2.189a2.19 2.19 0 010 4.379zm1.198-.887c-.577-1.062-.544-1.007-.577-1.05.261-.154.425-.46.425-.81 0-.57-.327-.931-1.1-.931h-.861a.132.132 0 00-.13.131v2.715c0 .077.054.131.13.131h.425a.133.133 0 00.131-.131v-.909h.348l.512.975c.022.043.076.065.12.065h.457c.109 0 .164-.098.12-.186zm-1.198-1.478h-.359v-.7h.294c.348 0 .424.131.424.35 0 .23-.13.35-.359.35z"></path>
+    </g>
+</svg>

package/.assets/logo-light.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 153 33">
+    <g fill="#24292F">
+        <path
+            d="M17.94 24.823h4.699c-.69 2.634-2.007 4.64-3.947 6.018C16.748 32.283 14.308 33 11.365 33c-3.57 0-6.355-1.157-8.36-3.475C1 27.27 0 24.04 0 19.837c0-4.009.968-7.142 2.912-9.397 2-2.319 4.79-3.482 8.36-3.482 3.76 0 6.668 1.13 8.736 3.385 1.127 1.38 1.94 2.978 2.444 4.794h-6.578c-.314-.624-.626-1.092-.936-1.409-.82-.878-1.976-1.317-3.476-1.317-1.382 0-2.508.44-3.383 1.317-1.127 1.254-1.691 3.327-1.691 6.21 0 2.88.564 4.915 1.69 6.107.81 1.002 2.03 1.503 3.664 1.503 1.065 0 1.968-.217 2.724-.657.188-.061.358-.173.514-.329.158-.16.329-.33.52-.517.122-.19.374-.438.748-.752.381-.31.942-.47 1.692-.47"></path>
+        <path fill-rule="evenodd" clip-rule="evenodd"
+            d="M24.314 25.72c.561 1.912 1.505 3.43 2.818 4.557 1.252 1.127 2.931 1.928 5.029 2.394 2.095.474 4.18.43 6.246-.138 2.314-.502 4.225-1.788 5.735-3.855.681-1.002 1.25-2.222 1.688-3.663.436-1.442.655-3.166.655-5.178 0-2.756-.535-5.165-1.6-7.236-1.124-2.316-2.876-3.95-5.255-4.888-2.066-.756-4.384-.955-6.953-.613-2.569.346-4.667 1.46-6.294 3.34-1.007 1.124-1.74 2.539-2.214 4.232a19.12 19.12 0 00-.7 5.078c0 2.06.28 4.056.845 5.97zm5.549-5.55c-.129-2.853.464-4.998 1.779-6.442.438-.436 1.13-.798 2.068-1.081a4.58 4.58 0 012.815.048c.942.316 1.775 1.033 2.491 2.164.724 1.127 1.081 2.82 1.081 5.078-.06 2.503-.467 4.321-1.22 5.449-.751 1.127-1.617 1.832-2.585 2.117a4.47 4.47 0 01-2.867-.097c-.935-.342-1.594-.763-1.968-1.267-.942-1.124-1.475-3.113-1.594-5.97z"></path>
+        <path
+            d="M69.311 32.534h-3.285c-.94 0-1.708-.3-2.302-.895-.597-.598-.89-1.362-.89-2.302V16.552c0-1.505-.458-2.604-1.366-3.295a4.928 4.928 0 00-3.054-1.034 4.73 4.73 0 00-3.004 1.034c-.878.69-1.317 1.79-1.317 3.295v15.982h-6.572V17.867c0-4.26 1.107-7.113 3.334-8.558 2.221-1.44 4.677-2.222 7.373-2.351 2.756 0 5.29.723 7.61 2.164 2.318 1.44 3.473 4.358 3.473 8.745v14.667z"></path>
+        <path fill-rule="evenodd" clip-rule="evenodd"
+            d="M118.667 24.823h-4.698c-.747 0-1.333.159-1.735.47-.408.314-.647.562-.704.752l-.148.147-.372.37a1.33 1.33 0 01-.517.33c-.751.44-1.659.656-2.722.656-1.629 0-2.855-.501-3.666-1.503-.877-.94-1.346-2.383-1.406-4.326h16.249c.064-.123.095-.341.095-.658v-1.034c0-4.134-.999-7.362-3.003-9.684-2.071-2.255-4.982-3.385-8.742-3.385-3.563 0-6.355 1.163-8.357 3.482-1.942 2.255-2.917 5.388-2.917 9.397 0 4.203 1.003 7.433 3.008 9.688 2.004 2.318 4.794 3.475 8.362 3.475 2.945 0 5.388-.718 7.331-2.16 1.936-1.378 3.254-3.384 3.942-6.017zm-6.389-7.335h-9.579c.06-1.628.529-2.88 1.407-3.76.878-.878 2.003-1.317 3.38-1.317 1.504 0 2.662.44 3.48 1.317.751.814 1.186 2.067 1.312 3.76z"></path>
+        <path
+            d="M120.077 32.533V20.402c0-2.442.362-4.494 1.08-6.157.721-1.66 1.705-2.991 2.96-3.992 1.19-.944 2.583-1.632 4.182-2.07a18.552 18.552 0 014.928-.66H134.168V14.2h-2.158c-1.818 0-3.168.44-4.04 1.311-.879.882-1.318 2.262-1.318 4.142v12.88h-6.575zM145.907 32.533c-2.062.121-4.304.093-6.713-.095-2.414-.188-3.614-1.723-3.614-4.606V.187h3.381c.81 0 1.533.317 2.158.943.627.627.941 1.38.941 2.258v4.229h3.846v1.317c0 .937-.31 1.706-.933 2.304a3.163 3.163 0 01-2.257.894h-.655v13.913c0 1.063.621 1.598 1.878 1.598h1.967v4.89h.001z"></path>
+        <path opacity=".5" d="M71.839 8.985l-1.47 3.61 3.073 6.95 3.341-8.689-4.944-1.871z"
+            fill="inherit"></path>
+        <path opacity=".75" d="M80.39 8.316l-5.478 14.438 3.073 7.085 7.617-19.517-5.211-2.006z"
+            fill="inherit"></path>
+        <path
+            d="M96.025 10.322L94.42 1.098l-7.35 5.614 2.005.802-9.754 25.266h5.612L94.02 9.52l2.005.802zM149.906 3.124c-1.492 0-2.7 1.226-2.7 2.715 0 1.5 1.208 2.714 2.7 2.714a2.715 2.715 0 000-5.43zm0 4.904a2.176 2.176 0 01-2.178-2.19c0-1.204.969-2.189 2.178-2.189a2.19 2.19 0 010 4.379zm1.198-.887c-.577-1.062-.544-1.007-.577-1.05.261-.154.425-.46.425-.81 0-.57-.327-.931-1.1-.931h-.861a.132.132 0 00-.13.131v2.715c0 .077.054.131.13.131h.425a.133.133 0 00.131-.131v-.909h.348l.512.975c.022.043.076.065.12.065h.457c.109 0 .164-.098.12-.186zm-1.198-1.478h-.359v-.7h.294c.348 0 .424.131.424.35 0 .23-.13.35-.359.35z"></path>
+    </g>
+</svg>

package/README.md

@@ -1,64 +1,125 @@
 # Convert MCP Server
 
-Connect your Convert optimization data directly to Claude Desktop, Cursor, or any Model Context Protocol-compatible AI assistant. No middleware, no complex setup—just plug and play.
+<div align="center">
+
+<a href="https://www.convert.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset=".assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset=".assets/logo-light.svg">
+    <img alt="Convert Insights, Inc." src=".assets/logo-light.svg" width="250">
+  </picture>
+</a>
+
+[![npm](https://img.shields.io/npm/v/@convertcom/mcp-server.svg)](https://www.npmjs.com/package/@convertcom/mcp-server)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Protocol-purple.svg)](https://modelcontextprotocol.io)
+
+**Connect Claude, Cursor, and other AI assistants to your Convert account**
+
+</div>
+
+---
+
+## 🌟 Overview
+
+The Convert MCP server lets AI assistants explore your Convert account without custom integrations. Once connected, the assistant can answer questions, surface insights, and (if you permit) manage entities such as experiences, audiences, and goals.
 
 **What is MCP?**
 
-MCP (Model Context Protocol) is an emerging standard that allows AI models to interact with applications through a consistent interface. It acts as an abstraction layer, letting AI agents access your Convert data without needing to understand specific API protocols.
+MCP (Model Context Protocol) is an open standard that allows AI models to interact with applications through a consistent interface. It acts as a bridge, letting AI assistants access your Convert data without needing to understand specific API protocols.
+
+**Key Benefits:**
+- 🔌 **Zero-config integration** – Works with Claude Desktop, Cursor, and any MCP-compatible client
+- 🔍 **Full API access** – Comprehensive coverage of Convert's [REST API v2](https://api.convert.com/doc/v2.0.0/)
+- 📚 **Built-in knowledge** – 5,279+ indexed chunks from Convert support documentation
+- 🛡️ **Configurable permissions** – Three access levels from reporting-only to full read/write
+- 🧩 **Namespaced tools** – Clean interface with 13 namespaces instead of 96+ individual tools
 
 ---
 
-## 🚀 Quick Start
+## 📚 Table of Contents
 
-### Prerequisites
+- [🚀 Quick Start](#-quick-start)
+- [🔧 Installation Options](#-installation-options)
+- [🔗 Client Integration](#-client-integration)
+- [🛠 Available Tools](#-available-tools)
+- [📊 Example Prompts](#-example-prompts)
+- [🔐 Authentication & Security](#-authentication--security)
+- [❓ Troubleshooting](#-troubleshooting)
 
-**Get your Convert API credentials:**
+---
 
-- Log into your Convert account
-- Go to Settings → Integrations → API
-- Generate or copy your Application ID and Secret Key
-- _Consider starting with read-only access (`TOOLS_FOR_CLIENT=reporting` or `TOOLS_FOR_CLIENT=readOnly` mod - see below)_
+## 🚀 Quick Start
 
-### Installation & Setup
+### What you need
 
-#### Option 1: NPX (Recommended)
+1. **Convert API credentials** – In Convert, go to **Settings → Integrations → API** and copy your Application ID and Secret Key.
+2. **Node.js 20+** – Only required if you run the server from source.
+3. **Access level** – Set `TOOLS_FOR_CLIENT` to control what the assistant can do:
+   - `reporting` (default) – basic analytics and read-only summaries
+   - `readOnly` – detailed configuration data without modifying anything
+   - `all` – read/write access (only use when you explicitly want the assistant to make changes)
 
+---
+
+## 🔧 Installation Options
+
+### Option A – Run instantly with npx (recommended)
 ```bash
-# No installation needed - run directly
-npx @convertcom/mcp-server
+npx -y @convertcom/mcp-server@latest
 ```
 
-#### Option 2: Global Installation
+### Option B – Install globally
+```bash
+npm install -g @convertcom/mcp-server@latest
+convert-mcp
+```
 
+### Option C – Run from source (developers)
 ```bash
-# Install globally
-npm install -g @convertcom/mcp-server
+git clone https://github.com/convertcom/convert-mcp.git
+cd convert-mcp/packages/server
+yarn install
+yarn build
+node build/index.js
+```
 
-# Run the server
-mcp-server-convert
+Before launching, export these variables (or set them in your MCP client config):
+```bash
+export CONVERT_API_KEY=your_application_id
+export CONVERT_API_SECRET=your_secret_key
+export TOOLS_FOR_CLIENT=reporting   # or readOnly / all
 ```
 
 ---
 
-## 🔧 Client Configuration
+## 🔗 Client Integration
+
+The server implements the [Model Context Protocol](https://modelcontextprotocol.io) and works with Claude Desktop, Cursor, and any MCP-compatible client.
+
+### Recommended Models
 
-### Claude Desktop
+For the best experience, use models with strong agentic capabilities:
+- **Claude Sonnet 4.5** or newer
+- **GPT-5** or newer
+- Other frontier models with multi-step reasoning abilities
 
-1. **Download Claude Desktop** from [claude.ai](https://claude.ai/download)
+**Enable extended thinking** – Extended thinking is a special reasoning mode that significantly improves MCP tool calling, multi-step workflows, and complex API interactions. Enable it in your client settings if available.
 
-2. **Add server configuration** to your Claude Desktop config file:
-   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+### Configuration
+
+Add this configuration to your MCP settings file:
 
 ```json
 {
   "mcpServers": {
     "convert": {
       "command": "npx",
-      "args": ["-y", "@convertcom/mcp-server"],
+      "args": ["-y", "@convertcom/mcp-server@latest"],
       "env": {
-        "CONVERT_API_KEY": "your_convert_application_id",
-        "CONVERT_API_SECRET": "your_convert_secret_key",
+        "CONVERT_API_KEY": "your_application_id",
+        "CONVERT_API_SECRET": "your_secret_key",
         "TOOLS_FOR_CLIENT": "reporting"
       }
     }
@@ -66,45 +127,66 @@ mcp-server-convert
 }
 ```
 
-1. **Save the file and restart Claude Desktop**. You should now see Convert tools available!
+**Configuration file locations:**
+- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+- **Cursor**: `.cursor/mcp.json` in your project directory
+- **Other clients**: Refer to your client's documentation for MCP server configuration
 
-2. **Visit the [troubleshooting section](#-troubleshooting)** if you encounter any issues.
+Save the file and restart your client to activate the Convert tools.
 
-### Cursor
+### Environment Variables
 
-1. **Create a `.cursor/mcp.json` file** in your project:
+| Variable             | Required | Description                                     | Default     |
+| -------------------- | -------- | ----------------------------------------------- | ----------- |
+| `CONVERT_API_KEY`    | ✅       | Your Convert **Application ID**                 | -           |
+| `CONVERT_API_SECRET` | ✅       | Your Convert **Secret Key**                     | -           |
+| `TOOLS_FOR_CLIENT`   |          | Access level: `reporting`, `readOnly`, or `all` | `reporting` |
 
-```bash
-mkdir -p .cursor && touch .cursor/mcp.json
-```
+---
 
-2. **Add the following configuration**:
+## 🛠 What You Can Do
 
-```json
-{
-  "mcpServers": {
-    "convert": {
-      "command": "npx",
-      "args": ["-y", "@convertcom/mcp-server"],
-      "env": {
-        "CONVERT_API_KEY": "your_convert_application_id",
-        "CONVERT_API_SECRET": "your_convert_secret_key",
-        "TOOLS_FOR_CLIENT": "reporting"
-      }
-    }
-  }
-}
-```
+Once connected, your AI assistant can:
+
+- 📊 **View experiment performance** – Get real-time stats on your A/B tests and experiences
+- 🎯 **Analyze goals and conversions** – See which goals are tracking and how they're performing
+- 👥 **Explore audience segments** – Understand your targeting rules and segmentation
+- 🔍 **Search Convert documentation** – The assistant has instant access to Convert's full support library
+- 📈 **Access account analytics** – Review live data, history, and visitor tracking
+- ⚙️ **Manage experiments** – Create, update, or pause experiences *(requires `TOOLS_FOR_CLIENT=all`)*
+
+The assistant doesn't need to know technical details—just ask questions in plain English.
+
+<details>
+<summary><b>13 Available Namespaces</b></summary>
 
-3. **Save the file and restart Cursor**. Convert tools will now be available!
+| Namespace | Reporting & readOnly actions | Extra actions in `all` |
+| --- | --- | --- |
+| `accounts` | list, get, get_live_data, get_history, list_users_accesses, list_api_keys, list_sdk_keys | create_sdk_key |
+| `projects` | list, get, get_live_data, get_history | create, update |
+| `domains` | list, get, get_by_url, check_code | create, update, delete |
+| `experiences` | list, get, get_by_key, get_live_data, get_history, aggregated_report, daily_report, daily_traffic_allocation, get_variation_screenshot, get_change | create, clone, update, update_variation, upload_variation_screenshot, convert_variation, update_change |
+| `sections` | list | create, update, update_experience_sections, add_version, update_version |
+| `goals` | list, get, get_by_key | create, update, delete, clone |
+| `tags` | list, get | create, update, delete |
+| `hypotheses` | list, get | create, update, update_status, convert, delete |
+| `knowledgebases` | list, get | create, update, delete |
+| `observations` | list, get | create, update, delete |
+| `locations` | list, get, presets | create, update, delete, clone |
+| `audiences` | list, get, presets | create, update, delete, clone |
+| `features` | list, get, get_by_key | create, update, delete |
+
+</details>
+
+**Access Control**: With `TOOLS_FOR_CLIENT=all`, additional write actions (create/update/delete) become available. Keep permissions as narrow as possible and escalate only when necessary.
 
 ---
 
-## 💬 Example Usage
+## 📊 Example Prompts
 
-Once set up, try these example prompts with your AI assistant:
+Once set up, try these prompts with your AI assistant:
 
-### Get Insights from Your Convert Data
+### Get Insights from Your Data
 
 ```
 Show me the performance of all active experiments in my account
@@ -132,170 +214,65 @@ Compare the performance of mobile vs desktop experiments this month
 Show me which audience segments are performing best across all active tests
 ```
 
-### Create and Manage Tests (Full Access Mode)
+### Manage Tests *(Requires `TOOLS_FOR_CLIENT=all`)*
 
 ```
-Create a new A/B test for the pricing page targeting returning visitors with a 70/30 traffic split
+Create a new A/B test for the pricing page targeting returning visitors
 ```
 
 ```
-Pause any experiences that have been running for more than 30 days with negative lift
+Update the traffic split on experience 789 to 50/50
 ```
 
 ```
-Update the traffic allocation for experiment ID 12345 to 50/50
+Pause any experiences that have been running for more than 30 days with negative lift
 ```
 
 ---
 
-## ⚙️ Configuration
-
-All configuration is handled through environment variables for maximum compatibility across different MCP clients.
-
-| Variable             | Required | Description                                     | Default     |
-| -------------------- | -------- | ----------------------------------------------- | ----------- |
-| `CONVERT_API_KEY`    | ✅       | Your Convert **Application ID**                 | -           |
-| `CONVERT_API_SECRET` | ✅       | Your Convert **Secret Key**                     | -           |
-| `TOOLS_FOR_CLIENT`   |          | Access level: `reporting`, `readOnly`, or `all` | `reporting` |
-
-### Access Levels
-
-Choose the appropriate access level based on your needs:
-
-#### 🔍 `reporting` (Default - Recommended)
-
-**Perfect for analytics and insights**
-
-- Account data and project information
-- Real-time experiment tracking and performance reports
-- Goals, audiences, and conversion analytics
-- Live visitor data and traffic allocation
-
-#### 📖 `readOnly`
-
-**All reporting tools plus detailed configuration access**
-
-- Everything in `reporting` mode
-- Detailed project and experience configurations
-- Historical data and change logs
-- Advanced analytics and forecasting data
-
-#### 🔧 `all` (Use with caution)
-
-**Complete access including write operations**
-
-- Everything in `readOnly` mode
-- Create, edit, and delete experiments
-- Manage audiences, goals, and project settings
-- Full account administration capabilities
-
-> **⚠️ Security Note**: Start with `reporting` mode and only escalate permissions as needed. The `all` access level can modify your Convert account.
-
----
-
-## 🛠️ Available Tools
-
-The server provides **100+ tools** covering the complete Convert REST API v2. Here's a quick overview:
-
-### Core Analytics Tools (All Access Levels)
+## 🔐 Security
 
-| Category                | Tools                                                                  | Description                              |
-| ----------------------- | ---------------------------------------------------------------------- | ---------------------------------------- |
-| **Account Management**  | `getaccountslist`, `getaccountlivedata`                                | Account overview and real-time tracking  |
-| **Project Operations**  | `getprojectslist`, `getproject`, `getprojectlivedata`                  | Project configuration and live data      |
-| **Experience Tracking** | `getexperienceslist`, `getexperience`, `getexperienceaggregatedreport` | A/B test performance and analytics       |
-| **Goal Analytics**      | `getgoal`, `getgoalbykey`                                              | Conversion goal tracking and performance |
-| **Audience Insights**   | `getaudienceslist`, `getaudience`                                      | Audience segment analysis                |
-| **Location Targeting**  | `getlocationslist`, `getlocation`                                      | URL targeting and location rules         |
+The server uses your Convert API credentials to authenticate requests. Your credentials are stored only in environment variables and never exposed in code.
 
-### Advanced Tools (ReadOnly & All Access)
-
-| Category            | Tools                                                            | Description                      |
-| ------------------- | ---------------------------------------------------------------- | -------------------------------- |
-| **Historical Data** | `getaccounthistory`, `getprojecthistory`, `getexperiencehistory` | Change logs and audit trails     |
-| **Screenshots**     | `getexperiencevariationscreenshot`                               | Visual variation previews        |
-| **Knowledge Base**  | `getknowledgebaseslist`, `getknowledgebase`                      | Test insights and learnings      |
-| **Observations**    | `getobservationslist`                                            | Recorded insights and hypotheses |
-
-### Management Tools (All Access Only)
-
-| Category                   | Tools                                                      | Description                    |
-| -------------------------- | ---------------------------------------------------------- | ------------------------------ |
-| **Experience Management**  | `createexperience`, `updateexperience`, `deleteexperience` | Full A/B test lifecycle        |
-| **Goal Management**        | `creategoal`, `updategoal`, `deletegoal`, `clonegoal`      | Conversion goal administration |
-| **Audience Management**    | `createaudience`, `updateaudience`, `deleteaudience`       | Audience segment management    |
-| **Project Administration** | `createproject`, `updateproject`                           | Project-level configuration    |
+**Best practices:**
+- Start with `TOOLS_FOR_CLIENT=reporting` and escalate only when needed
+- Keep your API credentials secure and never commit them to version control
 
 ---
 
-## 🔒 Security & Authentication
+## ❓ Troubleshooting
 
-### API Security
+| Problem | How to fix |
+| ------- | ---------- |
+| Tools not visible after install | Restart the client and confirm the JSON config points to the correct command/env vars. |
+| `401 Unauthorized` | Re-check API key/secret and your account permissions. |
+| Requests blocked or failing | Use a smart model like Claude Sonnet 4.5, GPT-5, or newer with strong agentic capabilities. Enable extended thinking if available. The model needs to handle multi-step API workflows and parse response alerts. |
+| Keyword search feels off | Refine the query with specific terms (product codes, URLs, field names). |
 
-- **HMAC-SHA256 signing**: Every request is cryptographically signed
-- **Automatic expiration**: Requests expire after 60 seconds
-- **No credential exposure**: API keys never leave your local environment
+Need more help? Visit the [Convert Help Center](https://support.convert.com/).
 
 ---
 
-## 🔧 Troubleshooting
-
-### Common Issues
-
-| Symptom                      | Likely Cause                        | Solution                                        |
-| ---------------------------- | ----------------------------------- | ----------------------------------------------- |
-| `401 Unauthorized` responses | Wrong API credentials or clock skew | Verify credentials, sync system clock           |
-| "Server not found" in Claude | JSON config syntax error            | Check `command` and `args` fields               |
-| Missing expected tools       | `TOOLS_FOR_CLIENT` too restrictive  | Switch to `readOnly` or `all` and restart       |
-| Connection timeouts          | Network/firewall issues             | Check connectivity to Convert's API endpoints   |
-| "No data returned"           | Empty account or wrong permissions  | Verify account has data and API key permissions |
+## 📦 API Coverage
 
-### Getting Help
+The server provides comprehensive coverage of Convert's [REST API v2](https://api.convert.com/doc/v2.0.0/):
 
-1. **Check the logs**: Development mode provides detailed error information
-2. **Verify credentials**: Ensure your API key and secret are correct and have proper permissions
-3. **Test connectivity**: Confirm you can reach Convert's API endpoints
-4. **Review permissions**: Make sure your Convert account has access to the data you're requesting
+- **Account Operations**: User management, billing, and settings
+- **Project Management**: Configuration, domains, and collaborators
+- **Experience Control**: A/B tests, MVT, Split URL, and deployments
+- **Analytics & Reporting**: Real-time data, conversion tracking, and statistical analysis
+- **Goal Tracking**: Conversion goals, revenue tracking, and custom events
+- **Audience Management**: Segmentation rules and targeting
+- **Feature Flags**: Feature management and rollout control
 
 ---
 
-## 📊 What You Can Do
+<div align="center">
 
-### Real-time Analytics
+**Made with ❤️ by the Convert Team**
 
-- Monitor live experiment performance
-- Track visitor behavior and conversions
-- Analyze traffic allocation and statistical significance
-- Get instant insights on goal performance
+© 2025 Convert Insights, Inc. Built for the automation-minded optimizer.
 
-### Experiment Management
-
-- Create and configure A/B tests
-- Set up multivariate experiments
-- Manage audience targeting and segmentation
-- Control traffic allocation and experiment lifecycle
-
-### Data-Driven Insights
-
-- Historical performance analysis
-- Conversion funnel optimization
-- Audience behavior patterns
-- ROI and revenue impact assessment
-
-### AI-Powered Optimization
-
-- Let AI analyze your experiment data
-- Get recommendations for test improvements
-- Automate routine optimization tasks
-- Generate insights from complex data patterns
-
----
-
-## 🆘 Support
-
-- **Documentation**: [Convert API Documentation](https://api.convert.com/doc/)
-- **Convert Support**: [Convert Help Center](https://support.convert.com/)
-
----
+[Website](https://www.convert.com) • [Documentation](https://support.convert.com/) • [API Reference](https://api.convert.com/doc/)
 
-_© 2025 Convert Insights, Inc. • Built with ❤️ for the optimization community_
+</div>

package/build/api-config.js

@@ -17,6 +17,7 @@ axios.interceptors.request.use((config) => {
     let applicationID = process.env.CONVERT_API_KEY;
     let applicationSecretKey = process.env.CONVERT_API_SECRET;
     let expires = 60; // In seconds. Request lifetime. If your requests take much time, try to increase this value
+    // URL already includes query string from executor.ts - use it directly for signing
     let requestURL = config.url;
     // It's already stringified in raw body in Postman but make sure it stringified correctly without whitespaces etc
     let requestBody = config.data ? JSON.stringify(config.data) : '{}';
@@ -25,10 +26,6 @@ axios.interceptors.request.use((config) => {
     let signString = applicationID + '\n' + expiresTimestamp + '\n' + requestURL + '\n' + requestBody;
     let hash = crypto.createHmac('sha256', applicationSecretKey).update(signString).digest('hex');
     let authorization = 'Convert-HMAC-SHA256 Signature=' + hash;
-    // console.warn('Debug data:', data); // Or console.warn
-    // console.warn(`Debug RequestBody: ${requestBody}`);
-    // console.warn(`Debug SigningString: ${signString}`);
-    // console.warn(`Debug Api Secret: ${applicationSecretKey ? 'SET' : 'NOT SET'}`); // Avoid logging secrets
     config.headers['Convert-Application-ID'] = applicationID;
     config.headers['Expires'] = expiresTimestamp;
     config.headers['Authorization'] = authorization;

package/build/api-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-config.js","sourceRoot":"","sources":["../src/api-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;AACjE,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;AAChE,kEAAkE;AAClE,KAAK,CAAC,QAAQ,CAAC,gBAAgB,GAAG;IAChC,UAAU,IAAS,EAAE,OAAY;QAC/B,6BAA6B;QAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC;AAEF,gEAAgE;AAChE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAC5B,CAAC,MAAM,EAAE,EAAE;IACT,IAAI,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAChD,IAAI,oBAAoB,GAAG,OAAO,CAAC,GAAG,CAAC,kBAA4B,CAAC;IACpE,IAAI,OAAO,GAAG,EAAE,CAAC,CAAC,4FAA4F;IAC9G,IAAI,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC;IAE5B,iHAAiH;IACjH,IAAI,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnE,yEAAyE;IACzE,IAAI,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC;IAEnD,IAAI,UAAU,GACZ,aAAa,GAAG,IAAI,GAAG,gBAAgB,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,GAAG,WAAW,CAAC;IAEnF,IAAI,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9F,IAAI,aAAa,GAAG,gCAAgC,GAAG,IAAI,CAAC;IAE5D,wDAAwD;IACxD,qDAAqD;IACrD,sDAAsD;IACtD,0GAA0G;IAE1G,MAAM,CAAC,OAAO,CAAC,wBAAwB,CAAC,GAAG,aAAa,CAAC;IACzD,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,gBAAgB,CAAC;IAC7C,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC;IAEhD,mDAAmD;IAEnD,OAAO,MAAM,CAAC;AAChB,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;IACR,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC,CACF,CAAC"}
+{"version":3,"file":"api-config.js","sourceRoot":"","sources":["../src/api-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;AACjE,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;AAChE,kEAAkE;AAClE,KAAK,CAAC,QAAQ,CAAC,gBAAgB,GAAG;IAChC,UAAU,IAAS,EAAE,OAAY;QAC/B,6BAA6B;QAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC;AAEF,gEAAgE;AAChE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAC5B,CAAC,MAAM,EAAE,EAAE;IACT,IAAI,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAChD,IAAI,oBAAoB,GAAG,OAAO,CAAC,GAAG,CAAC,kBAA4B,CAAC;IACpE,IAAI,OAAO,GAAG,EAAE,CAAC,CAAC,4FAA4F;IAE9G,mFAAmF;IACnF,IAAI,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC;IAE5B,iHAAiH;IACjH,IAAI,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnE,yEAAyE;IACzE,IAAI,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC;IAEnD,IAAI,UAAU,GACZ,aAAa,GAAG,IAAI,GAAG,gBAAgB,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,GAAG,WAAW,CAAC;IAEnF,IAAI,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9F,IAAI,aAAa,GAAG,gCAAgC,GAAG,IAAI,CAAC;IAE5D,MAAM,CAAC,OAAO,CAAC,wBAAwB,CAAC,GAAG,aAAa,CAAC;IACzD,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,gBAAgB,CAAC;IAC7C,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC;IAEhD,mDAAmD;IAEnD,OAAO,MAAM,CAAC;AAChB,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;IACR,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC,CACF,CAAC"}

package/build/debug-log.d.ts

@@ -0,0 +1,6 @@
+export declare class DebugLogger {
+    private readonly filePath;
+    private readonly enabled;
+    constructor(enabled: boolean);
+    log(message: string, payload?: unknown): void;
+}

package/build/debug-log.js

@@ -0,0 +1,46 @@
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export class DebugLogger {
+    filePath;
+    enabled;
+    constructor(enabled) {
+        this.enabled = enabled;
+        if (!enabled) {
+            this.filePath = null;
+            return;
+        }
+        try {
+            const baseDir = join(homedir(), '.convert');
+            mkdirSync(baseDir, { recursive: true });
+            this.filePath = join(baseDir, 'convert-mcp-debug.log');
+            writeFileSync(this.filePath, '', { encoding: 'utf8' });
+        }
+        catch (error) {
+            console.error('[DebugLogger] Failed to initialise debug log file:', error);
+            this.filePath = null;
+        }
+    }
+    log(message, payload) {
+        if (!this.enabled || !this.filePath) {
+            return;
+        }
+        try {
+            const time = new Date().toISOString();
+            const serialized = payload === undefined ? '' : `\n${safeSerialize(payload)}\n`;
+            appendFileSync(this.filePath, `[${time}] ${message}${serialized}\n`, { encoding: 'utf8' });
+        }
+        catch (error) {
+            console.error('[DebugLogger] Failed to write debug entry:', error);
+        }
+    }
+}
+function safeSerialize(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch (error) {
+        return `<<unserializable: ${String(error)}>>`;
+    }
+}
+//# sourceMappingURL=debug-log.js.map

package/build/debug-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-log.js","sourceRoot":"","sources":["../src/debug-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,OAAO,WAAW;IACL,QAAQ,CAAgB;IACxB,OAAO,CAAU;IAElC,YAAY,OAAgB;QAC1B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACrB,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;YAC5C,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAAC;YACvD,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,oDAAoD,EAAE,KAAK,CAAC,CAAC;YAC3E,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,GAAG,CAAC,OAAe,EAAE,OAAiB;QACpC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACtC,MAAM,UAAU,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC;YAChF,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,IAAI,KAAK,OAAO,GAAG,UAAU,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7F,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,KAAK,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;CACF;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,qBAAqB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAChD,CAAC;AACH,CAAC"}

package/build/executor.d.ts

@@ -0,0 +1,5 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import './api-config.js';
+type JsonObject = Record<string, any>;
+export declare function executeToolByName(toolName: string, toolArgs: JsonObject): Promise<CallToolResult>;
+export {};